API接口

更新: 4/10/2025 字数: 0 字时长: 0 分钟

用户的设备通过Web API与平台实现无缝通信。以下文档详细列出了平台支持的所有API接口及其功能。

硬件操作执行API: POST /hardware/operation

描述：硬件操作API用来直接控制外设。
请求体格式
- 采用JSON格式进行数据封装与传输

json

{
  "event": "...",  /* 硬件操作类型，可选now/schedule/trigger。 */
  "actions": [    
    [硬件操作_1], [硬件操作_2], ..   /* 一个或多个硬件操作 */
  ],
  "return": [...]    /* 可选，将操作结果发送到指定地址 */
}

根据请求体的不同，返回值不同，请参考下面的说明。

硬件操作类型

当即执行事件(now)

当平台收到http请求里的event为now时，会立即执行按顺序执行硬件操作。格式如下：

json

{
  "event":"now",                             /* 必填 */
  "cycle": 重复次数,                          /* 可选 */
  "actions": [[硬件操作_1], [硬件操作_2], ...] /* 必填 */
}

参数	说明
event	now事件，在actions中定义的硬件操作会立即执行。
cycle	重复次数，该参数对应的值需要为正整数。硬件操作会以该次数重复执行。
actions	硬件操作。

提示

请将下面例子中的IP地址换成正确的地址。

例子：下面的例子将会翻转平台上绿色LED的状态，当平台收到该请求后会立即执行。

powershellcurl

Invoke-WebRequest -Uri "http://192.168.4.1/hardware/operation" -Method Post -ContentType "application/json" -Body '{
    "event": "now",
    "actions": [["gpio", "led", "output", 2]]
}'

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"now",
    "actions": [["gpio", "led", "output",2]]
  }'

定时执行事件(schedule)

当平台收到http请求里的event为schedule时，平台会在请求中的时间要求满足时按顺序执行硬件操作。格式如下：

json

{
  "event":"schedule",                        /* 必填 */
  "interval":重复间隔,                        /* interval和start至少填一个 */
  "start":起始时间,
  "repeat":事件次数,                          /* 可选，事件按间隔时间重复执行的次数 */
  "cycle": 重复次数,                          /* 可选 */
  "actions": [[硬件操作_1], [硬件操作_2], ...] /* 必填 */
}

参数	说明
event	schedule事件，在满足时间要求的条件下执行。
interval	重复间隔，必须有时间单位量，目前支持：'s'(秒), 'm'(分钟), 'h'(小时) 和 'd'(天)
start	起始时间，"YYYY/MM/DD HH:MM:SS" (比如: "2020/11/28 15:30:0")或 "YYYY/MM/DDTHH:MM:SS" ( ISO 8601标准)
repeat	事件次数，如果请求里没有该参数，事件会以重复间隔一直执行。如果为0或正整数，那当第一次执行结束后，会再执行该次数。
cycle	同上。
actions	同上。

例子：下面的例子将会从2024年1月1号下午两点开始每隔1分钟翻转平台上绿色LED的状态。

powershellcurl

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation" -Method Post -Headers "Content-Type: application/json" -Body '{
    "event":"schedule",
    "start":"2024/1/1T14:00:00",
    "interval":"1m",
    "actions": [["gpio", "led", "output",2]]
  }'

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"schedule",
    "start":"2024/1/1T14:00:00",
    "interval":"1m",
    "actions": [["gpio", "led", "output",2]]
  }'

引脚触发执行事件(trigger)

当平台收到http请求里的event为pinstate时，该事件定义当指定引脚的电压发生改变时，硬件操作会被触发。改变包括上升沿，下降沿或任何电压改变。格式如下：

json

{
  "event": "pinstate",                           /* 必填 */
  "pin": 引脚编号,                                /* 必填 */
  "trigger": 触发条件,                            /* 必填 */
  "debouce": 防抖毫秒,                            /* 可选 */
  "cycle": 重复次数,                              /* 可选 */
  "actions": [[硬件操作_1], [硬件操作_2], ...],    /* 选填 */
}

参数	说明
event	pinstate事件，当指定引脚满足某个信号条件时，执行硬件操作命令。
pin	引脚编号。有效的值是数字0-19分别代表排针引脚，字符串"left"代表左按钮，或字符串"right"代表有按钮。
trigger	触发条件，支持：change/rising/falling，change即在引脚发生电压改变时触发，rising即在引脚上升沿触发，falling即在引脚下降沿触发。
debounce	防抖毫秒值，抖动会导致信号在短时间内多次快速变化，从而被误认为是多次触发。该时间段内无论信号有几次满足触发条件，最终只会触发一次。
cycle	同上。
actions	同上。

提示

请注意对于参数pin,如果排针引脚为数字，无需加引号，比如: "pin": 10 或 "pin": 3

而左按钮和右按钮是字符串，需要加引号，比如: "pin":"left" 或 "pin":"right"

例子：下面的例子将会等待平台上右边按钮按下，当按下时会翻转绿色LED的状态。

powershellcurl

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation" -Method Post -Headers "Content-Type: application/json" -Body '{
    "event":"pinstate",
    "pin": "right",
    "trigger": "falling",
    "debounce": 400,
    "actions": [["gpio", "led", "output",2]]
  }'

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"pinstate",
    "pin": "right",
    "trigger": "falling",
    "debounce": 400,
    "actions": [["gpio", "led", "output",2]]
  }'

