Sequans Monarch LTE Modem User Guide

Overview

ThingSpace is the Internet of Things (IoT) platform that offers a complete end-to-end solution for onboarding and activating your devices on the Verizon Wireless network. The ThingSpace client is integrated on the Sequans Monarch Category M1 (Cat-M1) LTE modem. The combination of the LTE Cat-M1 capabilities of the Monarch modem with Verizon’s 4G LTE network and ThingSpace offers a simplified approach for building, deploying and managing IoT devices and applications, which can be customized for a widerange of IoT uses including asset management, industrial automation, wearables, smart cities and more.

5-network Development Platform. FiPy is the world’s first 5-network development platform for IoT. It is a hardware module that is programmable with MicroPython. It features LTE-M powered by Sequans’ Monarch LTE Platform and four other LPWA connections: Wi-Fi, Bluetooth, LoRa, and Sigfox. FiPy presents an open source firmware playground with. Mar 13, 2019 The aerospace giant Lockheed Martin is working with Sequans Communications to develop new LTE for satellite technologies. The two companies are enabling LTE end user devices to connect directly to.

Features include:

• Proprietary ATtention (AT) commands to interact with the embedded ThingSpace client
• Very light MCU load, and no TCP/IP stack required
• Diagnostics
• Security
• Capability of cloud messaging

Before you begin

There are a few things you will need to do before you can get started.

1. Go to core.thingspace.verizon.com/portal

Download Sequans Network Password

2. Use a company email to create a ThingSpace account.

3. Download the following tools:

Setting up ThingSpace

The ThingSpace Software Development Kit (SDK) is included in the Sequans Monarch modem software. Please ensure you are using the correct software version. To update your Sequans modem firmware, please see the Flashing modem firmware section. Once you have the right firmware version on your modem, review the ATtention (AT) commands specific for ThingSpace.

Flashing modem firmware

Update your firmware to VZM20Q-REV2-EVK-BBA1-RFA3-SKY6800031_VERIZON-MQTT- NOLPM_LR5.1.1.0-34030 or later. See documentation with your corresponding module maker.

If you are using the NimbleLink Skywire CAT-M1 chip, see firmware update documentation here

Important notes

In order to use the Sequans Monarch modem on the Verizon network, you need to establish a PDN to connect to the ThingSpace server.

NOTE:
In some cases, (depending on the SIM card), you may need to attach first the Admin PDN (cid=2) before the establishment of Internet PDN.

Change Attach PDN (persistent configuration)

Integrating certificates

Certificates are required to establish a secure connection between the client and server. These certificates can be obtained directly from the ThingSpace Portal.

Click here for more information on Certificates.

How to download certificates

1. Login to ThingSpace and click the Credentials tab.

2. Download the certificates.

3. Add these “cacert.pem, client-cert.pem and client-key.pem” files to the datatx folder.

Sequans Non-Volatile Data Commands

The commands listed in this section allow writing and reading data (Certificate, etc.) to and from the non-volatile (NV) memory or to and from the Flash File System. Stored NV data will be persistent against device reboot and software upgrades.

This command allows you to write and delete data (Certificate, etc.) to/from the non-volatile (NV) memory. Write command usage & syntax may change depending on the type of data to store.

AT+SQNSNVW='certificate',<index>,<size><CR><LF><data>

This write command with 'certificate' type should be used to write the certificate to non-volatile memory. After the certificate is uploaded to your modem, public certificates are immediately available for all client secured IP connections (+SQNSUPGRADE, Secured socket). For secured socket in server mode, certificate <index> should be used to assign private certificate to secure server.

• An <index> will be used by the system to identify the certificate for future operations (delete, etc.)
• The <size> parameter corresponds to the exact number of bytes of the certificate to upload.

After AT+SQNSNVW write command issued, send certificates to the modem in Privacy-enhanced Electronic Mail (PEM) format. As soon as <size> bytes have been received, operation is automatically completed. If the certificate is successfully uploaded and verified, then the response is OK. If the certification upload fails, then an error code is reported. To delete a certificate, write a 0 byte certificate using certification ID as <index>.

AT+SQNSNVW='privatekey',<index>,<size><CR><LF><data>

This write command with 'privatekey' type will write a private key in PEM format to the non-volatile memory. Private keys are used by +SQNSJWTENCODE command.

NOTE:
Private RSA keys with password are not supported.

Adding ThingSpace Certificates to the Monarch modem

Before execution of any ThingSpace specific AT commands the TLS data must be uploaded to the device with following commands:

NOTE:
By default, the client ID will be an IMEI code from the device. All MQTT topics used for interactions between the ThingSpace cloud server are based on the client ID.

NOTE:
ThingSpace provides certificates and private keys files with CRLF (carriage return and line feed) line-ending. The <size> of the certificate or the private key must be the size of the appropriate file after removing CR (carriage return) from it. To remove CR use linux command: tr -d 015 < file_with_cr > no_cr_file

Sending and receiving data

