Sequans Monarch AT Commands Reference Guide

Sequans Monarch AT Commands Reference Guide

Introduction

Sequans Monarch Category M1 (Cat-M1) LTE Modem is a slim modem for cost-sensitive applications. It features an embedded ThingSpace client that enables ThingSpace IoT device management capabilities on products with very light MCU, without TCP/IP stack support. Your applications can interact with the ThingSpace client using the Sequans AT commands described in this guide.

This API reference guide specifies the complete list of AT commands for use with the Sequans Monarch Category M1 (Cat-M1) LTE Modem and the ThingSpace device management solution. The guide is intended for engineers using the Sequans Monarch Category M1 (Cat-M1) LTE Modem during the development and test phases of IoT solution development.


Bulb Demo with Embedded ThingSpace Client

In this section we describe how to connect and control a ThingSpace device from the ThingSpace portal and through Monarch’s embedded ThingSpace client.

To connect to the ThingSpace server, the Monarch device must establish a connection to the Internet PDN1.

1. Boot and make sure the board is connected to the Internet PDN. See your module vendor documentation for more details on how to connect to the Verizon network.

2. Type AT+VZWTSTEST=1.

3. Open the ThingSpace device management portal.

4. Set unitState property to True, then press Add and Set. You should see a bulb report in terminal.

1Public Data Network


Configuring ThingSpace Secure Connection

ThingSpace requires clients to establish a secure TLS2 connection with an MQTT3 broker. Perform the following tasks to establish the connection.

  1. Obtain a TLS CA4 certificate and private key for the Monarch device from the ThingSpace device management portal.
  2. Remove carriage returns from the certificate and private key files.
    ThingSpace issues certificates and private keys files with CRLF (carriage return and line feed) line-endings. But the <size> of the certificate and the private key in the AT+SQNSNVW commands must be the size after removing the carriage returns. To remove CRs, use Linux command:
  3. tr -d \015 < file_with_cr > <no_cr_file>

  4. Use the Sequans Non-Volatile Data Write commands in the table below to upload the certificate authority, certificate, and private key to the device.
    Notes:
    The syntax of the Sequans Non-Volatile Data Write command is:
  5. AT+SQNSNVW=<type>,<index>,<size><CR><LF><data>

    where

    <size> is the exact number of bytes of the certificate in PEM5 format, after removing carriage returns as described above.

    <index>is 0 for Verizon ThingSpace root certificate authority, 1 for certificate, and 2 for private key.

    If the certificate is successfully uploaded and verified, then the response is OK. If the certificate upload fails for some reason, then an error code is reported.

    To delete a certificate, one should simply write a 0-byte certificate using certification ID as <index>. For example:

    AT+SQNSNVW="certificate",1,0

Command Description Comment

AT+SQNSNVW="certificate",0,<size><CR><LF><ThingsSpace_CA_data>
Example:

AT+SQNSNVW="certificate",0,1346 AT+SQNSNVW="certificate",0,1346
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiIMA0GCSqGSIb3DfBAYTAkFVMRMwEQYDVQQ
IDApTb21lLVN0YXRlMSEwHwYDVx[…]C3Fayua4DRHyZOLmlvQ6tIChY0ClXXuefbm
VSDeUHwc8YuB7xxt8BVc69rLeHV15A0qyx77CLSj3tCx2IUXVqRs5mlSbvA=
=
-----END CERTIFICATE-----

Uploads Verizon
ThingSpace Root CA.

Verizon ThingSpace
Root CA ID must be 0.

AT+SQNSNVW="privatekey",2,<size><CR><LF><Private_Key_data>

Uploads the device
private key.

Device private
key ID must be 2.

AT+SQNSNVW="certificate",1,<size><CR><LF><Certificate_data><Certificate_data>

Uploads the
device certification.

Device certificate
ID must be 1.

2Transport Layer Security

3MQ Telemetry Transport

4Certificate Authority

5Privacy-enhanced Electronic Mail


Verizon MQTT AT Commands

Quick Reference

Command Name Description Comment
+VZWTSCFG Configures MQTT Verizon client.

XXX

+SQNSMQTTCLIENTCONNECT Initiate MQTT connection to a broker.

XXX

+VZWTSUNITONBOARDREQ Request to the MCU to provide the current sensor definition. URC triggered by receiving activation request
+VZWTSUNITONBOARDRSP Sends a JSON into ThingspaceSDK/<IMEI>/UNITOnBoard

XXX

+VZWTSUNITCMDREQ Forwards a unit command to the MCU. URC to process unit commands such as Set, getOtps
+VZWTSUNITCMDRSP Response to specific request from the server.

XXX

+VZWTSUNITCMDPLDRSP Response to a specific request from the server with custom payload.

XXX

+VZWTSCFG

Configures the ThingSpace MQTT client.

Syntax

