通用数码管与面向通用接口编程设计

周立功教授新书《面向AMetal框架与接口的编程（上）》，对AMetal框架进行了详细介绍，通过阅读这本书，你可以学到高度复用的软件设计原则和面向接口编程的开发思想，聚焦自己的“核心域”，改变自己的编程思维，实现企业和个人的共同进步。

第七章为面向通用接口的编程，本文内容为7.6 数码管。

7.6 数码管

>>> 7.6.1 通用数码管接口

AMetal 提供了一套通用数码管接口，详见表7.7。

表7.7 数码管通用接口（am_digitron_disp.h）

1． 设置段码解码函数

数码管的各个段可以组合显示出多种图形，使用该函数可以自定义字符的解码函数，其函数原型为：

其中，id 表示设置数码管显示器的编号，这里的id 指的是显示器的编号，而不是数码管的位索引。一般情况下，仅只有一个数码管显示器，比如，MiniPort-View 显示器，其包含两位数码管，仅只有一个数码管显示器时，id 为0。

pfn_decode 为函数指针，其指向的函数即为设置的解码函数，解码函数的参数为uint16_t类型的字符，返回值为uint16_t 类型的编码。

绝大部分情况下，对于8 段数码管，如字符'0' ~ '9'等都是有默认编码的，为此，AMetal提供了默认的8 段数码管解码函数，可以支持常见的字符'0' ~ '9'以及 'A' 、'B'、 'C' 、'D'、'E'、 'F'等的字符的解码。其在am_digitron_disp.h 文件中声明：

如无特殊需求，直接将该函数作为pfn_decode 的实参传递，范例程序详见程序清单7.40。

程序清单7.40 am_digitron_disp_decode_set()范例程序

若由于应用特殊需求，要求字符使用自定义的特殊编码，如要使字符'O'的编码为 0xFC，则可以自定义如下解码函数：

然后将该函数作为pfn_decode 的实参传递即可：

2． 设置数码管闪烁

该函数可以指定数码管显示器的某一位数码管闪烁，其函数原型为：

其中，id 为数码管显示器编号；index 为数码管索引，如MiniPort-View 有两位数码管，则两个数码管的索引分别为 0 和1；blink 表示该位是否闪烁，若其值为AM_TRUE，则闪烁，反之，则不闪烁，默认情况下，所有数码管均处于未闪烁状态。如设置1 号数码管闪烁的范例程序详见程序清单7.41。

程序清单7.41 am_digitron_disp_blink_set()范例程序

3． 显示指定的段码图形

该函数用于不经过解码函数解码，直接显示段码指定的图形，可以灵活的显示任意特殊图形，其函数原型为：

其中，id 为数码管显示器编号；index 为数码管索引；seg 为显示的段码。如在8 段数码管上显示字符'-'，即需要g 段点亮，对应的段码为0x02（即：0000 0010），范例程序详见程序清单7.42。

程序清单7.42 am_digitron_disp_at()范例程序

4． 显示单个字符

该函数用于在指定位置显示一个字符，字符经过解码函数解码后显示，若解码函数不支持该字符，则不显示任何内容，其函数原型为：

其中，id 为数码管显示器编号，index 为数码管索引，ch 为显示的字符。比如，显示字符'H'的范例程序详见程序清单7.43。

程序清单7.43 am_digitron_disp_char_at()范例程序

5． 显示字符串

该函数用于从指定位置开始显示一个字符串，其函数原型为：

其中，id 为数码管显示器编号，index 为显示字符串的数码管起始索引，即从该索引指定的数码管开始显示字符串，len 指定显示的长度，p_str 指向需要显示的字符串。

实际显示的长度是len 和字符串长度的较小值，若数码管位数不够，则多余字符不显示。如显示字符"HELLO"的范例程序详见程序清单7.44。

程序清单7.44 am_digitron_disp_str()范例程序

若使用的是MiniPort-View，由于只存在两个数码管，因此最终只会显示"HE"。

通常情况下，需要显示一些数字，如显示变量的值，此时，可以先将变量通过格式化字符串函数输出到字符串缓冲区中，然后再使用am_digitron_disp_str()函数显示该字符串。比如，显示一个变量i 的值，范例程序详见程序清单7.45。

程序清单7.45 使用am_digitron_disp_str()显示整数变量值的范例程序

其中，am_snprintf()与标准C 函数snprintf()函数功能相同，均用于格式化字符串到指定的缓冲区中，其函数原型为（am_vdebug.h）：

其与am_kprintf()函数的区别是，am_kprintf()将信息直接通过调试串口打印输出，而am_snprintf()函数将信息输出到大小为sz 的buf 缓冲区中。

6． 显示清屏

该函数用于显示清屏，清除数码管显示器中的所有内容，其函数原型为：

其中，id 为数码管显示器编号，范例程序详见程序清单7.46。

