---
agentTools:
projectIndex: https://docs.iotcreators.com/llms.txt
---
# Quectel BG96 - Tuino096
Learn how to setup and integrate dev-kit Quectel BG96 - Tuino096 with IoT Creators NB-IoT network and Data Provisioning Service (SCS)
# Introduction
***
To start with the NB-IoT module BG96 from Quectel you can use the development board Tuino096 from Gimasi (see images below).
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/cb9aa65-2021-03-23_17_08_18-Prsentation1.pptx_-_PowerPoint.png",
"2021-03-23 17_08_18-PrΓ€sentation1.pptx - PowerPoint.png",
1166
],
"align": "center",
"caption": "Tuino096 from Gimasi."
}
]
}
[/block]
**Links\***
| Titel | URL |
| :------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| Where can I get from? | |
| Product datasheet from Gimasi | |
| GitHub repository with EVERYTHING | |
| Inital Setup Guide | |
| BG96 User Guide, Hardware Design, Application Notes - Download Zone | |
| BG96 AT Commands Manual | |
# All useful resources
> π BG96 resources
>
> You can download all necessary resources here:
####
**Links to the AT command samples:**
* [Query device information](#at-commands-to-query-device-information)
* [Setup network configuration](#at-commands-to-setup-network-configuration)
* [Send "Hallo World" via UDP](#at-commands-to-send-hello-world)
* [Receive "Hallo Device" via UDP](#at-commands-to-receive-hello-device)
####
####
# Setup the Device
***
## Access Device from your Computer
[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/2d0489d-Unbenannt.png",
"Unbenannt.png",
973
],
"align": "center",
"caption": "Parts of the Quectel BG96 - Tuino096"
}
]
}
[/block]
**Enable your computer with "serial via USB"**\
To enable your windows box to with "serial via USB" you can install from 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
```text Startup output of BG96
Starting..
Powering UP BG96
RDY
```
> π :+1: :+1: :+1:
>
> 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.
```text Activate console echo
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.
```text Set error format to "long"
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.
| AT Command | Description |
| :--------- | :----------------------------------- |
| ATI | Request product type number |
| AT+CGSN | Request IMEI (product serial number) |
| AT+CGMI | Request manufacturer |
| AT+CGMM | Request model identification |
| AT+CGMR | Request firmware version |
| AT+CIMI | Request IMSI of SIM card |
| AT+CCID | Request ICCID of SIM card |
| ATI9 | Request modem version & appl version |
```text Important AT commands to query essential infos
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.
```text Query the SIM Card's IMSI
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:
```text Set APN
AT+CGDCONT=1,"IP","cdp.iot.t-mobile.nl"
```
```text Set mobile network operator
# 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 \
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.
```text Query available mobile network operators
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.
```text Set the frequency band of the radio module
# 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.
| Band | Code |
| :------ | :------ |
| LTE B1 | 1 |
| LTE B2 | 2 |
| LTE B3 | 4 |
| LTE B4 | 8 |
| LTE B5 | 10 |
| LTE B8 | 80 |
| LTE B12 | 800 |
| LTE B13 | 1000 |
| LTE B18 | 20000 |
| LTE B19 | 40000 |
| LTE B20 | 80000 |
| LTE B26 | 2000000 |
| LTE B28 | 8000000 |
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.
```text Query the IP address
AT+CGPADDR
+CGPADDR: 1,10.0.2.34
OK
```
> π :+1: CONGRATULATIONS :+1:
>
> 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](https://docs.iotcreators.com/docs/general-settings)
```text Ping UDP server of IoT Creators
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
```
> π :muscle: Great :clap:
>
> 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 :runner:
####
####
## AT Commands to setup Network Configuration
```text AT Commands to attach to the NB-IoT network
# 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.
```text Test if an IP addressed has been assigned
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 :cry:
As next you can open a UDP socket to the UDP server of the IoT Creators.
####
### Open UDP socket to UDP server
```text Open 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.
```text Ping a IP address
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
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:
```text
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 **11**bytes.
> π
>
> 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 .
> π
>
> 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
```text 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.
```text Startup output on the device console
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.
```text AT command to send "i am alive" uplink message to CDP
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
```text 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
>
>
####
# 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:
```text retrieve local time
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
```text enable ePCO
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
```text configure dns
AT+QIDNSCFG=1,"primarydnsipv4","secondarydnsipv4"
```