# 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

# 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
{
    "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

# 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

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

# 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
上次更新:: 2022/8/19 17:50:40