AWS example

Introduction

This AWS example serves as a demonstration of the MQTT cloud's connection and data post/receive functionalities. It also provides a BLE service for Wi-Fi provisioning and over-the-air (OTA) procedures via BLE. Additionally, this example offers three different sleep modes and enables users to execute various AT commands to achieve the above objectives. For a comprehensive description of the AT command list, please refer to the AT Command List.

Furthermore, this AWS example acts as a slave device that the host controls. The host microcontroller unit (MCU) transmits an AT command via UART to request that the Opulinks device execute various functions. Subsequently, the Opulinks device responds with the corresponding acknowledgment message to the host. To illustrate various scenarios, we provide an AWS host example.

Architecture

Host Connection

The host will send the request to the Opulinks device and the Opulinks device will respond to the corresponding ack message via the UART interface. The host and the Opulinks device also connect to the IO interface. One for the Opulinks device triggers the host, and the other for the host triggers(wakes up) the Opulinks device.

AWS_architecture

Software Architecture

When a user application initiates an MQTT connection request or others, it is transmitted to the cloud template. There are two components in Cloud Template - Cloud Kernel and Cloud Control. The request first passes through the cloud kernel and is then processed by event handlers. Some of these handlers are located in the cloud control, which is responsible for executing cloud events by calling the protocol API. Once the events are completed, the protocol responds to the user application via the Cloud Template.

The phone sends Wi-Fi provision request to the device via BLE. The BLE Manager receives this message and transmits it to the application, which passes it to the BLE Application. Different handlers in the BLE Application handle different requests. After executing the Wi-Fi process, the bottom layer sends the Wi-Fi process response results to the BLE Application via Network Manager, which then organizes and passes the message to the BLE Manager. The BLE Manager sends these messages to the phone.

AWS_sf_architecture

Features

AWS example provides the following features:

  • AWS MQTT:

    • AWS Server Connection
      • Indicate domain name, port
      • Adjustable keep alive setting
      • Client ID assignment
      • Last Will topic assignment
    • MQTT topic subscribe
    • MQTT topic publish

  • HTTP client:

    • HTTP get
    • HTTP post

  • BLE

    • WiFi provision via BLE
    • OTA via BLE

  • Power saving

    • Smart sleep
    • Timer sleep
    • Deep sleep

Testing

The AWS example is located at examples\cloud\.

BLE Service

In this section, the Opulinks device will establish a connection with WiFi through BLE and perform the Over-the-Air (OTA) update via BLE. The AWS example comes with the standard BLE service, which includes WiFi provisioning and OTA. Also, successful Wi-Fi provision via BLE enables automatic reconnection to the AP after disconnection. You can customize both of these services by editing OPL_DATA_ENABLED and OTA_ENABLED in sys_config\qd_module.h.

// OPL Data Protocol
#ifndef OPL_DATA_ENABLED
#define OPL_DATA_ENABLED                        (1)
#endif

// OTA
#ifndef OTA_ENABLED
#define OTA_ENABLED                             (1)
#endif

WiFi Provision via BLE Steps:

  1. Start BLE advertise at+blestart=0
  2. Connect to the device by Opulinks APP
    Please refer to WiFi provision via BLE.

OTA via BLE Steps:

  1. Start BLE advertise at+blestart=0
  2. Connect to the device by Opulinks APP
    Please refer to OTA via BLE.

AWS MQTT

Here is a demonstration of MQTT setup, connectivity, subscription topic, and published message. Make sure you have the following certificate, key files, and endpoint:

  • Amazon-root-CA-1.pem (Root CA certificate)
  • device.pem.crt (Device certificate)
  • private. pem.key (Private key)

  • endpoint

    The format of the endpoint is xxx-ats.iot.us-west-1.amazonaws.com.

Note

Follow AWS IoT Core to get your resources.

Most of QuickDev-Framework's cloud libraries are based on the Cloud Template architecture.