结果返回

当平台执行硬件操作后，除了HTTP返回外，可以选择将结果发送到指定的地址。可以用该功能将数据保存到Micro SD卡上，或是发送到指定服务器上。该功能可以和定时事件组合使用，实现数据收集。

将结果保存到Micro SD卡上

当硬件操作执行后，平台会将结果保存到Micro SD卡上的user文件夹中的指定文件中。该文件中除了记录硬件操作结果，还会记录发生该硬件操作的具体时间，供后面数据分析时使用。
格式:

json

["file", 文件名]

例子：下面的例子将会每隔10秒钟翻转平台上绿色LED的状态，并将结果写入到Micro卡上的/user/output.txt。

powershellcurl

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation" -Method Post -ContentType "application/json" -Body '{
    "event":"schedule",
    "interval":"10s",
    "actions": [["gpio", "led", "output",2]],
    "return": ["file", "output.txt"]
  }'

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "event":"schedule",
    "interval":"10s",
    "actions": [["gpio", "led", "output",2]],
    "return": ["file", "output.txt"]
  }'

保存在Micro卡上，/user/output.txt文件的内容为：

{"time":"2025-2-13 23:41:58","data":{"errorcode":0,"result":[[1]]}}
{"time":"2025-2-13 23:42:08","data":{"errorcode":0,"result":[[0]]}}
{"time":"2025-2-13 23:42:18","data":{"errorcode":0,"result":[[1]]}}
{"time":"2025-2-13 23:42:28","data":{"errorcode":0,"result":[[0]]}}
{"time":"2025-2-13 23:42:38","data":{"errorcode":0,"result":[[1]]}}
{"time":"2025-2-13 23:42:48","data":{"errorcode":0,"result":[[0]]}}
{"time":"2025-2-13 23:42:58","data":{"errorcode":0,"result":[[1]]}}
{"time":"2025-2-13 23:43:08","data":{"errorcode":0,"result":[[0]]}}
{"time":"2025-2-13 23:43:18","data":{"errorcode":0,"result":[[1]]}}
{"time":"2025-2-13 23:43:28","data":{"errorcode":0,"result":[[0]]}}
{"time":"2025-2-13 23:43:38","data":{"errorcode":0,"result":[[1]]}}
{"time":"2025-2-13 23:43:48","data":{"errorcode":0,"result":[[0]]}}
{"time":"2025-2-13 23:43:58","data":{"errorcode":0,"result":[[1]]}}
{"time":"2025-2-13 23:44:08","data":{"errorcode":0,"result":[[0]]}}
{"time":"2025-2-13 23:44:18","data":{"errorcode":0,"result":[[1]]}}

将结果通过TCP发送到指定服务器

当硬件操作执行后，平台会将结果通过TCP请求发送到指定的IP和端口。
格式：

json

["tcp", "IP地址:端口号"]

例子：下面的例子是一个now事件，当引脚0的电压翻转后，结果会通过tcp发送给IP地址192.168.1.110，端口5050：

json

{
  "event":"now",
  "actions": [["gpio", 0, "output", 2]],
  "return": ["tcp", "192.168.1.110:5050"]
}

将结果通过UDP发送到指定服务器

当硬件操作执行后，平台会将结果通过UDP请求发送到指定的IP和端口。
格式：

json

["udp", "IP地址:端口号"]

例子：下面的例子是一个schedule事件，每5秒会进行一个ADC采样，每次采样结束后，结果会通过udp的方式发送给IP地址192.168.1.110，端口8001：

json

{
  "event":"schedule",
  "interval": "5s",
  "actions": [["adc", 0, "3.1v"]],
  "return": ["udp", "192.168.1.110:8001"]
}

硬件操作

通用输入输出GPIO

设置 GPIO 为输入并读取当前电压

请求格式

["gpio", {引脚编号}, "input", {使用上拉电阻}]

参数	描述
引脚编号	GPIO 引脚，可选 0-19，或"led"代表绿色状态灯，或"left"代表左按钮，或"right"代表右按钮。
使用上拉电阻	是否使用上拉电阻，1 使用，0 使用

请求返回

[{引脚状态}]

参数	描述
引脚状态	1 表示引脚上的输入为高电平，0 表示引脚上输入为低电平

例子：以下的例子设置引脚 10 为输入，并且使用上拉电阻

{
  "event":"now",
  "actions": [["gpio", 10, "input", 1]]
}

{"event":"now","result":[[0]]}

设置 GPIO 为输出

请求格式

["gpio", {引脚编号}, "output", {模式}]

参数	描述
引脚编号	GPIO 引脚，可选 0-19
模式	0：输出低电平，1：输出高电平，2：高低电平反转

请求返回

[{引脚状态}]

参数	描述
引脚状态	引脚状态，1 表示引脚输出为高电平，0 表示引脚输出为低电平

例子：以下的例子设置引脚 10 输出低电平

{
  "event":"now",
  "actions": [["gpio", 10, "output", 0]]
}

{"event":"now","result":[[0]]}

curl命令python

#查询pnpm版本
pnpm -v

#查询yarn版本
yarn -v

脉宽调制PWM

PWM 可以在指定引脚输出特定频率和周期的方波，可以用来驱动电机，驱动蜂鸣器，调节 LED 灯的亮度等。最多可同时对三个引脚进行 PWM 输出。

请求格式

