Introduction

To start with the NB-IoT module BG96 from Quectel you can use the development board Tuino096 from Gimasi (see images below).

Links*

All useful resources

👍

BG96 resources

You can download all necessary resources here: https://github.com/iotcreators/doclib-downloads/tree/master/device-integrations/Quectel

Links to the AT command samples:

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

Setup the Device

Access Device from your Computer

Enable your computer with "serial via USB"
To enable your windows box to with "serial via USB" you can install from https://www.exar.com/product/interface/uarts/usb-uarts/xr21v1412 the required drivers.
If you work with a standard Linux distribution such as Ubuntu it shouldn't be neccessary to install additional drivers to the OS. As soon you plug in the device cabel into the USB port of your computer a device file such as /dev/ttypACM0 should appear in your file system.

Connect the antenna with the device. (the device shouldn't be connected via USB)

Insert NB-IoT SIM card into the card slot of the device. (the device shouldn't be connected via USB)

Connect the device with your computer via "serial" USB cabel and get access with terminal program.

After you connected the device with the computer via the USB cabel the devkit is set under power and some LEDs are shining.

To get console access to the device you can use terminal program such as putty (for windows) or screen (on Linux: $ screen /dev/ttyACM0 115200).

📘

On Linux

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

If you access your devkit very shortly after you set it under power you should see the output

Starting..
Powering UP BG96
	 
RDY

👍

👍 👍 👍

When you can see the the RDY in the console you can pat yourself on the shoulder. Well Done You are ready now to play with your devkit and input AT commands.

In the normal case you get echoed your input on the console. If this is not the case you can activate the console echo by using ATE1 command.

ATE1
OK

In case you have any troubles with any AT command and you get an ERROR response I recommand to configure the format of the error messages to long with the AT+CMEE command.

AT+CMEE=2    
OK

AT Commands to query Device Information

In the following I describe some AT commands with which you can query essential infos from your devkit.

ATI
Quectel
BG96
Revision: BG96MAR02A07M1G
OK

AT+CGSN
866425033313638
OK

AT+CGMI
Quectel
K

AT+CGMM 
BG96
OK

AT+CGMR
BG96MAR02A07M1G
OK

AT+CIMI
901405700009292
OK

AT+CCID
+CCID: 89882280000001294319
OK

ATI9 
Quectel
BG96
Revision: BG96MAR02A07M1G
OK

Attach to NB-IoT Network

This chapter explains how you can attach your Quectel BG96 devkit to the NB-IoT network.

📘

If you are only interested in the conclusion of the AT commands to configure the network setup go to chapter "'AT Setup Commands" end of this document.

After you managed successfully to connect your devkit with your computer via USB cabel and to get access to it with your terminal program such as putty or screen you connect your devkit with the Telekom NB-Iot network.
In the following I describe you the basic AT commands with which your devkit should end-up with an IP address and beeing able to ping the UDP server of IoT Creators.

Test if your SIM card is inserted properly

As first you can check if you inserted you SIM card properly into the SIM card slot of your devkit.
To do so I query the SIM card's IMSI with the AT+CIMI command. If you get the number and an OK returned everything is ok.

AT+CIMI
901405700009292
OK

Attach to Telekom NB-IoT network

To attach to the NB-IoT network in most of the cases it is enough to

• Set the APN to cdp.iot.t-mobile.nl
• Set the mobile network operator such as T-Mobile Netherland or Telekom Deutschland

🚧

Choosing the correct APN for your sim card

The command below represent an example, different sim cards can have different APNs, for the correct APN check this doc page here: https://docs.iotcreators.com/docs/general-settings

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

# T-Mobile Netherland
AT+COPS=1,2,"20416",9

# Telekom Deutschland
AT+COPS=1,2,"26201",9

# T-Mobile Poland
AT+COPS=1,2,"26002",9

The list of all PLMN IDs (Public Land Mobile Network) you can find at https://en.wikipedia.org/wiki/Mobile_country_code
In the normal case the AT+COPS command can take up to 30 seconds.

If you want to know which network operators are visible or your devkit you can also use the AT+COPS=? command. Don't be supprised that this command blocks somtimes up to an minute.

AT+COPS=?
+COPS: (1,"E-Plus","E-Plus","26203",0),(1,"Vodafone.de","Vodafone","26202",0),(1,"Telekom.de","TDG","26201",0),(1,"Telekom.de","TDG","26201",9),,(0,1,2,3,4),(0,1,2)
OK

In some cases it is not enough to set the just the APN and the MNO. Sometimes it is neccessary to set the band which is used by the modem as well. You can do this by using the AT+QCFG command. E.g. T-Mobile Netherlands and Telekom Deutschland use fequency band 8.
You can find all the frequency bands of European T-Mobile and Telekom networks in the chapter "IoT Configuration Paramter".
Normally you can not set the frquency band which shall be used by the radio module. Out of this reason you have to switch it off with the AT+CFUN=0 command before you set the band.

# Switch off the radio module
AT+CFUN=0

# Set the band to 8
AT+QCFG="band",0,0,80,1

# Set the band to 20
AT+QCFG="band",0,0,80000,1

# Switch on the radio module (or reboot the device)
AT+CFUN=1

Setting the fequency band for Quectel BG96 is a bit special compared to other chipsets and modems. In most of the cases an AT command is provided to set the band just using direct numbers such as 8 or 20. In the following list you can see which number as the 4th paramter of the AT command needs to be used to set a specific frequency band.

After setting the APN and the network operator you should reboot your devkit by power off and on again. After this you should wait ca. 30 seconds and use the AP+CGPADDR command to query the assigned IP address.

AT+CGPADDR
+CGPADDR: 1,10.0.2.34
OK

👍

👍 CONGRATULATIONS 👍

If you can see an IP address as result of the AT+CGPADDR command CONGRATULATIONS!! You just successfully attached your devkit to the T-Mobile/Telekom network.

Ping IoT Creators UDP server

After you connected successfully to the NB-IoT network you can test if you can reach the UDP server of IoT Creators. This actually really easy. You can do this with the AT+QPING command.

📘

PING Service

Check the correct ping address here: IoT Configuration Parameter

AT+QPING=1,"172.27.131.100"
OK

+QPING: 0,"172.27.131.100",32,611,255
+QPING: 0,"172.27.131.100",32,160,255

👍

💪 Great 👏

If you can see an OK and the response lines you are in a very very good shape.
You laid the base the NB-IoT communication with IoT Creators platform.

Now the fun can start 🏃

AT Commands to setup Network Configuration

# Query the ICCID from the SIM card to check if it properly inserted
AT+CIMI
901405700009292
OK

# Set the band to 8
AT+QCFG="band",0,0,80,1
OK

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

# Set the MNO (Germany, Telekom) 
AT+COPS=1,2,"26201",9
OK

# Query the assigned IP address
AT+CGPADDR
+CGPADDR: 1,10.0.2.34
OK

# Ping the IoT Creators UDP server
AT+QPING=1,"172.27.131.100"
OK

+QPING: 0,"172.27.131.100",32,611,255
+QPING: 0,"172.27.131.100",32,160,255

Send and Receive via UDP

Send "Hello World"

Preliminary Work

❗️

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.

Before you can send a "Hello World" UDP message from your device to IoT Creators platform make sure you did the following steps:

• Registered you device with the correct IMEI in the IoT Creators Portal.
  To be sure that you used the correct IMEI you can query it with the AT command directly from the device. For BG96 related devices use AT command AT+CGSN to query the IMEI.
• Connect the device via USB cabel with your laptop.
• Start the terminal program such as putty (Windows) or screen (Linux) with a baudrate of 115200.
• Attach you device with the network

To test if your device is probably attached with the network you should run the command AT+CGPADDR and you should see a valid IP address.

AT+CGPADDR
+CGPADDR: 1,10.0.2.2

OK

🚧

You should only continue with the next steps if you have seen the IP address of the network attachment displayed on the console.
If you don't see the IP address unfortunatelly you have to start trouble shooting now 😢

As next you can open a UDP socket to the UDP server of the IoT Creators.

Open UDP socket to UDP server

AT+QIOPEN=1,1,"UDP","172.27.131.100",15683,1001,0,0
OK
+QIOPEN: 1,0

This AT command opens a UDP socket with:

• Context ID = 1,
• Connection ID = 1,
• Service type = UDP,
• Server IP address = 172.27.131.100,
• UDP port of the server = 15683
• UDP port of the device for responses of the server = 1001,
• Buffered access mode = Yes

In all other AT commands which are related to this socket connection you should use 1 as connection id.

In case your AT+QIOPEN command doesn't return OK or +QIOPEN: 1,0 something went wrong.
At first you should double check if you can reach the UDP server with the AT+QPING command.

AT+QPING=1,"172.27.131.100"
OK

+QPING: 0,"172.27.131.100",32,3010,253

The ping result is returned by the first integer parameter of +PING: return. 0 means that every thing was fine. A value different 0 identies an error. You can use AT+QIGETERROR to get the error description.

Sending "Hello World" UDP Message to UDP Server

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.

To let your device sent this message via UDP to the UDP server of IoT Creators you can use the following AT command:

AT+QISENDEX=1,"48616c6c6f20576f726c64"
OK
SEND OK

This AT command sends via the connection with the id 1 the message 48656c6c6f20576f726c64 with a lenght of 11bytes.

👍

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

📘

The message length which is assigned to the command AT+QISENDEX as second parameter describes the length of the original message. It does NOT desribes the length of the hex message which has a length of 22 bytes.

As next we can change back to the project space of the IoT portal to check what has been received.

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.

👍

If you can decode your received message to Hello World **CONGRATULATIONS**! You just sent and receceived your first UDP message via NB-IoT.

AT Commands to send Hello World

# Open local UDP socket
AT+QIOPEN=1,1,"UDP","172.27.131.100",15683,1001,0
OK
+QIOPEN: 1,0

# Send Hello World as Hex
AT+QISENDEX=1,"48616c6c6f20576f726c64"
OK
SEND OK

# Close the socket
AT+QICLOSE=1
OK

Receive "Hallo Device"

In this chapter you will receive the previous posted "Hello Device" downlink message with your device.

Preliminary Work

Before you can send a "Hello World" UDP message from your device to IoT Creators platform make sure you did the following steps:

• Registered you device with the correct IMEI in the IoT Creators Portal.
  To be sure that you used the correct IMEI you can query it with the AT command directly from the device. For BG96 related devices use AT command AT+CGSN to query the IMEI.
• Connect the device via USB cabel with your laptop.
• Start the terminal program such as putty (Windows) or screen (Linux) with a baudrate of 115200.
• Attach you device with the network

To test if your device is probably attached with the network you should run the command AT+CGPADDR and you should see a valid IP address.

AT+CGPADDR
+CGPADDR: 1,10.0.2.2

OK

🚧

You should only continue with the next steps if you seen the IP address of the network attachment displayed on the console.
If you don't see the IP address unfortunatelly you have to start trouble shooting now :(

Receive Downlink Message on the Device

As mentioned before IoT Creators queues the posted downlink messages for a device until the device sends an uplink message. After IoT Creators received the uplink message it delivers the queued downlink messages to the device.

After you opened the socket to the UDP server of IoT Creators with the AT+QIOPEN go to the console of the device and send "i am alive" heartbeat message to IoT Creators.

AT+QISENDEX=1,"6920616d20616c697665"
SEND OK

+QIURC: "recv",1

AT+QIRD=1,100
+QIRD: 12
Hallo Device

OK

As you can see in the AT command console above it appears a +QIURC: "recv",1 command to notify that data has been received on the socket "1".

To retrieve the data you can use the AT command AT+QIRD=1,100. This command trys to retrieve 100 bytes. Of cause 100 bytes are not available. +QIRD: 12 indicates that only 12 bytes are returned.

👍

CONGRATULATIONS!! You send your first downlink message from the cloud to the device.

The whole story works exactly the same if you have your device switched off, and send first the downlink message. After this you can switch on your device, perform the alive-ping and get the received downlink message.

AT Commands to receive Hello Device

# Open the UDP socket to the server of IoT Creators
AT+QIOPEN=1,1,"UDP","172.27.131.100",15683,1001,0
OK
+QIOPEN: 1,0

# Send "i am alive" heartbeat message
AT+QISENDEX=1,"6920616d20616c697665"
SEND OK

+QIURC: "recv",1

# Try to get 100 bytes => only 12 bytes are returned
AT+QIRD=1,100
+QIRD: 12
Hallo Device
OK

# Close the socket
AT+QICLOSE=1
OK

Low power features

For low power features, see below

👍

Low power features

https://docs.iotcreators.com/docs/low-power-features#quectel-bg96

Other useful functions

Retrieve time from the network

You can retrieve the local time from the network (not all mobile networks support this command) by issuing:

AT+CCLK?

+CCLK: 2023/02/06,13:17:08GMT+1

Configuring DNS

📘

DNS configuration

The DNS configuration only makes sense only when using the public APN to reach the external internet, when using the private APN, please use the direct IP for the service of your choice.

DNS should be automatically retrieved by the local network, just make sure that the ePCO (extended protocol configuration options) is enabled with command

AT+QCFG="nccconf",80

🚧

DNS not configured

If DNS are not automatically retrieved by the network, it couldbe possible that the local network is not providing those. In this case, configure them manually.

Configure DNS manually

Alternatively, you can explicitely configure the DNS with command

AT+QIDNSCFG=1,"primarydnsipv4","secondarydnsipv4"