Steps:

  1. WiFi connection
    Users can refer to WiFi provision via BLE or use the AT command to connect WiFi.

  2. Certificate Upload

    • Root CA certificate

    at+fulmqttcert=1, <data len (byte)>

    Select the Root CA certificate file and send it.

    • Device Certificate

    at+fulmqttcert=2, <data len (byte)>

    Select the device.pem.crt (Device certificate) file and send it.

    • Private Key

    at+fulmqttcert=3, <data len (byte)>

    Select the private.pem.key (Private key) file and send it.

  3. MQTT client ID

    at+mqttclientid=<client id string>

  4. AWS MQTT keep alive interval set

    at+mqttkpintvl=<keep alive intv (ms) 60000 ms ~ 6000000 ms>
    default: 600000ms

  5. AWS MQTT last will set

    at+mqttlastwill=<last will topic name>, <payload len>\r\n <payload>

  6. AWS MQTT initial

    at+mqttinit

  7. AWS MQTT connection

    at+mqttconnect=<endpoint>,<port>,<auto connect flag>

  8. AWS MQTT topic subscribe

    at+mqttsub=<topic name string>, <QoS>

  9. AWS MQTT publish

    at+mqttpub=<topic name>, <QoS>, <payload len>\r\n
    <payload>

    We can use the MQTTX to check if the message has been published successfully. For more information about the MQTTX setting refer to MQTT demo.

  10. AWS MQTT disconnect

    at+mqttdisconect

HTTP

HTTP-related functions include HTTP post and HTTP get. The HTTP module is disabled by default. You can customize both of these services by editing HTTP_ENABLED in sys_config\qd_module.h. In addition, if OPL_DATA_ENABLED or OTA_ENABLED is enabled, HTTP_ENABLED will be disabled.

// HTTP client
#ifndef HTTP_ENABLED
#define HTTP_ENABLED                            (0)
#endif

Currently, there are some restrictions on HTTP-related services, so you can't use HTTP-related functions after MQTT is connected.

  1. HTTP get

    at+httpget=<url length>
    <url> httpget

  2. HTTP post

    at+httppost=<data len in string>,<url string> <raw data>

    httpget

Sleeping Mode

AWS example provides three kinds of sleep modes, including smart sleep, timer sleep, and deep sleep. The detail can refer to Power Saving. Users can request the Opulinks device to enter sleep mode by issuing the AT command.

Smart sleep:

  1. Enter smart sleep: at+sleepmode=1 Smart sleep

Timer sleep:

  1. Enter timer sleep: at+sleepmode=2,<sleep time> Timer sleep

Deep sleep:

  1. Enter deep sleep: at+sleepmode=3 Deep sleep

Sleeping Mechanism

Host State

Opulinks device will store two types of states that represent the current state of the host. These states are "WAIT" and "NOT WAIT".

  1. State “WAIT”

    This state is activated when the Opulinks device triggers the host and does not receive an AT command response from the host yet. The state is set to "WAIT" until the host provides the AT command response or the "Wait Host Rsp" timer times out.

  2. State “NOT WAIT”

    Except for the above condition will enter the "WAIT" state, other times is in the "NOT_WAIT" state.

Exit smart sleep

It is possible that the host actively asks the Opulinks device to exit smart sleep or the Opulinks device receives an event to passively exit smart sleep.

We can wake up the Opulinks device by triggering an output signal (rising edge) from the host via GPIO. After waking up, the module will send back an ack message to the host.

Smart sleep wakeup by IO

Opulinks device will trigger the host via IO and send ack messages when it is notified by these seven situations:

  1. BLE connect
  2. BLE disconnect
  3. BLE notify
  4. WiFi connect(when OPL_DATA_ENABLED is enable)
  5. WiFi disconnect
  6. Cloud disconnect
  7. Cloud receive data

After receiving the notification of these events, first, we will exit the smart sleep mode, and then we will store the information about this event. Then, we use GPIO to wake up the host and set the host state to “WAIT”.

When the host responds the AT command(at+hostready) to the Opulinks device. We will change the host state to “NOT WAIT”. In the end, we will send all the events’ ack messages in AckQueue to the host.

About the WiFi connection, the device needs to trigger the host by IO and save the ack tag only when OPL_DATA_ENABLED is enabled. Otherwise, the device will transfer ack message directly.

smart sleep event not wait

While the above event occurs in the “WAIT” state, this means that the module has triggered the host and changed the host state before. Currently, the module is waiting for the host's response. Consequently, the module only needs to save event (or data) information. However, there is a limit to the amount of data that can be stored. If there are more than 4 events, the module will delete the oldest events or data. After the host responds the AT command, the state will be set to “NOT WAIT" and the module will send all ack information in the queue to the host.

The limit of saving events' information can be adjusted in app_main.c.

#define APP_MAX_QUEUE_SIZE                          (4)

smart sleep event wait

Wait Host Response Timer

The host must respond to the AT command each time when the OPL triggers the host, but to prevent the host from not responding, which would cause the ack message not to be sent. Opulinks device will start the timer after triggering the host, if the host does not respond an AT command(at+hostready) within the time limit (currently set to 5 seconds), the slave will directly send the ack message of the event to the host.

Smart sleep timer timeout

Scenario

AWS host example provides some examples of different scenarios based on the aforementioned features.

