串口指令的介绍和用法

• 串口指令：串口屏内置的一套固定协议，也可以叫三易协议，以ASCII码方式发送给串口屏，用于用户端直接使用控制屏幕，串口屏内不用写数据解析脚本。

• 脚本代码：串口屏模块内部脚本，解析、计算数据，控制页面控件，以及发送数据给用户。

使用方式的区别：左边为串口指令，右边为脚本代码

注意

• 串口指令由用户端MCU直接发送去控制串口屏，脚本是运行于串口屏模块内部的代码，用于处理内部各种逻辑；

• 串口指令不能当作脚本写在串口屏的事件代码中；

• 绝大部分指令，只对串口屏发送有效，VP上位机模拟无效；

• 连接串口屏时，注意接4Pin座子串口而不是Type-C口，Type-C口只能用于下载工程文件，不能用于通信；

1. 串口屏信息查询指令：version

• 此串口指令用于查询串口屏的基础软硬件信息；VP模拟发送无效果；

  

2. 查看所有串口指令 ：help

• 此指令用于返回所有串口指令；VP上位机发送有效；

• 发送格式：help + 回车换行

指令名	功能	指令返回
help	回传所有可用串口指令	help - 返回所有指令 page - 翻页 wset - 设置控件属性值 wget - 获取控件属性值 sset - 设置系统变量值 sget - 获取系统变量值 event - 触发控件的脚本事件 click - 点击控件 adjust - 触摸校准 factory - 恢复出厂 addt - 曲线数据透传 pisx - 绘点(已弃用) version - 读取串口屏软硬件信息 reset - 屏幕复位

3. 页面跳转指令 ：page

指令名	功能	参数及举例
page	页面跳转	page name/id + 回车换行 参数： 页面名称/页面ID 举例： 跳转到页面“main”，页面”main”的id为 0，则命令为：page main 或者 page 0 回传数据：参看后面通讯指令返回值介绍 注：只有此命令可以使用ID号来跳转。

4. 控件属性设置指令 ：wset

指令名	功能	参数及举例
wset	设置页面以及控件的属性值	wset name value + 回车换行 参数：页面\控件名称·属性名称 属性值。 举例：wset text1.txt “明天会更好” //设置当前显示页面的文本控件text1的txt属性为“明天会更好” wset main.text1.txt “明天会更好” //设置页面‘main’中文本控件“text1”的“txt”为“明天会更好” wset num1.val 100 //设置当前页面数字控件num1的val属性为100 回传数据: 执行结果。参看后面通讯指令返回值介绍。

说明：

页面/控件名称是带有可查找路径的名称，要设置页面的属性，则用“wset 页面名称.属性名称”，

如：wset main.bgColor 0xFFFF0000 //设置页面main的背景颜色为红色

wset main.num1.val 123 //设置页面main中整数控件num1的当前值为123

wset numf1.valf 3.14 //设置浮点数控件numf1的值为3.14

wset text1.txt "ABC123" //设置文本控件text1的显示为"ABC123"

注意：字符串类型需要用英文双引号括起来。包含中文时，注意串口屏工程的编码设置（工具->项目设置），需和发送端的字符编码一致。如：VP中字符编码选择GBK，那么用户发送的字符串编码也得是GBK。

5. 控件属性值获取指令 : wget

指令名	功能	参数及举例
wget	取得页面以及控件的属性值	wget name + 回车换行 参数：页面\控件名称·属性名称。 举例：wget text1.txt//读取当前页面文本控件text1的txt属性 wget main.text1.txt //读取页面main中的文本控件text1的txt属性 回传: 属性值。参看后面通讯指令返回值介绍。

说明：

页面\控件名称是带有可查找路径的名称，如果要读取页面的属性，则用“wget 页面名称.属性名称”，

如：wget main.name //获取main页面的页名称（读出来是字符串形类型，可赋给文本控件打印显示）

wget page1.numf1.valf //获取page1页面的浮点数控件numf1的浮点数值

返回的属性值有三种类型，整数，小数，字符串，整数和小数都用十六进制码表示；中英文字符串，返回中英文的ascii码值或者区位码值，十六进制表示。

注意串口屏工程的编码设置（工具->项目设置），需和发送端的字符编码一致。如：VP中字符编码选择GBK，那么用户发送的字符串编码也得是GBK。

