Arduino® Portenta Cat. M1/NB IoT GNSS Shield Cheat Sheet

The Arduino Portenta Cat. M1/NB IoT GNSS Shield is a board that enables cellular connectivity with both Cat. M1 and NB-IoT networks. Easily track your valuable assets across the city or worldwide by choosing among GPS, GLONASS, Galileo or BeiDou Satellite navigation system.

This article is a collection of guides, API calls and tutorials that can help you get started with the Portenta Cat. M1/NB IoT GNSS Shield board. You can also visit the documentation product page for the Portenta Cat. M1/NB IoT GNSS Shield for more in-depth tutorials about the different features.

Core

The Portenta Cat. M1/NB IoT GNSS Shield uses the libraries from the Arduino Mbed OS Portenta core.

The libraries are included in the mbed Core version greater than 2.6.1

Installation

Arduino IDE

The Portenta Cat. M1/NB IoT GNSS Shield can be programmed through the Classic Arduino IDE 1.8.X and Arduino IDE 2.

To install your board, you can check out the guides below:

• Installing the Arduino Mbed OS Portenta Boards core
• How to use the board manager with the Arduino IDE 2

Web Editor

The board can be programmed through the Web Editor. To get started with your board, you will only need to install a plug-in, which is explained in the guide below:

• Getting started with the Web Editor

Pins

As a Portenta family shield, it uses High Density Connectors to interface with the Portenta board which is connected to.

GSM

Requirements

The GSM feature requires:

• An antenna (e.g Dipole antenna, at the Arduino store connected to the RF OUT antenna connector on the top side of the shield
• SIM card capable of running according to Cat. M1 specifications (check with your provider if your SIM card has this feature)

To check if your setup is properly working, you can open an example sketch from the GSM library inside the Mbed Portenta Core. Under Examples > GSM > GSMClient, open a sketch that allows you to connect to the SIM card provider, then connect to a webpage, download its content and display it inside the Serial Monitor.

Make sure you go to the

arduino_secrets.h

• Enter the PIN of your SIM card and store it in the variable

  SECRET_PIN

  .
• Check the mobile APN of your SIM card provider, e.g "online.provider.com", and save it inside the

  SECRET_APN

  . You can find this information by searching online for APN + provider name.

APN stands for 'Access Point Name'. An APN is a gateway between a cellular network and the Internet.

After finishing this setup, compile, and upload the program. If everything went fine, you should see the HTML content of the webpage printed in the Serial Monitor.

Sometimes it takes time to connect to the provider's APN, please be patient, it can take up to 30 minutes. If you cannot connect after that time, make sure you entered the correct SIM pin and the APN. If the issue persists, contact your provider and verify whether Cat. M1 is enabled on your SIM card.

API

To get familiar with the commands, you can take a look at the GSM library which uses the same API.

This library contains some commands that are quite different, because it leverages mbed APIs. In this case, it uses the NetworkInterface, CellularContext and CellularDevice classes. For more information about API visit https://os.mbed.com/docs/mbed-os/v6.14/apis/network-interface-apis.html.

GSM.begin(PIN, APN, USERNAME, PASSWORD, CATNB/CATM1, BAND_#)

GSMClient

GSM.getTime()

GSM.getLocalTime()

GSM.setTime()

GSM.debug()

GSMClient.connect(server,port)

GSMClient.available()

GSMClient.read()

GSMClient.stop()

Available Frequency Bands

It is possible to establish a connection within desired frequency band for the Portenta Cat. M1/NB IoT GNSS Shield. To do this, you need to define frequency bands for

GSM.begin(PIN, APN, USERNAME, PASSWORD, CATNB/CATM1, BAND_#)

BAND_#

The list of available frequency bands that can be used for the device's credential configuration is as follows:

These are Cat.M and Cat.NB frequency bands that are available for use with TX62-W, referred to as the LTE Cat.M1 and Cat.NB1 Engine. The Portenta Cat. M1/NB IoT GNSS Shield is capable of the present network connectivity thanks to its onboard TX62-W Cellular-GNSS LPWAN modem.

The band configuration is available to allow the user to restrict to a specific or combination of frequency bands. It helps to operate under enforced frequency policy requirements, or to lower the network search time, reducing the device power consumption.

If you leave the frequency band

BAND_#

GSM.begin(PIN, APN, USERNAME, PASSWORD, CATNB/CATM1, BAND_#)

Each country has a compatible frequency band, so it is a good practice to check the if desired band is suitable for its region. You can check the frequency band compatibility of the region by using a website that compiles network status such as here.

Connect to Your Provider

You need to enter the Pin code and the APN link of your provider.

The username and password depend on your provider; these are required to authenticate with the APN gateway. These values can usually be found by searching online for APN credentials and provider names. Sometimes they can be left blank.

The following sketch will initialize the SIM card and connect to your provider network within supported bands:

Copy
1#include <GSM.h>
2
3char pin[]      = SECRET_PIN;     //example "1234"
4char apn[]      = SECRET_APN;    //example "live.provider.com"
5char username[] = SECRET_USERNAME;
6char pass[]     = SECRET_PASSWORD;
7
8void setup() {
9  Serial.begin(115200);
10  while(!Serial) {}
11
12  if(GSM.begin(pin, apn, username, pass, CATM1)){
13    Serial.println("connected");
14    // ...
15  }
16}

The following example shows how the

GSM.begin()

BAND_20

BAND_19

Copy
1void setup() {
2  Serial.begin(115200);
3  while(!Serial) {}
4
5  if(GSM.begin(pin, apn, username, pass, CATM1, BAND_20 | BAND_19)){
6    Serial.println("connected");
7    // ...
8  }
9}

Please check how the frequency band configuration works briefly within the Available Frequency Bands section. The list of available frequency bands for the shield's cellular connectivity configuration can also be found in the previous section.

Send a HTTP GET Request and Receive Data

The following sketch will connect to your provider and use a HTTP GET request to get data from the server you are connected to. In this case, it connects to "example.com" and prints out the content through the Serial Monitor.

Copy
1#include <GSM.h>
2
3REDIRECT_STDOUT_TO(Serial);
4
5char pin[]      = SECRET_PIN;       //example "1234"
6char apn[]      = SECRET_APN;         //example "live.provider.com"
7char username[] = SECRET_USERNAME;
8char pass[]     = SECRET_PASSWORD;
9
10const char  server[] = "www.example.com";
11const char* ip_address;
12int port = 80;
13
14GSMClient client;
15
16void setup() {
17  Serial.begin(115200);
18  while(!Serial) {}
19
20  GSM.begin(pin, apn, username, pass, CATNB);
21  
22  Serial.println("\nStarting connection to server...");
23  // if you get a connection, report back via serial:
24  if (client.connect(server, port)) {
25    Serial.println("connected to server");
26    // Make a HTTP request:
27    client.println("GET / HTTP/1.1");
28    client.print("Host: ");
29    client.println(server);
30    client.println("Connection: close");
31    client.println();
32  } else {
33    Serial.println("unable to connect to server");
34  }
35  
36}
37
38void loop() {
39
40  // if there are incoming bytes available
41  // from the server, read them and print them:
42  while (client.available()) {
43    char c = client.read();
44    Serial.write(c);
45  }
46
47  // if the server's disconnected, stop the client:
48  if (!client.connected()) {
49    Serial.println();
50    Serial.println("disconnecting from server.");
51    client.stop();
52
53    // do nothing forevermore:
54    while (true);
55  }
56
57}

GPS

Requirements

The GPS feature requires:

• A GPS active antenna (e.g GPS active antenna 28dB) connected to the GNS ANT antenna connector on the top side of the shield.
• You may need a connector converter from the active GPS antenna, we used this one Coaxial to SMA

To check if your setup is properly working, you can open an example inside the GSM library from the Mbed Portenta Core, going to Examples > GSM > GNSSClient. You will open an sketch that connects to the SIM card provider and initializes the active GPS antenna. At this point, it will print out GPS readings.

Make sure you go to the

arduino_secrets.h

• Add the PIN of the SIM card you are using and store it in the variable

  SECRET_PIN

  .
• Browse your IT provider and check the mobile APN link, e.g "online.provider.com" save it inside the

  SECRET_APN

Sometimes it takes time to connect to the provider's APN, please be patient, it can take up to 30 minutes. If you cannot connect after that time, make sure you added the correct SIM pin and the APN. If the issue continues, contact your provider and verify whether Cat. M1 is enabled on your SIM card.

API

GPS.begin()

GPS.end()

GPS.available()

GPS.read()

char

GPS.readAndPrint()

GPS.readAndDrop()

GPS.checkGNSSEngine()

Get GPS Data

The following example connects to the GSM provider, then initializes the GPS antenna, gets data and prints them out on the Serial Monitor. As done previously, you need to provide the GSM data by filling the secrets in

arduino_secrets.h

Open the example by going to Examples > GSM > GNSSClient.

Copy
1#include <GPS.h>
2  #include <GSM.h>
3
4  REDIRECT_STDOUT_TO(Serial);
5
6  #include "arduino_secrets.h"
7  char pin[]      = SECRET_PIN;
8  char apn[]      = SECRET_APN;
9  char username[] = SECRET_USERNAME;
10  char pass[]     = SECRET_PASSWORD;
11
12  void setup() {
13    Serial.begin(115200);
14    while (!Serial) {}
15    //GSM.debug(Serial);
16    Serial.println("\nStarting connection to GSM...");
17    GSM.begin(pin, apn, username, pass, CATNB);
18
19    Serial.println("\nEnable GNSS Engine..."); 
20    GPS.begin();  //start and enable the GNSS engine
21    Serial.println("\nGNSS Engine enabled...");
22  }
23
24  void loop() {
25    while(GPS.available()){
26      Serial.print((char) GPS.read());
27      delay(1);
28    }
29
30    delay(1000);
31  }

Remember to connect to the GSM provider first and secondly connect to the GNSS (mandatory).

You will see the NMEA data in the Serial Monitor.

Parse NMEA GPS Sentences

Previously we went through how to show the GPS data in the Serial Monitor, but it was not possible to evaluate those messages (NMEA sentences).

To do so, you can use an NMEA parser. This will convert messages received from the GPS modem, parsing and saving them into variables. You can use the 107-Arduino-NMEA-Parser library. This library can be found in the library manager inside the Arduino IDE.

In this way, it is possible to interact with the data that you need for your application, for instance getting only latitude and longitude. You will be able to save those values into variables, instead of having the whole NMEA messages.

Open the example from the library at Examples > 107-Arduino-NMEA-Parser > NMEA-Basic and add the following:

Include the needed libraries.

Copy
1#include "GPS.h"
2  #include "GSM.h"
3  #include "ArduinoNmeaParser.h"
4  #include "Arduino_secrets.h"
5
6  char pin[]      = SECRET_PIN;
7  char apn[]      = SECRET_APN;
8  char username[] = SECRET_LOGIN;
9  char pass[]     = SECRET_PASS;

Inside the

setup()

Copy
1void setup(){
2    Serial.begin(115200);
3    while (!Serial) {}
4    Serial.println("GSM...");
5    GSM.begin(pin, apn, username, pass, CATNB);
6    Serial.println("GPS...");
7    GPS.begin();
8    Serial.println("Success");
9  }

Edit the loop to parse the

GPS

Serial1

Copy
1void loop(){
2    while(GPS.available()){
3      parser.encode((char)GPS.read());
4    }
5  }

You will see the output data as various "-1" until the GPS has enough visible satellites to get the correct data. Make sure the GPS antenna is pointing at the sky.

Low Power GPS

The GPS antenna is active, that means that it needs power to function as it has electronics inside of it.

One way to save power on your project is to enable the GPS module only when it needs to read data:

Copy
1//Start the GPS module
2  GPS.begin();    
3
4  // Print data
5  while(GPS.available()){
6    Serial.print((char) GPS.read());
7    delay(1);
8  }
9
10  //stop and disable the GNSS engine
11  GPS.end();

By using this method, you don't need to initialize the GPS inside the

setup()

Conclusion

This cheat sheet is written as a quick reference to look up the GSM and GPS feature of this product. For a more in-depth walk through experience, please have a look at the other tutorials.

Troubleshooting

• If you are getting compiling errors using GPS and GSM, make sure you included first the

  GPS.h

  library and then the

  GSM.h

  .
• Sometimes, while the GPS module is getting readings, you will not be able to upload a new sketch. Double tap the reset button on your Portenta H7 and upload the new sketch.