AT command

Function

Return value (Hex) will be divided into Header + Payload + End, the format of Header and End is fixed. For details, please refer to Payload.

  • Header : 0x2B(+)
  • Ack Tag (1 byte): AT Command type
  • Ack Status (1 byte): AT Command status (0: ok, 1: fail)
  • Payload: Depending on the content of each at command
  • End: 0x0D, 0x0A (\r\n)

The following is a description of each at command and its return value.

Boot

Feature

Device boot / reset

AT command

N/A

Prameter

N/A

Step

  1. Turn on or reset the device

Result

Host received ACK_TAG_MODULE_READY from OPL module.

Return Value

Ack Tag:

  • (Request) ACK_TAG_MODULE_READY (0x34)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)

Payload: NULL

at+blestart

Feature

Start BLE advertising.

AT command

at+blestart=<auto advertising flag>

Prameter

  1. auto advertise flag:

  2. 0 : Disable auto advertise

  3. 1 : Enable auto advertise

Step

Prestep:

  1. Device ble idle

Step:

  1. AT Command: at+blestart=< auto ble adv flag >
  2. Check if the device is advertising on the Opulinks APP.

Result

The device will start advertising and can check on the Opulinks APP.

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to start Bluetooth broadcast, and Indicate is the result of the execution.

  • (Request) ACK_TAG_BLE_START_ADV_REQ (0x01)
  • (Indicate) ACK_TAG_BLE_START_ADV_IND (0x09)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+blestop

Feature

Stop BLE advertising.

AT command

at+blestop

Prameter

N/A

Step

Prestep:

  1. Device ble should be advertising

Step:

  1. AT Command: at+blestop
  2. Check if the device is not advertising on the Opulinks APP.

Result

The device will stop advertising and can check on the Opulinks APP.

Return Value

Ack Tag: Divided into Request and Indiacate, Request is the at command to stop Bluetooth broadcast, and Indicate is the result of the execution.

  • (Request) ACK_TAG_BLE_STOP_REQ (0x02)
  • (Indicate) ACK_TAG_BLE_STOP_IND (0x0A)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+netscan

Feature

WiFi scan.

AT command

at+netscan

Prameter

N/A

Step

Prestep: N/A

Step:

  1. AT Command: at+netscan
  2. Check if the scan AP list is correct.

Result

The AP scan list is right.

Return Value

  1. AP Number

    Ack Tag: (Request)ACK_TAG_WIFI_SCAN_REQ (0x0E)

    Ack Status:

    • Execution succeeded ACK_STATUS_OK (0x00)
    • Execution failed ACK_STATUS_FAIL (0x01)

    Payload: It varies depending on the Ack Status

    • Ack Status is ACK_STATUS_OK (0x00), the payload represent to scanned AP number
    • Ack Status is ACK_STATUS_FAIL (0x01), payload is NULL

  2. AP Information

    Ack Tag: (Request)ACK_TAG_WIFI_SCAN_REQ (0x0E)

    Ack Status:

    • Success ACK_STATUS_OK (0x00)
    • Failure ACK_STATUS_FAIL (0x01)

    Payload: It varies depending on the Ack Status

    • Ack Status is ACK_STATUS_OK (0x00), the payload represents to scanned AP information that is bssid (6 bytes), ssid len (1 byte), ssid (max len =31), channel (1 byte), rssi (1 byte), authority mode (1 byte)
    • Ack Status is ACK_STATUS_FAIL (0x01), payload is NULL

at+netconnect

Feature

WiFi connect.

AT command

at+netconnect=<ssid or bssid>,<password>

Ex:

  • at+netconnect=ap_ssid,12345678
  • at+netconnect=01:02:03:04:05:06,12345678
  • at+netconnect=opulinks

Prameter

  1. < ssid or bssid >
    ssid_max_len = 31 bssid_max_len = 6

  2. < password >
    If you don't have a password < password > you can leave it blank.

Step

Prestep:

  1. WiFi scan

Step:

  1. AT Command: at+netconnect=< ssid/bssid >,< pwd >
  2. WiFi connected

Result

Device connects to the desired AP.

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to connect WiFi ap, and Indicate is the result of the execution.

  • (Request) ACK_TAG_WIFI_CONNECT_REQ (0x10)
  • (Indicate) ACK_TAG_WIFI_NETWORK_UP_IND (0x14)

Ack Status:

  • Success: ACK_STATUS_OK (0x00)
  • Failure: ACK_STATUS_FAIL (0x01)

Payload: NULL

at+netdisconnect

Feature

WiFi disconnect.

AT command

at+netdisconnect

Prameter

N/A