Command Possible Responses
AT+VZWTSCFG=<enabled>[,<MQTT URL>[,MQTT PORT]] OK
ERROR
+AT+VZWTSCFG=? +VZWTSCFG=<enabled>[,<MQTT URL>[,MQTT PORT]]

Description

This command allows you to configure the Verizon MQTT client to work with ThingSpace cloud server. All MQTT topics which are used for interactions with the ThingSpace cloud server are based on clientid. By default the client ID will be an IMEI code from the device.

Defined values

<enabled> 1 or 0. To enable use 1, to disable use 0.
<MQTT URL> ThingSpace server name.
NOTE: Make sure you loaded appropriate certificates before use.
<MQTT PORT> Port number. TLS is applied and cannot be removed. Default port 8883 is used, assigned by IANA.

+SQNSMQTTCLIENTCONNECT

Initiate MQTT connection to a broker.

+VZWTSUNITONBOARDREQ

Incoming URC for activation request.

Syntax

Possible Requests
+VZWTSUNITONBOARDREQ

Description

This is an asynchronous URC which comes upon remote device activation.

+VZWTSUNITONBOARDRSP

Reports current sensor definition.

Syntax

Command Possible Responses
AT+VZWTSUNITONBOARDRSP=<bytes>,<CR><JSON> OK
ERROR
AT+VZWTSUNITONBOARDRSP=? +VZWTSUNITONBOARDRSP=<bytes>,<CR><JSON>

Description

This predefined message will be reported after client has successfully connected.

Defined values

<bytes> Number of bytes used in JSON.

+VZWTSUNITCMDREQ

Incoming URC for command request.

Syntax

Possible Requests
+VZWTSUNITCMDREQ=<UCD>,<CUUID>[,<CNAME>][,<VALUE>]

Description

This is an asynchronous URC which comes upon remote command request in topic
ThingspaceSDK/<IMEI>/TSServerPublishCommand.
URC request examples:
+VZWTSUNITCMDREQ="GetOtp","00000000-0000-0000-C000-446655440000"
+VZWTSUNITCMDREQ="Set","00000000-0000-0000-C000-446655440000","unitState","false"
+VZWTSUNITCMDREQ="Get","00000000-0000-0000-C000-446655440000","MovementEvent"

Defined values

<UCD> Unit command. Set, Get, GetOtp, SetOtp
<CUUID> Command uuid
<CNAME> Characteristic name
<VALUE> Characteristic value (for Set)

+VZWTSUNITCMDRSP

Responds to a server request.

Syntax

Command Possible Requests
AT+VZWTSUNITCMDRSP=<UCD>,<CUUID>,<SCD>,<SMG> OK
ERROR
AT+COMMAND=? +VZWTSUNITCMDRSP=<UCD>,<CUUID>,<SCD>,<SMG>

Description

Response:
{

"unitCommand": "<UCD>",
"statusMsg": "<SMG>",
"statusCode": "<SCD>",
"commandUUID": "<CUUID>"

}

Defined values

<UCD> Unit command. Set, Get, GetOtp, SetOtp
<CUUID> Command uuid
<SCD> Status code
<SMG> Status message

+VZWTSUNITCMDPLDRSP

Responds to a server request with a payload.

Syntax

Command Possible Responses
AT+VZWTSUNITCMDPLDRSP=<UCD>,<CUUID>,<SCD>,<SMG><CR>,<plsize>,<payload> OK
ERROR
AT+VZWTSUNITCMDPLDRSP=? +VZWTSUNITCMDPLDRSP=<UCD>,<CUUID>,<SCD>,<SMG><CR>,<plsize>,<payload>

Description

Response:
{

"unitCommand": "GetOtp",
"characteristicsName": "DevcieInfo",
"commandUUID": "00000000-0000-0000-C000-446655440000",
"statusMsg": "OK",
"statusCode": 200,
"payload": {

"DeviceInfo": {

"Baseband Version": "1.0.0",
"Build ID": "abc123",
"Device ID": "abc123",
"ICCID": "MMCCIINNNNNNNNNNNNCx",
"IMEI": "359223015426526",
"IMSI": "250-07-ХХХХХХХХХХ",
"Kernel Version": "4.x.y",
"Language": "en",
"Last Power On": "MM-DD-YYYY HH:MM:SS",
"Manufacturer": "Verizon",
"Model": "vas-model-1",
"Chipset": "MDM9206",
"NFC": "Off",
"Network Location Provider": "Off",
"OS Version": "6.0.0",
"Rooted": "yes",
"Screen Size": "1920*1080",
"Screen Timeout": "10",
"Standalone GPS": "off",
"Time Zone": 3

}

}

}

Defined values

<UCD> Unit command. Set, Get, GetOtp, SetOtp
<CUUID> Command uuid
<SCD> Status code
<SMG> Status message
<plsize> Payload size
<payload> JSON payload

6Unsolicited Result Code