In this chapter you will learn how you can setup the development kit SIMCom SIM7022-EVB and how you can connect it with Telekom NB-IoT network and how you can interact with IoT Creators platform by sending and receiving Hello World messages via UDP.https://files.readme.io/090c4d0-simcom_sim7022_01_v1_klein.png

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 SIMCom modem.

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/ttyUSB0. It is automatically created when you connect your devkit with your computer and it disappears again after you disconnected your devkit from the computer.

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:.

Execute AT commands on your devkit the first time.

To execute AT commands on your devkit you need connect your devkit via the serial USB line with your compute and start a terminal program such as putty on Windows or minicom on Linux . 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 on Linux by using the minicom and how to send those AT commands to the modem to query device product and IMEI information.

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/ttyUSB0
  • Set the baudrate (Bps/Par/Bits) to 115200 8N1
  • Set Hardware flow control to No
  • Set Software flow control to No
• Enter Screen and keyboard
  • Set Local echo to Yes
  • Set *Add linefeed to No**
  • Set Add carriage return to No
• Enter Save setup as
  • Give sim7022 as the name to save the configuration
• Enter Exit from Minicom

After configuring minicom for your SIM7022 devkit you can start minicom with the configuration sim7022 which just created before.

$ minicom sim7022

📘

In case you have any problems to access the device file /dev/ttyUSB0 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 SIM7022-EVB with the capabiltiy to pass your AT commands from the serial USB terminal interface directly through to the 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.

# Request IMEI
AT+CGSN=1
+CGSN: "863266050003162"
OK

# Request product type number
ATI
SIM7022 R2110
OK

# Request manufacturer
AT+CGMI
SIMCOM_Ltd
OK

# Request model identification
AT+CGMM
SIM7022
OK

# Request firmware version
AT+CGMR
2110B01SIM7022
OK

# Request IMSI of SIM card
AT+CIMI
901409700009293
OK

# Request ICCID of SIM card
AT+QCICCID
+QCICCID: 89882280000001294327
OK

Attach to the NB-IoT Network

This chapter explains how you can attach your SIM7022 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 Commands Only"

❗️

Before you send any UDP 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. as described above.
• 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 your devkit.
• Attach to the network and verify your network configuration.
• Ping an IP address.

Setup Network Configuration

After switching on your devkit test if your SIM card is correctly input and if it is accessable.

# Test if the SIM card is correclty input by quering IMSI ans ICCID 

# Request IMSI of SIM card
AT+CIMI
901409700009293
OK

# Request ICCID of SIM card
AT+QCICCID
+QCICCID: 89882280000001294327
OK

# Test if a PIN is required by the SIM card. If everything is fine "READY" is returned.
AT+CPIN?
+CPIN: READY
OK

After you made sure that your modem can access the SIM card you will configure your network settings and attach to the network with the following commands.

🚧

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

# Let the modem display network connection status 
AT+CEREG=5
OK

# Switch off the radio module
AT+CFUN=0 
+CEREG: 0
OK

# Set the frequency band to 8 for NB-IoT of Telekom in Germany
AT+QCBAND=0,8
OK

# Switch on the radio again
AT+CFUN=1,1
OK

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

# Set the mobile operator id 26201 for Telekom in Germany
# or 20416 for T-Mobile in Netherland
AT+COPS=1,2,"26201",9
OK

# Request the assigned IP address  
AT+CGPADDR
+CGPADDR: 0,"10.128.1.112"
+CGPADDR: 1
OK

After you could successfully attach to the mobile NB-IoT network and your device got assigned an IP address of the private IoT Creators network you should test if you can ping the UDP server of IoT Creators with the AT command AT$QCPING.

📘

PING Service

Check the correct ping address here: IoT Configuration Parameter

AT+QCPING="172.27.131.100"
OK

QCPING: SUCC, dest: 172.27.131.100, RTT: 1772 ms
QCPING: SUCC, dest: 172.27.131.100, RTT: 1641 ms
QCPING: SUCC, dest: 172.27.131.100, RTT: 473 ms
QCPING: SUCC, dest: 172.27.131.100, RTT: 449 ms
QCPING: DONE
 rtt min/avg/max = 449 / 1083 / 1772 mss transmittted, 4 received, 0 % packet loss

📘

What to do if it doesn't work

If you are not able to get established a network attachment you shouldn't forget the different mobile operators in different countries using different frequency bands and different mobile operator ids (https://docs.iotcreators.com/docs/roaming-mobile-iot-networks-in-europe). You should double check the following

• Did you setup the correct frequency band?
• 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?

👍

In case your device got assigned an IP address and you could successfully ping the UDP server of IoT Creators you are done.

Great! Your setup of network configuration is complete now.

The next steps are to register you device in IoT Creators portal and send a Hello World uplink and downlink messages..

Good Luck

AT Commands Only

#######################################################################
# Test SIM card 
#######################################################################
# Request IMSI of SIM card
AT+CIMI

# Request ICCID of SIM card
AT+QCICCID

# Test if a PIN is required by the SIM card. If everything is fine "READY" is returned.
AT+CPIN?

#######################################################################
# Network attach
#######################################################################
# Let the modem display network connection status 
AT+CEREG=5