6. 设置系统变量 : sset

指令名	功能	参数及举例
sset	设置系统变量	sset name value + 回车换行 参数：系统变量名称 系统变量值（全部为整数类型）。 举例：设置系统亮度为100 。 命令：sset sys_light 100 回传数据: 执行结果。参看后面通讯指令返回值介绍。 说明：sys_light = 100；也是设置亮度为100，但只能在脚本中使用。

7. 设置系统变量 : sget

指令名	功能	参数及举例
sget	读取系统变量的值	sget name + 回车换行 参数：系统变量名称。 举例：获取系统的亮度。 命令：sget sys_light 回传数据: 系统变量值。参看后面通讯指令返回值介绍。 说明：num1.val = sys_lightd;读取亮度给整数控件num1显示，但只能在脚本中使用。

8. 事件触发 ：event

指令名	功能	参数及举例
event	事件触发	event name value + 回车换行 name ：控件名称，支持 按钮，触摸热区，双态按钮。val：触发类型值：1 按下事件，2 弹起事件。 举例：event button0 1 //触发按钮button0的按下事件。

说明： 此指令可以触发按钮控件，触摸热区控件，双态按钮控件的按下、弹起的处理脚本。

event timer 1 //触发定时器脚本，会立即执行定时器脚本，定时器的interval设置（触发事件的间隔时间）将无效。

9. 模拟点击 ：click

指令名	功能	参数及举例
click	模拟点击事件	click name + 回车换行 参数：name ：控件名称，支持 按钮，触摸热区，双态按钮。 举例：click button0 //模拟按钮button0被按下。 发送此指令按下按钮后，就等于模拟做了按下弹起动作，按钮会执行按下和弹起里面的脚本事件。

说明：

此指令可以模拟按下按钮控件，触摸热区控件，双态按钮控件。

方便没有触摸屏时，用户使用物理按键操作串口屏模组实现点击触摸效果。

10. 触摸校准&恢复出厂 ：adjust & factory

指令名	功能	参数及举例
adjust	触发触屏校准功能	adjust + 回车换行 参数：无 注意：进入触屏校准页面后，需手动触屏校准完才退出。 此指令VP编辑软件模拟无效。 电容屏无需校准操作。
factory	恢复出厂状态	factory + 回车换行 参数：无 注意：此命令会擦除用户工程。对固件无影响。 如果需要重新下载串口屏工程，请重新上电下载。 此指令VP编辑软件模拟无效。

11. 曲线数据透传 ：addt

指令名	功能	参数及举例
addt	曲线控件数据透传指令 该指令参数使用16进制数据 不需要结束符回车换行\r\n(0x0D 0x0A)	命令格式： [0~3] 指令名addt，即 0x61 0x64 0x64 0x74 [4] 页ID [5] 控件ID [6] 通道号0~2，一个曲线控件最多3个通道 [7~8] 数据字节字节数N，小端模式。例如100个char型数据，十六进制为0x0064，命令中为64 00。 注意曲线控件的属性numType，char类型：1个字节表示一个点；short类型：2个字节表示一个点；int、float类型：4个字节表示一个点。 [9~11] 备用。填00 00 00即可。 [12~12+N] 数据。可以分为4个类型：int（4字节） short（2字节） char（1字节） float（4字节），在串口屏工程中曲线控件属性中设置，组织传输数据时，要和属性设置一致。

举例：

设置0通道byte类型10个点：61 64 64 74 00 04 00 0A 00 00 00 00 01 02 04 06 08 0A 0C 0E 10 12

byte类型，一个字节表示一个点

设置0通道int类型3个点：61 64 64 74 00 04 00 0C 00 00 00 00 01 00 00 00 02 00 00 00 03 00 00 00<

int 类型，4个字节表示一个点，小端模式，这里三个点分别是0x00000001,0x00000002,0x00000003

设置0通道float类型3个点：61 64 64 74 00 04 00 0C 00 00 00 00 9a 99 99 3F 9A 99 19 40 66 66 66 40

float类型，4个字节表示一个点，小端模式，这里三个点分别是1.2 ， 2.4 ， 3.6

12. 显示点阵 ：pisx（已弃用）

