|
| 1 | +# Arduino Cellular Library |
| 2 | + |
| 3 | + |
| 4 | +## Initialising |
| 5 | +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. |
| 6 | + |
| 7 | +First, you need to include the ArduinoCellular library in your sketch. This library facilitates communication between your Arduino board and the cellular module. |
| 8 | + |
| 9 | +```c |
| 10 | +#include <ArduinoCellular.h> |
| 11 | +``` |
| 12 | + |
| 13 | +Create an instance of the ArduinoCellular class. This instance will be used to interact with the cellular module. |
| 14 | + |
| 15 | +```c |
| 16 | +ArduinoCellular cellular = ArduinoCellular(); |
| 17 | +``` |
| 18 | + |
| 19 | +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. |
| 20 | +```c |
| 21 | +cellular.begin(); |
| 22 | +``` |
| 23 | + |
| 24 | +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). |
| 25 | + |
| 26 | +```c |
| 27 | +cellular.connect(SECRET_GPRS_APN, SECRET_GPRS_LOGIN, SECRET_GPRS_PASSWORD, SECRET_PINNUMBER); |
| 28 | + |
| 29 | +``` |
| 30 | + |
| 31 | +Note: It's a best practice to store sensitive information like the GPRS APN, login credentials, and PIN number in a separate header file named arduino_secrets.h. This prevents hardcoding sensitive information in your main sketch file. |
| 32 | + |
| 33 | +**arduino_secrets.h** |
| 34 | +Create or edit the arduino_secrets.h file in your project directory and define the necessary secrets as follows: |
| 35 | + |
| 36 | +```c |
| 37 | +#define SECRET_GPRS_APN "your_apn_here" |
| 38 | +#define SECRET_GPRS_LOGIN "your_login_here" |
| 39 | +#define SECRET_GPRS_PASSWORD "your_password_here" |
| 40 | +#define SECRET_PINNUMBER "your_pin_here" |
| 41 | +``` |
| 42 | +
|
| 43 | +Replace the placeholder values with the actual APN, login, password, and PIN number provided by your mobile network operator or SIM card provider. |
| 44 | +
|
| 45 | +
|
| 46 | +## Network |
| 47 | +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. |
| 48 | +
|
| 49 | +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. |
| 50 | +
|
| 51 | +For different networking hardware, specific libraries provide concrete implementations of the Client class. For example: |
| 52 | +
|
| 53 | +* **Ethernet Library:** Contains the EthernetClient, tailored for wired network connections. |
| 54 | +* **WiFi Library:** Includes the WiFiClient, designed for wireless network interactions. |
| 55 | +* **TinyGSM Library:** Offers the TinyGSMClient for cellular network communications. |
| 56 | +These implementations handle the low-level details of communicating over their respective network mediums while presenting a unified interface to the user. |
| 57 | +
|
| 58 | +
|
| 59 | +A powerful feature of this design is the ability to layer and chain clients to add functionalities. For instance, you might start with a basic network client for TCP/IP communication. If you need secure communications, you can wrap this client within a SSL/TLS client that encrypts the data, such as BearSSLClient. On top of this, if your application communicates over HTTP or HTTPS, you can use an HTTP client that leverages the underlying secure client. |
| 60 | +
|
| 61 | +This layered approach is not only modular but also highly flexible, allowing developers to mix and match functionalities as needed. |
| 62 | +
|
| 63 | +
|
| 64 | +### Network Client (OSI Layer 3) |
| 65 | +Represents a basic client for network communication, suitable for protocols like TCP/IP. |
| 66 | +```c |
| 67 | +TinyGSMClient client = cellulat.getNetworkClient(); |
| 68 | +``` |
| 69 | + |
| 70 | +### Secure Network Client |
| 71 | +Adds a layer of security by implementing SSL/TLS encryption over the basic client. |
| 72 | +```c |
| 73 | +BearSSLClient secureClient = cellular.getSecureNetworkClient(); |
| 74 | +``` |
| 75 | + |
| 76 | +For convenience we added getters for http and https clients. |
| 77 | + |
| 78 | +### HTTP and HTTPS Clients: |
| 79 | +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. |
| 80 | + |
| 81 | +```c |
| 82 | +HttpClient http = cellular.getHTTPClient(server, port); |
| 83 | +HttpClient http = cellular.getHTTPSClient(server, port); |
| 84 | +``` |
| 85 | + |
| 86 | + |
| 87 | + |
| 88 | +## SMS |
| 89 | + |
| 90 | + |
| 91 | +## Time and Location |
0 commit comments