# Switch off the radio module
AT+CFUN=0 

# Set the frequency band to 8 for NB-IoT of Telekom in Germany
AT+QCBAND=0,8

# Switch on the radio again
AT+CFUN=1,1

# Set APN of IoT Creators 
AT+CGDCONT=1,"IP","cdp.iot.t-mobile.nl"

# Set the mobile operator id 26201 for Telekom in Germany
# or 20416 for T-Mobile in Netherland
AT+COPS=1,2,"26201",9

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

# Check if attached to network
AT+CGATT?

# Check MNO
AT+COPS?

# Check APN
AT+CGDCONT?

# Check signal strength and qualitay
AT+CSQ

#######################################################################
# Ping UDP server of IoT Creators
#######################################################################
AT+QCPING="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.

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 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 AT$QCPING command.

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

AT$QCPING="172.27.131.100"
OK

+QCPING: SUCC, dest: 172.27.131.100, RTT: 1772 ms
+QCPING: SUCC, dest: 172.27.131.100, RTT: 1641 ms
+QCPING: SUCC, dest: 172.27.131.100, RTT: 473 ms
+QCPING: SUCC, dest: 172.27.131.100, RTT: 449 ms
+QCPING: DONE
 rtt min/avg/max = 449 / 1083 / 1772 mss transmittted, 4 received, 0 % packet loss

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 AT$QCSOCR command. The returned value of this command ("1" in the sample below) represents the identifier of the opened socket.

AT+QCSOCR="DGRAM",17,2000,1,"AF_INET"
1
OK

The AT$QCSOCR command opens a UDP socket with the following parameters:

To close the UDP socket you can use the command AT$QCSOCL later. The "1" as command parameter references the socket identifier as it has been returned by the AT$QCSOCL command before.

AT$QCSOCL=1

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 AT$QCSOST command as shown in the following.
The AT$QCSOST command returns the socket identification as a first digit and the length of successfully sent data as second digit.

AT$QCSOST=1,"172.27.131.100",15683,11,48616c6c6f20576f726c64
1,11
OK

The AT$QCSOST 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$QCSOST 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 server socket at port 2000
AT$QCSOCR="DGRAM",17,2000,1,"AF_INET"
1
OK

# Send "Hello World" as HEX to UDP server at 172.27.131.100:15683
AT$QCSOST=1,"172.27.131.100",15683,11,48616c6c6f20576f726c64
1,11
OK

# Close the socket
AT$QCSOCL=1
OK

Receive "Hello Device"

Welcome back to the tutorial .
In this step I will explain you how you can send a "Hello Device" downlink message from the IoT Creators portal to the device and how you can receive it via UDP on the device.

Send "Hello Device" from IoT Creators Portal to Device

To send a downlink message from IoT Creators portal to the device click on the context actions button "Actions" and select Send a downlink messages.

The dialog to send a downlink message to the device will be opened. Input your message and send it by clicking SEND button.

The downlink message 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.

Receive "Hello Device" on Device

To receive a UDP message on the device you need to 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
Open the UDP socket and send a UDP message with the commands AT$QCSOCR. To let the UDP server deliver the queued downlink message to your device you need to send an uplink message to the server with AT$QCSOST. In this sample we will send a i am alive heartbeat messsage to the UDP server of IoT Creators.

# Open local UDP server socket at port 2000
AT$QCSOCR="DGRAM",17,2000,1,"AF_INET"
1
OK

# Send "i am alive" as HEX to UDP server at 172.27.131.100:15683
AT$QCSOST=1,"172.27.131.100",15683,10,6920616d20616c697665
1,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 4th parameter "1" in the AT$QCSOCR 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.
In our sample the device prints $QCSONMI: 1,16 to notify that 16 bytes of been received.
To query the received bytes we use the command AT$QCSORF=1,16. As you can see the number of bytes in the query command is the same as in the URC notification. In both cases it is 16.

$QCSONMI: 1,16                                                                                             
    
# Query the received data
AT$QCSORF=1,16

$QCSONMI: 1,"172.27.131.100",15683,12,"48656C6C6F20446576696365",0
                                                                                                      
OK

The received data 48656C6C6F20446576696365 is HEX encoded. To decode it we can use again the online tool http://string-functions.com/hex-string.aspx.

AT Commands to receive Hello Device

# Open local UDP server socket at port 2000
AT$QCSOCR="DGRAM",17,2000,1,"AF_INET"
1
OK

# Send "i am alive" as HEX to UDP server at 172.27.131.100:15683
AT$QCSOST=1,"172.27.131.100",15683,10,6920616d20616c697665
1,10
OK

# Notification about the reception of 16 bytes 
$QCSONMI: 1,16                                                                                             
    
# Query the received data
AT$QCSORF=1,16

$QCSONMI: 1,"172.27.131.100",15683,12,"48656C6C6F20446576696365",0
                                                                                                      
OK

Low power features

Check this guide for the BC66 low power features:

👍

SIMCOM SIM7022 low power features

https://docs.iotcreators.com/docs/low-power-features#simcom-sim7022

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$QCCFG="Epco",1

🚧

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$QCDNSCFG="primarydnsipv4","secondarydnsipv4"