diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index bd5d74a..0000000 Binary files a/.DS_Store and /dev/null differ diff --git a/.github/workflows/check-arduino.yml b/.github/workflows/check-arduino.yml deleted file mode 100644 index adb330f..0000000 --- a/.github/workflows/check-arduino.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: Check Arduino - -# See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows -on: - push: - pull_request: - schedule: - # Run every Tuesday at 8 AM UTC to catch breakage caused by new rules added to Arduino Lint. - - cron: "0 8 * * TUE" - workflow_dispatch: - repository_dispatch: - -jobs: - lint: - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Arduino Lint - uses: arduino/arduino-lint-action@v1 - with: - compliance: specification - library-manager: update - # Always use this setting for official repositories. Remove for 3rd party projects. - official: true - project-type: library diff --git a/.github/workflows/compile-examples.yml b/.github/workflows/compile-examples.yml index 310d297..b1d15b8 100644 --- a/.github/workflows/compile-examples.yml +++ b/.github/workflows/compile-examples.yml @@ -26,7 +26,8 @@ env: - examples/HTTPClient - examples/HTTPSClient - examples/TimeAndLocation - - examples/SMSReceive + - examples/ReceiveSMS + - examples/SendSMS SKETCHES_REPORTS_PATH: sketches-reports SKETCHES_REPORTS_ARTIFACT_NAME: sketches-reports @@ -65,9 +66,10 @@ jobs: libraries: | # Install the library from the local path. - source-path: ./ - - name: Arduino_USBHostMbed5 - - name: Arduino_POSIXStorage - - name: ArduinoRS485 + - name: ArduinoBearSSL + - name: StreamDebugger + - name: TinyGSM + - name: ArduinoHttpClient # Additional library dependencies can be listed here. # See: https://github.com/arduino/compile-sketches#libraries sketch-paths: | diff --git a/README.md b/README.md index 4e0a51e..7126dca 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,15 @@ # Arduino Cellular +[![Arduino Lint](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/check-arduino.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Cellular/actions/workflows/check-arduino.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) + 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/SMSReceive]() - Example for the SMS sending and receiving functionality -* [examples/TimeAndLocation]() - Use GPS, or Cellular to aquire the location and time of the device. +* [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 diff --git a/docs/readme.md b/docs/readme.md index 4fe8619..20c9ef4 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -123,7 +123,7 @@ These features enable precise tracking of device locations and ensure synchroniz GPS Location is ideal for applications requiring high-precision location data, such as asset tracking or outdoor navigation solutions. This functionality relies on the Global Version of the modem, which is equipped with GPS capabilities. -To enable GPS Location you will need to call `enableGPS(bool assisted)`. Assisted GPS or A-GPS is an enchancement of GPS that uses the cellular network to get the location, it performs that much quicker than without assistence but depends on Cellular network coverage. +To enable GPS Location you will need to call `enableGPS(bool assisted)`. Assisted GPS or A-GPS is an enhancement of GPS that uses the cellular network to get the location, it performs that much quicker than without assistance but depends on Cellular network coverage. ### Cellular Location **Method Overview:** `getCellularLocation(unsigned long timeout = 10000)` also provides location tracking but utilizes the cellular network. Similar to the GPS method, it's a blocking call with a specified timeout, returning latitude and longitude values through a Location structure. If the location is not obtained, the values default to 0.0. diff --git a/examples/ReceiveSMS/ReceiveSMS.ino b/examples/ReceiveSMS/ReceiveSMS.ino index 4d1720b..6564db4 100644 --- a/examples/ReceiveSMS/ReceiveSMS.ino +++ b/examples/ReceiveSMS/ReceiveSMS.ino @@ -7,7 +7,7 @@ constexpr int NEW_SMS_INTERRUPT_PIN = A0; ArduinoCellular cellular = ArduinoCellular(); -volatile boolean newSMSavailable = false; +volatile boolean smsReceived = false; void printMessages(std::vector msg){ for(int i = 0; i < msg.size(); i++){ @@ -17,21 +17,22 @@ void printMessages(std::vector msg){ Serial.print("\t * Timestamp: "); Serial.println(msg[i].timestamp.getISO8601()); } } -void newSMSCallback(){ +void onSMSReceived(){ Serial.println("New SMS received!"); - newSMSavailable = true; + smsReceived = true; } void setup(){ Serial.begin(115200); while (!Serial); + cellular.setDebugStream(Serial); cellular.begin(); Serial.println("Connecting..."); cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD, SECRET_PINNUMBER); // Register interrupt based callback for new SMS - attachInterrupt(digitalPinToInterrupt(NEW_SMS_INTERRUPT_PIN), newSMSCallback, RISING); + attachInterrupt(digitalPinToInterrupt(NEW_SMS_INTERRUPT_PIN), onSMSReceived, RISING); Serial.println("Read SMS:"); std::vector readSMS = cellular.getReadSMS(); @@ -43,8 +44,8 @@ void setup(){ } void loop(){ - if(newSMSavailable){ - newSMSavailable = false; + if(smsReceived){ + smsReceived = false; std::vector unreadSMS = cellular.getUnreadSMS(); if (unreadSMS.size() > 0){ printMessages(unreadSMS); diff --git a/library.properties b/library.properties index d8289a5..138d0c3 100644 --- a/library.properties +++ b/library.properties @@ -8,4 +8,4 @@ category=Communication url=https://github.com/arduino-libraries/Arduino_Cellular depends=ArduinoBearSSL,StreamDebugger,TinyGSM,ArduinoHttpClient architectures=renesas_portenta, mbed_portenta -includes=ArduinoCellular.h +includes=Arduino_Cellular.h \ No newline at end of file diff --git a/src/ArduinoCellular.cpp b/src/ArduinoCellular.cpp index 46e4577..55f12f3 100644 --- a/src/ArduinoCellular.cpp +++ b/src/ArduinoCellular.cpp @@ -45,7 +45,7 @@ void ArduinoCellular::begin() { bool ArduinoCellular::connect(String apn, String gprsUser, String gprsPass, String pin){ SimStatus simStatus = getSimStatus(); - if(simStatus == SimStatus::SIM_LOCKED) { + if(simStatus == SimStatus::SIM_LOCKED && pin.length() > 0){ unlockSIM(pin.c_str()); } @@ -53,8 +53,15 @@ bool ArduinoCellular::connect(String apn, String gprsUser, String gprsPass, Stri if(simStatus == SimStatus::SIM_READY) { if(awaitNetworkRegistration()){ if(connectToGPRS(apn.c_str(), gprsUser.c_str(), gprsPass.c_str())){ - Serial.println("Setting DNS..."); - Serial.println(this->sendATCommand("+QIDNSCFG=1,\"8.8.8.8\",\"8.8.4.4\"")); + if(this->debugStream != nullptr){ + this->debugStream->println("Setting DNS..."); + } + + auto response = this->sendATCommand("+QIDNSCFG=1,\"8.8.8.8\",\"8.8.4.4\""); + + if(this->debugStream != nullptr){ + this->debugStream->println(response); + } return true; } } else { @@ -83,7 +90,9 @@ Location ArduinoCellular::getGPSLocation(unsigned long timeout){ return loc; } else { - Serial.println("Unsupported modem model"); + if(this->debugStream != nullptr){ + this->debugStream->println("Unsupported modem model"); + } return Location(); } } @@ -108,7 +117,11 @@ void ArduinoCellular::sendSMS(String number, String message){ modem.stream->print(message); // Actually send the message modem.stream->write(static_cast(0x1A)); // Terminate the message modem.stream->flush(); - Serial.println(modem.waitResponse(10000L)); + auto response = modem.waitResponse(10000L); + + if(this->debugStream != nullptr){ + this->debugStream->println("Response: " + String(response)); + } } @@ -141,9 +154,13 @@ bool ArduinoCellular::isConnectedToOperator(){ } bool ArduinoCellular::connectToGPRS(const char * apn, const char * gprsUser, const char * gprsPass){ - Serial.print(F("Connecting to 4G network...")); + if(this->debugStream != nullptr){ + this->debugStream->println("Connecting to 4G network..."); + } while(!modem.gprsConnect(apn, gprsUser, gprsPass)) { - Serial.print("."); + if(this->debugStream != nullptr){ + this->debugStream->print("."); + } delay(2000); } return true; @@ -155,7 +172,9 @@ bool ArduinoCellular::isConnectedToInternet(){ SimStatus ArduinoCellular::getSimStatus(){ int simStatus = modem.getSimStatus(); - Serial.println("SIM Status: " + String(simStatus)); + if(this->debugStream != nullptr){ + this->debugStream->println("SIM Status: " + String(simStatus)); + } if (modem.getSimStatus() == 0) { return SimStatus::SIM_ERROR; @@ -171,21 +190,30 @@ SimStatus ArduinoCellular::getSimStatus(){ } bool ArduinoCellular::unlockSIM(const char * pin){ - Serial.println("Unlocking SIM..."); + if(this->debugStream != nullptr){ + this->debugStream->println("Unlocking SIM..."); + } modem.simUnlock(pin); } bool ArduinoCellular::awaitNetworkRegistration(){ - Serial.print("Waiting for network registration..."); + if(this->debugStream != nullptr){ + this->debugStream->println("Waiting for network registration..."); + } while (!modem.waitForNetwork()) { - Serial.println("."); + if(this->debugStream != nullptr){ + this->debugStream->print("."); + } delay(2000); } return true; } bool ArduinoCellular::enableGPS(bool assisted){ - Serial.println("Enabling GPS..."); + if(this->debugStream != nullptr){ + this->debugStream->println("Enabling GPS..."); + } + if(assisted){ sendATCommand("AT+QGPSCFG=\"agpsposmode\",33488767"); } else { @@ -304,4 +332,6 @@ std::vector ArduinoCellular::getUnreadSMS(){ } } - +void ArduinoCellular::setDebugStream(Stream &stream){ + this->debugStream = &stream; +} diff --git a/src/ArduinoCellular.h b/src/ArduinoCellular.h index c2f2afd..e6ab0a6 100644 --- a/src/ArduinoCellular.h +++ b/src/ArduinoCellular.h @@ -99,7 +99,7 @@ class ArduinoCellular { * @param pin The SIM card PIN. * @return True if the connection is successful, false otherwise. */ - bool connect(String apn, String gprsUser, String gprsPass, String pin); + bool connect(String apn, String gprsUser, String gprsPass, String pin = ""); /** * @brief Checks if the modem is registered on the network. @@ -214,6 +214,16 @@ class ArduinoCellular { */ int getSignalQuality(); + /** + * @brief Sets the debug stream for ArduinoCellular. + * + * This function allows you to set the debug stream for ArduinoCellular. + * The debug stream is used to output debug messages and information. + * + * @param stream A pointer to the Stream object that will be used as the debug stream. + */ + void setDebugStream(Stream& stream); + private: bool connectToGPRS(const char * apn, const char * gprsUser, const char * gprsPass); @@ -249,6 +259,8 @@ class ArduinoCellular { ModemModel model; /**< The modem model. */ + Stream* debugStream = nullptr; /**< The stream to be used for printing debugging messages. */ + static unsigned long getTime(); /** Callback for getting the current time as an unix timestamp. */ }; diff --git a/src/Arduino_Cellular.h b/src/Arduino_Cellular.h new file mode 100644 index 0000000..c38a772 --- /dev/null +++ b/src/Arduino_Cellular.h @@ -0,0 +1,5 @@ +#ifndef ARDUINO_CELLULAR_H + +#include "ArduinoCellular.h" + +#endif \ No newline at end of file