程序清单7.46 am_digitron_disp_clr()范例程序

基于数码管通用接口，可以编写一个简易的60s 倒计时程序，当倒计时还剩5s 时，数码管闪烁。基于模块化编程思想，将应用程序存放到app_digitron_count_down.c 文件中，并将其接口声明到app_digitron_count_down.h 文件中，详见程序清单7.47 和程序清单7.48。

程序清单7.47 倒计时应用程序实现（app_digitron_count_down.c）

程序清单7.48 倒计时应用程序接口声明（app_digitron_count_down.h）

由此可见，要使用此应用程序，只需在调用其入口函数app_digitron_count_down()时，指定应用程序所使用的数码管显示器编号即可。应用程序与具体MCU、数码管驱动方式无关，可以在任何AMetal 平台上运行。

显然，要使应用程序可以使用通用操作数接口操作数码管，就需要为具体的数码管提供相应的驱动。AMetal 提供了MiniPort-View 的驱动，用户可以直接使用。

>>> 7.6.2 数码管驱动

AMetal 数码管驱动提供了一个初始化函数，使用该函数初始化一个数码管实例后，即可使用通用数码管接口操作数码管。其函数原型为：

其中，p_dev 为指向am_digitron_scan_gpio_dev_t 类型实例的指针，p_info 为指向am_digitron_scan_gpio_info_t 类型实例信息的指针。

1. 实例

定义am_digitron_scan_gpio_dev_t 类型（am_digitron_scan_gpio.h）实例如下：

其中，miniport_view 为用户自定义的实例，其地址作为p_dev 的实参传递。

2. 实例信息

实例信息主要描述与数码管相关的信息，比如，使用的GPIO 引脚号、数码管个数等以及本实例对应的显示器编号（通用接口即可使用该显示器编号操作该数码管实例）等。其类型am_digitron_scan_gpio_info_t 的定义（am_digitron_scan_gpio.h）如下：

其中，scan_info 是数码管动态扫描相关的信息，包含了扫描频率、扫描方式和缓存的定义等；base_info 是数码管基础信息，如数码管个数、段码位数等；p_seg_pins 指向存放各个段对应引脚号的数组，p_com_pins 指向存放各个位选对应引脚号的数组。若使用AM824-Core 开发板与MiniPort-View 直接连接，其段码引脚为PIO0_8 ~ PIO0_15，位选引脚分别为PIO0_17 和PIO0_23。分别定义存放段码引脚号和位选引脚号的数组：

g_digitron_seg_pins 数组的地址即可作为p_seg_pins 的值；g_digitron_com_pins 数组的地址即可作为p_com_pins 的值。

scan_info 成员的类型am_digitron_scan_devinfo_t 定义（am_digitron_scan.h）如下：

其中，devinfo 是标准数码管设备的信息，其仅包含显示器ID 号，其类型定义（am_digitron_dev.h）如下：

当前只连接了单个数码管实例，因此，将id 设置为0，在使用数码管通用接口时，将显示器id 参数赋值为0 即可操作此处初始化的数码管实例。

scan_freq 指定扫描的频率，通常情况下，为避免看到闪烁现象，将频率设置为50Hz。blink_on_time 和blink_off_time 分别指定了数码管闪烁时，数码管点亮的时间和熄灭的时间，以此可以达到调节闪烁效果的作用。通常情况下，数码管以1Hz 频率闪烁，点亮和熄灭的时间分别设置为500ms。

p_disp_buf 指向数码管的显存，显存的类型为uint8_t，显存的大小与数码管个数相同。对于MiniPort-View，共计有两个数码管，因此大小为2 的显存定义如下：

g_disp_buf 数组的地址即可作为p_disp_buf 的值。

p_scan_buf 指向数码管的扫描缓存，用于存储单次扫描到的数码管的段码，对于8 段数码管，其缓存的类型为uint8_t ，缓存的大小与单次扫描的数码管个数相同， 对于MiniPort-View，一次只能扫描一个数码管，因此扫描缓存的大小为1，扫描缓存可定义如下：

g_scan_buf 数组的地址即可作为p_scan_buf 的值。

base_info 成员的类型am_digitron_base_info_t 定义（am_digitron_base.h）如下：

其中，num_segment 表示数码管的段数，对于MiniPort-View，其数码管为8 段数码管，因此num_segment 的值为8。num_rows 和num_cols 分别表示数码管的行数和列数，对于MiniPort-View，其数码管的排布方式为 1×2，即单行两个数码管，因此num_rows 和num_cols的值分别为1 和2。

如表7.8 所示为数码管扫描方式，scan_mode 表示数码管的扫描方式，可选的扫描方式有行扫描或列扫描方式，扫描方式是由硬件决定的，对于MiniPort-View，其仅单行两个数码管，横向的两个数码管共用段码引脚，因此，只能使用列扫描方式，即一次扫描一列（一个数码管），scan_mode 的值为AM_DIGITRON_SCAN_MODE_COL。