["pwm", {PWM编号}, {频率}, {输出时长}, {模式}, {PWM输出1引脚号}, {输出1占空比}, {PWM输出2引脚号}, {输出2占空比}, {PWM输出3引脚号}, {输出3占空比}]

参数	描述
PWM 编号	PWM 模块编号，可选 0-3
频率	频率，单位 Hz。比如需要在一秒钟产生 1000 个 PWM 方波，则该频率为 1000。最小值为 1，最大值为 50000。
输出时长	PWM 输出时长，单位秒
模式	如果等待该请求在输出时长结束后再返回，使用"sync"；如果不需要等待，立即返回，使用"async"。
PWM 输出 1 引脚号	输出 1 引脚编号。
PWM 输出 1 占空比	每个 PWM 周期会被等分 1024，占空比在 1-1023 之间。
PWM 输出 2 引脚号	输出 2 引脚编号。如果不需要输出 2 引脚，则不需要该参数。
PWM 输出 2 占空比	每个 PWM 周期会被等分 1024，占空比在 1-1023 之间。如果不需要输出 2 引脚，则不需要该参数。
PWM 输出 3 引脚号	输出 3 引脚编号。如果不需要输出 3 引脚，则不需要该参数。
PWM 输出 3 占空比	每个 PWM 周期会被等分 1024，占空比在 1-1023 之间。如果不需要输出 3 引脚，则不需要该参数。

请求返回

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

例子：以下的例子使用 PWM 模块 0，在引脚 0，1，2 上面输出频率为 1000Hz 的 PWM 方波。引脚 10 的占空比为 0.2(200/1024)，引脚 11 的占空比为 0.3(300/1024)，引脚 12 的占空比为 0.4(400/1024)。 PWM 的输出时长为 30 秒，且在 30 秒结束后再返回结果。

{
    "event":"now",
    "actions": [["pwm", 0, 1000, 30.0, "sync", 10, 200, 11, 300, 12, 400]]
}

{"event":"now","result":[["succeeded"]]}

高级输出 Advance Output

很多外设的协议依赖于宽度精确的信号，而高级输出操作可以设定逻辑 0 和逻辑 1 的时序。

高级输出配置

请求格式

["advance_output", {引脚编号}, "setup", {时间单位},
{逻辑值1}, {逻辑值1的周期}, {逻辑值1的高电平时长},{逻辑值2},{逻辑值2的周期}，{逻辑值2的高电平时长}]

参数	描述
引脚编号	GPIO 引脚，可选 0-19。
时间单位	可选毫秒 ms 或微秒 us。
逻辑值 1	选择 one 代表逻辑 1 或者 zero 代表逻辑 0。
逻辑值 1 的周期	该逻辑以指定时间单位的周期长度。
逻辑值 1 的高电平时长	该逻辑以指定时间单位的高电平时长。
逻辑值 2	选择 one 代表逻辑 1 或者 zero 代表逻辑 0。
逻辑值 2 的周期	该逻辑以指定时间单位的周期长度。
逻辑值 2 的高电平时长	该逻辑以指定时间单位的高电平时长。

请求返回

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

例子：以下的例子在引脚 15 输出的逻辑 1 定义为长度为 2.5 微秒，高电平 1.2 微秒。而逻辑 0 定义为长度 2.5 微秒，高电平为 0.5 微秒。

{
  "event":"now",
  "actions": [["advance_output",15,"setup","us","zero", 2.5,0.5, "one",2.5,1.2]]
}

{"event":"now","result":[["succeeded"]]}

高级输出启动

请求格式

["advance_output", {引脚编号}, "start", {一共的字节个数}, {字节数据}]

参数	描述
引脚编号	GPIO 引脚，可选 0-19。需要和高级输出配置中的引脚编号一致。
一共的字节个数	需要发送数据的字节数量。
字节数据	字节数据。

请求返回

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

例子：下面的例子根据之前高级输出配置，用高级输出在引脚 15 输出数据 146，147，148。146 的二进制为 10010010，高级输出会从最高位开始依次向最低位进行处理，即 1->0->0->1->0->0->1->0。当遇到 0 时，会在引脚 15 输出 0.5 微秒的高电平，接着 2.0 微秒的低电平，当遇到 1 时，会在引脚 15 输出 1.2 微秒的高电平，接着 1.3 微秒的低电平。当 146 处理完成后，会接下来处理 147，以此类推。

{
  "event":"now",
  "actions": [["advance_output",15,"start",3,146,147,148]]
}

{"event":"now","result":[["succeeded"]]}

捕捉 Capture

一些传感器通过不同长度的高低电平组合将信息发送给平台，这时平台需要准确地测量出不同电平的长度，捕捉操作测量出电平的长度。

一般请求格式

["capture",{引脚编号}, {数据最大数量}, {时间单位},{捕获条件},{捕捉时长}]

触发模式请求格式

一些传感器需要先输入一个特定宽度的脉冲信号，然后传感器返回一个脉冲信号。使用触发模式可以向传感器输入特定宽度的脉冲信号，然后测量输出的脉冲长度。

比如超声波测距传感器，需要先在传感器的输入引脚输入一个大于5微妙的脉冲，当传感器收到该脉冲后，会进行距离测量，距离信息会在输出引脚以脉冲的形式告诉发送端，距离越远返回脉冲的长度越长。这种情况可利用触发模式。