Step

Prestep:

  1. Device should be WiFi connected.

Step:

  1. AT Command: at+netdisconnect
  2. WiFi disconnected

Result

Device disconnect to the AP.

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to connect WiFi ap, and Indicate is the result of the execution.

  • (Request) ACK_TAG_WIFI_CONNECT_REQ (0x10)
  • (Indicate) ACK_TAG_WIFI_NETWORK_UP_IND (0x14)

Ack Status:

  • Success ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+netapinfo?

Feature

WiFi AP information get.

AT command

at+netapinfo?

Prameter

N/A

Step

Prestep:

  1. Device should be wifi connected.

Step:

  1. AT Command: at+netapinfo?
  2. Verify that the AP information sent to the Host is correct.

Result

AP Information is right (bssid, ssid, ssid len, channel, rssi, auth mode).

Return Value

Ack Tag: (Request)ACK_TAG_WIFI_GET_AP_INFO_REQ (0x12)

Ack Status:

  • Success ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: It varies depending on the Ack Status

  • Ack Status is ACK_STATUS_OK (0x00), payload is bssid (6 bytes), ssid (max len =31),
    ssid len (1 byte), channel (1 byte), rssi (1 byte), authority mode (1 byte)
  • Ack Status is ACK_STATUS_FAIL (0x01), payload is NULL

at+netdevmac?

Feature

WiFi mac address get.

AT command

at+netdevmac?

Prameter

N/A

Step

Prestep:

N/A

Step:

  1. AT Command: at+netdevmac?
  2. Confirm the WIFI MAC sent to the host is correct.

Result

Device Wi-Fi MAC address is right.

Return Value

Ack Tag: (Request) ACK_TAG_WIFI_GET_MODULE_MAC_ADDR_REQ (0x13)

Ack Status:

  • Success ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: It varies depending on the Ack Status

  • Ack Status is ACK_STATUS_OK (0x00), payload is wifi mac addres (6 bytes)
  • Ack Status is ACK_STATUS_FAIL (0x01), payload is NULL

at+netreset

Feature

WiFi reset.

AT command

at+netreset

Prameter

N/A

Step

Prestep:

N/A

Step:

  1. AT Command: at+netreset
  2. The device network disconnects and clears the AP Profile.

Result

Devcie wifi disconnect & clear AP profile.

Return Value

N/A

at+fulmqttcert

Feature

Upload mqtt root ca, client cert & private key.

AT command

at+fulmqttcert=<enum file type>, <data len (byte)>\r\n
(Delay time : 1~5ms)
<data>
Prameter

  1. < enum file type >
    file type: 1 : Root CA 2 : Client Cert 3 : Private Key

  2. < data len >

  3. < data >

Step

Prestep:

N/A

Step:

  1. AT Command: at+fulmqttcert=< file type >, < data len >
  2. Verify that the Certificate file uploaded is correct.

Result

Files upload successfully.

Return Value

AcK Tag: (Request) ACK_TAG_FILE_UPLOAD (0x25)

Ack Status:

  • Download file beginning ACK_STATUS_BEGIN (0x02)
  • Download file progressing ACK_STATUS_PROGRESS (0x03)
  • Download file ending ACK_STATUS_END (0x04)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: Depending on the file type payload will be different.

File Type:

  • MQTT RootCA UPLOAD_FILE_TYPE_MQTT_ROOT_CA (0x01)
  • MQTT Client Certificate UPLOAD_FILE_TYPE_MQTT_CLIENT_CERT (0x02)
  • MQTT Private Key UPLOAD_FILE_TYPE_MQTT_PRIVATE_KEY(0x03)
  • MQTT Private Key UPLOAD_FILE_TYPE_HTTPS_CA_CHAIN(0x04)

at+mqttclientid

Feature

AWS mqtt clientID set.

AT command

at+mqttclientid=<clientid string>

EX: at+mqttclientid=OPL_AWS_TEST

Prameter

  1. < clientid string >

    max clientid len = 64

Step

Prestep:

  1. Client ID should be set before MQTT connect

Step:

  1. at+mqttclientid= < clientid string >
  2. Set the AWS client ID

Result

Device set AWS mqtt clientID successfully.

Return Value

Ack Tag: (Request) ACK_TAG_CLOUD_MQTT_CLIENTID_SET (0x32)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+mqttkpintvl

Feature

AWS mqtt keep alive interval set.

AT command

at+mqttkpintvl=<keep alive intv (ms)>

Prameter

  1. < keep alive intv > 60000 ms ~ 6000000 ms, default: 600000ms

Step

Prestep:

  1. Keep alive should be set before MQTT connect.

