GUI Composer 库用户指南¶

1. 引言¶

GUI Composer 工程示例展示了 LaunchPad 与可在 PC 上运行的可自定义 GUI 应用程序之间基于 UART 的数据交换。这些 GUI 可以完全按照您的自定义来显示、处理数据并控制固件的执行。这些 GUI 也可以安装到 Code Composer Studio 中，以辅助基本调式功能，同时为非专业的手动测试人员提供简化的用户界面。

MSPM0 SDK 包括为配合使用 GUI Composer 而在目标 MSP 器件上运行的软件示例。此外，此 SDK 还包括预制的 GUI，它可以导入到 GUI Composer 并可配合提供的软件示例直接轻松使用。

有关初始设置和运行示例应用程序的更多入门信息，请查看快速入门指南。

2. 架构/总体概览¶

下图显示了示例中不同层之间的关系。

HAL：从 GUI 发送和接收数据的驱动程序。当前使用器件 UART。
传输层协议：用于通过物理传输层传输数据的协议/编码方案。目前支持两种方案：JSON 和 MessagePack。
- JSON：使用 JSON 格式的字符串发送和接收数据
- MessagePack：使用 MessagePack 协议发送和接收数据
GUIComm API：提供的抽象层，独立于传输层。应用程序可以在不知晓底层协议的情况下调用这些 API。
应用程序：用户应用程序。提供的示例展示了应用程序层如何独立于传输层及其下方的 HAL 层。

3. 文件夹结构¶

MSPM0 SDK 的根目录下提供以下文件夹：

docs/middleware/gui_composer - 包含与 MSP GUI Composer 包相关的所有文档
examples/nortos//gui_composer - 包含所有代码示例以及应用程序和工程文件
source/ti/gui_composer - 包含可导入到终端应用程序的泛型/可重用源代码

4. 了解示例¶

4.1 在 MSP 上接收来自 GUI 的数据¶

以 tGUI_RxCmd 类型的结构接收 GUI 命令。main.c 文件中定义了此结构。

每一条都包含 GUI 命令及其各自的回调函数。

在上例中，bEnable 是从 GUI 接收的命令，在 GUI 中，bEnable 是绑定到小工具的变量名。GUICallback_boolEnable 是各自的回调函数。应用程序回调文件 callbacks_.c 中定义了这些回调函数。GUI_RXCommands[] 结构很容易修改，可根据需要为 GUI 增加或删除命令。

4.2 从 MSP 向 GUI 发送数据¶

可以在应用程序中使用 GUIComm.h 中列出的 API，以便轻松地将数据从 MSP 器件发送到 GUI，而不依赖于下面的传输层协议。GUIComm API 负责在选择的协议中对数据编码，并将数据发送到 GUI。

例如，应用程序中将调用以下函数：

GUIComm_sendBool("bEnable", STR_LEN_SEVEN, bEnableSwitch);

此 API 发送布尔变量 bEnableSwitch 中的值，以更新绑定到令牌 bEnable 的 GUI 小工具。STR_LEN_SEVEN 是发送的令牌的长度。

下图显示了一个按钮小工具的示例，其属性表明它绑定到令牌 bEnable。

4.2.1 支持的类型¶

GUIComm 函数支持以下数据类型：

ints
uints
bools
floats/doubles
- mpack 原生或通过使用 QMath/IQMath 库支持 floats/doubles
- json 仅可以通过使用 QMath/IQMath 库发送 floats/doubles

此外，支持 8、16、32 和 64 位的数据大小。

5. MessagePack 优化¶

mpack 库支持根据应用程序需求进行配置。在应用程序的 mpack.h 中可找到这些配置。

启用 MPACK_OPTIMIZE_FOR_SIZE 配置会在 mpack 解码器中开启优化，以通用性为代价减小 mpack 库的代码大小。启用优化时，用户可配置以下方面来减小代码大小：

解码器数据大小（解码器可以接收的数据大小）
解码器数据类型（解码器支持使用的数据类型）

通过减少允许的数据大小和数据类型数量，可以减小应用程序的大小。

