Introduction

To help developers to start with the NB-IoT module "uBlox SARA N211" (NB-IoT module for Europe; Cat NB1; Band 8, 20; ATEX certified) you can use the developer kit (devkit) SODAQ SARA Arduino Form Factor (AFF) N211 (see https://shop.sodaq.com/sodaq-sara-aff-n211.html).

Links

Links to the AT command samples:

• Query device information
• Setup network configuration and verification
• Send "Hallo World" via UDP
• Receive "Hallo Device" via UDP

Setup the Device

In the following I will describe you how to setup your devkit so that you are able to send AT commands directly from your computer to the ublox modem. To do so you need to

1. connect your your devkit with your computer via USB,
2. install AT command passthrough sketch on your devkit and
3. execute AT commands on your devkit the first time.

Connect your devkit with your computer

Your devkit will be connected with your compute by using mini USB and can be accessed with a terminal program such as "putty" on Windows or "screen" or "minicom" on Linux.

In case you are working with Linux your are lucky. The USB/Serial drivers should be already available on your system and you don't need to install anything else.
After you connected your devkit via USB with your computer you should find the device file
/dev/ttyACM0 (or /dev/ttyUSB0). It is automatically created when you connect your devkit with your computer and if you disconnects it your devkit disappears again.

Unfortunately I can not tell you how to enable the serial terminal connection via USB on Window or Mac because I am only working with Linux. Sorry :disappointed_relieved:.

Install AT command passthrough sketch on your devkit

In contrast to other devkits the SODAQ SARA AFF N211 is not delivered to you with an out-of-the-box capability that AT commands on the serial USB interface are directly passed through to the modem. Out of this reason you need to install the passthrough sketch for SODAQ on your devkit first

Install Arduino IDE on your computer

The passthrough sketch is Arduino source code written in "C". To compile and to upload it to your devkit you need to install the Arduino IDE on your computer first.
You can download the latest version of Arduino IDE from

https://www.arduino.cc/en/Main/Software.

Make sure you install or update the latest version of Arduino IDE.
When your Arduino IDE is installed, it might be necessary to restart your computer. In some cases, if you don’t restart your computer, the IDE will not launch.

Configure Arduino IDE for SODAQ SARA AFF N211

After you installed or updated your Arduino IDE you need to configure your Arduino IDE with the Board Files for the SODAQ SARA AFF N211. Please follow the SODAQ setup guide which you can find at

https://learn.sodaq.com/getting_started/.

Compile and upload passthrough sketch to your devkit

As mentioned before the passthrough sketch is "C" source code for Arduino. The sketch which passes the AT commands from the serial terminal interface directly through to the modem you can get from

https://learn.sodaq.com/Boards/Sara_AFF/Examples/passthrough/.

To compile and upload the sketch perform the following steps:

1. In Linux shell: Start Arduino IDE on your computer by executing the command arduino.
2. In Arduino IDE: Create a new sketch by executing File/New.
3. In Arduino IDE: Replace the complete default code in the new sketch with the code which you can copy from https://learn.sodaq.com/Boards/Sara_AFF/Examples/passthrough/ (see image below)
4. In Arduino IDE: Compile the code by executing Sketch/Compile ( see image below)
5. On your Computer: Connect the devkit with your compute via USB
6. In Arduino IDE: Upload the compiled sketch by executing Sketch/Upload (see image below)

Execute AT commands on your devkit the first time.

To execute AT commands on your devkit you need start on your computer a terminal program such as putty on Windows or minicom or screen on Linux and connect it with your devkit via the serial USB line. After this you can send AT commands to the modem of your devkit.

In the following I will explain to you how to do this stuff on Linux by using the minicom and to send those AT commands to the modem to query device product and IMEI information.

📘

I tryed to use screen as terminal progam instead of minicom. But for any reason I couldn't activate the local echo of my input on the terminal window. Out of this reason I use minicom for SODAQ devices.
If you can activate the local echo of your input with screen please let me know, I am highly interested in it.

Connect your devkit with your Linux computer via terminal program minicom

In case minicom is not already installed on your computer you can install it with

$ sudo apt-get install minicom

After that you can configure minicom by executing

$ sudo minicom -s

🚧

It is important that you run the configuration of minicom as root because the resulting configuration file will be stored in the directory /etc/minicom to which root has only write permissions.

In the minicom configuration menu change the following settings:

• Enter Serial port setup
  • Set Serial Device to /dev/ttyACM0
  • Set the baudrate (Bps/Par/Bits) to 9600 8N1
• Enter Screen and keyboard
  • Set Local echo to Yes
• Enter Save setup as
  • Give sodaq as the name to save the configuration
• Enter Exit from Minicom

After configuring minicom for your SODAQ devkit you can start minicom with the configuration *sodaq'* which just created before.

$ minicom sodaq

📘

In case you have any problems to access the device file /dev/ttyACM0 because you don't have enough access privilages for this file execute the following command

$ sudo usermod -a -G dialout YOUR-USER-NAME

As very first AT command you should input the command AT. This command shall always return OK. If not, there is something wrong.

AT

OK

👍

Congratulations

If you reached this point you equipt your SODAQ SARA AFF N211 with the capabiltiy to pass your AT commands from the serial USB terminal interface directly through to the ublox modem.

Now the fun begins!

AT Commands to get IMEI, IMSI and other product information from your devkit

In the following various AT commands are shown to query the IMEI and other product information from your devkit.

📘

If you deal with AT commands for the ublox SARA N2 and N3 series I recommand always have the ublox AT command documentation

https://content.u-blox.com/sites/default/files/SARA-N2-N3_ATCommands_UBX-16014887.pdf

closed to you.

# Request IMEI
AT+CGSN=1
                                                                                
+CGSN: 357518080495450

OK

# Request IMSI of the SIM card
AT+CIMI

901405700009293

OK

# Request SIM card identification number
AT+CCID

+CCID: 89882280000001294327

OK

# Device statistics
AT+NUESTATS

"Signal power",-1093                                                            
"Total power",-1016                                                             
"TX power",230                                                                  
"TX time",44903                                                                 
"RX time",310684                                                                
"Cell ID",26926859                                                              
"ECL",1                                                                         
"SNR",64                                                                        
"EARFCN",3740                                                                   
"PCI",171                                                                       
"RSRQ",-116                                                                     
                                                                                
OK                                    
# Request manufacturer identification
AT+CGMI

u-blox

OK

# Rquest model identification 
AT+CGMM

SARA-N211

OK

# Request firmware version identification  
AT+CGMR

06.57

OK

# Request prodct type number
ATI

SARA-N211-02X-02

OK

# Request the version of the modem and the application
ATI9

06.57,A10.08

OK

Attach to the NB-IoT Network

This chapter explains how you can attach your SODAQ SARA AFF N211 devkit to the NB-IoT network. I recommend to read the chapter "Setup SODAQ SARA AFF N211" first.

🚧

If you are only interested in the conclusion of the AT commands to configure the network setup go to chapter "'AT Commands Only"

❗️

Before you send any UDP or COAP message to IoT Creators make sure you registered the device IMEI before.

If you forget, you will have problems to register your device afterwards. In this case please get in contact with IoT Creators support team.

A few assumptions and notes before starting with this manual

• You should be able to send AT commands to your devkit with a terminal program such as putty, screen, minicom, etc.
• Your device is on the latest firmware
• Be gentle to your device and have some patience. After each AT command he/she/it needs a few seconds to execute the command and respond

In the following we will walk through together the AT commands with which you can perform the following actions:

• Setup network configuration of you devkit.
• Attach to the network and verify your network configuration.
• Ping an IP address.

Setup Network Configuration

After switching on your devkit deactivate the radio functionality with +CFUN. You should do this to make sure no miss-configured automatic dial-in action make your setup difficult.

AT+CFUN=0

Switch on some basic configuration parameters of the modem with +NCONFIGsuch as autoconnect, scambling.

AT+NCONFIG="AUTOCONNECT","TRUE"

AT+NCONFIG="CR_0354_0338_SCRAMBLING","TRUE"

AT+NCONFIG="CR_0859_SI_AVOID","TRUE"

❗️

Roaming via Vodafone in UK

In case of romaing via Vodafone in UK you probably need to use AT+NCONFIG="CR_0859_SI_AVOID","FALSE".

Set the APN of IoT Creators with +CGDCONT to cdp.iot.t-mobile.nl.

AT+CGDCONT=0,"IP","cdp.iot.t-mobile.nl"

Sometimes you get an ERROR response of the +CGDCONT command. Reason for this can be that the radio is not deactivated with +CFUN=0 and the modem already attached to the network. In this case just deactivat the radio and try it again.

Set the bands with +NBANDcommand.

AT+NBAND=8,20

Set the EPS network registration status with +CEREG command.

AT+CEREG=5

Select the network operator of your choice with +COPS command manually (1) by given the numeric identification (2) of the operator ("26201", "20416", "26002", etc.)

AT+COPS=1,2,"26201"

AT+COPS=1,2,"20416"

AT+COPS=1,2,"26002"

👍

Great! Your setup of network configuration is complete now.

The next step is it to test if it is correct and if your devkit is able to attach the network with it.

Good Luck

The setup of the network configuration is complete. Because we deactivated the radio in the
beginning with +CFUN=0 nothing should happen so far.
To see your configuration in action you can trigger a reboot of your devkit with the +NRB command.

AT+NRB

After you triggered the reboot with ```+NRB you should see the following on your terminal and your devkit should attach to the network automatically.

REBOOTING
�
REBOOT_CAUSE_APPLICATION_AT
u-blox 
OK

+UFOTAS: 0,1

As next we will verify if your devkit is actually attached to the network and verify the network configuration with some more AT commands.

Attach to the Network and verify your Network Configuration

After you have rebooted your devkit the most interesting question is if your devkit got an IP address assigned by the network.
You can query the assigned IP address from your devkit with the +CGPADDR command.

AT+CGPADDR

+CGPADDR: 0,"10.128.1.157"
OK

As the result your devkit returns the current IP address. In this sample it is 10.128.1.157

📘

What to do if it doesn't work

If you are not able to get established a network attachment double check the following

• Did you configure the correct APN?
• Did you configure the correct mobile network operator in your country?
• Did you make sure your SIM card has active roaming in case you are not in the home country of your network operator?

AT Commands to query Network Information

In the following I show you some more AT commands with which you can query other information regarding mobile connection status.

# Query if the devkit is attached to the network
AT+CGATT?
+CGATT: 1
OK

# Query the configured MNO (Mobile Network Operator)
AT+COPS?
+COPS: 0,2,"26201"
OK

# Query the configured APN
AT+CGDCONT?
+CGDCONT: 0,"IP","cdp.iot.t-mobile.nl",,0,0,,,,,0
OK

# Query the configuration
AT+NCONFIG?
+NCONFIG: "AUTOCONNECT","TRUE"
+NCONFIG: "CR_0354_0338_SCRAMBLING","TRUE"
+NCONFIG: "CR_0859_SI_AVOID","TRUE"
+NCONFIG: "COMBINE_ATTACH","FALSE"
+NCONFIG: "CELL_RESELECTION","FALSE"
+NCONFIG: "ENABLE_BIP","FALSE"
+NCONFIG: "NAS_SIM_POWER_SAVING_ENABLE","TRUE"
+NCONFIG: "RLF_UPDATE","FALSE"
OK

# Query signal power and quality
# Power should be between 0-31 and NOT 99. 99 means "no network detactable"
# Quality should be between 0-9. 99 means not know or not detactable.
AT+CSQ
+CSQ: 9,99
OK

Ping the first IP address

With the AT+CGPADDR command you could query the current IP address of your devkit. But you still not know if your devkit is able communicate in the IP network correctly.
To test this you should ping the UDP server of IoT Creators platform with th +NPING command.

AT+NPING="172.27.131.100"

OK

+NPING: "172.27.131.100",253,7478

In case your devkit could ping the given IP address response will be
´´´
+NPINGERR: 1
´´´

👍

Congratulations

If you reached this point and if you were able to ping successfully the IoT Creators' UDP server you reached a very important milestone.

Experience has shown that most of the problems arise during the devkit commissioning and the first attachment with the network.

The rest journey the next steps of the tutorial will be easy

AT Commands Only

#######################################################################
# Network attach
#######################################################################
# Switch off radio
AT+CFUN=0

# Switch autoconnect and scrambling on:
AT+NCONFIG="AUTOCONNECT","TRUE"
AT+NCONFIG="CR_0354_0338_SCRAMBLING","TRUE"
AT+NCONFIG="CR_0859_SI_AVOID","TRUE"

# Set the APN
AT+CGDCONT=0,"IP","cdp.iot.t-mobile.nl"

# Set the bands
AT+NBAND=8

# EPS network registration status
AT+CEREG=2

# select an operator DE:"26201", NL:"20416"
AT+COPS=1,2,"26201"

# Reboot the device
AT+NRB

#######################################################################
# Network attach verification
#######################################################################
# Check IP address
AT+CGPADDR

# Check if attached to network
AT+CGATT?

# Check MNO
AT+COPS?

# Check APN
AT+CGDCONT?

# Check the configuration
AT+NCONFIG?

# Check signal strength and qualitay
AT+CSQ

# Device statistics
AT+NUESTATS

# Extended error report
AT+CEER

#######################################################################
# Ping UDP server of IoT Creators
#######################################################################
AT+NPING="172.27.131.100"

Send and Receive via UDP

In the following chapters I will explain to you how you can send a "Hello World" message from the device to the IoT Creators SCS and how you can receive a a "Hello Device" message on your devkit from IoT Creators SCS via UDP.

Send "Hello World"

❗️

Register your device first!

Make sure that you have registered your device with its IMEI at the IoT Creators portal BEFORE you send your first message to the UDP or CoAP server of IoT Creators.

If you forget, you will have problems to register your device afterwards. In this case please get in contact with IoT Creators support team.

Welcome to this step of tutorial. You probably ended up here because you could successfully connect your devkit to the network.
Before you continue make sure your device has an IP address assigned and you can ping the UDP server of IoT Creators. You test both with the +CGPADDR and the +NPING command.

AT+CGPADDR
+CGPADDR: 0,"10.128.4.109"
OK

AT+NPING="172.27.131.100"
OK
+NPING: "172.27.131.100",253,2396

In the next steps you will

• Open local UDP socket to send UDP messages.
• Create a hex coded "Hello World" message.
• Send the hex coded "Hello World" message to the UDP server of IoT Creators.
• Verify if the messages has been arrived at the IoT Creators platform.

Open local UDP Socket to send message

To send UDP messages to a UDP server you need to open a local UDP socket. For this you can use the +NSOCR command. The returned value of this command ("0" in the sample below) represents the identifier of the opened socket.

AT+NSOCR="DGRAM",17,7000,1

0
OK

The +NSOCR command opens a UDP socket with the following parameters:

To close the UDP socket you can use the command +NSOCL later. The "0" as command parameter references the socket identifier as it has been returned by the +NSOCR command before.

AT+NSOCL=0

OK

Create a HEX coded "Hello World" Message

I recommand not to send plain text or binary data from the device to your backend applications or vice versa. You can use a hex or a base64 encoding format of data. In our sample we send Hello World as a hex converted string to the IoT Creators.

To convert Hello World you can use online tool http://string-functions.com/string-hex.aspx

The hex string for Hello World is 48656c6c6f20576f726c64.

Sending HEX coded "Hello World" Message to UDP Server

To let your device sent this message via UDP to the UDP server of IoT Creators you can use the +NSOST command as shown in the following.
The +NSOST command returns the socket identification as a first digiti and the length of successfully sent data as second digit.

AT+NSOST=0,"172.27.131.100",15683,11,"48656c6c6f20576f726c64"

0,11
OK

The +NSOST command sends a UDP message with the following parameters:

👍

CONGRATULATIONS

If you see OK on the device console CONGRATULATIONS! you just send your first UDP message from your device to an UDP server of IoT Creators.

📘

The data length which is assigned to the command AT+NSOST describes the length of the original data. It does NOT desribes the length of the data in hex format which has a length of 22 bytes in the "Hello World" case.

View the received Messages in IoT Creators Portal

For each device the IoT Creators Portal makes the laste received message available by showing it in the Payload column. In case of our Hello World message

If you click on the payload the value of it is copied to the clipboard.

As already mentioned above it is a nice behaviour to transfer strings and binary data not as they are. It is better to encode them to hex or base64 for the transfer.
We sent our Hello World as hex encoded string on its way. Out if this reason we see in the IoT Creators Portal the string 48656c6c6f20576f726c64.

To decode the received message back from hex to a readable string we can use the online tool http://string-functions.com/hex-string.aspx.

👍

CONGRATULATIONS

If you can decode your received message to Hello World **CONGRATULATIONS**! You just sent your first UDP message from your device via NB-IoT to IoT Creators platform.

🚧

Maybe you have to send the first message twice. The first message will be considered as a registration message, so the it will not be forwarded to the GUI.

AT Commands to send Hello World

# Open local UDP socket on port 7000
AT+NSOCR="DGRAM",17,7000,1
0
OK

# Send UDP message to UDP server via socket=0
AT+NSOST=0,"172.27.131.100",15683,11,"48656c6c6f20576f726c64"
0,11
OK

# Close socket=0
AT+NSOCL=0
OK

Receive "Hello Device"

Welcome back to the tutorial .
In this step I will explain you how you can receive the "Hello Device" downlink message 48656c6c6f20446576696365 via UDP which you have posted before to the IoT Creators platform.

The downlink message which you posted to IoT Creators API before is queued by the IoT Creators platform. The queued downlink message is sent to the device after IoT Creators platform received the uplink message from the device.

In this tutorial you will perform the following steps:

• Open local UDP socket.
• Send a "i am alive" heartbeat message via UDP to the UDP server of IoT Creators.
• Receive the previous queued "Hello Device" message from the IoT Creators platform.

Open local UDP socket and send "i am alive" heartbeat

As already described in chapter 4 of this tutorial you can open the UDP socket and send a UDP message with the commands +NSOCR and NSOST.

Before you open the UDP socket you can verify your IP address and if you are able to heartbeat the UDP server of IoT Creators.

AT+CGPADDR
+CGPADDR: 0,"10.128.5.88"
OK

AT+NPING="172.27.131.100"
OK
+NPING: "172.27.131.100",253,4934

Send "i am alive" heartbeat message and receive downlink message

After you verified the network attach of your device you can open the UDP socket on your device and send a "i am alive" heartbeat message to the UDP server of IoT Creators. As already explained in chapter 4 the message should be in hex format.

AT+NSOCR="DGRAM",17,7000,1
0
OK

AT+NSOST=0,"172.27.131.100",15683,10,"6920616d20616c697665"
0,10
OK

The "i am alive" message causes the UDP server of the IoT Creator portal to send out the previous queued "Hallo Device" message to the device.
Because you used as last parameter "1" in the +NSOCR command to open the socket the device notifiers you with an URC (Unsolicited Result Code) code as soon data has been been received by the modem of the device.

+NSONMI: 0,12

AT+NSORF=0,12
0,"172.27.131.100",15683,12,"48616C6C6F20446576696365",0
OK

The +NSONMI in the sample above indicats that 12 bytes of data have been received on socket 0.

To retrieve the 12 bytes of the received data from socket 0 you can use the +NSORF`=0,12`` command. +NSORF``` returns the following elements:

To decode the hex data 48616C6C6F20446576696365 into a readable string you can use the online tool http://string-functions.com/hex-string.aspx.

🚧

Downlink only possible after uplink

If you try to send a downlink message to a device that has not send any uplink messages you will receive the error : Serial number not found.
After sending an uplink message the device registration is completed and downlinking will work.

AT Commands to receive Hello Device

#  Test if device has an IP address asigned
AT+CGPADDR 
+CGPADDR: 0,"10.0.5.112"
OK

# Ping UDP server of IoT Creators
AT+NPING="172.27.131.100" 
OK
+NPING: "172.27.131.100",253,4135

# Open local UDP socket 
AT+NSOCR="DGRAM",17,7000,1 
0
OK

# Send "i am alive" message to UDP server
AT+NSOST=0,"172.27.131.100",15683,10,"6920616d20616c697665"
0,10
OK

# URC about received data
+NSONMI: 0,12

# Retrieve the received data
AT+NSORF=0,12
0,"172.27.131.100",15683,12,"48616C6C6F20446576696365",0
OK

Send and Receive via Leul Messaging (CoAP)

In the following chapters I will explain to you how you can send a "Hello World" message from the device to the IoT Creators SCS and how you can receive a "Hello Device" message on your devkit from IoT Creators SCS via the proprietary Leul messaging protocol.
The AT commands which are used for this are proprietary. They have been designed to communicate with OceanConnect NB-IoT platform and implemented by some chipset manufacturers.
Leul messages wrapped in LWM2M (Light Weight Machine to Machine) packets on top of the CoAP (Constrained Application Protocol) and transported over UDP sockets.
IoT Creators SCS provides a server to interact with devices via this protocoll.

Send "Hello World"

❗️

Register your device first!

Make sure that you have registered your device with its IMEI at the IoT Creators portal BEFORE you send your first message to the UDP or Leul server of IoT Creators.

If you forget, you will have problems to register your device afterwards. In this case please get in contact with IoT Creators support team.

Welcome to this step of tutorial. You probably ended up here because you could successfully connect your devkit to the network.
Before you continue make sure your device has an IP address assigned and you can ping the server of IoT Creators. You test both with the +CGPADDR and the +NPING command.

AT+CGPADDR
+CGPADDR: 0,"10.128.4.109"
OK

AT+NPING="172.27.131.100"
OK
+NPING: "172.27.131.100",253,2396

In the next steps you will

• Establish the connection to IoT Creators Leul server
• Send the hex coded "Hello World" message to the Leul server.

Establish the connection to IoT Creators Leul server

To send messages to IoT Creators Leul server you need to open it with the AT command AT+NCDP at port 5683.

AT+NCDP="172.27.131.100",5683

OK

The parameter of the +NCDP command are pretty simple. The first parameter is the IP address of the server. The second parameter is the port on which the server listens for client requests.

Sending HEX coded "Hello World" Message to Leul Server

To let your device sent this message via Leul messaging to IoT Creators Leul server you can use the +NMGS command as shown in the following.
Before you start sending any messages you can switch on the "success" notification with the ´´´+NSMI´´´ command.

AT+NSMI=1                                                                                                                                                            
OK             

AT+NMGS=11,"48656c6c6f20576f726c64"                                                
                                                                                   
OK                                                                                 
                                                                                   
+NSMI: SENT

The big advantage of sending messages with Leul instead of using basic UDP is that ´´´+NSMI: SENT´´´ notification is prompted after the reception of the message has been acknowledged by the receiver.

👍

CONGRATULATIONS

If you see OK on the device console CONGRATULATIONS! you just send a Leul message from your device to IoT Creators Leul server.

Receive "Hello Device"

In this step I will explain you how you can receive "Hello Device" (48656c6c6f20446576696365 as HEX) downlink message in HEX format via Leul which you have posted before to the IoT Creators platform (see https://docs.iotcreators.com/docs/_-send-downlink-message-to-devkit).

The downlink message which you posted to IoT Creators API before is queued by the IoT Creators platform. The queued downlink message is sent to the device after IoT Creators platform received the uplink message from the device.

In this sample you will perform the following steps:

• Open connection to IoT Creators Leul server.
• Send "i am alive" heartbeat message via Leul to the server.
• Receive the previous queued "Hello Device" message from the IoT Creators platform.

Downlink messages can be received in two different ways.

1. With AT+NNMI=1 the new message indicator +NNMI automatically returns the received downlink message as parameter.
2. With AT+NNMI=2 the new message indicator +NNMI only indicates that a message is available. In this case the received downlink message has to be fetched with AT+NMGR command.
   In the following for both the samples are given.

# Connect to Leul server
AT+NCDP="172.27.131.100",5683
OK

# Activate the "+NSMI: SENT" notification
AT+NSMI=1
OK             

# Let automatically display the received messages 
AT+NNMI=1
OK

# Send "i am alive" heartbeat message
AT+NMGS=10,"6920616d20616c697665"
OK
+NSMI: SENT

# Received message is automatically displayed
+NNMI: 12,"48616C6C6F20446576696365"

# Connect to Leul server
AT+NCDP="172.27.131.100",5683
OK

# Activate the "+NSMI: SENT" notification
AT+NSMI=1
OK             

# Only indicate that a downlink message is available.
AT+NNMI=2
OK

# Send "i am alive" heartbeat message
AT+NMGS=10,"6920616d20616c697665"
OK
+NSMI: SENT

# Indcation that a message has been received and can be fetched.
+NNMI

# Fetch the received message
AT+NMGR
12,"48616C6C6F20446576696365"
OK