指令名	功能	参数及举例
pisx	显示点阵数据	参数介绍： [0~3]指令名pisx，即 0x70 0x69 0x78 0x73 [4-5] 起始横坐标 [6-7] 起始竖坐标 [8]单个字模宽度 [9]单个字模高度 [10-12]颜色，小端模式，如红色0xFF0000， [11]00， [12]00， [13]FF [13-14]字模数据字节数 [15-N]字模数据，1bit对应一个像素点 取模说明：逐行式，从第一行开始向右每取8个点作为一个字节，如果最后不足8个点就补满8位。 取模顺序是从高到低，即第一个点作为最高位

说明：

此功能实现了客户想显示一些字库中没有特殊字符或者单色图片，显示时需要用户实时发送，

例如 笑脸等用户自定义有个性的图标。

举例： 70 69 78 73 命令码 | 00 00 起始横坐标 | 0A 00 起始竖坐标 | 10 字模宽度16 | 10 字模高度16

00 00 FF 颜色0xFF0000，红色 |20 00 字模字节数32

08 80 08 80 08 80 11 FE 11 02 32 04 34 20 50 20 91 28 11 24 12 24 12 22 14 22 10 20 10 A0 10 40 字模数据”你”，16*16，宋体，不加粗，不斜体

注意：该命令已弃用，建议使用图片或者其他控件，显示特殊字符。

13. 复位屏幕 ：reset

指令名	功能	参数及举例
reset	复位屏幕	reset 1 + 回车换行 参数：1 举例：reset 1

说明：

此指令可以模拟屏幕断电重启。

通过串口发送指令复位，无需断电也可重启复位串口屏。

此指令对VP编辑软件无效。

14. 通讯指令返回值介绍1

	说明
条件	只有当系统变量bkcmd为非0的时候才会返回指令执行成功或者失败数据。
格式	返回指令格式为命令码(1字节)+参数(长度随命令码而不同)+结束符(2字节，\r\n)
数据	所有指令名以及参数全部16进制数据，非ASCII数据，便于软件解析。

15. 通讯指令返回值介绍2

命令码	含义	格式	参数说明
0x00	指令执行结果	执行结果代码+返回数据+结束符（\r\n）	执行结果代码：1字节 0x00 指令执行成功 0x01 命令码无效（指令第一个字符串无效） 0x02 指令参数1无效（指令第二个字符串无效） 0x03 指令参数2无效（指令第三个字符串无效） 0x04 指令参数3无效（指令第四个字符串无效） 0x05 指令参数4无效（指令第五个字符串无效） 0x06 指令参数5无效（指令第六个字符串无效） 0x07 指令参数个数错误 0x08 串口接收超时
0x01	整数返回	0x01+4字节整数+结束符	4字节整数：4字节小端模式存储，低字节在前
0x02	小数返回	0x02+4字节小数+结束符	4字节小数：4字节小端模式存储，低字节在前
0x03	字符串返回	0x03+字符串+结束符	字符串：GBK编码

说明：

如果客户发送的指令有错，例如命令码拼写错误，属性名称拼写错误等，造成串口屏不能解析，将返回不同的错误码，方便客户查错。

只有当系统变量bkcmd为非0的时候才会返回指令执行成功或者失败数据。

这个命令提供了一种客户的调试命令的方式，大部分情况下，在调试完毕后，都会把系统变量bkcmd置0，不会收到此命令。 举例：如果客户发送指令的命令码拼写错误，返回：“00010d0a”。解释：从左到右，00 表示返回的命令码，01表示命令码无效，0d表示 \r，0a表示 \n。

返回结果包括：命令执行情况和需要返回的数据。执行情况即执行结果，需要返回的数据主要是取串口屏控件属性的值。值的类型有整数，小数，字符串。

举例：获取按钮1的x坐标。发送指令“wget button1 x\r\n”，返回为：“01880000000d0a” 解释：01 表示返回值为整数；88000000表示位buttton1的 x坐标，低字节在前的格式；0D0A是命令结束符。

如果系统变量bkcmd没有设置为0，这个指令会接收到两个返回指令，“00000d0a”，和“01880000000d0a”，第一个指令表示命令执行成功，

第二个指令是用户需要的结果。如果系统变量bkcmd设置为0，则只返回第二个指令（默认不返回执行成功或失败）。