["capture",{引脚编号}, {数据最大数量}, {时间单位},{捕获条件},{捕捉时长},{触发模式},{触发引脚},{触发电平},{触发时间长度单位},{触发时间长度}]

参数	描述
引脚编号	可选 0-19。
数据最大数量	最多捕获的电平个数
时间单位	测量所用的时间单位。
捕获条件	选择上升沿，下降沿或者任意电平改变，进行时间记录。
捕捉时长	单位为秒，可为浮点数，比如0.1(100毫秒)。
触发模式(仅触发模式)	固定值为"trigger"
触发引脚(仅触发模式)	可选 0-19。
触发电平(仅触发模式)	可选"high","low"
触发时间长度单位(仅触发模式)	可选"us","ms","s"。
触发时间长度(仅触发模式)	正整数

请求返回

[{引脚初始状态}, {捕获时间}, ...]

参数	描述
引脚初始状态	如果初始值为低电平，则为 0，如果初始值为高电平，则为 1。
捕获时间	当引脚满足捕获条件，会记录从上一个捕获点到该捕获点的时长。如果之前没有捕获发生，则为捕获开始的时间到捕获点的时长。

例子：下面的例子在引脚 10 上进行捕获，捕获条件为上升沿，捕捉时长为 5 秒，最多可捕获 750 个上升沿。返回数据的单位为毫秒。

{
  "event":"now",
  "actions": [["capture",10,750,"ms","positive",5]]
}

返回：在下面的返回中，引脚 10 的初始状态为低电平。在捕获开始后，经过 2800 毫秒发生了一次上升沿。在第一次上升沿结束后的 755 毫秒后，又发生了一次上升沿。

{"event":"now","result":[[0,2800,755]]}

下面的例子在引脚 10 上进行捕获，捕获条件为任意电平改变，捕捉时长为 3 秒。返回数据的单位为毫秒。

{
  "event":"now",
  "actions": [["capture",10,"ms","change",3]]
}

返回：在下面的返回中，引脚 10 的初始状态为高电平。在捕获开始后，经过 1300 毫秒发生了下降沿。在下降沿后，经过 855 毫秒后发生了上升沿。又过了 1250 毫秒后发生了下降沿。

{"event":"now","result":[[1,1300,855,1250]]}

例子：下面的例子利用触发模式在引脚 0 先发送一个10微秒的高电平脉冲信号，然后等待传感器在引脚0上返回高电平的脉冲，并记录脉冲长度，捕捉时长为100毫秒(0.1秒)，最多可捕获5个变化信号。返回数据的单位为微秒。

{
  "event":"now",
  "actions": [["capture",0, 5, "us","change",0.1,"trigger",0,"high","us",10]]
}

返回：在下面的返回中，引脚0的初始状态为低电平，经过8053微秒后，变成了高电平，高电平的时长为11251微秒。则返回脉冲宽度为11251微秒。

{"event":"now","result":[[0,8053,11251]]}

模数转换 ADC

模数转换（Analog-to-Digial Converter）将电平经过采样，得到引脚上电平对应的数值。

ADC 单次采样

进行一次 ADC 采样。

请求格式

["adc", {引脚编号}, {参考电压}]

参数	描述
引脚编号	并不是所有引脚都支持 ADC，可选 0-8。
参考电压	可选 "3.1v"/"1.75v"/"1.25v"/"0.95v"。ADC 的输出数值需要和参考电压一块计算得到引脚上的电压值

请求返回

[{采样值}]

参数	描述
采样值	ADC 采样数值，精度是 12 位，即 0-4095。

例子以下的例子对引脚 1 进行单次采样，参考电压为 3.1V。采样并返回采样值:

{
  "event":"now",
  "actions": [["adc", 1, "3.1v"]]
}

{"event":"now","result":[[358]]}

ADC 采样值为 358，参考电压为 3.1V，所以得到引脚 1 上的电压为 358/4095*3.1，即 0.27V。

ADC 连续采样

很多时候需要 ADC 进行不间断地连续采样。平台支持连续采样，即平台会按指定的 ADC 采样频率，将连续采样的结果发送给指定地址。

注意指定的返回地址需要首先打开端口，否则平台无法将发送连续采样结果。

请求格式

