Merge pull request #9 from arduino-libraries/various-fixes

SMS Enhancements and minor fixes

Author: cristidragomir97

.github/workflows/arduino-lint.yml

@@ -22,7 +22,7 @@ jobs:
         uses: arduino/arduino-lint-action@v1
         with:
           compliance: specification
-          library-manager: submit
+          library-manager: update
           # Always use this setting for official repositories. Remove for 3rd party projects.
           official: true
           project-type: library

README.md

@@ -1,39 +1,44 @@
-# Arduino Cellular 
+# 📡 Arduino Cellular 
 
 [![Arduino Lint](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/arduino-lint.yml) [![Compile Examples](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/compile-examples.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/compile-examples.yml) [![Spell Check](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/spell-check.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/spell-check.yml) [![Sync Labels](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/sync-labels.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/sync-labels.yml) [![Render Documentation](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/render-documentation.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/render-documentation.yml)
 
 
 This library provides a toolkit for interacting with the official Arduino 4G Modules. It allows you to connect to the internet, send and receive SMS messages, and get location from the cellular network or GPS. 
 
 ## Examples
-* [examples/HTTPClient]() - Example of using this library together with [HttpClient]() to connect to a web server
-* [examples/HTTPClient]() - Example of using this library together with [HttpClient]() that uses [BearSSL]() under the hood to create a secure connection to a web server
-* [examples/ReceiveSMS]() - Example for the SMS sending and receiving functionality 
-* [examples/TimeAndLocation]() - Use GPS, or Cellular to acquire the location and time of the device. 
-* [examples/ModemTerminal]() - A handy example for debugging and Testing AT commands 
-
-## Features
+* [DeleteSMS](examples/DeleteSMS) - Example that shows how to delete SMS.
+* [GetLocation](examples/GetLocation) - Shows how to get the current GPS location.
+* [GetTime](examples/GetTime) - Use GPS to acquire the time of the device.
+* [HTTPClient](examples/HTTPClient) - Example of using this library together with [ArduinoHttpClient]() to connect to a web server
+* [HTTPSClient](examples/HTTPSClient) - Example of using this library together with [ArduinoHttpClient]() that uses [BearSSL]() under the hood to create a secure connection to a web server
+* [ModemTerminal](examples/ModemTerminal) - A handy example for debugging and Testing AT commands 
+* [ReceiveSMS](examples/ReceiveSMS) - Example for the SMS sending and receiving functionality 
+* [SendSMS](examples/SendSMS) - Shows how to send an SMS
+
+## ✨ Features
 * Fast 4G connection to the internet
 * Secure SSL connections with BearSSL
 * Get location using GPS or GSM
 * Synchronise time with the cell provider
 * Send and Receive SMS Messages
 
-## Instructions
+## 👀 Instructions
 1. Insert your Arduino 4G module to the Arduino Portenta Mid Carrier
 2. Insert a valid SIM card either on the back of the Arduino 4G miniPCI board, or the **PCIE_SIM** connector on the Portenta Mid Carrier
 3. Connect the 6 **SERIAL1** header pins to their corresponding pins on the **PCIE_BREAKOUT** header using jumpers
 ![](https://raw.githubusercontent.com/arduino-libraries/Arduino_Cellular/main/extras/connection_img/header.jpg?token=GHSAT0AAAAAACNPRJPUBHNVP3J3KMRPUULUZQVDLKQ)
 4. Connect the **3V3 PCIE** pin to the **3V3 Buck** 
 ![](https://raw.githubusercontent.com/arduino-libraries/Arduino_Cellular/main/extras/connection_img/buck.jpg?token=GHSAT0AAAAAACNPRJPUBUCALG2FUCDZ7AVCZQVDLJA)
 5. Connect external power to the Mid Carrier, via the **VIN** (5-12V) because modem use a lot of power when connecting or getting a GPS location. Make sure your supply can handle around 3A. 
-6. Get the APN settings from your network operator and add them to the "ArduinoSecrets.h" file for each sketch
-```c
+6. Get the APN settings from your network operator and add them to the "arduino_secrets.h" file for each sketch
+```cpp
 const char apn[]      = "live.vodafone.com";
 const char gprsUser[] = "live";
 const char gprsPass[] = "";
 ```
 7. Install the library and it's dependencies 
 8. Enjoy
 
+## 📖 Documentation
 
+For more information about this library please read the documentation [here](./docs).

examples/DeleteSMS/DeleteSMS.ino

@@ -0,0 +1,63 @@
+/**
+ * This example demonstrates how to delete SMS messages using the ArduinoCellular library.
+ * 
+ * Instructions:
+ * 1. Insert a SIM card with or without PIN code in the Arduino Pro 4G Module.
+ * 2. Provide sufficient power to the Arduino Pro 4G Module. Ideally, use a 5V power supply
+ *    with a current rating of at least 2A and connect it to the VIN and GND pins.
+ * 3. Send an SMS to the SIM card number to test the SMS reception.
+ * 4. Upload the sketch to the connected Arduino board.
+ * 5. Check the serial monitor for the received SMS.
+ * 6. Enter the index of the SMS you want to delete in the serial monitor.
+ * 
+ * Initial author: Sebastian Romero
+*/
+
+#include "ArduinoCellular.h"
+
+ArduinoCellular cellular = ArduinoCellular();
+
+void printMessages(std::vector<SMS> msg){
+     for(int i = 0; i < msg.size(); i++){
+        Serial.println("SMS:");
+        Serial.print("* Index: "); Serial.println(msg[i].index);
+        Serial.print("* From: "); Serial.println(msg[i].sender);
+        Serial.print("* Timestamp: "); Serial.println(msg[i].timestamp.getISO8601());
+        Serial.println("* Message: "); Serial.println(msg[i].message);
+        Serial.println("--------------------\n");
+    }
+}
+
+void setup(){
+    Serial.begin(115200);
+    while (!Serial);
+    cellular.begin();
+    delay(2000); // Give the modem some time to initialize
+}
+
+void loop(){
+    std::vector<SMS> readSMS = cellular.getReadSMS();
+    if(readSMS.size() > 0){
+        Serial.println("Read SMS:");
+        printMessages(readSMS);
+    }
+
+    std::vector<SMS> unreadSMS = cellular.getUnreadSMS();
+    if(unreadSMS.size() > 0){
+        Serial.println("Unread SMS:");
+        printMessages(unreadSMS);
+    }
+
+    // Prompt user which SMS to delete
+    Serial.println("Enter the index of the SMS you want to delete:");
+    
+    while(Serial.available() == 0);
+    auto index = Serial.readStringUntil('\n').toInt();
+    Serial.println("Deleting SMS...");
+
+    if(cellular.deleteSMS(index)){
+        Serial.println("SMS deleted.");
+    } else {
+        Serial.println("Failed to delete SMS.");
+    }
+}

examples/GetLocation/GetLocation.ino

@@ -0,0 +1,37 @@
+/**
+ * This example demonstrates how to get the current GPS location using the ArduinoCellular library.
+ * 
+ * Instructions:
+ * 1. Move the Arduino Pro 4G Module to an outdoor location with a clear view of the sky.
+ * 2. Provide sufficient power to the Arduino Pro 4G Module. Ideally, use a 5V power supply
+ * 3. Upload the sketch to the connected Arduino board.
+ * 4. Open the serial monitor to view the output.
+ * 
+ * Initial author: Sebastian Romero
+*/
+
+#include "ArduinoCellular.h"
+
+ArduinoCellular cellular = ArduinoCellular();
+
+void setup(){
+    Serial.begin(115200);
+    while (!Serial);
+    cellular.setDebugStream(Serial);
+    cellular.begin();
+    
+    if(!cellular.enableGPS()){
+        Serial.println("Failed to enable GPS");
+        while(true); // Stop the program
+    }
+    delay(2000); // Give the modem some time to initialize
+}
+
+void loop(){
+    Location location = cellular.getGPSLocation();
+    Serial.println("GPS Location:");
+    Serial.print("* Latitude: "); Serial.println(location.latitude, 6);
+    Serial.print("* Longitude: "); Serial.println(location.longitude, 6);
+    Serial.println("--------------------\n");
+    delay(10000);
+}

examples/GetTime/GetTime.ino

@@ -0,0 +1,41 @@
+/**
+ * This example demonstrates how to get the current time using the ArduinoCellular library.
+ * It derives the time from GPS connection.
+ * 
+ * Instructions:
+ * 1. Move the Arduino Pro 4G Module to an outdoor location with a clear view of the sky.
+ * 2. Provide sufficient power to the Arduino Pro 4G Module. Ideally, use a 5V power supply
+ * 3. Upload the sketch to the connected Arduino board.
+ * 4. Open the serial monitor to view the output.
+ * 
+ * Initial author: Cristian Dragomir
+*/
+
+#include "ArduinoCellular.h"
+
+ArduinoCellular cellular = ArduinoCellular();
+
+void setup(){
+    Serial.begin(115200);
+    while (!Serial);
+    cellular.begin();
+
+    if(!cellular.enableGPS()){
+        Serial.println("Failed to enable GPS");
+        while(true); // Stop the program
+    }
+    delay(2000); // Give the modem some time to initialize
+}
+
+void loop(){
+    Location location = cellular.getGPSLocation(10000);
+
+    if(location.latitude == 0.0 && location.longitude == 0.0){
+        Serial.println("Failed to get GPS location");
+    } else {
+        Time time = cellular.getGPSTime();
+        Serial.print("Current time (ISO8601): "); Serial.println(time.getISO8601());
+    }
+    
+    delay(10000);
+}

examples/HTTPClient/HTTPClient.ino

@@ -1,3 +1,18 @@
+/**
+ * This example demonstrates how to make a HTTP GET request using 
+ * the ArduinoHttpClient library and the ArduinoCellular library.
+ * 
+ * Instructions:
+ * 1. Insert a SIM card with or without PIN code in the Arduino Pro 4G Module.
+ * 2. Provide sufficient power to the Arduino Pro 4G Module. Ideally, use a 5V power supply
+ *    with a current rating of at least 2A and connect it to the VIN and GND pins.
+ * 3. Specify the APN, login, and password for your cellular network provider.
+ * 4. Upload the sketch to the connected Arduino board.
+ * 5. Open the serial monitor to view the output.
+ * 
+ * Initial author: Cristian Dragomir
+*/
+
 #define ARDUINO_CELLULAR_DEBUG
 
 #include "ArduinoCellular.h"
@@ -10,14 +25,7 @@ const int  port       = 80;
 ArduinoCellular cellular = ArduinoCellular();
 HttpClient client = cellular.getHTTPClient(server, port);
 
-void setup(){
-    Serial.begin(115200);
-    while (!Serial);
-    cellular.begin();
-    cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD, SECRET_PINNUMBER);
-}
-
-void loop(){
+void getResource(){
 
   Serial.println("Making GET request...");
 
@@ -32,7 +40,27 @@ void loop(){
   Serial.println(response);
 
   client.stop();
+}
 
-  delay(5000);
+void setup(){
+    Serial.begin(115200);
+    while (!Serial);
+    // cellular.setDebugStream(Serial); // Uncomment this line to enable debug output
+    cellular.begin();
 
+    if(String(SECRET_PINNUMBER).length() > 0 && !cellular.unlockSIM(SECRET_PINNUMBER)){
+        Serial.println("Failed to unlock SIM card.");
+        while(true); // Stop here
+    }
+
+    Serial.println("Connecting...");
+    if(!cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD)){
+        Serial.println("Failed to connect to the network.");
+        while(true); // Stop here
+    }
+    Serial.println("Connected!");
+
+    getResource();
 }
+
+void loop(){}

examples/HTTPSClient/HTTPSClient.ino

@@ -1,3 +1,17 @@
+/**
+ * Example demonstrating how to make an HTTPS GET request using 
+ * the ArduinoHttpClient library and the ArduinoCellular library.
+ * 
+ * Instructions:
+ * 1. Insert a SIM card with or without PIN code in the Arduino Pro 4G Module.
+ * 2. Provide sufficient power to the Arduino Pro 4G Module. Ideally, use a 5V power supply
+ *   with a current rating of at least 2A and connect it to the VIN and GND pins.
+ * 3. Specify the APN, login, and password for your cellular network provider.
+ * 4. Upload the sketch to the connected Arduino board.
+ * 5. Open the serial monitor to view the output.
+ * 
+ * Initial author: Cristian Dragomir
+*/
 
 #include <Arduino.h>
 #include "ArduinoCellular.h"
@@ -11,15 +25,7 @@ const int  port       = 443;
 ArduinoCellular cellular = ArduinoCellular();
 HttpClient client = cellular.getHTTPSClient(server, port);
 
-void setup(){
-    Serial.begin(115200);
-    while (!Serial);
- 
-    cellular.begin();
-    cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD, SECRET_PINNUMBER);
-}
-
-void loop(){
+void getResource(){
   Serial.println("Making GET request...");
 
   client.get(resource);
@@ -33,5 +39,28 @@ void loop(){
   Serial.println(response);
 
   client.stop();
-  delay(5000);
 }
+
+void setup(){
+    Serial.begin(115200);
+    while (!Serial);
+ 
+    // cellular.setDebugStream(Serial); // Uncomment this line to enable debug output
+    cellular.begin();
+
+    if(String(SECRET_PINNUMBER).length() > 0 && !cellular.unlockSIM(SECRET_PINNUMBER)){
+        Serial.println("Failed to unlock SIM card.");
+        while(true); // Stop here
+    }
+
+    Serial.println("Connecting...");
+    if(!cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD)){
+        Serial.println("Failed to connect to the network.");
+        while(true); // Stop here
+    }
+    Serial.println("Connected!");
+
+    getResource();
+}
+
+void loop(){}