默认情况下，禁用 MPACK_OPTIMIZE_FOR_SIZE。禁用 MPACK_OPTIMIZE_FOR_SIZE 时，会启用所有数据大小（8、16、32 和 64 位）和所有支持的数据类型（uints、ints、bools 和 arrays）。

5.1 配置解码器数据大小¶

用户可以配置 MPACK_DECODE_SIZE 宏组，以启用解码器可以接收的数据大小。例如，如果仅启用 MPACK_DECODE_SIZE_16_BITS，则从 GUI 接收的所有传入数据必须是 16 位。它不会识别以 8 位、32 位或 64 位发送的数据。此外，一次可启用不止一个 MPACK_DECODE_SIZE 宏。通过减少解码器预期的数据大小数量，可以减小应用程序的代码大小。

GUI Composer 默认会发送数据大小最小的数据，因此 GUI 必须修改为以特定数据大小发送所有数据。GUI 可以轻松修改，以完成此变更，更多详情参见 GUI 修改部分。

这些宏只影响 uints 和 ints，而不影响 maps、bools、strings 等其他数据类型。

启用 MPACK_OPTIMIZE_FOR_SIZE 时，默认启用 MPACK_DECODE_SIZE_16_BITS。

5.2 配置支持的数据类型¶

用户可以配置宏组，以启用解码器会识别的数据类型。例如，如果仅启用 MPACK_UINTS，则解码器只能识别来自 GUI 的 uint 数据。如果收到 int 或 bool 数据，则会导致错误。

启用 MPACK_OPTIMIZE_FOR_SIZE 时，应用程序默认支持 uints、ints 和 bools 类型。

5.3 GUI 修改¶

如前所述，mpack 库可以优化，将 mpack 解码器配置为仅支持特定的数据大小。为此，必须在 GUI 中进行更改，使得从 GUI 发出的所有 uint 和 int 数据都以特定数据大小发送出去。

要进行此更改，必须将包含必要代码更改的新文件 main.js. 添加到 GUI。预制的 GUI MSPM0_SimpleGUI_mpack_optimized 中将提供此文件和必要代码。

此修改将所有数据以 16 位 uint/ints 类型从 GUI 发送到器件。这样做可以减小器件上的代码大小，因为解码器只能接收 16 位数据。可在应用程序中完成此更改，方法是在应用程序的 mpack.h 中启用 MPACK_DECODE_SIZE_16_BITS，这会告知 MessagePack 解码器仅接收和解码 16 位数据。要发送其他数据大小，请在 main.js 文件中相应地修改 encodeIntegerBitsize。

6. 基准测试¶

6.1 代码大小¶

下表显示了 gc_simple_json 示例和 gc_simple_mpack 示例中某些 MSPM0 器件上的代码大小。此表的目的是比较传输层协议在总体代码大小上的差异，特别是 JSON、MessagePack（未优化）与针对 16 位解码优化的 MessagePack 之间的差异。代码示例是使用 TI Clang 在优化级别 -02 上编译的。

	gc_simple_json	gc_simple_mpack（MPack 未优化）	gc_simple_mpack（MPack 已针对 16 位解码优化）
LP_MSPM0G3507	6.73kB	4.02kB	3.68kB
LP_MSPM0L1306	6.73kB	3.88kB	3.54kB

6.2 消息大小¶

JSON 和 MessagePack 都对数据编码以便传输数据。下表比较了不同数据类型编码后的消息大小和每种协议下的数据大小。

要编码的数据	JSON 编码后的消息大小	MPack 编码后的消息大小
4294967295 (uint32)	10 字节	5 字节
65535 (uint16)	5 字节	3 字节
255 (uint8)	3 字节	2 字节
-2147483648 (int32)	11 字节	5 字节
-32768 (int16)	6 字节	3 字节
-128 (int8)	4 字节	2 字节
true (boolean)	4 字节	1 字节

7. 其他信息¶

有关 GUI Composer 的更多信息，请查看 GUI Composer 用户指南。