SimpleNB

This is an Arduino library for communicating with NB-IoT/CAT-M1 modules that using AT command interface, such as such as SIMCOM SIM70XX series, Quectel BG96, uBlox SARA-R410M.

This library is based on the works of TinyGSM which try to be all-things-AT-commands. What make this library different from the TinyGSM is that this library stripped out the supports of all the legacy GSM modules and unrelated WiFi modules, focus only on NB-IoT/CAT-M1 modules to make the library easier to setup, and add new new features and functionalities related to NB-IoT/CAT-M1 technologies to the library.

If you like SimpleNB - give it a star, or fork it and contribute!

Supported modules
Features
Getting Started
How does it work?
API Reference
Troubleshooting
License

Supported modules

SIMCom SIM7000X CAT-M1/NB-IoT Module
SIMCom SIM7020X CAT-M1/NB-IoT Module
SIMCom SIM7070/SIM7080/SIM7090 CAT-M1/NB-IoT Module
u-blox LTE-M/NB-IoT Modems (SARA-R4xx, SARA-N4xx, but NOT SARA-N2xx)
Sequans Monarch LTE Cat M1/NB1 (VZM20Q)
Quectel BG96

With the exception of SIM7000, SIM7070/7080/7090, SIM7020 and BG96, the rest of supported modules are inherited from TinyGSM without further test.

Supported Features

Some of the modules does not support some of the features due to hardware design (e.g. GNSS receiver), some functionality are available but not implemtented (those marked as TBI), here is a summary of features and functionalities supported by each modules:

| Functionality | BG96 | Sara 4 | uBlox | Sequans | SIM7000 | SIM7020 | SIM70x0 | Xbee | |----------------|:----:|:------:|:-----:|:-------:|:-------:|:-------:|:-------:|:----:| | TCP | x | x | x | x | x | x | x | x | | SSL | x | x | x | x | x | TBI | x | x | | GNSS | x | x | x | | x | | x | | | GSM LBS | | x | x | | | | x | | | SMS | x | x | x | x | x | x | x | x | | Voice Call | x | | x | x | | | | | | Network Time | x | x | x | x | x | x | x | | | NTP | x | | | | x | x | x | | | Battery Status | x | x | x | | x | x | x | x | | Temperature | x | x | | x | | | | x | | GPRS | x | x | x | x | x | x | x | x |

Data connections

TCP (HTTP, MQTT, Blynk, ...)
- ALL modules support TCP connections
- Most modules support multiple simultaneous connections, however please noted that some network only allows less or even one connection, so please check with your network operator for number of network connections it supported:
  - Quectel BG96 - 12
  - Sequans Monarch - 6
  - SIM7000 - 8 possible without SSL, only 2 with SSL
  - SIM7020 - Currently only 1 supported
  - SIM 7070/7080/7090 - 12
  - u-blox SARA R4/N4 - 7
  - Digi XBee - only 1 connection supported!
SSL/TLS
- Supported on:
  - SIM7000, SIM7070/80/90, Quectel, u-Blox, and Sequans Monarch
- Not implemented on:
  - SIM7020
- Like TCP, most modules support simultaneous connections
- TCP and SSL connections can usually be mixed up to the total number of possible connections

SMS

Only sending SMS is supported, not receiving
- Supported on all modules

Voice Calls

Supported on:
- Quectel modems, u-blox
Not implemented on:
- SIM7000, SIM7020 and SIM7070/7080/7090
Not possible on:
- u-blox SARA R4/N4
Functions:
- Dial, hangup
- DTMF sending

Location

GPS/GNSS
- SIM7000, SIM7070/SIM7080/SIM7090, BG96, u-blox
- NOTE: u-blox chips do NOT have embedded GPS - this functionality only works if a secondary GPS is connected to primary cellular chip over I2C
GSM LBS location service
- SIM7070/SIM7080/SIM7090, u-blox

Credits