["adc", {引脚编号}, {参考电压}, {采样频率}, {采样时长}, {返回结果方式}, {返回结果地址}"]

参数	描述
引脚编号	并不是所有引脚都支持 ADC，可选 0-8。
参考电压	可选 "3.1v"/"1.75v"/"1.25v"/"0.95v"。ADC 的输出数值需要和参考电压一块计算得到引脚上的电压值
采样频率	在一秒钟进行的采样次数，范围 700 到 10000。
采样时长	连续采样的总时长，单位秒。
返回结果方式	在连续采样进行中，平台会不断将采样结果返回到指定地址。目前只支持"udp"。
返回结果地址	需要提供 ip 地址和端口号。格式为"ip 地址:端口"

请求返回

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

当状态返回成功后，平台会立即开始 ADC 采样并放入缓存，当缓存存满后，后将缓存通过指定的方式和地址返回。返回格式为：

[{ADC引脚编号}，{采样值1}, {采样值2}, ...]

参数	描述
ADC 引脚编号	ADC0 到 ADC8。
采样值	会有多个采样值。

例子

以下的例子对引脚 1 进行连续采样，参考电压为 3.1V，采样频率为每秒 1500 次，采样时长 10 秒，将结果通过 UDP 的方式返回给 192.168.1.103 端口 5000。

{
  "event":"now",
  "actions": [["adc", 1, "3.1v",1500,10,"udp","192.168.1.103:5000"]]
}

{"event":"now","result":[["succeeded"]]}

同时平台会发送 UDP 数据到 IP 地址 192.168.1.103 的端口 5000。在 10 秒的采样时间里，一共收到了 200 个左右的 UDP 数据包，每个数据包的数据类似于：

["adc1",2598,2933,3004,2807,2693,2390,
2183,1647,1072,711,286,0,0,0,0,0,53,28,
153,233,595,781,953,1307,1919,2616,2875,
3018,2813,2637,2459,2103,1661,1057,743,
288,0,0,0,0,0,33,26,103,285,567,822,933,
1325,1904,2620,2947,2925,2873,2629,2461,
2094,1653,1097,697,334,0,0,0,0,0,21,50,
59,304,525,825,929,1263,1971,2535,2977,
2913,2880,2629,2413,2169,1596,1131,653,
342,0,0,0,0,52,0,92,53,302,585,775,1001,
1200,2009,2571,2953,2965,2823,2718,2352]

I2C

I2C 是一种常用的通信总线，由一个数据线和一个是时钟线组成。

I2C读数据

请求格式

["i2c", {I2C编号}, "read", {数据线引脚}, {时钟线引脚}, {速度}, {外设地址}, {寄存器地址1}, {寄存器地址2}, {读数据字节数量}]

参数	描述
I2C 编号	平台有一个 I2C 模块，这里的编号为 0。
数据线引脚	数据线对应的 GPIO 引脚。
时钟线引脚	时钟线对应的 GPIO 引脚。
速度	I2C 数据传输速度，单位 kHz。
外设地址	I2C 连接的外设的地址，在外设的数据手册里会写。
寄存器地址 1	寄存器地址的第一个字节，如果不需要可填写-1，在外设的数据手册里会有寄存器说明。
寄存器地址 2	寄存器地址的第二个字节，如果不需要可填写-1，在外设的数据手册里会有寄存器说明。
读数据字节数量	读取字节的数量。

请求返回

[{I2C数据}]

参数	描述
I2C 数据	返回 I2C 的读出的数据(十进制)，读取失败会返回 failed

例子下面的例子中，平台设置 I2C 的引脚 18 为 I2C 数据线，引脚 19 为 I2C 的时钟线，I2C 的数据为 400kHz，设备的地址是 80 或 0x50(十六进制)，无寄存器地址。从 I2C 连接的设备中读出 10 字节的数据。

["i2c", 0, "read", 18, 19, 400, 80, -1, -1, 10]

{"event":"now","result":[[30,31,32,33,34,35,36,37,38,39]]}

I2C 写数据

请求格式

["i2c", {I2C编号}, "write", {数据线引脚}, {时钟线引脚}, {速度}, {外设地址}, {寄存器地址1}, {寄存器地址2}, {写数据字节数量}, {写入数据}]

参数	描述
I2C 编号	平台有一个 I2C 模块，这里的编号为 0。
数据线引脚	数据线对应的 GPIO 引脚。
时钟线引脚	时钟线对应的 GPIO 引脚。
速度	I2C 数据传输速度，单位 kHz。
外设地址	I2C 连接的外设的地址，在外设的数据手册里会写。
寄存器地址 1	寄存器地址的第一个字节，如果不需要可填写-1，在外设的数据手册里会有寄存器说明。
寄存器地址 2	寄存器地址的第二个字节，如果不需要可填写-1，在外设的数据手册里会有寄存器说明。
写数据字节数量	写入的字节数量。
写入数据	十进制数据

请求返回

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

例子下面的例子中，平台设置 I2C 的引脚 18 为 I2C 数据线，引脚 19 为 I2C 的时钟线，I2C 的数据为 400kHz，设备的地址是 80 或 0x50(十六进制)，无寄存器地址。向 I2C 连接的设备写入 10 字节的数据。

["i2c", 0, "write", 18, 19, 400, 80, -1, -1, 10, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

{"event":"now","result":[[“succeeded]]}

SPI

SPI 也是一种常用的通信总线，它一般由一个时钟线，一个主输出(MOSI)线，一个从输出(MISO)线和一个片选(CS)线组成。 SPI可以全双工通信，对于主设备来说，可以从MOSI线输出数据，同时从MISO线接收数据。

请求格式

["spi", {SPI编号}, {主输出引脚} {从输出引脚}, {时钟引脚}, {片选引脚}, {速度}, {模式}, {接收跳过的字节数量}, {接收的字节数量}, {发送的字节数量}, {发送字节数据}]

参数	描述
SPI 编号	平台有一个 SPI 模块，这里的编号为 0。
主输出引脚	MOSI 的引脚号。
从输出引脚	MISO 的引脚号，如果不涉及从输出引脚，可填-1。
时钟引脚	时钟引脚号。
片选引脚	片选引脚号，如果不涉及片选引脚，可填-1。
速度	SPI 速度，单位 kHz。
模式	SPI 极性与相位选择。
接收跳过的字节数量	SPI 跳过该字节数量，然后进行数据接收。
接收的字节数量	SPI 接受的字节数量。
发送的字节数量	SPI 发送的字节数量，可为 0。
发送字节数据	SPI 发送的字节的十进制数据。

请求返回

如果接收的字节数量为 0。

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

如果接收的字节数量大于 0

[{SPI数据}]

参数	描述
SPI 数据	返回 SPI 的读出的数据(十进制)，读取失败会返回 failed

例子以下例子设置 SPI 的主输出为引脚 18，从输出为引脚 19，时钟是引脚 16，片选用引脚 17，用每秒 500kHz 的速率，用 SPI 模式 0，发送十进制 51 到从设备。对于主设备的接收端，会跳过一个字节，然后接收 4 个字节的数据：

{
  "event":"now",
  "actions": [["spi", 0, 18, 19, 16, 17, 500, 0, 1, 4, 1, 51]]
}

{"event":"now","result":[[0,0,0,0]]}

以下例子设置 SPI 的主输出为引脚 0，从输出为引脚 1，时钟是引脚 2，片选用引脚 3，用每秒 1MHz 的速率，用 SPI 模式 0，发送十进制 23, 24, 25 到从设备。对于主设备的接收端，会跳过一个字节，然后接收 3 个字节的数据：

{
  "event":"now",
  "actions": [["spi", 0, 0, 1, 2, 3, 500, 0, 1, 3, 3, 23, 24, 25]]
}

{"event":"now","result":[[100, 140, 145]]}

UART

和 SPI 类似，UART 也是一种常用的通信总线。UART 需要一个发送线(TX)和一个接收线(RX)。但 UART 并不需要时钟线，发送方和接收方根据已经定义好的速度进行通信。

请求格式

["uart", {UART编号}, {发送引脚}, {接收引脚}, {速度}, {奇偶校验位选择}, {停止位选择}, {每个数据单元长度}, {接收等待时间}, {接收的字节数量}, {发送的字节数量}, {发送字节数据}]

参数	描述
UART 编号	平台有一个 3 个 UART 模块，这里的编号可以选择 0,1,2。
发送引脚	TX 引脚号。
接收引脚	RX 引脚号。
速度	可以选择三个波特率，"9.6k"/"38.4k"/"115.2k"
奇偶校验位选择	可以选择不使用奇偶校验或奇校验或偶校验，"disabled"/"even"/"odd"
停止位选择	选择 1 或者 2。
每个数据单元长度	一次发送的位数量，可以选择 5/6/7/8。
接收等待时间	如果接收的字节数量大于 0，uart 会等待接收端发回数据。这里定义最长的等待时间。单位为秒。
接收的字节数量	UART 接受的字节数量。
发送的字节数量	UART 发送的字节数量，可为 0。
发送字节数据	UART 发送的字节的十进制数据。

请求返回

如果接收的字节数量为 0。

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

如果接收的字节数量大于 0

[{UART数据}]

参数	描述
UART 数据	返回 UART 的读出的数据(十进制)，读取失败会返回 failed

例子以下例子展示用 UART 模块 0，将引脚 5 设置为发送端，引脚 6 设置为接收端，用 115200 的波特率，发送 1，2，3，4 到接收端，并等待 10 个字节的返回，最长等待 3 秒。

{
  "event":"now",
  "actions": [["uart", 0, 5, 6, "115.2k", "disabled", 1, 8, 3, 10, 4, 1, 2, 3, 4]]
}

{"event":"now","result":[[20,24,54,20,17,51,34,56,31,10]]}

延迟

可以通过延迟操作进行精确的定时，比如产生一个宽度为 100us 的方波，或是在某两个硬件操作之间进行一定时间的等待。

请求格式

["delay", {编号}, {延迟时间单位}, {延迟时间值}]

参数	描述
编号	可为任意 0-255 的正整数
延迟时间单位	选择秒(s)/毫秒(ms)/微秒(us)之一
延迟时间值	延迟时间，最小值为 1,最大值为 65535

请求返回

[{状态}]

参数	描述
状态	成功为 suceeded,失败为 failed

说明

延迟操作通常用在硬件操作之间，由于每个硬件操作需要处理时间，实际的延迟时间大约比请求中指定的延迟多 70 微秒。如果需要精确的延迟，推荐用示波器确定。

例子：以下的例子设置将引脚 10 拉到，等待 30 微秒，然后在拉低。即产生一个方波。请注意，由于硬件操作本身需要时间处理，这里实际的方波宽度大概为 100 微秒

{
  "event":"now",
  "actions": [["gpio", 10, "output", 1],["delay",0,"us",30].["gpio",10,"output",0]]
}

{"event":"now","result":[[1],["succeeded"],[0]]}

硬件操作获取API: GET /hardware/operation

描述：该API返回目前平台里的定时事件和触发事件。
不需要请求体
返回值为JSON数组包含平台目前的定时事件和引脚触发事件的信息。

例子：下面的例子假设平台有一个定时事件，一个引脚触发事件。利用获得硬件操作API得到它们的详细信息。

powershellcurl

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation" -Method Get

curl --location --request GET "192.168.4.1/hardware/operation"

json

/* 返回 */
 [{"event":"schedule","interval":"10s"},{"event":"pinstate","pin":"right","trigger":"falling"}]

硬件操作删除API: DELETE /hardware/operation?id=参数

描述：该API可将平台里的某个定时事件或触发事件删除
URL参数：id为获取硬件操作API返回JSON数组的序号。
不需要请求体
返回值为JSON格式表示是否执行成功。

例子：下面的例子根据上面JSON返回值（即平台有一个定时事件，一个引脚触发事件），继而删除引脚触发事件。

提示

上面的JSON返回值，定时事件的序号为0，引脚触发事件的序号为1。所以删除引脚触发事件的id为1。

powershellcurl

Invoke-WebRequest -Uri "192.168.4.1/hardware/operation?id=1" -Method Delete

curl --location --request DELETE "192.168.4.1/hardware/operation?id=1"

json

/* 返回 */
{"errorcode": 0}

系统状态API: GET /hardware/status

描述：获取当前系统状态
不需要请求体
返回值为JSON数组表示系统状态。
- 1 = 系统时间未设置
- 2 = 电源不支持TypeC PD协议
- 3 = 电源支持TypeC PD协议，但所需的电压该电源不支持
- 4 = 请求连接的路由器不存在
- 5 = 连接路由器密码错误
- 6 = Micro SD卡加载错误或未发现Micro SD卡
- 7 = 缺少配置文件
- 8 = 缺少前端文件
- 9 = 版本错误

例子：下面的例子获得当前系统状态。

powershellcurl

Invoke-WebRequest -Uri "192.168.4.1/hardware/status" -Method Get

curl --location --request Get "192.168.4.1/hardware/status"

json

/* 返回：系统状态正常 */
{"status":[]}

/* 返回：系统未设置时间， Micro SD卡加载失败*/
{"status":[1, 6]}

系统配置读取API: GET /hardware/config

描述：获取当前系统配置信息
不需要请求体
返回值为JSON数组表示系统配置信息。

例子：下面的例子将会得到系统的配置信息。

powershellcurl

Invoke-WebRequest -Uri "http://192.168.4.1/hardware/config" -Method Get

curl --location --request GET "192.168.4.1/hardware/config"

json

{
  "timedate": "2025-2-13T21:28:04",   /* 时间 */
  "mode": "station",                  /* 平台连接模式 */
  "ssid": "TP-LINK",                  /* SSID */
  "password": "abc123xyz",            /* SSID的密码 */
  "voltage": 5,                       /* TypeC PD输出电压 */
  "mdns": "testplatform",             /* mdns名称 */
  "fwver": "V1-0-1",                  /* 固件版本号 */
  "hwver": "V1-3",                    /* 硬件版本号 */
  "state": "normal",                  /* 系统状态 */
  "tmzoneoffset": -8                  /* 时区信息 */
}

系统配置修改API: POST /hardware/config

描述：获取当前系统配置信息
请求体为JSON格式，包含配置信息的键-值

json

{
  "key": "value",
  ...
}

返回值为JSON格式表示是否执行成功。

提示

不支持修改固件版本号，硬件版本号和系统状态

例子：下面的例子设置平台的TypeC PD输出电压为20V，时区信息为+3区。

powershellcurl

Invoke-WebRequest -Uri "http://192.168.4.1/hardware/config" -Method Post -ContentType "application/json" -Body '{
    "voltage": 20,
    "tmzoneoffset: 3
}'

curl --location --request POST "192.168.4.1/hardware/operation" --header 'Content-Type: application/json' --data-raw '{
    "voltage": 20,
    "tmzoneoffset": 3
}'

