Merge pull request #10 from arduino-libraries/docs

Update documentation

.github/workflows/render-documentation.yml

@@ -21,7 +21,7 @@ jobs:
   render-docs:
     permissions:
       contents: write
-    uses: sebromero/render-docs-github-action/.github/workflows/render-docs.yml@main
+    uses: sebromero/render-docs-github-action/.github/workflows/render-docs.yml@pr
     with:
       source-path: './src'
       target-path: './docs/api.md'

README.md

@@ -27,9 +27,9 @@ It allows you to connect to the internet, send and receive SMS messages, and get
 1. Insert your Arduino 4G module to the [Arduino Portenta Mid Carrier](https://store.arduino.cc/collections/portenta-family/products/portenta-mid-carrier)
 2. Insert a valid SIM card either in the **PCIE_SIM** connector on the Portenta Mid Carrier
 3. Connect the 5 **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)
+![](./docs/header.jpg)
 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)
+![](./docs/buck.jpg)
 5. Connect external power to the Mid Carrier, via the **VIN** (5V) because modems 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 "arduino_secrets.h" file for each sketch
 ```cpp

docs/api.md

@@ -22,7 +22,7 @@ This class provides methods to interact with the Arduino Pro Modem, such as conn
 | [`connect`](#class_arduino_cellular_1a7fb3c3e841b39c4faacef32cec6277b4) | Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided. |
 | [`isConnectedToOperator`](#class_arduino_cellular_1af7453ef90702e9042e2b4b18fa89db03) | Checks if the modem is registered on the network. |
 | [`isConnectedToInternet`](#class_arduino_cellular_1a6f8251e06de1810897b8bd8f8fb1b1a2) | Checks if the GPRS network is connected. |
-| [`enableGPS`](#class_arduino_cellular_1abe77a53e0eba6e8d62ba5db3bb6f5e92) | Enables or disables the GPS module. |
+| [`enableGPS`](#class_arduino_cellular_1abe77a53e0eba6e8d62ba5db3bb6f5e92) | Enables or disables the GPS functionality. |
 | [`getGPSLocation`](#class_arduino_cellular_1aee57a2eec5be06172b2fb7cd574d9106) | Gets the GPS location. (Blocking call) |
 | [`getCellularTime`](#class_arduino_cellular_1a6b3ce5485badff582584d539e790aff4) | Gets the current time from the network. |
 | [`getGPSTime`](#class_arduino_cellular_1a4aeb898c958e6eb001d606f0c7da8799) | Gets the current time from the GPS module. |
@@ -126,13 +126,13 @@ True if the GPRS network is connected, false otherwise.
 bool enableGPS(bool assisted)
 ```
 
-Enables or disables the GPS module.
+Enables or disables the GPS functionality.
 
 #### Parameters
 * `assisted` True to enable assisted GPS, false to disable it. Assist GPS uses the network to get the GPS location faster, so cellular needs to be enabled. 
 
 #### Returns
-True if the GPS module is enabled, false otherwise.
+True if GPS was enabled successfully, false otherwise.
 <hr />
 
 ### `getGPSLocation` <a id="class_arduino_cellular_1aee57a2eec5be06172b2fb7cd574d9106" class="anchor"></a>

docs/readme.md

@@ -1,30 +1,30 @@
-# Arduino Cellular Library
+# 📡 Arduino Cellular Library
 
-
-## Initialising 
+## ⤵️ Initialising 
 This guide outlines the steps to establish cellular network connectivity using an Arduino equipped with a cellular modem. The process involves initializing the modem, setting necessary configurations, and establishing a connection to the network.
 
 First, you need to include the ArduinoCellular library in your sketch. This library facilitates communication between your Arduino board and the cellular module.
 
-```c
+```cpp
 #include <ArduinoCellular.h>
 ```
 
 Create an instance of the ArduinoCellular class. This instance will be used to interact with the cellular module.
 
-```c
+```cpp
 ArduinoCellular cellular = ArduinoCellular();
 ```
 
 To begin, initialize the modem with basic configurations such as setting the modem to text mode, enabling intrrerupts etc.  This is done by calling the begin() method on your cellular instance. 
-```c
+```cpp
 cellular.begin();
 ```
 
-To connect to your mobile network and start a cellular data session, use the connect() method. This requires the APN (Access Point Name), login credentials (if any), and your SIM card's PIN number (if it's locked).
+To connect to your mobile network and start a cellular data session, use the connect() method. This requires the APN (Access Point Name) and login credentials (if any). You can unlock your SIM card's using its PIN number (if it's locked).
 
-```c
-cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD, SECRET_PINNUMBER);
+```cpp
+cellular.unlockSIM(SECRET_PINNUMBER)
+cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD);
 
 ```
 
@@ -33,7 +33,7 @@ Note: It's a best practice to store sensitive information like the GPRS APN, log
 **arduino_secrets.h**
 Create or edit the arduino_secrets.h file in your project directory and define the necessary secrets as follows:
 