TinyGSM Primary Authors/Contributors:
- vshymanskyy
- SRGDamia1
SIM7000:
- captFuture
- FStefanni
Sequans Monarch:
- nootropicdesign

Getting Started

First Steps

Check your balance if you had an prepaid plan. Ensure that the PIN code on the SIM card is disable, the APN, Username and Password are correctly provisioned, contact your local carier if you are unsure.
Ensure the SIM card is correctly inserted into the NB-IOT/CAT-M1 board that you used.
Ensure that antenna is firmly attached.
Ensure that you have a stable power supply to the module of at least 500mA.
Check if serial connection is working (Hardware Serial is recommended). Use AT Debug tool to check if the module can response to an AT command.
Try out the examples included in this Library.

Writing your own code

Prior using the library, there is some boiler-plat configuration required. The general flow of your code should be:

Define the module that you are using (choose one and only one)
- ie, #define SIMPLE_NB_MODEM_SIM7080
Included SimpleNB library
- #include <SimpleNBClient.h>
Create a SimpleNB modem instance, and pass-in the Serial Communication port for AT-Command interface as parameter
- SimpleNB modem(SerialAT);
Create one or more SimpleNB client instances
- For a single connection, use
  - SimpleNBClient client(modem); or SimpleNBClientSecure client(modem); (on supported modules)
- For multiple connections (on supported modules) use:
  - SimpleNBClient clientX(modem, 0);, SimpleNBClient clientY(modem, 1);, etc or
  - SimpleNBClientSecure clientX(modem, 0);, SimpleNBClientSecure clientY(modem, 1);, etc
Begin your serial communication and set all your pins as required to power your module and bring it to full functionality.
- The examples attempt to guess the module's baud rate. In working code, consider use a set baud.
Initialize the modem
- modem.init() or
- modem.restart(), restart generally takes much longer than init but ensures the module doesn't have lingering connections
Unlock your SIM, if necessary (optional):
- modem.simUnlock(GSM_PIN)
Wait for network registration to be successful
- modem.waitForRegistration(600000L)
Check the Signal Quality to make sure it has reached to a stable stage with
- modem.getSignalQuality()
To establish a data connection (GPRS or EPS), If using cellular, establish the GPRS or EPS data connection after your are successfully registered on the network
- modem.gprsConnect(apn, gprsUser, gprsPass) (or simply modem.gprsConnect(apn)). The same command is used for both GPRS or EPS connection
- For SIM7070/7080/7090, use the new API modem.activateDataNetwork() to establish a data connection
- If using a Digi brand cellular XBee, you must specify your GPRS/EPS connection information before waiting for the network. This is true ONLY for Digi cellular XBees!
Connect the TCP or SSL client client.connect(server, port)
Send out your data as TCP packet, or compose your HTTP request as per HTTP protocol.

If you have any issues

Read the whole README (you're looking at it!), particularly the troubleshooting section below.
Take a look at the example similar to your application.
Try running the Diagnostics sketch

How does it work?

SimpleNB behind the scene wrap AT commands and parse the feedback fom the AT Commands to get the important parameters, and provide an easy-to-use API. In most of the case, the syntax of the APIs are resemble of typical Arduino Client interface.

This library is "blocking" in all of its communication. Depending on the function, your code may be blocked for a long time waiting for the module responses. Some functions (e.g. modem.waitForRegistration(), modem.retart() or modem.getGPS()) may block your code for several seconds or even 1 to 2 minute, others may need you to loop through until the return value confirms a value indicating a success (e.g. modem.checkSignalQuality()).

This libary does not support any sort of "hardware" or pin level controls for the modules. If you need to turn your module on or reset it using some sort of High/Low/High pin sequence, you must write those functions yourself.

API Reference

For TCP data streams, this library follows the standard Arduino Client API interface. The AllFunctions example pro

SimpleNB

Install / Use

README

SimpleNB

Supported modules

Supported Features

Credits

Getting Started

First Steps

Writing your own code

If you have any issues

How does it work?

API Reference