返回值

json

{"errorcode": 0}

系统重启API: POST /hardware/restart

描述：系统重启
不需要请求体
返回值为JSON数组表示是否成功。

例子：

powershellcurl

Invoke-WebRequest -Uri "http://192.168.4.1/hardware/restart" -Method Post

curl --location --request POST "192.168.4.1/hardware/restart"

返回值

json

{"errorcode":0}

错误码


INVALID_HARDWARE_ACTION(无效的硬件操作指令) = 1
INVALID_EVENT_WORD(无效的event值) = 2
INVALID_ACTIONS_WORD(无效的actions值) = 3
INVALID_RETURN_WORD(无效的return值) = 4
INVALID_START_WORD(无效的start值) = 5
INVALID_END_WORD(无效的end值) = 6
INVALID_REPEAT_WORD(无效的repeat值) = 7
INVALID_INTERVAL_WORD(无效的interval值) = 8
INVALID_PIN_WORD(无效的pin值) = 9
INVALID_TRIGGER_WORD(无效的trigger值) = 10
INVALID_DEBOUNCE_WORD(无效的debounce值) = 11
INVALID_CYCLE_WORD(无效的cycle值) = 12
INVALID_FILENAME(无效的文件名) = 13
FILENAME_EXCEEDS_LIMIT(文件名超过长度限制) = 14
INVALID_POST_REQUEST(无效的POST请求) = 15