Step:

  1. AT Command: at+mqttkpintvl=< keep alive intv (ms) >

Result

MQTT keep alive set successful.

Return Value

Ack Tag: (Request) ACK_TAG_CLOUD_MQTT_KEEP_ALIVE_SET_REQ(0x1A)

Ack Status:

  • Success ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: Keep alive interval (4 Byte)

at+mqttlastwill

Feature

AWS mqtt last will set.

AT command

at+mqttlastwill=<last will topic name string>,<payload_len>\r\n
(Delay time:1~5ms) 
<payload>

EX:

at+mqttlastwill=OPL_AWS_TOPIC,18\r\n
(Delay time: 1ms)
Last will message.

Prameter

  1. < last will topic name string >
  2. < payload len >
  3. < payload >
    max last will topic name len = 128
    max payload max len = 1024

Step

Prestep:

  1. Last will should be set before MQTT connect

Step:

  1. at+mqttlastwill=< last will topic name string >,< payload_len >\r\n (Delay time:1~5ms) < payload >

  2. Set AWS mqtt last will

Result

Device set AWS mqtt last will successfully.

Return Value

Ack Tag: (Request) ACK_TAG_CLOUD_MQTT_LASTWILL_SET (0x33)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+mqttinit

Feature

AWS mqtt cloud initialize.

AT command

at+mqttinit

Prameter

N/A

Step

Prestep:

  1. Device should upload root ca, client cert & private key.

Step:

  1. AT Commnad: at+mqttinit
  2. Verify that mqtt cloud initial was successful

Result

Mqtt cloud init successful

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to initiate mqtt, and Indicate is the result of the execution.

  • (Request) ACK_TAG_CLOUD_MQTT_INIT_REQ (0x17)
  • (Indicate) ACK_TAG_CLOUD_MQTT_INIT_IND (0x1E)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+mqttconnect

Feature

AWS mqtt cloud connect.

AT command

at+mqttconnect=<endpoint>, <host port>,<bool autoconn flag>

Ex:

at+mqttconnect=amazon.com.mqtt.url,8883,0

Prameter

  1. < endpoint >
  2. < host port >
  3. < bool autoconn flag >

Step

Prestep:

  1. Device should mqtt cloud initialize successful

Step:

  1. AT Command: at+mqttconnect=< endpoint >, < host port >,< bool autoconn flag >
  2. Verify that the connection to the mqtt broker was successful

Result

Mqtt cloud connect is successful.

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to connect mqtt broker, and Indicate is the result of the execution.

  • (Request) ACK_TAG_CLOUD_MQTT_ESTAB_REQ (0x18)
  • (Indicate) ACK_TAG_CLOUD_MQTT_CONNECT_IND (0x1F)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+mqttdisconnect

Feature

AWS mqtt cloud disconnect.

AT command

at+mqttdisconnect

Prameter

N/A

Step

Prestep:

  1. Device should mqtt cloud connect successfully

Step:

  1. AT Command: at+mqttdisconnect
  2. Verify that disconnecting the mqtt broker was successful.

Result

Mqtt cloud disconnects successfully.

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to disconnect MQTT broker, and Indicate is the result of the execution.

  • (Request) ACK_TAG_CLOUD_MQTT_DISCON_REQ (0x19)
  • (Indicate) ACK_TAG_CLOUD_MQTT_DISCON_IND (0x20)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+mqttsub

Feature

AWS mqtt cloud subscribe.

AT command

at+mqttsub=<topic neme string>,<qos (0 or 1)>

EX: at+mqttsub=/topic/name,1

Prameter

  1. < topic name string > Max topic name length: 128
  2. < QoS > 0 : QoS = 0 1 : QoS = 1

Step

Prestep:

  1. Device should connect mqtt broker successfully.

Step:

  1. AT Command:at+mqttsub=< topic name >,< QoS >
  2. Verify the published message from the topic publisher is correct

Result

Mqtt cloud subscribes successfully.

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to subscribe the topic from mqtt broker, and Indicate is the result of the execution.

  • (Request) ACK_TAG_CLOUD_MQTT_SUB_TOPIC_REQ (0x1B)
  • (Indicate) ACK_TAG_CLOUD_MQTT_SUB_TOPIC_IND (0x21)

Ack Status:

  • Success ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+mqttpub

Feature

AWS mqtt cloud publish.

AT command

at+mqttpub=<topic name string>,<qos (0 or 1)>,<payload_len>\r\n
<payload>

EX: at+mqttpub=/topic/name,1,10\r\n Helloworld

