.. _api_decription: 指令集说明 ================= .. role:: blue :class: blue 0.术语 --------------------- - **attr**：表示控件属性、系统变量属性、自定义变量的名称 - **pagename**: 表示页面名 - **widname**: 表示控件名 - **id**: 表示页面id、控件id、资源id(音频、图片)。数值类型 - **str**: 表示常量字符串 1.page(页面切换) --------------------- **发送格式** ：page(pagename | id) - 参数说明： + pagename | id：页面名称或页面数值ID - 举例： + page(1):切换到ID为1的页面（不推荐此方法，工程编辑时可能会拖动页面调整页面顺序） + page(main):切换到页面名称为main的页面（推荐此方法） **返回格式** : - 无 .. hint:: - 脚本中，执行了page()指令，后续的代码将不会执行 - page()指令不能切换到屏保页面，会报“页面ID无效”警告 .. _get指令: 2.get(获取属性) --------------------- **发送格式** ：get(attr) - 参数说明： + attr: 可以为控件属性名称、系统变量名称、其他变量名称、常量数值 - 举例： + get(btn0.x): 获取控件btn0.x属性的值 + get(sys.bl): 获取系统变量sys.bl的值 + get(123) : 获取123 + get(btn0.txt) : 获取控件btn0的文本值，即字符串 **返回格式** : -getn:100 \ -gets:btntxt - 返回结果为数值型：-getn:100 - 返回结果为字符串型：-gets:btntxt 3.play(播放音乐) --------------------- **发送格式** ：play(str | id, mode) - 参数说明： + str | id: str字符串,如"/test.ATKA"（播放TF卡里面的资源）、id，如0（播放添加工程里ID为0音乐） + mode: 0-播放一遍 1-循环播放 - 举例： + play(0, 1) : 播放工程资源里面ID为0的音乐，循环播放 + play("/test.ATKA", 0) : 播放TF卡根目录下，test.ATKA音乐，播放一遍 **返回格式** : - 无 .. hint:: - play()指令可以直接播放音乐，无需页面添加音频控件 - 调用play()指令后，可调用系统变量sys.audio来控制播放和暂停 - 串口屏同一时刻仅支持播放一个音频（音频和视频共享） - 使用play()指令和页面添加音频控件播放的区别：:ref:`音频控件和play指令区别` 4.move(移动控件) --------------------- **发送格式** ：move(widname | id, x0, y0, x1, y1, time, mode) - 参数说明： + widname | id: 控件名或控件id + x0: 移动的起始坐标x + y0: 移动的起始坐标y + x1: 结束坐标x + y1: 结束坐标y + time: 移动时间（单位毫秒） + mode:移动方式，范围:0-5 ==== =========== 值 移动方式 ==== =========== 0 线性 1 缓入 2 缓出 3 缓入缓出 4 过冲 5 反弹 ==== =========== - 举例： + move(1, 10, 10, 100, 100, 300, 0) : 移动当前页面第1个控件，线性移动 + move(btn1, 10, 10, 100, 100, 300, 5) : 移动当前页面控件名为btn1的控件，反弹方式 **返回格式** : - 无 **说明**： - 只能移动当前页面的控件 - 页面、屏保、系统键盘等不能移动 5.click(激发控件事件) --------------------- **发送格式** : click(widname | id, event) - 参数说明： + widname | id: 控件名或控件id + event: 0-激活弹起事件 1-激活按下事件 - 举例： + click(1, 0) : 激活当前页面控件ID为1的弹起事件 + click(btn1, 1) : 激活当前页面控件名为btn1的控件的按下事件 **返回格式** : - 无 .. hint:: - 当前事件脚本，只允许调用不超过10次click指令 - click指令和其他指令不同，它先缓存指令，执行完当前事件脚本之后再依次执行click指令 - click不能激活自己，否则执行过程返回警告。因为click激活自己会造成死循环 6.vis(隐藏控件) --------------------- **发送格式** : vis(widname | id, state) - 参数说明： + arwidname | id: 控件名或控件id + state: 0-隐藏 1-显示 - 举例： + vis(1, 0) : 隐藏当前页面控件ID为1的控件 + vis(btn1, 1) : 激活当前页面控件名为btn1的控件 **返回格式** : - 无 .. _cadd: 7.cadd(曲线添加数据) ------------------------------- **发送格式** : cadd(widname | id, ch, value) - 参数说明： + arwidname | id: 控件名或控件id(仅支持曲线控件的名称，否则报错) + ch: 通道0-3 + value: 值 (0~255) - 举例： + cadd(chart0, 2, 100) : 给chart0曲线控件的通道2，添加一个数据，值为100 **返回格式** : - 无 .. _covx指令 : 8.covx(变量类型转换) ------------------------------- **发送格式** : covx(attr0, attr1, lenth, format) - 参数说明： + attr0: 源变量 + attr1: 目标变量 + lenth: 字符串的长度(0为自动长度，非0为固定长度) + format: 目前未使用,设为0即可 - 举例： + covx(h0.val, btn0.txt, 0, 0) : 将滑块控件h0的值，数值转换为字符串并赋值给btn0.txt + covx(btn0.txt, h0.val, 0, 0) : 将btn0.txt的数值字符串转换为数值，并赋值给h0.val **返回格式** : - 无 **说明** : 1. 源变量为数值型变量时，目标变量必须是字符串型变量。 2. 相反，源变量为字符串型时，目标变量必须是数值型。 9.reset(复位) ------------------------------- **发送格式** : reset() - 参数说明：无参数 - 举例： reset() : 复位屏幕 **返回格式** : - 无 10.ack(握手) ------------------------------- **发送格式** : ack() - 参数说明：无参数 - 举例： ack(): 和串口屏握手 **返回格式** : - -ack 11.rtcs(设置RTC时间) ------------------------------- **发送格式** : rtcs(year, month, mday, hour, min, sec) - 参数说明： + year: 年，设置范围2000-2099 + month: 月，范围1-12 + mday: 日，范围1-31 + hour: 时，范围0-23 + min: 分，范围0-59 + sec: 秒，范围0-59 - 举例： + rtcs(2022, 10, 20, 17, 20, 0) : 设置时间给RTC芯片，RTC控件时间使用该指令校准时间 **返回格式** : - 无 .. attention:: 输入的参数一定要在范围内，否则设置不成功！返回-war:131警告 12.beep(激活蜂鸣器) ------------------------------- **发送格式** : beep(time, frequency) - 参数说明： + time: 激活时间，单位毫秒 + frequency: 频率，单位hz - 举例： + beep(300, 1000) : 激活蜂鸣器300毫秒，频率1000hz **返回格式** : - 无 13.version(获取固件版本) ------------------------------- **发送格式** : version() - 参数说明：无参数 - 举例： + version() : 获取版本号，返回版本号字符串 **返回格式** : - -version:V1.2.9 .. _rand_ref: 14.randset(设置随机数范围) ------------------------------- **发送格式** : randset(min, max) - 参数说明：无参数 + min: 最小值, int32_t类型 + max: 最大值，int32_t类型 - 举例： + randset(0, 100) : 设置系统变量随机数（sys.rand）属性的范围，0-100。 **返回格式** : - 无 15.cclear(曲线清除数据) ------------------------------- **发送格式** : cclear(widname | id, ch) - 参数说明： + arwidname | id: 控件名或控件id(仅支持曲线控件的名称，否则报错) + ch: 通道0-3 - 举例： + cclear(chart0, 0) : 清除chart0曲线控件通道0的数据，即清除波形 **返回格式** : - 无 .. _caddt: 16.caddt(曲线透传添加数据) ------------------------------- **发送格式** : caddt(widname | id, ch, points) - 参数说明： + arwidname | id: 控件名或控件id(仅支持曲线控件的名称，否则报错) + ch: 通道0-3 + points: 透传的点数 范围：0-1024 - 举例： + caddt(chart0, 0, 100) // 设置设备串口进入透传状态，然后给chart0曲线控件通道0一次性添加100个点 **返回格式** : - -caddt:start // 表示设备已进入透传状态，用户可以开始发送波形数据 - -caddt:end // 设备退出透传状态（传输完成points个点，或5秒内设备没接收到数据） **说明** : 1. 发送caddt指令后，设备串口进入透传状态（不解析数据，直接将接收的数据发送给曲线控件的指定通道） 2. 当设备接收完points个点后或5秒内没接收到数据，设备串口退出透传状态。 3. 退出透传状态，设备返回：-caddt:end 17.prints(发送字符串数据) ------------------------------- **发送格式** ：prints("fmt", ...) // 用法和C语言printf一模一样 - 参数说明： + fmt: 格式化字符串(必须带双引号) + ...: 可变参数（最多支持9个参数） - 举例： + prints("123"): 发送字符串“123” + prints("b0.x=%d", b0.x) : 如b0.x=100，发送字符串“b0.x=100” + prints("str=%s", b0.txt.str) : 如b0.txt.str="Btn"，发送字符串“str=Btn” **返回格式** : - 发送：prints("123")， 返回：-prints:123 - 发送：prints("b0.x=%d", b0.x) 返回：-prints:b0.x=100 - 发送：prints("str=%s", b0.txt.str) 返回：-prints:str=Btn .. note:: 1. 用法和C语言printf一模一样,只不过可变参数仅支持9个 2. 注意参数类型和格式化类型一定要匹配！如：prints("%d", b0.txt.str),输出可能是0。 3. 此指令通常用在串口屏发送给设备，而非设备发给串口屏 18.printh(发送十六进制数据) ------------------------------- **发送格式** ：printh(hex) - 参数说明： + hex: 十六进制数据，如：aa ff 01 - 举例： + printh(aa ff 01): 发送十六进制数据： aa ff 01 **返回格式** : - 无 .. note:: 1. hex: aa ff 01。写法：必须是两位的十六进制格式，且每个数据之间间隔一个空格 2. hex: 最多可以发送256个数据 3. 此指令通常用在串口屏发送给设备，而非设备发给串口屏 19.get_sdsize(获取SD卡剩余空间) ------------------------------- **发送格式** get_sdsize() - 参数说明： + 无 - 举例： + get_sdsize(): 获取SD卡容量信息 **返回格式** : - -get_sdsize: remain = 2878996kb; // 获取SD 剩余空间，单位kb 注意: 1. 必需先插上了SD卡再上电，才能读到剩余空间，否则读出来是0kb。