INVALID_JSON_REQUEST(无效的JSON请求) = 30
REQUEST_LEN_ZERO(请求长度为0) = 31
REQUEST_LEN_EXCEEDS_LIMIT(请求长度超过最大限制) = 32
RESPONSE_LEN_EXCEEDS_LIMIT(返回长度超过最大限制) = 33
RESOURCE_NOT_ENOUGH(平台资源不够) = 34
RESOURCE_BUSY(平台资源忙碌) = 35
RETURN_BAD_CONNECTION(平台资源忙碌) = 35
CONSTRUCT_RESPONSE_FAIL(返回连接失败) = 36
CONSTRUCT_RESPONSE_FAIL(构建返回包失败) = 37
SCHEDULE_EVENT_NO_SLOT(没有足够的资源存放定时事件) = 38
PINSTATE_EVENT_NO_SLOT(没有足够的资源存放引脚触发事件) = 39
INVALID_URI_PARAM(无效的请求参数) = 40
SCHEDULE_EVENT_INVALID_REQUEST(无效的定时事件) = 41
TIMEDATE_NOTSET(设置时间失败) = 42
TIMEDATE_RETRIEVE_FAILED(读取时间失败) = 43
TIMEDATE_PARSE_FAILED(时间格式错误) = 44
CREATE_FILE_FAILED(创建文件失败) = 45
RECEIVE_FILE_FAILED(接收文件失败) = 46
WRITE_FILE_FAILED(写入文件失败) = 47
HTTP_POST_BAD_STATE(保存文件状态错误) = 48
OPEN_FILE_FAILED(打开文件失败) = 49
SD_MOUNT_FAILED(Micro SD卡加载失败) = 50