Prameter

  1. < topic name string > Max topic name length: 128
  2. < qos (0 or 1) >
  3. < payload_len >
  4. < payload > Max payload length receive: 1024 - 7 - topic name length

Step

Prestep:

  1. Device should connect to MQTT broker successfully.

Step:

  1. AT Command: at+mqttpub=< topic name >,< QoS >,< payload >,< payload >
  2. Verify by topic subscriber.

Result

MQTT cloud publishes successfully.

Return Value

Ack Tag: Divided into Request and Indicate, Request is the at command to publish the topic to mqtt broker, and Indicate is the result of the execution.

  • (Request) ACK_TAG_CLOUD_MQTT_PUB_DATA_REQ (0x1D)
  • (Indicate) ACK_TAG_CLOUD_MQTT_PUB_DATA_IND (0x23)

Ack Status:

  • Success ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+sleepmode - 1

Feature

Smart sleep

AT command

at+sleepmode=<sleep mode=1>

EX: at+sleepmode=1

Prameter

  1. < sleepmode >: set as 1

Step

Prestep: N/A

Step:

  1. AT Command: at+sleepmode=1
  2. Device enters smart sleep

Result

Device Smart sleep successful.

Return Value

Ack Tag: (Request) ACK_TAG_SMART_SLEEP (0x27)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+sleepmode - 2

Feature

Timer sleep

AT command

at+sleepmode=<sleepmode = 2>,<sleeptime>

EX: at+sleepmode=2,1000

Prameter

  1. < sleepmode >: set as 2
  2. < sleeptime >: (ms)

Step

Prestep: N/A

Step:

  1. AT Command: at+sleepmode=2,1000
  2. The device enters timer sleep and will wake up after 1000ms.

Result

Device Timer sleep successful.

Return Value

Ack Tag: (Request) ACK_TAG_TIMER_SLEEP (0x28)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+sleepmode - 3

Feature

Deep sleep.

AT command

at+sleepmode=<sleepmode = 3>

Prameter

  1. : set as 3

Step

Prestep: N/A

Step:

  1. AT Command: at+sleepmode=3
  2. The device enter deep sleep

Result

Device Deep sleep successful

Return Value

Ack Tag: (Request) ACK_TAG_DEEP_SLEEP (0x29)

Ack Status:

  • Succeess ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

at+httppost

Feature

HTTP post.

AT command

at+httppost=<data len in string>,<url string>\r\n 
(Delay time : 1~5ms)
<raw data>

EX:

at+httppost=10,http://192.168.0.195/localhost\r\n
(Delay time: 1ms)
Helloworld

Prameter

  1. < data len in string >

  2. < url string >

    Max URL length: 254 - 13 - data len digit number.

    ex.at+httppost=12,http...., the max URL length = 254 - 13 - 2

  3. < raw data >

  4. Max server reposnonds data length: 6144

Step

Prestep:

  1. Device should got IP

Step:

  1. AT Command: at+httppost=< data len in string >,< url >\r\n (Delay time: 1ms) < raw data >
  2. The device post to HTTP Server
Result

Device HTTP-post to HTTP server successfully.

Return Value

AcK Tag:

  • (Request) ACK_TAG_FILE_HTTP_POST_REQ (0x2E)
  • (Indicate) ACK_TAG_FILE_HTTP_POST_RSP (0x2F)

Ack Status:

  • Download file beginning ACK_STATUS_BEGIN (0x02)
  • Download file progressing ACK_STATUS_PROGRESS (0x03)
  • Download file ending ACK_STATUS_END (0x04)
  • Failure ACK_STATUS_FAIL (0x01)

Payload:

  • Ack Status are ACK_STATUS_BEGIN (0x02), ACK_STATUS_PROGRESS (0x03). ACK_STATUS_END (0x04), that payload is the response raw data from HTTP server
  • Ack Status is ACK_STATUS_FAIL (0x01), that payload is NULL

at+httpget

Feature

HTTP get.

AT command

at+httpget=<url length>
(Delay time : 1~5ms)
<url string>

EX: at+httpget=33\r\n (delay 1ms) https://api.ikey-lock.com/v1/time

Prameter

  1. < url length > Max URL length: 1536

  2. < url string >

  3. Max server responds data length: 6144

Step

Prestep:

  1. Device should got IP

Step: 1. at+httpget=< url length > (Delay time : 1~5ms) < url string >

  1. Device get raw data from HTTP server
Result

Device get raw data from HTTP server successfully.

Return Value

AcK Tag:

  • (Request) ACK_TAG_FILE_HTTP_GET_REQ (0x30)
  • (Indicate) ACK_TAG_FILE_HTTP_GET_RSP (0x31)

