# the API for configure esp32c3_wifi gateway
[TOC]
# preface
These APIs are applicable to the gateway firmware of esp32c3_wifi(mg3-a-lychee、mg4-a-longan). The API uses HTTP's POST GET method to configure the gateway parameters.
| api_version | gateway_version | Author | Remark |
|---|---|---|---|
| 1 | v0.0.1 | justin | first draft |
# API list
| Fields | Remark |
|---|---|
| hello | Get the Gateway Information |
| upload | Upload the certificate |
| set | Send a command to the gateway |
# hello
- description：
An HTTP GET handler. Get the Gateway MAC Address、Model and Version
- Request URL：
http://127.0.0.1/hello
- Request method：
GET
- demo
curl -X GET 192.168.22.122:80/hello
1
- Return Gateway Information
{
"mac": "ae233fc00001",
"ip": "192.168.22.191",
"model": "mg3-a-lychee",
"version": "v1.0.0",
"code": 200,
"message": "hello"
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# upload
- description：
**This API is An POST handler. Upload the certificate(ca.crt、client.crt、client.key) to the gateway **
- Request URL：
http://127.0.0.1/upload?type=param
param is ca.crt、client.crt or client.key.
- Request method：
POST
- parameter：
This parameter is a binary certificate file in the body.
- Return Gateway Information
{
"code": 200,
"message": "File uploaded successfully!"
}
1
2
3
4
2
3
4
{
"code": 400,
"message": "NO file type!"
}
{
"code": 400,
"message": "File size must be less than 2k!"
}
{
"code": 500,
"message": "File reception failed!"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
# set
- description：
This API is An POST handler. Send a command to the gateway
- Request URL：
http://127.0.0.1/set
- Request method：
POST
- parameter：
This parameter is JSON format. The command type determines the content.
| parameter | required | type | remark |
|---|---|---|---|
| action | YES | string | Command Type: HeartBeat GetVersion GetConfig ClrWiFi ClrConfig ReBoot SetConfig Upgrade |
| requestId | NO | string | UUID format or the other format you defined, when the request message contain a request Id, the response message will returns to this field too, which is used to match the request and response messages. |
| mqtt | NO | json | used by SetConfig |
| http | NO | json | used by SetConfig |
| scan | NO | json | used by SetConfig |
| common | NO | json | used by SetConfig |
| other | NO | json | used by SetConfig |
| wifi | NO | json | used by SetConfig |
- demo
# curl -d '${json string}' http://${ip}/set
# ${json string} specifies the content to be sent
# ${ip} specifies the ip to access device
curl -X POST -d '{"action" : "HeartBeat"}' 192.168.22.122:80/set
1
2
3
4
2
3
4
Divided into different commands according to the action
# Reboot
This command is used to reboot the gateway remotely. The request message sample is as follows:
curl -X POST -d '{"action" : "ReBoot","requestId" : "abc"}' 192.168.22.122:80/set
1
return:
{"code":200,"message":"Action Reboot will be run!","requestId":"abc"}
1
# Heartbeat
This command is used to test whether the gateway is online or not remotely. The request message sample is as follows:
curl -X POST -d '{"action" : "HeartBeat","requestId" : "abc"}' 192.168.22.122:80/set
1
return:
{"code":200,"message":"Action HeartBeat succeed!","requestId":"abc"}
1
The server sends a heartbeat package to the gateway to determine whether the gateway is online, and if the gateway receives the control instruction, it returns the successful message directly. If the gateway is not online, it does not return.
# GetVersion
This command is used to get the current version of the gateway. The request message sample is as follows:
curl -X POST -d '{"action" : "GetVersion","requestId" : "abc"}' 192.168.22.122:80/set
1
return:
{"code":200,"message":"Action GetVersion succeed!","requestId":"abc","currentVersion":"1.0.0"}
1
# GetConfig
This command is used to get the current configuration information of the gateway. The message data field is described in detail as follows:
curl -X POST -d '{"action" : "GetConfig","requestId" : "abc"}' 192.168.22.122:80/set
1
return:
{
"wifi" : {
"ssid" : "@PHICOMM_AE",
"password" : "beacon888",
"bssid_set" : 1,
"bssid" : "fc7c027eabb1"
},
"mqtt" : {
"keepalive" : 120,
"qos" : 0,
"mqtt_url" : "mqtts://192.168.5.251:8883",
"publish_topic" : "/mg3/ae233fc00001/status",
"subscribe_topic" : "/mg3/ae233fc00001/action",
"response_topic" : "/mg3/ae233fc00001/response",
"client_id" : "ae233fc00001",
"lwt_msg" : "{\"status\" : \"GW-AE233FC00001 disconnected!\"}",
"username" : "",
"password" : "",
"use_ssl" : 1
},
"http" : {
"http_url" : "http://tagcloud.minew.com:8080/gw/ae233fc00001/status",
"auth_type" : "None",
"username" : "",
"password" : "",
"use_ssl" : 0
},
"scan" : {
"itvl" : 100,
"window" : 100,
"passive" : 1,
"filter_duplicates" : 0
},
"common" : {
"protocol" : "mqtt",
"upload_interval" : 1,
"rssi" : 0,
"regex_mac" : "",
"regex_raw" : "",
"mac_list": ""
},
"other" : {
"led_on" : 1,
"log_on" : 1,
"timeserver" : "cn.pool.ntp.org",
"timezone" : "UTC-8"
},
"code" : 200,
"message" : "Action GetConfig succeed!",
"requestId" : "abc"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# SetConfig
This command is used to get set configuration of the gateway. The message data field is described in detail as follows:
curl -X POST -d '{"action" : "SetConfig","mqtt":{"keepalive":120,"qos":0,"mqtt_url":"mqtt://tagcloud.minew.com:2883","publish_topic":"/mg3/ae233fc00001/status","subscribe_topic":"/mg3/ae233fc00001/action","response_topic":"/mg3/ae233fc00001/response","lwt_msg":"{\"status\" : \"GW-AE233FC00001 disconnected!\"}","username":"","password":""}, "http":{"http_url" : "http://tagcloud.minew.com:8080/gw/ae233fc00001/status","auth_type":"None","username":"","password":"","use_ssl" : 0},"scan":{"itvl":100,"window":100,"passive":1,"filter_duplicates":0},"common":{"upload_interval":1,"rssi":0,"regex_mac":"","regex_raw":"","mac_list": ""},"other":{"led_on":1,"log_on":1,"timeserver":"cn.pool.ntp.org","timezone":"UTC-8"},"requestId":"fdsjfl54g65fgs5gs"}' 192.168.22.122:80/set
1
curl -X POST -d '{"action" : "SetConfig","common":{"upload_interval":6,"rssi":-67},"requestId":"12ab"}' 192.168.22.122:80/set
1
curl -X POST -d '{"action" : "SetConfig","mqtt":{"publish_topic":"/mgx/{mac}/status"},"requestId":"12ab"}' 192.168.22.122:80/set
1
return:
{"code":200,"message":"Action SetConfig succeed!","requestId":"abc"}
1
| wifi Field（reserved） | Name | default | Remark |
|---|---|---|---|
| ssid | wifi ssid | \ | |
| password | wifi password | \ | |
| bssid_set | use wifi mac | 1 | |
| bssid | wifi mac | \ |
| mqtt Field | Name | default | Remark | Range |
|---|---|---|---|---|
| mqtt_url | Complete MQTT broker URI | "mqtt://tagcloud.minew.com:2883" | Format: scheme+domain name/IP Address+port scheme:Optional value is mqtt://, mqtts:// . Note: You can use the MQTT.fx desktop software to subsribe the gateway’s Status Publish Topic to fetch gateway’s data. | domain name string len 128 |
| use_ssl | Use certificate | 0 | The premise is to burn the certificate in flash | 0or1 |
| username | MQTT username | "" | The Username defined by the MQTT protocol | string len 64 |
| password | MQTT password | "" | The password defined by the MQTT protocol | string len 64 |
| client_id | MQTT client_id | {mac} | The cliend_id defined by the MQTT protocol | string len 64 |
| lwt_msg | LWT (Last Will and Testament) message | "{\"status\" : \"GW-{MAC}} disconnected!\"}" | Offline messages are sent to the response_topic | string len 64 |
| qos | MQTT QoS level | 0 | The Qos level defined by the MQTT protocol. QoS=0: at most times, it is possible to repeat or lose. QoS=1: at least once, it's possible to repeat it. | 0、1、2 |
| keepalive | Keep alive interval | 120 | The keep alive interval defined by the MQTT protocol. 0 by default mean 120 seconds . Some MQTT IoT Hub, such as Aliyun, do not allow such a frequent heartbeat interval, and need to set this parameter to 60 seconds to connect | 0-2147483647 |
| publish_topic | Topic to publish the BLE data | "/mgx/{mac}/status" | Topic used by gateway to publish BLE data {mac} for the gateway's Mac in the hexadecimal lowercase character form, such as /mgx/ae233fc00001/status. {MAC} corresponds to uppercase | string len 64 |
| subscribe_topic | Topic to receive action control data | "/mgx/{mac}/action" | For the gateway receiving control command, the message is JSON format. {mac} for the gateway's Mac in the hexadecimal lowercase character form, such as /mgx/ae233fc00001/action. {MAC} corresponds to uppercase | string len 64 |
| response_topic | Topic to response action control result data | "/mgx/{mac}/response" | For the gateway response action control command result,message is JSON format.{mac} for the gateway's Mac in the hexadecimal lowercase character form, such as /mgx/ae233fc00001/response. {MAC} corresponds to uppercase | string len 64 |
| http Field | Name | default | Remark | Range |
|---|---|---|---|---|
| http_url | Url of HTTP server | "http://tagcloud.minew.com:8080/gw/{mac}/status" | domain name string len 128 | |
| use_ssl | Use certificate | 0 | The premise is to burn the certificate in flash | 0or1 |
| auth_type | HTTP authentication type | "none" | "none" or "basic" | \ |
| username | Authentication user name | "" | Http basic authentication | string len 64 |
| password | Authentication | "" | Http basic authentication | string len 64 |
| scan Field | Name | default | Remark | Range |
|---|---|---|---|---|
| itvl | Scan Interval | 100 | The scan interval and the scan window are used together. | 10-10000ms |
| window | Scan Window | 100 | The scan window parameter should not be larger than the scan interval parameter. When the two parameters are equal, the scanning rate can reach to 100%. | 10-10000ms |
| passive | passive (1)or active(0) | 1 | 1. There are two types of advertising packets in BLE tags,including advertising packet and scan response packet. Advertising packets are broadcasted actively by BLE tags, while scan response packets are broadcasted passively by BLE tags after receiving requests from scanner. 2. There are two scanning strategies for the BLE module of the gateway,including active scanning and passive scanning. Active scanning sends requests for scan response packets to the BLE tag, while passive scanning only receives advertising packets and does not send requests for scan response packets. 3. If your BLE tag does not have the scan response packet, you can set this parameter to NO, which can improve the scanning rate of the BLE advertising packets. | 0or1 |
| filter_duplicates | Duplicate data within the time interval be filtered to upload or not | 0 | Default value is NO,Optional Value:YES,NO Note: Gateway determines duplicate data based on BLE MAC address. If BLE broadcasts multiple packets, such as Minew's MiniBeaconPlus firmware, Please use this filter option carefully | 0or1 |
| common Field | Name | default | Remark | Range |
|---|---|---|---|---|
| protocol | Service Access selection | "mqtt" | "mqtt" or "http" | \ |
| upload_interval | Upload Interval | 1 | The unit of time is seconds. The value range is 1-300 | 1-300s |
| rssi | Filtering by rssi value | 0 | Default value is 0. Only upload the rssi data that the signal intensity is greater than that, unit is dBm. When not filled, it is not filtered, and the value of -100 < RSSI <=0 can be filled. For example, when -67 is filled in, the -68 and the below weak signals are not uploaded to the server. | -99-0 |
| regex_mac | filtering BLE mac via regular expression | "" | The regular expression (Except for the |) of BLE mac address you wanna recevice. Note: Only uppercase Raw Data strings can be recognized by gateway | string len 64 |
| regex_raw | filtering raw data through regular | "" | The regular expression (Except for the |) of Raw Data you wanna recevice. Note: Only uppercase Raw Data strings can be recognized by gateway | string len 64 |
| mac_list | List of Mac addresses to be filtered | "" | Input in the form of AABBCCDDEEFF;FFEEDDCCBBAA MAC addresses must be separated by symbols | string len 129 |
| other Field | Name | default | Remark | Range |
|---|---|---|---|---|
| led_on | The led switch | 1 | on(1-255,brightness,1 means 58) or off(0) | 0or(1-255) |
| log_on | The log switch | 0 | on(1) or off(0) for debug, please ignore | 0or1 |
| timeserver | Time Server url | "cn.pool.ntp.org" | string len 64 | |
| timezone | The time zone | "UTC-8" | string len 32 |
# ClrWiFi
This command is only used to clear WiFi configuration. Enter smartconfig automatically at next startup.
curl -X POST -d '{"action" : "ClrWiFi","requestId" : "abc"}' 192.168.22.122:80/set
1
return:
{"code":200,"message":"Action ClrWiFi succeed!","requestId":"abc"}
1
# ClrConfig
This command is used to clear all configurations, which is equivalent to restoring factory settings. Enter smartconfig automatically at next startup.
curl -X POST -d '{"action" : "ClrConfig","requestId" : "abc"}' 192.168.22.122:80/set
1
return:
{"code":200,"message":"Action ClrConfig succeed!","requestId":"abc"}
1
# Upgrade
The gateway supports sending commands to upgrade the gateway’s firmware to the specified version. param is path (the upgrade firmware downloaded from the HTTP server).
curl -X POST -d '{"action" : "Upgrade","param" : "http://192.168.5.55/firmware/thingoo-mg4-a-longan-v0.0.2.bin","requestId" : "abc"}' 192.168.22.122:80/set
1
return:
{"code":200,"message":"Action Upgrade will be run!","requestId":"abc"}
1