/* GPIO */
GPIO_INDEX_OUT_OF_RANGE(GPIO序号超过限制) = 100
GPIO_CMD_INVALID(无效的GPIO请求) = 101
GPIO_DRIVER_FAILURE(GPIO驱动错误) = 102

/* PWM */
PWM_INDEX_OUT_OF_RANG(pwm序号超过限制)E  = 200
PWM_CMD_INVALID(无效的pwm请求) = 201
PWM_DRIVER_FAILURE(pwm驱动错误) = 202

/* i2c */
I2C_INDEX_OUT_OF_RANGE(i2c序号超过限制) = 300
I2C_CMD_INVALID(无效的i2c请求) = 301
I2C_DRIVER_FAILURE(i2c驱动错误) = 302

/* spi */
SPI_INDEX_OUT_OF_RANGE(spi序号超过限制) = 400
SPI_CMD_INVALID(无效的spi请求) = 401
SPI_DRIVER_FAILURE(spi驱动错误) = 402

/* uart */
UART_INDEX_OUT_OF_RANGE(uart序号超过限制) = 500
UART_CMD_INVALID(无效的uart请求) = 501
UART_DRIVER_FAILURE(uart驱动错误) = 502
UART_RECEIVE_NOTHING(uart在指定时间未收到任何数据) = 503

/* adc */
ADC_INDEX_OUT_OF_RANGE(adc序号超过限制) = 600
ADC_CMD_INVALID(无效的adc请求) = 601
ADC_DRIVER_FAILURE(adc驱动错误) = 602
ADC_MISS_RETURN_INFO(adc请求缺少返回信息) = 603

/* capture */
CAPTURE_INDEX_OUT_OF_RANGE(capture序号超过限制) = 600
CAPTURE_CMD_INVALID(无效的capture请求) = 601
CAPTURE_DRIVER_FAILURE(capture驱动错误) = 602

/* advance output */
ADV_OUTPUT_INDEX_OUT_OF_RANGE(advance output序号超过限制) = 600
ADV_OUTPUT_CMD_INVALID(无效的advance output请求) = 601
ADV_OUTPUT_DRIVER_FAILURE(advance output驱动错误) = 602

/* delay */
DELAY_INDEX_OUT_OF_RANGE(delay序号超过限制) = 600
DELAY_CMD_INVALID(无效的delay请求) = 601
DELAY_DRIVER_FAILURE(delay驱动错误) = 602

API接口 ​

硬件操作执行API: POST /hardware/operation ​

硬件操作类型 ​

当即执行事件(now) ​

定时执行事件(schedule) ​

引脚触发执行事件(trigger) ​

结果返回 ​

将结果保存到Micro SD卡上 ​

将结果通过TCP发送到指定服务器 ​

将结果通过UDP发送到指定服务器 ​

硬件操作 ​

通用输入输出GPIO ​

设置 GPIO 为输入并读取当前电压 ​

设置 GPIO 为输出 ​

脉宽调制PWM ​

高级输出 Advance Output ​

高级输出配置 ​

高级输出启动 ​

捕捉 Capture ​

模数转换 ADC ​

ADC 单次采样 ​

ADC 连续采样 ​

I2C ​

I2C读数据 ​

I2C 写数据 ​

SPI ​

UART ​

延迟 ​

硬件操作获取API: GET /hardware/operation ​

硬件操作删除API: DELETE /hardware/operation?id=参数 ​

系统状态API: GET /hardware/status ​

系统配置读取API: GET /hardware/config ​

系统配置修改API: POST /hardware/config ​

系统重启API: POST /hardware/restart ​

错误码 ​

API接口

硬件操作执行API: POST /hardware/operation

硬件操作类型

当即执行事件(now)

定时执行事件(schedule)

引脚触发执行事件(trigger)

结果返回

将结果保存到Micro SD卡上

将结果通过TCP发送到指定服务器

将结果通过UDP发送到指定服务器

硬件操作

通用输入输出GPIO

设置 GPIO 为输入并读取当前电压

设置 GPIO 为输出

脉宽调制PWM

高级输出 Advance Output

高级输出配置

高级输出启动

捕捉 Capture

模数转换 ADC

ADC 单次采样

ADC 连续采样

I2C

I2C读数据

I2C 写数据

SPI

UART

延迟

硬件操作获取API: GET /hardware/operation

硬件操作删除API: DELETE /hardware/operation?id=参数

系统状态API: GET /hardware/status

系统配置读取API: GET /hardware/config

系统配置修改API: POST /hardware/config

系统重启API: POST /hardware/restart

错误码