Skip to content

api.md

Latest commit

 

History

History
857 lines (593 loc) · 26.8 KB

api.md

File metadata and controls

857 lines (593 loc) · 26.8 KB

Summary

Members Descriptions
class ArduinoCellular This class provides methods to interact with the Arduino Pro Modem, such as connecting to the network, sending SMS messages, getting GPS location, and more.
class ModemInterface Represents the interface to the 4G modem module which extends the TinyGsmBG96 class.
class SMS Represents an SMS message.
class Time Represents a point in time with year, month, day, hour, minute, second, and offset.
struct Geolocation Represents a geographic location with latitude and longitude coordinates.

class ArduinoCellular

This class provides methods to interact with the Arduino Pro Modem, such as connecting to the network, sending SMS messages, getting GPS location, and more.

Summary

Members Descriptions
ArduinoCellular Creates an instance of the ArduinoCellular class.
begin Initializes the modem. This function must be called before using any other functions in the library.
unlockSIM Unlocks the SIM card using the specified PIN.
connect Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided.
isConnectedToOperator Checks if the modem is registered on the network.
isConnectedToInternet Checks if the GPRS network is connected.
enableGPS Enables or disables the GPS functionality.
getGPSLocation Gets the GPS location. (Blocking call)
getCellularTime Gets the current time from the network.
getGPSTime Gets the current time from the GPS module.
sendSMS Sends an SMS message to the specified number.
getReadSMS Gets the list of read SMS messages.
getUnreadSMS Gets the list of unread SMS messages.
deleteSMS Deletes an SMS message at the specified index.
sendATCommand Sends an AT command to the modem and waits for a response, then returns the response.
sendUSSDCommand Sends a USSD command to the network operator and waits for a response.
getNetworkClient Gets the Network client. (OSI Layer 3)
getSecureNetworkClient Gets the Transport Layer Security (TLS) client. (OSI Layer 4)
getHTTPClient Gets the HTTP client for the specified server and port.
getHTTPSClient Gets the HTTPS client for the specified server and port.
getIPAddress Gets the local IP address.
getSignalQuality Gets the signal quality.
setDebugStream Sets the debug stream for ArduinoCellular.

Members

ArduinoCellular 

ArduinoCellular()

Creates an instance of the ArduinoCellular class.

begin 

void begin()

Initializes the modem. This function must be called before using any other functions in the library.

unlockSIM 

bool unlockSIM(String pin)

Unlocks the SIM card using the specified PIN.

Parameters

  • pin The SIM card PIN.

Returns

True if the SIM card is unlocked, false otherwise.

connect 

bool connect(String apn, String username, String password)

Registers with the cellular network and connects to the Internet if the APN, GPRS username, and GPRS password are provided.

Parameters

  • apn The Access Point Name.

  • username The APN username.

  • password The APN password.

Returns

True if the connection is successful, false otherwise.

isConnectedToOperator 

bool isConnectedToOperator()

Checks if the modem is registered on the network.

Returns

True if the network is connected, false otherwise.

isConnectedToInternet 

bool isConnectedToInternet()

Checks if the GPRS network is connected.

Returns

True if the GPRS network is connected, false otherwise.

enableGPS 

bool enableGPS(bool assisted)

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 GPS was enabled successfully, false otherwise.

getGPSLocation 

Geolocation getGPSLocation(unsigned long timeout)

Gets the GPS location. (Blocking call)

Parameters

  • timeout The timeout (In milliseconds) to wait for the GPS location.

Returns

The GPS location. If the location is not retrieved, the latitude and longitude will be 0.0.

getCellularTime 

Time getCellularTime()

Gets the current time from the network.

Returns

The current time.

getGPSTime 

Time getGPSTime()

Gets the current time from the GPS module.

Returns

The current time.

sendSMS 

void sendSMS(String number, String message)

Sends an SMS message to the specified number.

Parameters

  • number The phone number to send the SMS to.

  • message The message to send.

getReadSMS 

std::vector< SMS > getReadSMS()

Gets the list of read SMS messages.

Returns

A vector of SMS messages.

getUnreadSMS 

std::vector< SMS > getUnreadSMS()

Gets the list of unread SMS messages.

Returns

A vector of SMS messages.

deleteSMS 

bool deleteSMS(uint16_t index)

Deletes an SMS message at the specified index.

Parameters

  • index The index of the SMS message to delete.

Returns

True if the SMS message was successfully deleted, false otherwise.

sendATCommand 

String sendATCommand(const char * command, unsigned long timeout)