Ack Status:

  • Download file beginning ACK_STATUS_BEGIN (0x02)
  • Download file progressing ACK_STATUS_PROGRESS (0x03)
  • Download file ending ACK_STATUS_END (0x04)
  • Failure ACK_STATUS_FAIL (0x01)

Payload:

  • Ack Status are ACK_STATUS_BEGIN (0x02), ACK_STATUS_PROGRESS (0x03). ACK_STATUS_END (0x04), that payload is the response raw data from HTTP server
  • Ack Status is ACK_STATUS_FAIL (0x01), that payload is NULL

at+hostready

Feature

After the device triggers the host, the device will wait for "at+ostready" to transfer the ack message to the host.

AT command

at+hostready

Prameter

N/A

Step

Prestep: N/A

Step:

  1. at+hostready

Result

Device sends the event's ack message to the host.

Return Value

Ack Tag: (Request) ACK_TAG_HOST_READY (0x36)

Ack Status:

  • Success ACK_STATUS_OK (0x00)
  • Failure ACK_STATUS_FAIL (0x01)

Payload: NULL

Payload Format

  • Normal ACK message
Header (0x2B) ACK Tag ACK Status Payload Len *Payload (not have if NULL) Sum NewLine(0x0D) NewLine(0x0A)
1 byte 1 byte 1 byte 2 bytes n byte(s) 2 bytes 1 byte 1 byte
  • Scan List ACK message (AP number message)

When returning the scan list ACK message, the AP number message will be sent first to identify the number of APs, and then the scanned AP message will be returned for each AP.

Header (0x2B) ACK Tag ACK Status AP number Sum NewLine (0x0D) NewLine (0x0A)
1 byte 1 byte 1 byte 1 bytes 2 byte(s) 1 byte 1 bytes
  • Scan List ACK message (Scanned AP message)
Header (0x2B) ACK Tag ACK Status BSSID SSID Len SSID Channel RSSI (int8) Auth Mode Sum NewLine (0x0D) NewLine (0x0A)
1 byte 1 byte 1 byte 6 bytes 1 bytes n byte(s) 1 byte 1 byte 1 byte 2 bytes 1 byte 1 byte
Authenticate Mode Idx
WIFI_AUTH_OPEN 0
WIFI_AUTH_WEP 1
WIFI_AUTH_WPA_PSK 2
WIFI_AUTH_WPA2_PSK 3
WIFI_AUTH_WPA_WPA2_PSK 4
WIFI_AUTH_WPA2_ENTERPRISE 5
  • MQTT Rcv ACK message
Header (0x2B) ACK Tag ACK Status Topic Name Len Topic Name Payload Len Payload Sum NewLine (0x0D) NewLine (0x0A)
1 byte 1 byte 1 byte 2 bytes n byte(s) 2 bytes n byte(s) 2 bytes 1 byte 1 byte
  • Http Get & Post ACK message
Header (0x2B) ACK Tag ACK Status Reserved (No use) File Total Len Payload Len Payload Sum NewLine (0x0D) NewLine (0x0A)
1 byte 1 byte 1 byte 1 byte 4 bytes 2 bytes n byte(s) 2 bytes 1 byte 1 byte

Ack Tag List

Normal Ack Tag

  • BLE
Ack name Value Description
ACK_TAG_BLE_START_ADV_REQ 0x01 BLE adv start request
ACK_TAG_BLE_STOP_REQ 0x02 BLE adv stop request
ACK_TAG_BLE_ADV_DATA_REQ 0x03 Set BLE adv data request
ACK_TAG_BLE_APPEAR_ERQ 0x04 Set BLE appearance
ACK_TAG_BLE_FW_REV_REQ 0x05 Set BLE firmware version
ACK_TAG_BLE_MODEL_NB_REQ 0x06 Set BLE model number
ACK_TAG_BLE_GET_DEVICE_MAC_REQ 0x07 Get BLE Mac address
ACK_TAG_BLE_NOTIFY_DATA_REQ 0x08 BLE notify request
ACK_TAG_BLE_START_ADV_IND 0x09 BLE adv start indicate
ACK_TAG_BLE_STOP_IN 0x0A BLE adv stop indicate
ACK_TAG_BLE_CONNECTED_IND 0x0B BLE connected indicate
ACK_TAG_BLE_DISCONNECTED_IND 0x0C BLE disconnected indicate
ACK_TAG_BLE_RECV_DATA_IND 0x0D Receive BLE data indicate
  • WiFi
