|
| 1 | +--- |
| 2 | +title: 'Arduino® Portenta Cat. M1/NB IoT GNSS Shield Cheat Sheet' |
| 3 | +description: 'Learn how to set up the Arduino® Portenta Cat. M1/NB IoT GNSS Shield and get a quick overview of the functionality. Obtain information regarding pins and how to use the different communication technologies.' |
| 4 | +tags: |
| 5 | + - Installation |
| 6 | + - Cat. M1 |
| 7 | + - NB IoT |
| 8 | + - GNSS |
| 9 | +author: 'Pablo Marquínez' |
| 10 | +hardware: |
| 11 | + - hardware/04pro/shields/portenta-cat-m1-nb-iot-gnss-shield |
| 12 | +software: |
| 13 | + - ide-v1 |
| 14 | + - ide-v2 |
| 15 | + - web-editor |
| 16 | +--- |
| 17 | + |
| 18 | + |
| 19 | + |
| 20 | +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 with your choice of the GPS, GLONASS, Galileo or BeiDou Satellite navigation system. |
| 21 | + |
| 22 | +This article is a collection of guides, API calls and tutorials that can help you get started with the Arduino® Portenta Cat. M1/NB IoT GNSS Shield board. You can also visit the [documentation product page for the Arduino® Portenta Cat. M1/NB IoT GNSS Shield](/hardware/portenta-cat-m1-nb-iot-gnss-shield) for more in-depth tutorials about the different features. |
| 23 | + |
| 24 | +## Core |
| 25 | + |
| 26 | +The Arduino® Portenta Cat. M1/NB IoT GNSS Shield uses the libraries from the [Arduino Mbed OS Portenta core](https://github.com/arduino/ArduinoCore-mbed). |
| 27 | + |
| 28 | +***The libraries are included in the mbed Core version greater than 2.6.1*** |
| 29 | + |
| 30 | +## Installation |
| 31 | + |
| 32 | +### Arduino IDE 1.8.X |
| 33 | + |
| 34 | +The Arduino® Portenta Cat. M1/NB IoT GNSS Shield can be programmed through the **Classic Arduino IDE 1.8.X**. To install your board, you can check out the guide below: |
| 35 | + |
| 36 | +- [Installing the Arduino Mbed OS Portenta Boards core](/software/ide-v1/tutorials/getting-started/cores/arduino-mbed_portenta) |
| 37 | + |
| 38 | +### Arduino IDE 2.0.X |
| 39 | + |
| 40 | +The Arduino® Portenta Cat. M1/NB IoT GNSS Shield can be programmed through the **Arduino IDE 2**. To install your board, you can check out the guide below: |
| 41 | + |
| 42 | +- [How to use the board manager with the Arduino IDE 2.0](https://www.arduino.cc/en/Tutorial/getting-started-with-ide-v2/ide-v2-board-manager) |
| 43 | + |
| 44 | +### Web Editor |
| 45 | + |
| 46 | +The board can be programmed through the **Web Editor**. To get started with your board, you will only need to install a plugin, which is explained in the guide below: |
| 47 | + |
| 48 | +- [Getting started with the Web Editor](/cloud/web-editor/tutorials/getting-started/getting-started-web-editor) |
| 49 | + |
| 50 | +## Pins |
| 51 | +As a Portenta family Shield it uses the High density pins to be available for the Portenta board which is being connected. |
| 52 | + |
| 53 | + |
| 54 | +## GSM |
| 55 | + |
| 56 | +### Requirements |
| 57 | + |
| 58 | +The GSM Feature requires: |
| 59 | +* An antenna (e.g [Dipole antenna, at the arduino store](https://store.arduino.cc/products/dipole-pentaband-waterproof-antenna?queryID=52d9fdab80e7fcace62aae924c084a93&_gl=1*msh8uc*_ga*MjA5OTMyMzAwMC4xNjIxNTE1OTY3*_ga_NEXN8H46L5*MTYzMDkzMzQ3NS40NS4xLjE2MzA5MzM5MTAuMA..)) at the **RF OUT** antenna connector on the top side of the shield. |
| 60 | +* SIM Card capable of running with the CatM1 specifications (check with your provider if your Card has that feature) |
| 61 | + |
| 62 | +To check if our setup it's working we can open an example sketch from the GSM library inside the Mbed Portenta Core. Under **Examples > GSM > GSMClient** we open a sketch that connects to the SIM card provider, then connects to a webpage and downloads the content of it to display it inside the Serial Monitor. |
| 63 | + |
| 64 | +Make sure you go to the `arduino_secrets.h` tab and: |
| 65 | +* Enter the PIN of your SIM card and store it at `SECRET_PIN`. |
| 66 | +* Check the mobile APN of your SIM card provider, e.g "online.provider.com" and save it inside the `SECRET_APN` |
| 67 | + |
| 68 | +After finishing this setup compile and upload the program. If everything went fine you should see the HTML content of the web page printed in the serial monitor. |
| 69 | +***Note: 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 make sure they have CAT M1 enabled on your SIM card.*** |
| 70 | + |
| 71 | +### API |
| 72 | + |
| 73 | +To get familiar with the commands, you can have a look at the [MKR GSM library](https://www.arduino.cc/en/Reference/GSM) which uses the same API. |
| 74 | + |
| 75 | +This library contains some commands that are quite different, that's because it is using mbed APIs. In this case it uses the NetworkInterface, CellularContext and CellularDevice classes. For more information about their API visit [https://os.mbed.com/docs/mbed-os/v6.14/apis/network-interface-apis.html](https://os.mbed.com/docs/mbed-os/v6.14/apis/network-interface-apis.html). |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +| Command | Information | |
| 80 | +| :----------------------------------------------------: | :----------------------------------------------------------: | |
| 81 | +| `GSM.begin(PIN, APN, USERNAME, PASSWORD, CATNB/CATM1)` | Unlock the SIM card using the PIN parameter and connects to the provider. | |
| 82 | +| `GSMClient`| Client constructor, on the examples we define it as client | |
| 83 | +| `GSM.getTime()`|Returns the time, you can set a new one with setTime()| |
| 84 | +| `GSM.getLocalTime()`| Returns the local time| |
| 85 | +| `GSM.setTime()`| Set the time, it will be saved and it can be read with getTime() | |
| 86 | +| `GSM.debug()`| After this command, the Serial monitor will output more detailed info about the GSM class commands, connections, etc... | |
| 87 | +| `GSMClient.connect(server,port)` | Connect to a remote server | |
| 88 | +| `GSMClient.available()` | Check if the server that is connected to has some bytes ready to be read | |
| 89 | +| `GSMClient.read()` | Returns data from the server | |
| 90 | +| `GSMClient.stop()` | Disconnects from the server | |
| 91 | + |
| 92 | +#### Connect to Your Provider |
| 93 | + |
| 94 | +You need to enter the Pin code and the APN link of your provider. |
| 95 | +The user name and password depends on the provider you have. |
| 96 | + |
| 97 | +This sketch will initialize the SIM card and connect to your provider's network |
| 98 | + |
| 99 | +```cpp |
| 100 | +#include <GSM.h> |
| 101 | + |
| 102 | +char pin[] = SECRET_PIN; //example "1234" |
| 103 | +char apn[] = SECRET_APN; //example "live.provider.com" |
| 104 | +char username[] = SECRET_USERNAME; |
| 105 | +char pass[] = SECRET_PASSWORD; |
| 106 | + |
| 107 | +void setup() { |
| 108 | + Serial.begin(115200); |
| 109 | + while(!Serial) {} |
| 110 | + |
| 111 | + if(GSM.begin(pin, apn, username, pass, CATM1)){ |
| 112 | + Serial.println("connected"); |
| 113 | + // ... |
| 114 | + } |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +#### Send a HTTP GET Request and Receive Data |
| 119 | + |
| 120 | +The following sketch will connect to your provider and use a HTTP GET request to get the data from the server you connect to. In this case it connects to "example.com" and prints out the content through the Serial monitor. |
| 121 | + |
| 122 | +```cpp |
| 123 | +#include <GSM.h> |
| 124 | + |
| 125 | +REDIRECT_STDOUT_TO(Serial); |
| 126 | + |
| 127 | +char pin[] = SECRET_PIN; //example "1234" |
| 128 | +char apn[] = SECRET_APN; //example "live.provider.com" |
| 129 | +char username[] = SECRET_USERNAME; |
| 130 | +char pass[] = SECRET_PASSWORD; |
| 131 | + |
| 132 | +const char server[] = "www.example.com"; |
| 133 | +const char* ip_address; |
| 134 | +int port = 80; |
| 135 | + |
| 136 | +GSMClient client; |
| 137 | + |
| 138 | +void setup() { |
| 139 | + Serial.begin(115200); |
| 140 | + while(!Serial) {} |
| 141 | + |
| 142 | + GSM.begin(pin, apn, username, pass, CATNB); |
| 143 | + |
| 144 | + Serial.println("\nStarting connection to server..."); |
| 145 | + // if you get a connection, report back via serial: |
| 146 | + if (client.connect(server, port)) { |
| 147 | + Serial.println("connected to server"); |
| 148 | + // Make a HTTP request: |
| 149 | + client.println("GET / HTTP/1.1"); |
| 150 | + client.print("Host: "); |
| 151 | + client.println(server); |
| 152 | + client.println("Connection: close"); |
| 153 | + client.println(); |
| 154 | + } else { |
| 155 | + Serial.println("unable to connect to server"); |
| 156 | + } |
| 157 | + |
| 158 | +} |
| 159 | + |
| 160 | +void loop() { |
| 161 | + |
| 162 | + // if there are incoming bytes available |
| 163 | + // from the server, read them and print them: |
| 164 | + while (client.available()) { |
| 165 | + char c = client.read(); |
| 166 | + Serial.write(c); |
| 167 | + } |
| 168 | + |
| 169 | + // if the server's disconnected, stop the client: |
| 170 | + if (!client.connected()) { |
| 171 | + Serial.println(); |
| 172 | + Serial.println("disconnecting from server."); |
| 173 | + client.stop(); |
| 174 | + |
| 175 | + // do nothing forevermore: |
| 176 | + while (true); |
| 177 | + } |
| 178 | + |
| 179 | +} |
| 180 | +``` |
| 181 | +
|
| 182 | +## GPS |
| 183 | +
|
| 184 | +### Requirements |
| 185 | +
|
| 186 | +The GSM Feature requires: |
| 187 | +* A GPS active antenna (e.g [GPS active antenna 28dB](https://www.digikey.com/en/products/detail/adafruit-industries-llc/960/5353630)) at the **GNS ANT** antenna connector on the Top side of the shield. |
| 188 | +* You may need a connector converter from the active GPS antenna, we used this one [Coaxial to SMA](https://www.digikey.com/en/products/detail/taoglas-limited/CAB.719/3664639) |
| 189 | +
|
| 190 | +To check if our setup it's working we can open an example inside the GSM library from the Mbed Portenta Core, going to **Examples > GSM > GNSSClient** we will open an sketch that connects to the SIM card provider and initialize the active GPS antenna, then it will print out GPS readings. |
| 191 | +
|
| 192 | +Make sure you go to the `arduino_secrets.h` tab and: |
| 193 | +* introduce the PIN of the SIM card you are using and store it at `SECRET_PIN`. |
| 194 | +* Browse to your IT provider and check the mobile APN link, e.g "online.provider.com" save it inside the `SECRET_APN` |
| 195 | +
|
| 196 | +>**Note:** Sometimes it needs time to connect to the provider's APN, please be patient, it can take up to 30 minutes. If you can not connect after that time, make sure you introduced the correct SIM pin and the APN, if the issue continues, contact with your provider and make sure they have CAT M1 enabled on your SIM card. |
| 197 | +
|
| 198 | +### API |
| 199 | +
|
| 200 | +
|
| 201 | +| Command | Information | |
| 202 | +| :--------------------------------------------------: | :----------------------------------------------------------: | |
| 203 | +| `GPS.begin()` | Initialize the GPS modem | |
| 204 | +| `GPS.end()` | Turn OFF the GPS modem. | |
| 205 | +| `GPS.available()` | Check if the GPS has new data to be read. | |
| 206 | +| `GPS.read()` | Returns a `char` with the reading from the GPS module. | |
| 207 | +| `GPS.readAndPrint()` | Output data on the Serial monitor, only if there is new data.| |
| 208 | +| `GPS.readAndDrop()` | Read the data and do nothing with it. | |
| 209 | +| `GPS.checkGNSSEngine()` | Check if the GNSS modem is receiving data correctly. | |
| 210 | +
|
| 211 | +
|
| 212 | +#### Get GPS Data |
| 213 | +
|
| 214 | +We included an example inside the GSM example that connects to the GSM provider, then initialize the GPS antenna, gets the data and print it out on the Serial monitor. |
| 215 | +
|
| 216 | +Open the example by going to **Examples > GSM > GNSSClient** |
| 217 | +
|
| 218 | +The sketch: |
| 219 | +```cpp |
| 220 | + #include <GPS.h> |
| 221 | + #include <GSM.h> |
| 222 | +
|
| 223 | + REDIRECT_STDOUT_TO(Serial); |
| 224 | +
|
| 225 | + #include "arduino_secrets.h" |
| 226 | + char pin[] = SECRET_PIN; |
| 227 | + char apn[] = SECRET_APN; |
| 228 | + char username[] = SECRET_USERNAME; |
| 229 | + char pass[] = SECRET_PASSWORD; |
| 230 | +
|
| 231 | + void setup() { |
| 232 | + Serial.begin(115200); |
| 233 | + while (!Serial) {} |
| 234 | + //GSM.debug(Serial); |
| 235 | + Serial.println("\nStarting connection to GSM..."); |
| 236 | + GSM.begin(pin, apn, username, pass, CATNB); |
| 237 | +
|
| 238 | + Serial.println("\nEnable GNSS Engine..."); |
| 239 | + GPS.begin(); //start and enable the GNSS engine |
| 240 | + Serial.println("\nGNSS Engine enabled..."); |
| 241 | + } |
| 242 | +
|
| 243 | + void loop() { |
| 244 | + if(GPS.available()){ |
| 245 | + Serial.print((char) GPS.read()); |
| 246 | + delay(1); |
| 247 | + } |
| 248 | +
|
| 249 | + delay(1000); |
| 250 | + } |
| 251 | +``` |
| 252 | +***As you previously done, you need to set up the GSM info and fill the `arduino_secrets.h`*** |
| 253 | + |
| 254 | +***Remember to connect to the GSM provider and secondly connect to the GNSS (mandatory).*** |
| 255 | + |
| 256 | +You will see the **NMEA** data on the Serial monitor. |
| 257 | + |
| 258 | + |
| 259 | +#### Low Power GPS |
| 260 | + |
| 261 | +The GPS antenna is active, that means that it needs power to function as it has electronics inside of it. |
| 262 | +One way to save power on your project is enabling only the GPS module when it is needed to read the data. |
| 263 | + |
| 264 | +You can do so as follows: |
| 265 | + |
| 266 | +```cpp |
| 267 | + //Start the GPS module |
| 268 | + GPS.begin(); |
| 269 | + |
| 270 | + // Print data |
| 271 | + if(GPS.available()){ |
| 272 | + Serial.print((char) GPS.read()); |
| 273 | + delay(1); |
| 274 | + } |
| 275 | + |
| 276 | + //stop and disable the GNSS engine |
| 277 | + GPS.end(); |
| 278 | +``` |
| 279 | +***By using this method, you don't need to initialize the GPS inside the `setup()`*** |
| 280 | +
|
| 281 | +## Conclusion |
| 282 | +
|
| 283 | +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 walkthrough experience please have a look at the other tutorials. |
| 284 | +
|
| 285 | +## Troubleshooting |
| 286 | +
|
| 287 | +### Getting Compiling Errors Using GPS and GSM |
| 288 | +
|
| 289 | +Make sure you included first the `GPS.h` library and then the `GSM.h` |
| 290 | +
|
| 291 | +### Can't Upload the Sketch |
| 292 | +
|
| 293 | +Sometimes if the GPS module is getting readings, you will not be able to upload a new sketch, double tap the reset button on your Potenta H7 and upload the new sketch. |
0 commit comments