The Sequans Monarch ThingSpace integration leverages ATtention (AT) commands to simplify the integration effort with applications.

The logic of this solution can be viewed on the example below:

Configure MQTT ThingSpace Client: +VZWTSCFG

Description

This command allows you to configure your ThingSpace implementation modem with the ThingSpace server.

Defined values

<enabled>

1 or 0. To enable use 1, to disable use 0 respectively.

simpm.thingspace.verizon

ThingSpace server name. Make sure you loaded appropriate certificates before use.

8883

Port number. TLS is applied and cannot be removed. Default port 8883 is used, assigned by IANA.

<AT+SQNSMQTTCLIENTCONNECT>

Initiate MQTT connection to a broker.

Incoming Unsolicited Result Code (URC) for activation: +VZWTSUNITONBOARDREQ:

Possible Requests(s)

Description

This is an asynchronous URC indicating that wireless service has been activated for the device.

Reports Current Sensor Definition: +VZWTSUNITONBOARDRSP

Description

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

Defined values

<bytes>

Number of bytes used in JSON.

Incoming URC for command request: +VZWTSUNITCMDREQ

Possible Requests(s)

++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

Download Sequans Network & Wireless Cards Drivers

<UCD>

Unit command. Set, Get, GetOtp, SetOtp

<CUUID>

Command uuid

<CNAME>

Characteristic name

<VALUE>

Characteristic value (for Set)

Responding to a Server Request: +VZWTSUNITCMDRSP

Description

Here is a response:

{

'unitCommand': '<UCD>',
'statusMsg': '<SMG>',
'statusCode': '<SCD>',
'commandUUID': '<SMG>',

}

Defined values

<UCD>

Unit command. Set, Get, GetOtp, SetOtp

<CUUID>

Command uuid

<SCD>

Status code

<SMG>

Status message

Responding to a Server Request with a Payload: +VZWTSUNITCMDPLDRSP

Description

Set response to specific request from the server.

Example 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': '8991101200003204510',
'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': 'Sequans 3330',
'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
}
}

Download Sequans Network App

}

Defined values

<UCD>

Unit command. Set, Get, GetOtp, SetOtp

<CUUID>

Command uuid

<SCD>

Status code

<SMG>

Status message

<plsize>

Payload size

<Payload>

JSON payload

Running the ThingSpace Sample App

Verizon provides a temperature sensor ThingSpace End Device application template script written in Python. You must install Python 2.7 or later and pyserial to run the script. This script automatically reports sensor, MCU, and modem diagnostic data to ThingSpace every 5 seconds. The temperatureSensor.py application simulates a temperature sensor (ts.device.sdk.thermometer) and reports temperatures periodically to the ThingSpace server. The TemperatureSensor.py script requires the pySerial module.

NOTE:
The modem needs to establish Internet PDN to connect the ThingSpace server.
See Flashing the modem firmware section for more information.

End-device is connected to the Monarch modem through UART0 (921600 bauds, HW flow control) and communicates using an AT interface. A debug PC can be connected to the Monarch console through UART1 (115200 bauds, no flow control).

For Monarch test kit usage, please refer to dedicated documentation:

• Sequans test kit user manual: VZM20Q-TestKitUserManual_B4-B13_Rev2.pdf
• Nimbelink test kit user manual: 30192_NL-M1DK_UserManual.pdf

usage: temperatureSensor.py [-h] [-p PORT] [-V] [-r BAUDRATE]
[--ca CA] [--cert CERT] [--key KEY]
[--uid UID] [--name NAME]
[--report REPORT]
Temperature sensor (ts.device.sdk.thermometer) Thingspace End Device application template script.
optional arguments:
-h, --help show this help message and exit
-p PORT, --port PORT serial port name (e.g., COM17 or /dev/ttyUSB1)
-V, --verbose Enable verbose mode
-r BAUDRATE, --baudrate BAUDRATE
serial port baud rate
--ca CA ThingSpace Root CA
--cert CERT ThingSpace Client Cert
--key KEY ThingSpace Client Key
--uid UID ThingSpace Device Uuid
--name NAME ThingSpace Device Name
--report REPORT Temperature reporting period in seconds (0 for no reporting)

Creating a device on ThingSpace

In order for the ThingSpace platform to receive data from your device and associate your device with a certificate, you need to create a new device on ThingSpace.

To create a new device on ThingSpace, visit the ThingSpace Portal Guide.

End-device connection

1. Connect the End-Device (test PC) to the Sequans test kit.

• UART0 (921600 bauds, HW flow control): AT command
• UART1 (115200 bauds, no flow control): Monarch console (Optional)

2. Power on the VZM20Q test kit.

3. Open the interactive shell to launch the ThingSpace End-Device sample application command line (temperatureSensor.py script)

To establish the connection, upload the Server CA certificate, client certificate and private key to the Monarch device.

To learn more about certificates see Integrating Certificates.