Sends an AT command to the modem and waits for a response, then returns the response.

Parameters

  • command The AT command to send.

  • timeout The timeout (In milliseconds) to wait for the response. Default is 1000ms.

Returns

The response from the modem.

sendUSSDCommand 

String sendUSSDCommand(const char * command)

Sends a USSD command to the network operator and waits for a response.

Parameters

  • command The USSD command to send.

Returns

The response from the network operator. (Note: The response may be an SMS message or a USSD response)

getNetworkClient 

TinyGsmClient getNetworkClient()

Gets the Network client. (OSI Layer 3)

Returns

The GSM client.

getSecureNetworkClient 

BearSSLClient getSecureNetworkClient()

Gets the Transport Layer Security (TLS) client. (OSI Layer 4)

Returns

The GSM client.

getHTTPClient 

HttpClient getHTTPClient(const char * server, const int port)

Gets the HTTP client for the specified server and port.

Parameters

  • server The server address.

  • port The server port.

Returns

The HTTP client.

getHTTPSClient 

HttpClient getHTTPSClient(const char * server, const int port)

Gets the HTTPS client for the specified server and port.

Parameters

  • server The server address.

  • port The server port.

Returns

The HTTPS client.

getIPAddress 

IPAddress getIPAddress()

Gets the local IP address.

Returns

The local IP address.

getSignalQuality 

int getSignalQuality()

Gets the signal quality.

Returns

The signal quality.

setDebugStream 

void setDebugStream(Stream & stream)

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.

Parameters

  • stream A pointer to the Stream object that will be used as the debug stream.

class ModemInterface 

class ModemInterface
  : public TinyGsmBG96

Represents the interface to the 4G modem module which extends the TinyGsmBG96 class.

Summary

Members Descriptions
stream The stream object for communication with the modem.
powerPin The pin number for controlling the power of the modem.
ModemInterface Constructor for the ModemInterface class.
init Initializes the modem interface. (Overrides the init method in TinyGsmBG96)

Members

stream 

Stream * stream

The stream object for communication with the modem.

powerPin 

int powerPin

The pin number for controlling the power of the modem.

ModemInterface 

inline explicit ModemInterface(Stream & stream, int powerPin)

Constructor for the ModemInterface class.

Parameters

  • stream The stream object for communication with the modem.

  • powerPin The pin number for controlling the power of the modem.

init 

inline bool init(const char * pin)

Initializes the modem interface. (Overrides the init method in TinyGsmBG96)

Parameters

  • pin The PIN code for the SIM card (optional).

Returns

True if initialization is successful, false otherwise.

class SMS

Represents an SMS message.

Summary

Members Descriptions
index The index of the SMS message.
sender The phone number associated with the SMS.
message The content of the SMS message.
timestamp The timestamp when the SMS was received.
SMS Default constructor for SMS. Initializes the number, message, and timestamp to empty values.
SMS Constructor for SMS.

Members

index 

int16_t index

The index of the SMS message.

sender 

String sender

The phone number associated with the SMS.

message 

String message

The content of the SMS message.

timestamp 

Time timestamp

The timestamp when the SMS was received.

SMS 

inline SMS()

Default constructor for SMS. Initializes the number, message, and timestamp to empty values.

SMS 

inline SMS(int16_t index, String sender, String message, Time timestamp)

Constructor for SMS.

Parameters

  • index The index of the SMS message.

  • sender The phone number associated with the sender of the SMS.

  • message The content of the SMS message.

  • timestamp The timestamp when the SMS was received.

class Time

Represents a point in time with year, month, day, hour, minute, second, and offset.

The Time class provides methods to manipulate and retrieve information about a specific point in time. It supports conversion to and from ISO8601 format and UNIX timestamp.

Summary

Members Descriptions
Time Constructor for Time class. Initializes the year, month, day, hour, minute, second, and offset to zero.
Time Default constructor for Time class. Initializes the year, month, day, hour, minute, second, and offset to zero.
fromISO8601 Parses an ISO8601 formatted string and sets the time components accordingly.
fromUNIXTimestamp Parses a UNIX timestamp and sets the time components accordingly.
fromComponents Initialises the time components with the given values.
getISO8601 Returns the time in ISO8601 format.
getUNIXTimestampString Returns the time in UNIX timestamp format.
getUNIXTimestamp Returns the time in UNIX timestamp format.
parseISO8601 Returns the year component of the time.\
parseUNIXTimestamp Parses a UNIX timestamp and sets the time components accordingly.
setYear Sets the year component of the time.
setMonth Sets the month component of the time.
setDay Sets the day component of the time.
setHour Sets the hour component of the time.
setMinute Sets the minute component of the time.
setSecond Sets the second component of the time.
setOffset Sets the timezone offset of the time.
getYear Returns the year component of the time.
getMonth Returns the month component of the time.
getDay Returns the day component of the time.
getHour Returns the hour component of the time.
getMinute Returns the minute component of the time.
getSecond Returns the second component of the time.
getOffset Returns the timezone offset of the time.