Ack name Value Description
ACK_TAG_WIFI_CONNECT_REQ 0x10 WiFi connect request
ACK_TAG_WIFI_DISCONNECT_REQ 0x11 WiFi disconnect request
ACK_TAG_WIFI_GET_AP_INFO_REQ 0x12 WiFi get ap info request
ACK_TAG_WIFI_GET_MODULE_MAC_ADDR_REQ 0x13 WiFi get module mac address request
ACK_TAG_WIFI_NETWORK_UP_IND 0x14 WiFi network up indicate
ACK_TAG_WIFI_NETWORK_DOWN_IND 0x15 WiFi network down indicate
ACK_TAG_WIFI_NETWORK_RESET_IND 0x16 WiFi network reset indicate
  • Cloud
Ack name Value Description
ACK_TAG_CLOUD_MQTT_INIT_REQ 0x17 MQTT Initiation request
ACK_TAG_CLOUD_MQTT_ESTAB_REQ 0x18 MQTT connect broker request
ACK_TAG_CLOUD_MQTT_DISCON_REQ 0x19 MQTT disconnect broker request
ACK_TAG_CLOUD_MQTT_KEEP_ALIVE_SET_REQ 0x1A MQTT keep alive time setting
ACK_TAG_CLOUD_MQTT_SUB_TOPIC_REQ 0x1B MQTT subscribe the topic to borker request
ACK_TAG_CLOUD_MQTT_UNSUB_TOPIC_REQ 0x1C MQTT unsubscribe the topic to borker request
ACK_TAG_CLOUD_MQTT_PUB_DATA_REQ 0x1D MQTT publish the topic to borker request
ACK_TAG_CLOUD_MQTT_INIT_IND 0x1E MQTT Initiation indicate
ACK_TAG_CLOUD_MQTT_CONNECT_IND 0x1F MQTT connect broker indicate
ACK_TAG_CLOUD_MQTT_DISCON_IND 0x20 MQTT disconnect broker indicate
ACK_TAG_CLOUD_MQTT_SUB_TOPIC_IND 0x21 MQTT subscribe the topic to borker indicate
ACK_TAG_CLOUD_MQTT_UNSUB_TOPIC_IND 0x22 MQTT unsubscribe the topic to borker indicate
ACK_TAG_CLOUD_MQTT_PUB_DATA_IND 0x23 MQTT publish the topic to borker indicate
ACK_TAG_CLOUD_MQTT_CLIENTID_SET 0x2E AWS mqtt clientID set
ACK_TAG_CLOUD_MQTT_LASTWILL_SET 0x2F AWS mqtt last will set
  • Module Sleep
Ack name Value Description
ACK_TAG_SLEEP 0x26 Enter sleep mode
ACK_TAG_SMART_SLEEP 0x27 Set module smart sleep
ACK_TAG_TIMER_SLEEP 0x28 Set module timer sleep
ACK_TAG_DEEP_SLEEP 0x29 Set module deep sleep
ACK_TAG_MODULE_WAKEUP 0x30 Response module wake up signal from smart sleep
ACK_TAG_TIMER_SLEEP_WAKEUP 0x37 Response module wake up signal from timer sleep
  • Trigger MCU Wakeup
Ack name Value Description
ACK_TAG_TRIGGER_MCU 0x28 Trigger MCU wakeup
ACK_TAG_HOST_READY 0x36 Module receive "at+hostready"
  • OTA
Ack name Value Description
ACK_TAG_MODULE_OTA 0x29 Set module OTA
ACK_TAG_OTA_START 0x2C Module OTA start
ACK_TAG_OTA_DONE 0x2D Module OTA done
  • HTTP Post & Get
Ack name Value Description
ACK_TAG_FILE_HTTP_POST_REQ 0x2A Http post request
ACK_TAG_FILE_HTTP_POST_RSP 0x2B Http post response
ACK_TAG_FILE_HTTP_GET_REQ 0x2C Http get request
ACK_TAG_FILE_HTTP_GET_RSP 0x2D Http get response
  • System
Ack name Value Description
ACK_TAG_MODULE_READY 0x30 OPL module ready
ACK_TAG_FW_VER 0x31 OPL firmware version

Scan List Ack Tag

Ack name Value Description
ACK_TAG_WIFI_SCAN_REQ 0x0E WiFi scan request
ACK_TAG_WIFI_SCAN_LIST_GET_REQ 0x0F WiFi scan result list request

MQTT Recv Ack Tag

Ack name Value Description
ACK_TAG_CLOUD_MQTT_RECV_DATA_IND 0x24 MQTT receive data indicate

File Ack Tag

Ack name Value Description
ACK_TAG_FILE_UPLOAD 0x25 Upload file for MQTT