User can directly exercise AT commands or delegate the job to temperatureSensor.py script (automatizes usage of same AT command).

Configuring certificates with the temperature sensor script

You can use the temperatureSensoer.py script to load new certificates and keys to the modem. Each time certificates and keys are provided on the command line; ThingSpace certificates will be overwritten by new certificates and keys.

Launching the script without security data previously configured in the module will generate the following errors:

!WARN! ThingSpace Root CA certificate is absent, please upload it using --ca option
!WARN! ThingSpace Client certificate is absent, please upload it using --cert option
!WARN! ThingSpace Client private key is absent, please upload it using --key option

To load security material, use the command line options below:

This command will upload certificates and keys to the LTE module, and check connections to ThingSpace.

NOTE:
In your terminal logs, '+VZWTSCONNECT: 1' state means that connection has been established successfully with the ThingSpace server.

Download Sequans Network Login

Testing and Validation

ThingSpace logs are displayed in your modem terminal by default

NOTE:
You need to create a ThingSpace account and download and install the certificates before testing and validation.

temperatureSensor.py -p COM20 -r 921600 --name mySuperThermometer --uid c49153be-de94-6f5d- eec0-8f94e1d98fc4
Write : 'AT+VZWTSCONNECT?'
Read : '<LF><CR>'
Read : +VZWTSCONNECT: 1 '<LF><CR>'
Read : '<LF><CR>'
Read : 'OK<LF><CR>'

NOTE:
If you have not activated your device on ThingSpace, see the Activating Devices section of the ThingSpace Portal Guide

Device communication server testing

1. Launch the ThingSpace End-Device sample command line application (temperatureSensor.py script).

2. Wait for the connection (ensure certificates are added and the device is activated in ThingSpace).

temperatureSensor.py -p COM20 -r 921600 --name mySuperThermometer --uid c49153be-de94-6f5d- eec0-8f94e1d98fc4
[...]
Write : 'AT+VZWTSCONNECT?'
Read : '<LF><CR>'
Read : +VZWTSCONNECT: 1 '<LF><CR>'
Read : '<LF><CR>'
Read : 'OK<LF><CR>'

3. Open the ThingSpace portal Devices page.

4. Click on the device UID to access the Device Details page.

5. Select the Properties panel.

6. Use the drop-down menu to select a property you want to configure.

7. Click in the Value box and set a new value.

8. Click on the Add green button. The Set Device Properties widget appears.

9. Click on the Set green button. The response status will display when the action is complete on the server side.

10. End-Device receives set message.

Thu Dec 14 14:35:03 2017 >EXE> Read :
'+VZWTSUNITCMDREQ:'Set','358227051529086_g8u3qyiz','temperature','1234'

11. Answer with Set OK message.

Device property SET request handler
CUUID: 358227051529086_g8u3qyiz
CNAME: 'temperature'
VALUE: 1234
Reset device temperature to 1234
Write : 'AT+VZWTSUNITCMDRSP='Set','358227051529086_g8u3qyiz','200','OK'
Read : '<LF><CR>'
Read : 'OK<LF><CR>'

12. Corresponding raw messages can be viewed on your device.

I [SQNSMQTT] sqnsmqtt_message_callback @ mqttclient.cc:331: MQTT RX: Received new message:'{'unitCommand':'Set','commandUUID':'358227051529086_g8u3qyiz','characteristicsName':'temper ature','value':'1234'}' from topic 'ThingspaceSDK/358227051529086/TSServerPublishCommand'
I [SQNSMQTT] sqnsmqtt_message_callback @ mqttclient.cc:338: Calling external handler (0x0x1c46ae60) for new incomming message for client (0) with result (0)
I [VZWTS] vzwOnNewIncommingMsgCbk @ vzwts_at.cc:420: Incoming message to 'TSServerPublishCommand' from the broker
I [VZWTS] atVzwTsUnitCmdRspHandler @ vzwts_at.cc:582: New JSON: {'unitCommand':'Set','commandUUID':'358227051529086_g8u3qyiz','statusCode':'200','statusMsg' :'OK'}
I [SQNSMQTT] sqnsmqtt_client_publish @ mqttclient.cc:705: MQTT TX: Client (0) publishing payload ({'unitCommand':'Set','commandUUID':'358227051529086_g8u3qyiz','statusCode':'200','statusMsg ':'OK'}) into topic (ThingspaceSDK/358227051529086_g8u3qyiz/UNITCmdResponse), with QoS 0 (at most once)
D [SQNSMQTT] sqnsmqtt_log_callback @ mqttclient.cc:264: Client 358227051529086 sending PUBLISH (d0, q0, r1, m3, 'ThingspaceSDK/358227051529086_g8u3qyiz/UNITCmdResponse', ... (98 bytes))
I [SQNSMQTT] sqnsmqtt_publish_callback @ mqttclient.cc:289: Publish confirmed. PUBLISH CONFIRMATION HANDLER DOES NOTHING BY DEFAULT, to override use publish_callback