表7.8 数码管扫描方式

seg_active_low 表示驱动段点亮的有效电平是否为低电平，由于MiniPort-View 使用的是共阳数码管，因此，段的驱动电平为低电平，seg_active_low 的值为AM_TRUE。

com_active_low 表示驱动位选有效的电平是否为低电平，虽然共阳数码管的公共端是高

电平有效，但由于添加了三极管驱动电路，三极管是GPIO 输出低电平时导通，进而使数码管公共端为高电平。因此驱动位选有效的同样是低电平，com_active_low 的值为AM_TRUE。基于以上信息，实例信息定义如下：

基于实例和实例信息，即可完成MiniPort-View 数码管的初始化：

当完成初始化后，可使用通用数码管接口操作显示器编号为0 的数码管设备。为了便于配置数码管（修改实例信息）。基于模块化编程思想，将初始化相关的实例、实例信息等的定义存放到数码管的配置文件中，通过头文件引出实例初始化函数接口，源文件和头文件的程序范例分别详见程序清单7.49 和程序清单7.50。

程序清单7.49 数码管实例初始化函数实现（am_hwconf_miniport_view.c）

程序清单7.50 数码管实例初始化函数声明（am_hwconf_miniport_view.h）

后续只需使用无参数的实例初始化函数，即可执行以下语句完成数码管实例的初始化：

当完成初始化后，可使用通用数码管接口操作显示器编号为0 的数码管设备，运行如程序清单7.47 所示的倒计时程序，检验能否达到预期的效果，主程序详见程序清单7.51。

程序清单7.51 运行倒计时应用程序的主程序

>>> 7.6.3 数码管驱动（HC595 输出段码）

当GPIO 资源不足时，则可以在AM824-Core 与MiniPort-View 之间增加MiniPort-595，使用HC595 驱动数码管的段码，达到节省引脚的目的。

显然，在前面的数码管驱动中，8 位段码是直接由GPIO 输出的，若改由HC595 输出段码，则使用的驱动也需要发生相应的改变。AMetal 提供了使用HC595 输出段码的数码管驱动，仅包含一个初始化函数，使用该函数初始化一个数码管实例后，即可使用通用数码管接口操作数码管。其函数原型为：

• p_dev 为指向am_digitron_scan_hc595_gpio_dev_t 类型实例的指针；

• p_info 为指向am_digitron_scan_hc595_gpio_info_t 类型实例信息的指针。

1. 实例

am_digitron_scan_hc595_gpio_dev_t 类型（am_digitron_scan_hc595_gpio.h）实例的定义

如下：

其中，miniport_view_595 为用户自定义的实例，其地址作为p_dev 的实参传递。

2. 实例信息

实例信息主要描述与数码管相关的信息，比如，使用的位选GPIO 引脚号、数码管个数等以及本实例对应的显示器编号（通用接口即可使用该显示器编号操作该数码管实例）等。

其类型am_digitron_scan_hc595_gpio_info_t 的定义（am_digitron_scan_hc595_gpio.h）如下：

将其与GPIO 输出段码的数码管实例信息相比（am_digitron_scan_gpio_info_t）可以发现，其仅仅少了一个数据成员p_seg_pins，其它信息都是完全一样的。这是由于当使用595输出段码时，不再需要使用GPIO 输出段码，因此，也就不用指定段码引脚。基于此，只需要从GPIO 输出段码的数码管实例信息中去掉段码引脚，即可得到HC595 输出段码的数码管实例信息：

3. HC595 句柄handle

若使用Miniport-595 输出码段，则应通过MiniPort-595 的实例初始化函数获得HC595的句柄。即：

HC595 句柄即可直接作为handle 的实参传递。

基于实例、实例信息和HC595 句柄，可以完成数码管实例的初始化。比如：

当完成初始化后，可使用通用数码管接口操作显示器编号为0 的数码管设备。基于模块化编程思想，将初始化相关的实例、实例信息等的定义存放到数码管的配置文件中，将相关内容新增到am_hwconf_miniport_view.c 文件中，同时,将实例初始化函数的声明新增到am_hwconf_miniport_view.h 文件中，详见程序清单7.52 和程序清单7.53。

程序清单7.52 数码管实例初始化函数实现（am_hwconf_miniport_view.c）

程序清单7.53 am_hwconf_miniport_view.h 文件更新

后续只需使用无参数的实例初始化函数，即可执行以下语句完成数码管实例的初始化：

当完成初始化后，可调用通用数码管接口操作显示器编号为0 的数码管，运行如程序清单7.47 所示的倒计时程序，检验能否达到预期的效果，主程序详见程序清单7.54。

程序清单7.54 运行倒计时应用程序的主程序