GL-S20 蓝牙配网接口¶
GL-S20提供两个GATT服务。
第一个是为了接收指令和消息，服务的UUID是000000FF-0000-1000-8000-00805F9B34FB，它包含一个特征值，特征值的UUID是0000FF01-0000-1000-8000-00805F9B34FB，该特征值的读写权限只有可写。
第二个是为了发送通知，如发送指令回复数据，服务的UUID是000000EE-0000-1000-8000-00805F9B34FB，它也只有一个特征值，特征值的UUID是0000EE01-0000-1000-8000-00805F9B34FB。该特征值的权限是可读可通知 (read | notify)。 使能了第二个服务的notify功能，才可以获取通知。
数据包格式¶
设备无论是从客户端接收指令还是响应执行结果，都需要遵循以下数据包格式。
它由七个部分组成：包头、版本号、包长度、滚动计数、CRC-16校验码、命令ID和数据段。
| 包头 | 版本号 | 包长度 | 滚动计数 | CRC-16校验码 | 命令ID | 数据段 |
|---|---|---|---|---|---|---|
| 1 byte | 1 byte | 2 byte | 1 byte | 2 byte | 1 byte | N byte |
| 无加密 | 基于AES-128加密 | |||||
- 包头
包头默认为0xFE。
- 版本号
版本号默认为0x01。
- 包长度
整个数据包的长度。
- 滚动计数
滚动计数的有效范围为0-255。在初始连接时，计数重置为零，并且后续数据包的计数值大于前一个。（包索引防止数据包粘连）
注意：发送第一个包时，计数字段应填写0x01。在那之后就自增一的滚动计数。
- CRC-16校验码
在完成包头、版本号、包长度、滚动计数、命令ID、数据段的打包后，再进行CRC计算。
注意：在CRC-16计算之前，先用0x0000填充CRC-16字段。然后再将计算结果填入CRC-16字段。
- 命令ID
标识该数据包的命令。
- 数据段
如果不存在参数，则此字段可以为NULL。
注意：命令ID和数据段应使用AES-128加密。
CRC-16 验证¶
具体配置如下：
| CRC-16 配置参数 | |
| 名称 | "XMODEM", 也称作 "ZMODEM", "CRC-16/ACORN" |
| 宽度位数 | 16 bit |
| 多项式 | 1021 (x^16 + x^12 + x^5 + 1) |
| 初始值 | 0000 |
| 输入数据反转 | False |
| 输出数据反转 | False |
| 结果异或值 | 0000 |
AES-128 加密¶
AES128对称加密使用CBC加密模式，该模式首先将明文划分为几个小片段，然后在用密钥加密之前，对每个片段与初始块或前一个密文片段执行XOR运算。
| AES-128 加密参数 | |
| 加密模式 | CBC |
| 宽度位数 | 128 bit |
| 偏移量 | "0000000000000000" |
| 填充方式 | PKCS7Padding |
| 密码 | "goodlife--00XXXX" 注意: 将设备不带“:”的大写BLE MAC由CRC-16计算，然后转换为大写HEX字符串的结果作为[XXXX]。 |
蓝牙接口¶
蓝牙接口的数据需要填写在数据包格式的命令ID和段中。蓝牙接口输入参数和输出参数均采用JSON格式。
-
对于命令
-
无输入参数
命令ID 数据段 描述 命令ID NULL 例子 0x01 NULL -
带输入参数
命令ID 数据段 描述 命令ID 输入参数 \n 例子 0x08 (json格式参数转hex) 0x0a -
对于回复
命令ID
| 数据段
| | ||
| 描述 | 命令ID | \n | 输出参数 |
| 例子 | 0x01 | 0x0a | (json格式参数转hex) |
命令ID 列表¶
| 命令ID | 命令名 | 是否带输入参数 | 描述 |
|---|---|---|---|
| 0x01 | gl_check_initialized | N | 获取设备初始化状态 |
| 0x02 | gl_set_init_admin_password | Y | 初始化web登录密码 |
| 0x03 | gl_eth_get_status | N | 获取以太网的当前状态 |
| 0x04 | gl_eth_get_config | N | 获取以太网配置 |
| 0x05 | gl_eth_set_config | Y | 设置以太网配置 |
| 0x06 | gl_wifi_get_status | N | 获取WiFi的当前状态 |
| 0x07 | gl_wifi_stop | N | 断开WiFi连接 |
| 0x08 | gl_wifi_start | Y | 开始连接到指定的WiFi |
| 0x09 | gl_wifi_get_save_wifi | N | 获取已保存的WiF配置i列表，最多保存3个 |
| 0x0a | gl_wifi_delete_save_wifi | Y | 删除已保存WiFi列表中的WiFi配置 |
| 0x0b | gl_wifi_scan | N | 扫描当前WiFi环境，获取WiFi信息列表 |
| 0x0c | gl_wan_failover_get_config | N | 获取当前WAN故障切换配置 |
| 0x0d | gl_wan_failover_set_config | Y | 设置当前WAN故障切换配置 |
| 0x0e | gl_set_admin_pwd | Y | 更改web登录密码 |
| 0x0f | gl_sys_reset | N | 将设备重置为出厂 |
| 0x10 | gl_sys_restart | N | 重启设备 |
初始化¶
gl_check_initialized¶
-
命令ID: 0x01
-
功能描述: 获取设备初始化状态
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| firmware_category | 强制 | string | 固件类型: "2c" |
| firmware_version | 强制 | string | 固件版本 |
| hostname | 强制 | string | 设备host名 |
| build_time | 强制 | string | 固件编译时间 |
| initialized | 强制 | boolean | 是否完成初始化 |
| mac | 强制 | string | 设备基础mac |
| model | 强制 | string | 设备模型 |
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_set_init_admin_password¶
-
命令ID: 0x02
-
功能描述: 初始化web登录密码
-
输入参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| password | 强制 | string | web的登录密码，字符要求范围 [10,32] |
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
以太网¶
gl_eth_get_status¶
-
命令ID: 0x03
-
功能描述: 获取以太网的当前状态
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| status | 强制 | number | 连接状态 0: 未连接 1: 已连接 2: 连接中 3: 物理网口未连接 |
| protocol | 强制 | string | 网络模式 “dhcp” 或 “static” |
| ipv4 | 可选 | object | IPv4相关状态, 只有连接后才可获取到 |
| ipv4.ip | 强制 | string | ipv4 地址 |
| ipv4.gateway | 强制 | string | ipv4 网关 |
| ipv6 | 可选 | object | IPv6相关状态, 只有连接后才可获取到 |
| ipv6.ip | 强制 | string | ipv6 地址 |
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_eth_get_config¶
-
命令ID: 0x04
-
功能描述: 获取以太网配置
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| protocol | 强制 | string | 网络模式 “dhcp” or “static” |
| ipv4 | 可选 | object | ipv4 设置，当选用static模式时才有效 |
| ipv4.ip | 强制 | string | 静态IPv4 地址 |
| ipv4.netmask | 强制 | string | 静态ipv4 掩码 |
| ipv4.gateway | 强制 | string | 静态ipv4 网关 |
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_eth_set_config¶
-
命令ID: 0x05
-
功能描述: 设置以太网配置
-
输入参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| protocol | 强制 | string | 网络模式 “dhcp” or “static” |
| ipv4 | 可选 | object | ipv4 设置，当选用static模式时才有效 |
| ipv4.ip | 可选 | string | 静态IPv4 地址 |
| ipv4.netmask | 可选 | string | 静态ipv4 掩码 |
| ipv4.gateway | 可选 | string | 静态ipv4 网关 |
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
WiFi¶
gl_wifi_get_status¶
-
命令ID: 0x06
-
功能描述: 获取WiFi的当前状态
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| status | 强制 | number | 连接状态 0: 闲置; 1: 连接中; 2: 已连接, 3: 连接失败 |
| fail_msg | 可选 | string | 连接失败的信息 |
| ssid | 可选 | string | 已连接或当前正在连接的ssid |
| bssid | 可选 | string | 已连接WiFi的bssid |
| ipv4 | 可选 | object | IPv4相关状态, 只有连接后才可获取到 |
| ipv4.ip | 强制 | string | ipv4 地址 |
| ipv4.gateway | 强制 | string | ipv4 网关 |
| ipv6 | 可选 | object | IPv6相关状态, 只有连接后才可获取到 |
| ipv6.ip | 强制 | string | ipv6 地址 |
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_wifi_stop¶
-
命令ID: 0x07
-
功能描述: 断开WiFi连接
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_wifi_start¶
-
命令ID: 0x08
-
功能描述: 开始连接到指定的WiFi
-
输入参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| enable_wifi_save | 强制 | boolean | 连接 WiFi 时是否保存此配置 |
| protocol | 强制 | string | 网络模式 “dhcp” or “static” |
| ipv4 | 可选 | object | ipv4 设置，当选用static模式时才有效 |
| ipv4.ip | 可选 | string | 静态IPv4 地址 |
| ipv4.netmask | 可选 | string | 静态ipv4 掩码 |
| ipv4.gateway | 可选 | string | 静态ipv4 网关 |
| ssid | 强制 | string | wifi ssid |
| pwd | 强制 | string | wifi 密码 |
| lock_bssid | 强制 | boolean | 设备是否连接到指定的 bssid |
| bssid | 可选 | string | wifi bssid |
| auth_mode | 强制 | number | wifi 认证模式 0: open 1: WEP 2: WPA_PSK 3: WPA2_PSK 4: WPA_WPA2_PSK 5: WPA2_ENTERPRISE (Not support) 6: WPA3_PSK 7: WPA2_WPA3_PSK 8: WAPI_PSK 9: OWE |
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_wifi_get_save_wifi¶
-
命令ID: 0x09
-
功能描述: 获取已保存的WiF配置i列表，最多保存3个
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| list | 强制 | array | wifi 已保存配置列表 |
| list[x].ssid | 可选 | string | wifi ssid |
| list[x].bssid | 可选 | string | wifi bssid |
| list[x].lock_bssid | 可选 | boolean | 是否锁定bssid |
| list[x].auth_mode | 可选 | number | wifi 认证模式 |
| list[x].pwd | 可选 | string | wifi 密码 |
| list[x].protocol | 可选 | string | 网络模式 “dhcp” or “static” |
| list[x].ipv4 | 可选 | object | 静态IPv4 配置 |
| list[x].ipv4.ip | 可选 | string | 静态IPv4 地址 |
| list[x].ipv4.netmask | 可选 | string | 静态ipv4 掩码 |
| list[x].ipv4.gateway | 可选 | string | 静态ipv4 网关 |
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_wifi_delete_save_wifi¶
-
命令ID: 0x0a
-
功能描述: 删除已保存WiFi列表中的WiFi配置
-
输入参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| ssid | 强制 | string | 需要删除哪个 wifi ssid |
| auth_mode | 强制 | number | 待删除 WIFI 的认证模式 0: open 1: WEP 2: WPA_PSK 3: WPA2_PSK 4: WPA_WPA2_PSK 5: WPA2_ENTERPRISE (Not support) 6: WPA3_PSK 7: WPA2_WPA3_PSK 8: WAPI_PSK 9: OWE |
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_wifi_scan¶
-
命令ID: 0x0b
-
功能描述: 扫描当前WiFi环境，获取WiFi信息列表
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| list | 强制 | array | 扫描到的wifi 列表 |
| list[x].ssid | 可选 | string | wifi ssid |
| list[x].bssid | 可选 | string | wifi bssid |
| list[x].auth_mode | 可选 | number | wifi 认证模式 0: open 1: WEP 2: WPA_PSK 3: WPA2_PSK 4: WPA_WPA2_PSK 5: WPA2_ENTERPRISE (Not support) 6: WPA3_PSK 7: WPA2_WPA3_PSK 8: WAPI_PSK 9: OWE |
| list[x].rssi | 可选 | number | 信号强度 RSSI |
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
WAN故障切换¶
gl_wan_failover_get_config¶
-
命令ID: 0x0c
-
功能描述: 获取当前WAN故障切换配置
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| eth | 强制 | object | 以太网故障切换配置 |
| eth.enable | 强制 | boolean | 是否启用以太网检查 |
| eth.check_interval | 强制 | number | 以太网检查间隔，单位为分钟 |
| eth.check_success_time | 强制 | number | 以太网变更为可获取状态条件: 所设置IP集所有累计ping通次数 |
| eth.check_fail_time | 强制 | number | 以太网变更为可无效状态条件: 所设置IP集单条ping不通次数 |
| eth.check_ipv4 | 强制 | array | 以太网IPv4测试地址列表, 最多三个 |
| eth.check_ipv4[x] | 强制 | string | 以太网IPv4测试地址 |
| eth.check_ipv6 | 强制 | array | 以太网IPv6测试地址列表, 最多三个 |
| eth.check_ipv6[x] | 强制 | string | 以太网IPv6测试地址 |
| wifi | 强制 | object | WiFi故障切换配置 |
| wifi.enable | 强制 | boolean | 是否启用WiFi检查 |
| wifi.check_interval | 强制 | number | WiFi检查间隔，单位为分钟 |
| wifi.check_success_time | 强制 | number | WiFi变更为可获取状态条件: 所设置IP集所有累计ping通次数 |
| wifi.check_fail_time | 强制 | number | WiFi变更为可无效状态条件: 所设置IP集单条ping不通次数 |
| wifi.check_ipv4 | 强制 | array | WiFi IPv4测试地址列表, 最多三个 |
| wifi.check_ipv4[x] | 强制 | string | WiFi IPv4测试地址 |
| wifi.check_ipv6 | 强制 | array | WiFi IPv6测试地址列表, 最多三个 |
| wifi.check_ipv6[x] | 强制 | string | WiFi IPv6测试地址 |
| priority | 强制 | object | 优先级配置 |
| priority.eth | 强制 | number | 以太网优先级，数字越小，优先级越高 |
| priority.wifi | 强制 | number | WiFi优先级，数字越小，优先级越高 |
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_wan_failover_set_config¶
-
命令ID: 0x0d
-
功能描述: 设置当前WAN故障切换配置
-
输入参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| eth | 强制 | object | 以太网故障切换配置 |
| eth.enable | 强制 | boolean | 是否启用以太网检查 |
| eth.check_ipv4 | 强制 | array | 以太网IPv4测试地址列表, 最多三个 |
| eth.check_ipv4[x] | 强制 | string | 以太网IPv4测试地址 |
| eth.check_ipv6 | 强制 | array | 以太网IPv6测试地址列表, 最多三个 |
| eth.check_ipv6[x] | 强制 | string | 以太网IPv6测试地址 |
| wifi | 强制 | object | WiFi故障切换配置 |
| wifi.enable | 强制 | boolean | 是否启用WiFi检查 |
| wifi.check_ipv4 | 强制 | array | WiFi IPv4测试地址列表, 最多三个 |
| wifi.check_ipv4[x] | 强制 | string | WiFi IPv4测试地址 |
| wifi.check_ipv6 | 强制 | array | WiFi IPv6测试地址列表, 最多三个 |
| wifi.check_ipv6[x] | 强制 | string | WiFi IPv6测试地址 |
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
系统¶
gl_set_admin_pwd¶
-
命令ID: 0x0e
-
功能描述: 更改web登录密码
-
输入参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| username | 强制 | string | 用户名，必须为 'root' |
| old_pwd | 强制 | string | 旧密码 |
| new_pwd | 强制 | string | 新密码 |
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_sys_reset¶
-
命令ID: 0x0f
-
功能描述: 将设备重置为出厂
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |
gl_sys_restart¶
-
命令ID: 0x10
-
功能描述: 重启设备
-
输入参数
无
- 输出参数
| 字段参数 | 要求 | 参数类型 | 描述 |
|---|---|---|---|
| code | 强制 | number | 错误码 |
| err_msg | 可选 | string | 错误消息 |