-```c
+```cpp
 #define SECRET_GPRS_APN        "your_apn_here"
 #define SECRET_GPRS_LOGIN      "your_login_here"
 #define SECRET_GPRS_PASSWORD   "your_password_here"
@@ -43,7 +43,7 @@ Create or edit the arduino_secrets.h file in your project directory and define t
 Replace the placeholder values with the actual APN, login, password, and PIN number provided by your mobile network operator or SIM card provider.
 
 
-## Network  
+## 🌐 Network  
 The Arduino environment provides a set of classes designed to abstract the complexities of handling network communications. Among these, the Client class plays a crucial role as it defines a standard interface for network communication across various Arduino-compatible networking libraries. 
 
 The Arduino networking stack is designed to simplify the process of implementing network communication for IoT (Internet of Things) projects. This stack encompasses both hardware (e.g., Ethernet shields, WiFi modules) and software components (libraries that interface with the hardware). The stack is built in a way that allows sketches (Arduino programs) to communicate over the network using common protocols like TCP and UDP without needing to delve into the low-level mechanics of these protocols.
@@ -63,13 +63,13 @@ This layered approach is not only modular but also highly flexible, allowing dev
 
 ### Network Client (OSI Layer 3)
 Represents a basic client for network communication, suitable for protocols like TCP/IP.
-```c
+```cpp
 TinyGSMClient client = cellular.getNetworkClient();
 ```
 
 ### Secure Network Client 
 Adds a layer of security by implementing SSL/TLS encryption over the basic client.
-```c
+```cpp
 BearSSLClient secureClient = cellular.getSecureNetworkClient();
 ```
 
@@ -78,28 +78,28 @@ For convenience we added getters for http and https clients.
 ### HTTP and HTTPS Clients:
 These are high-level clients designed for web communication. They abstract the complexities of HTTP/HTTPS protocols, making it easy to send web requests and process responses.
 
-```c
+```cpp
 HttpClient http = cellular.getHTTPClient(server, port);
 HttpClient http = cellular.getHTTPSClient(server, port);
 ```
 
 
 
-## SMS 
+## 📨 SMS 
 The SMS functionality allows devices to exchange information with users or other systems through simple text messages, enabling a wide range of applications from remote monitoring to control systems or a fallback communication method when the others are not available. 
 
 ### Reading SMS Messages
 **getReadSMS():** This method returns a vector containing SMS messages that have already been read. It's particularly useful for applications that need to process or display messages that have been acknowledged.
 
-**getUnreadSMS(): **This method fetches a vector of unread SMS messages, allowing the application to process or notify users about new messages.
+**getUnreadSMS():** This method fetches a vector of unread SMS messages, allowing the application to process or notify users about new messages.
 
 Each SMS message is represented as an instance of the `SMS` class, which contains the sender's number, the message text, and a timestamp marking when the message was received.
 
 
 ### The SMS Class
 The SMS class serves as a container for information related to a single SMS message. It includes the following attributes:
 
-* `number`: The phone number from which the SMS was sent.
+* `sender`: The phone number from which the SMS was sent.
 * `message`: The body of the SMS message.
 * `timestamp`: A timestamp indicating when the message was received by the module.
 
@@ -115,7 +115,7 @@ The method sendSMS() is designed for this purpose, taking two parameters:
 
 This functionality allows Arduino devices to communicate outwardly to users or other systems, sending alerts, data, or control commands via SMS.
 
-## Time and Location
+## ⌚️📍 Time and Location
 These features enable precise tracking of device locations and ensure synchronized operations across different systems. This guide focuses on utilizing GPS and cellular network capabilities for location tracking and time synchronization. It's important to note that GPS functionality is exclusively available in the Global Version of the modem, highlighting the need for appropriate hardware selection based on the project requirements.
 
 ### GPS Location
@@ -125,11 +125,6 @@ GPS Location is ideal for applications requiring high-precision location data, s
 
 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.
-
-Cellular location is suitable for scenarios where GPS signals are weak or unavailable, offering a broader coverage area at the expense of location accuracy. This method leverages the cellular network's infrastructure to approximate the device's location.
-
 ### Time Synchronization
 Time synchronization is crucial for maintaining accurate timing across IoT devices, especially for data logging, scheduled tasks, and time-stamped communications.
 

src/ArduinoCellular.cpp

@@ -10,7 +10,6 @@ unsigned long ArduinoCellular::getTime() {
 }
 
 ArduinoCellular::ArduinoCellular() {
-
 }
 
 void ArduinoCellular::begin() {

src/ArduinoCellular.h

@@ -124,9 +124,9 @@ class ArduinoCellular {
         bool isConnectedToInternet();
 
         /**
-         * @brief Enables or disables the GPS module.
+         * @brief Enables or disables the GPS functionality.
          * @param assisted True to enable assisted GPS, false to disable it. Assist GPS uses the network to get the GPS location faster, so cellular needs to be enabled. 
-         * @return True if the GPS module is enabled, false otherwise.
+         * @return True if GPS was enabled successfully, false otherwise.
          */
         bool enableGPS(bool assisted = false);