Members

Time 

inline Time(int year, int month, int day, int hour, int minute, int second, int offset)

Constructor for Time class. Initializes the year, month, day, hour, minute, second, and offset to zero.

Parameters

  • year The year component of the time.

  • month The month component of the time.

  • day The day component of the time.

  • hour The hour component of the time.

  • minute The minute component of the time.

  • second The second component of the time.

  • offset The timezone offset in hours (default is 0).

Time 

inline Time()

Default constructor for Time class. Initializes the year, month, day, hour, minute, second, and offset to zero.

fromISO8601 

inline void fromISO8601(String ISO8601)

Parses an ISO8601 formatted string and sets the time components accordingly.

Parameters

  • ISO8601 The ISO8601 formatted string to parse.

fromUNIXTimestamp 

inline void fromUNIXTimestamp(String UNIXTimestamp)

Parses a UNIX timestamp and sets the time components accordingly.

Parameters

  • UNIXTimestamp The UNIX timestamp to parse.

fromComponents 

inline void fromComponents(int year, int month, int day, int hour, int minute, int second, int offset)

Initialises the time components with the given values.

Parameters

  • year The year component of the time.

  • month The month component of the time.

  • day The day component of the time.

  • hour The hour component of the time.

  • minute The minute component of the time.

  • second The second component of the time.

  • offset The timezone offset in hours (default is 0).

getISO8601 

inline String getISO8601()

Returns the time in ISO8601 format.

Returns

The time in ISO8601 format.

getUNIXTimestampString 

inline String getUNIXTimestampString()

Returns the time in UNIX timestamp format.

Returns

The time in UNIX timestamp format.

getUNIXTimestamp 

inline unsigned long getUNIXTimestamp()

Returns the time in UNIX timestamp format.

Returns

The time in UNIX timestamp format.

parseISO8601 

inline void parseISO8601(String iso8601)

Returns the year component of the time.\

Parameters

  • iso8601 The ISO8601 formatted string to parse.

parseUNIXTimestamp 

inline void parseUNIXTimestamp(long unixTimestamp)

Parses a UNIX timestamp and sets the time components accordingly.

Parameters

  • unixTimestamp The UNIX timestamp to parse.

setYear 

inline void setYear(int year)

Sets the year component of the time.

Parameters

  • year The year component of the time.

setMonth 

inline void setMonth(int month)

Sets the month component of the time.

Parameters

  • month The month component of the time.

setDay 

inline void setDay(int day)

Sets the day component of the time.

Parameters

  • day The day component of the time.

setHour 

inline void setHour(int hour)

Sets the hour component of the time.

Parameters

  • hour The hour component of the time.

setMinute 

inline void setMinute(int minute)

Sets the minute component of the time.

Parameters

  • minute The minute component of the time.

setSecond 

inline void setSecond(int second)

Sets the second component of the time.

Parameters

  • second The second component of the time.

setOffset 

inline void setOffset(int offset)

Sets the timezone offset of the time.

Parameters

  • offset The timezone offset of the time.

getYear 

inline int getYear()

Returns the year component of the time.

Returns

The year component of the time.

getMonth 

inline int getMonth()

Returns the month component of the time.

Returns

The month component of the time.

getDay 

inline int getDay()

Returns the day component of the time.

Returns

The day component of the time.

getHour 

inline int getHour()

Returns the hour component of the time.

Returns

The hour component of the time.

getMinute 

inline int getMinute()

Returns the minute component of the time.

Returns

The minute component of the time.

getSecond 

inline int getSecond()

Returns the second component of the time.

Returns

The second component of the time.

getOffset 

inline int getOffset()

Returns the timezone offset of the time.

Returns

The timezone offset of the time.

struct Geolocation

Represents a geographic location with latitude and longitude coordinates.

Summary

Members Descriptions
latitude The latitude coordinate of the location.
longitude The longitude coordinate of the location.

Members

latitude 

float latitude

The latitude coordinate of the location.

longitude 

float longitude

The longitude coordinate of the location.