Ethernet class: EthernetClass

The Ethernet class initializes the Ethernet library and network settings. The actual class name is EthernetClass, and an object named Ethernet is instantiated in the library file Ethernet.cpp and exported in Ethernet.h. You can create your own instance of EthernetClass if you wish, or just use what the library provides.

begin()

Used to initialize the Ethernet library and establish networking parameters. The begin() method (or, function, if you prefer) is overloaded so that there are five ways to invoke it.

All of the arguments are arrays of uint8_t bytes. The DHCP-only form of this method (Ethernet.begin(mac)) returns 1 if a DHCP lease was successfully obtained, or 0 if it failed. All other forms return nothing. The IPAddress class type is described in the next section.

int Ethernet.begin(uint8_t *mac);
void Ethernet.begin(uint8_t *mac, IPAddress ip);
void Ethernet.begin(uint8_t *mac, IPAddress ip, IPAddress dns);
void Ethernet.begin(uint8_t *mac, IPAddress ip, IPAddress dns, 
                    IPAddress gateway);
void Ethernet.begin(uint8_t *mac, IPAddress ip, IPAddress dns, 
                    IPAddress gateway, IPAddress subnet);

localIP()

Obtains the IP address of the local host (i.e., the Ethernet shield). This is useful for determining the local IP address when DHCP is used. If the local Ethernet has been initialized successfully, Ethernet.localIP() will return an IPAddress object containing the assigned or specified IP address.

IPAddress Ethernet.localIP();

maintain()

This method does not appear in older versions of the library. When a device is assigned an IP address by a DHCP server it is called a lease, and a DHCP lease is given for a specific period of time (it depends on how the DHCP server has been configured). The Ethernet.maintain() method is used to renew a DHCP lease.

Ethernet.maintain() will return 0 if nothing occurred, 1 if the lease renewal failed, 2 if the lease was successfully renewed, 3 if the DHCP rebind failed, and 4 if the rebind succeeded.

int Ethernet.maintain();

IPAddress class

The IPAddress class defines a data object that is used to contain data for local and remote IP addressing. The class has four types of overloaded constructors. Each accepts a different form of IP address, as shown here:

IPAddress()
IPAddress(uint8_t first_octet,
          uint8_t second_octet,
          uint8_t third_octet,
          uint8_t fourth_octet)
IPAddress(uint32_t address)
IPAddress(const uint8_t *address)

An IPAddress object can hold a set of four IP address octets (the 192.168.1.100 format, for example, sans the periods), a 32-bit integer version of an IP address, or an array of unsigned bytes. The IPAddress class is used to create instances of address data types. For example:

IPAddress ip(192, 168, 0, 2);
IPAddress dnServer(192, 168, 0, 1);
IPAddress gateway(192, 168, 0, 1);
IPAddress subnet(255, 255, 255, 0);

ip, dnServer, gateway, and subnet are objects of type IPAddress. The Ethernet library knows to look for these names when initializing an Ethernet interface. Notice that they all use the multiple-octet form of initialization.

You can find the source files for IPAddress in the directory Arduino/hardware/arduino/avr/cores/arduino of the Arduino source.

Server class: EthernetServer

In Ethernet parlance, a server is a system (or host) that will accept a request for a connection from another system and establish a communications channel. The system requesting the connection is called a client. A server waits passively for clients to contact it; it doesn’t initiate a connection. For a real-world example, consider a web server. The web server waits for browser clients to connect and request web pages. It returns the requested data to the client and then waits for the next request. Each time a link is selected, a button clicked, or text entered into a text field of a browser display, a request is created and sent to the web server.

The Server class is the base class for the EthernetServer class in the Ethernet library. It is not called directly. The other classes utilize it. As with IPAddress, the source for the Server class is located in the directory Arduino/hardware/arduino/avr/cores/arduino of the Arduino source.

EthernetServer()

Establishes the port to use when listening for a connection request from a client. The port is typically specified when an object of type EthernetServer is instantiated. It returns nothing (void).

EthernetServer server(int port);

Example:

EthernetServer newserv = EthernetServer(port);

The value of the port argument may be any number between 0 and 65535, but values between 0 and 1024 are typically reserved for system services such as FTP, SSH, and possibly a web server. Use high port values (greater than 9000, for instance) to avoid conflicts.

begin()

Commands the server to begin listening for connections from clients on the port set when the server object was created.

void newserv.begin();

available()

Returns a connection to a client that is connected and ready to communicate.

EthernetClient newclient = newserv.available();

write()

Writes data to a client connected to a server. The data is written to all connected clients. Accepts either a single char (or byte) value, or a pointer to an array of char values, and returns the number of bytes written.

int newserv.write(char data);
int newserv.write(char *data, int size);

print()

Prints data to all clients connected to a server as a sequence of ASCII characters.

println()

Similar to print(), but adds a newline character at the end of the output. Accepts data as char, byte (uint8_t), int, long, or string types. Returns the number of bytes written. With no arguments, the function simply sends a newline character.

int newserv.println();
int newserv.println(char *data);
int newserv.println(char *data, int BASE);

Client class: EthernetClient

The Client class creates client objects, which can connect to a server to send and receive data. A transaction, or exchange, of data between a server and a client is typically initiated by the client. A server listens and waits for a client to connect, and once connected the client can request data from the server, send data to the server, or request that the server perform some action on the client’s behalf.

The Client class is the base class for the EthernetClient class in the Ethernet library. It is not called directly; the EthernetClient class inherits from it. As with Server, the source for the Client base class is located in the directory Arduino/hardware/arduino/avr/cores/arduino of the Arduino source.

EthernetClient()

Creates a client object that can connect to a server at a specific IP address using a specific port. The connect() method is used to define the server and the port to use. For example:

byte servaddr[] = {172, 120, 40, 10};
EthernetClient newclient;
newclient.connect(servaddr, 80);

connected()

Determines whether a client is connected or not. Returns true or false.

bool newclient.connected();

if (newclient.connected()) {
    // do something
}

connect()

Connects to a server at a specific IP address (an array of four bytes) and port. Instead of an IP address, a URL (web address) may be used.

int newclient.connect();
int newclient.connect(byte *servIP, int port);
int newclient.connect(char *URL, int port);

Returns an integer representing the connection status:

• SUCCESS = 1

• TIMED_OUT = -1

• INVALID_SERVER = -2

• TRUNCATED = -3

• INVALID_RESPONSE = -4

write()

Sends either a value or the contents of a buffer to the connected server. The data is sent as a series of bytes. The write() method returns the number of bytes written. This return value can be safely ignored.

int newclient.write(uint8_t value);
int newclient.write(uint8_t *buffer, int len);

print()

Prints data to the connected server as a sequence of ASCII characters. Accepts data as char, byte (uint8_t), int, long, or string types. Can also take a base specified. The valid base types are BIN (binary), DEC (base 10), OCT (base 8), and HEX (base 16). Returns the number of bytes written.

int newclient.print(data);
int newclient.print(data, base);

println()

Identical to the print() method except that a newline character is appended to the end of the output of ASCII characters. A println() with no parameters will send a single newline character to the connected server.

int newclient.println();
int newclient.println(data);
int newclient.println(data, base);

available()

Returns the number of characters available for reading from the connected server. Can be used to check for presence of incoming data.

int newclient.available();

read()

Reads the next available byte from the server. Use a loop to read multiple characters, or read and evaluate each character one at a time.

char newclient.read();

flush()

Discards any unread characters from the server that are in the receive buffer.

void newclient.flush();

stop()

Disconnects from the currently connected server. Once disconnected, the client may connect to another server (or to the same server again, of course).

void newclient.stop();

EthernetUDP class

Unlike TCP/IP, which is a stream protocol (i.e., it has no definite start and stop boundaries), UDP is a datagram protocol. Each item of data is a single packet, called a datagram, and the data must fit within the boundaries of the datagram packet. UDP does not have error detection, nor does it guarantee delivery of the data, but for short packets of noncritical data, or where the upper-level software can handle things like error detection and retries, it offers a fast and relatively simple way to move data around between hosts.

begin()

Initializes the UDP class to start listening for incoming data on a specific port.

byte UDP.begin(int port);

read()

Reads incoming data from the specified buffer. If no parameters are given, it will return one character from the current buffer. If the buffer and size are specified, it will return up to maxsize bytes from the buffer.

char UDP.read();
char *UDP.read(char *pkt_buffer, int maxsize)

Note that this function is intended to be used immediately after a call to UDP.parsePacket().

write()

Sends data to a remote connection. The write() function must be placed between beginPacket() and endPacket() calls. beginPacket() initializes the data packet, and the endPacket() call actually sends the data to the remote host.

byte UDP.write(char *message);
byte UDP.write(char *buffer, int size)

beginPacket()

Opens a UDP connection to a remote host at a specific IP address and port. Returns 1 (true) if the connection succeeded or 0 on failure.

int UDP.beginPacket(byte *ip, int port);

endPacket()

Sends a UDP packet created by the write() function to the remote host specified by the beginPacket() function.

int UDP.endPacket();

parsePacket()

Checks an open UDP connection for the presence of a datagram packet and returns the size of the waiting data. parsePacket() must be called before the read() or available() function is used to retrieve the data (if any).

int UDP.parsePacket();

available()

Returns the number of bytes of received data currently in the receive buffer. Note that this should only be called after a call to parsePacket().

int UDP.available();

stop()

Disconnects from the remote UDP host and releases any resources used during the UDP session.

void USP.stop();

remoteIP()

Returns the IP address of the remote UDP connection as an array of 4 bytes. This function should only be called after a call to parsePacket().

byte *UDP.remoteIP();

remotePort()

Returns the UDP port of the remote UDP connection as an integer. This function should only be called after a call to parsePacket().

int UDP.remotePort();

Base methods

We’ll look at each of these categories in turn in the following sections.

begin()

The basic form of begin() initializes the Firmata library and sets the serial data rate to a default of 57,600 baud. The second form accepts an argument of type long, which contains the desired baud rate for the communication between Firmata and a host system. The third form starts the library using a stream other than Serial. It is intended to work with any data stream that implements the Stream interface (Ethernet, WiFi, etc.). Refer to the issue discussions on Firmata’s GitHub page for more information on the current status of this method.

void Firmata.begin();
void Firmata.begin(long);
void Firmata.begin(Stream &s);

printVersion()

Sends the library protocol version to the host computer.

void Firmata.printVersion();

blinkVersion()

Blinks the protocol version on pin 13 (the on-board LED on an Arduino).

void Firmata.blinkVersion();

printFirmwareVersion()

Sends the firmware name and version to the host computer.

void Firmata.printFirmwareVersion();

setFirmwareVersion()

Sets the firmware name and version using the sketch’s filename, minus the extension.

void Firmata.setFirmwareVersion(const char *name, 
                                     byte vers_major, byte vers_minor);

Sending messages

sendAnalog()

Sends an analog data message.

void Firmata.sendAnalog(byte pin, int value);

sendDigitalPort()

Sends the state of digital ports as individual bytes.

void Firmata.sendDigitalPort(byte pin, int portData);

sendString()

Sends a string to the host computer.

void Firmata.sendString(const char* string);

sendString()

Sends a string to the host computer using a custom command type.

void Firmata.sendString(byte command, const char* string);

sendSysex()

Sends a command containing an arbitrary array of bytes.

void Firmata.sendSysex(byte command, byte bytec, byte* bytev);

Receiving messages

available()

Checks to see if there are any incoming messages in the input buffer.

int Firmata.available();

processInput()

Retreives and processes incoming messages from the input buffer and sends the data to registered callback functions.

void Firmata.processInput();

Callback functions

In order to attach a function to a specific message type, the function must match a callback function. There are three basic types of callback functions in Firmata. We’ll look at each of these in turn in the following sections: generic, string, and sysex, and a fourth type to handle a system reset. The callback functions are:

attach()

Attaches a function to a specific incoming message type.

void attach(byte command, callbackFunction newFunction);
void attach(byte command, systemResetCallbackFunction newFunction);
void attach(byte command, stringCallbackFunction newFunction);
void attach(byte command, sysexCallbackFunction newFunction);

detach()

Detaches a function from a specific incoming message type.

void Firmata.detach(byte command);

Message types

A function may be attached to a specific message type. Firmata provides the following message types:

ANALOG_MESSAGE

The analog value for a single pin

DIGITAL_MESSAGE

Eight bits of digital pin data (one port)

REPORT_ANALOG

Enables/disables the reporting of an analog pin

REPORT_DIGITAL

Enables/disables the reporting of a digital port

SET_PIN_MODE

Changes the pin mode between INPUT/OUTPUT/PWM/etc.

FIRMATA_STRING

For C-style strings; uses stringCallbackFunction for the function type

SYSEX_START

For generic, arbitrary-length messages (via MIDI SysEx protocol); uses sysexCallbackFunction for the function type

SYSTEM_RESET

Resets firmware to its default state; uses systemResetCallbackFunction for the function type

Ethernet library compatibility

The GSM library is largely compatible with the current Arduino Ethernet library, such that porting a program that uses the Arduino Ethernet or WiFi libraries to the GSM for use with the GSM shield should be relatively straightforward. Some minor library-specific modifications will be necessary, such as including the GSM- and GPRS-specific libraries and obtaining network settings from your cellular network provider.

Library structure

The GSM library is rather complex, and is comprised of 10 primary classes. The following list shows the functions in each of the GSM classes:

• GSM class

  • begin()

  • shutdown()

• GSMVoiceCall class

  • getVoiceCallStatus()

  • ready()

  • voiceCall()

  • answerCall()

  • hangCall()

  • retrieveCallingNumber()

• GSM_SMS class

  • beginSMS()

  • ready()

  • endSMS()

  • available()

  • remoteNumber()

  • read()

  • write()

  • print()

  • peek()

  • flush()

• GPRS class

  • attachGPRS()

• GSMClient class

  • ready()

  • connect()

  • beginWrite()

  • write()

  • endWrite()

  • connected()

  • read()

  • available()

  • peek()

  • flush()

  • stop()

• GSMServer class

  • ready()

  • beginWrite()

  • write()

  • endWrite()

  • read()

  • available()

  • stop()

• GSMModem class

  • begin()

  • getIMEI()

• GSMScanner class

  • begin()

  • getCurrentCarrier()

  • getSignalStrength()

  • readNetworks()

• GSMPIN class

  • begin()

  • isPIN()

  • checkPIN()

  • checkPUK()

  • changePIN()

  • switchPIN()

  • checkReg()

  • getPINUsed()

  • setPINUsed()

• GSMBand class

  • begin()

  • getBand()

  • setBand()

GSM class

This class prepares the functions that will communicate with the modem. It manages the connectivity of the shield and performs the necessary system registration with the GSM infrastructure. All Arduino GSM/GPRS programs need to include an object of this class to handle the low-level communications functions.

This is the base class for all GSM-based functions. It should be instantiated as shown:

GSM gsmbase;

begin()

Starts the GSM/GPRS modem and attaches to a GSM network. The full prototype for the begin() method looks like this:

begin(char* pin=0, bool restart=true, bool synchronous=true);

The begin() method can be called four different ways because each argument has been assigned a default value. The first form takes no arguments, and it is assumed that the SIM has no configured pin.

gsmbase.begin();
gsmbase.begin(char *pin);
gsmbase.begin(char *pin, bool restart);
gsmbase.begin(char *pin, bool restart, bool sync);

shutdown()

Shuts down the modem (power-off).

gsmbase.shutdown();

GSMVoiceCall class

The GSMVoiceCall class enables voice communication through the modem, provided that a microphone, a speaker, and a small amount of circuitry are connected to the GSM shield.

This is the base class for all GSM functions used to receive and make voice calls and should be instantiated as follows:

GSMVoiceCall gsmvc;

getVoiceCallStatus()

Returns the status of a voice call as one of IDLE_CALL, CALLING, RECEIVINGCALL, or TALKING.

GSM3_voiceCall_st getVoiceCallStatus();

gsmvc.getVoiceCallStatus();

ready()

Returns the status of the last command: 1 if the last command was successful, 0 if the last command is still executing, and >1 if an error occurred.

int ready();

gsmvc.ready();

voiceCall()

Places a voice call in either asynchronous or synchronous mode. If asynchronous, voiceCall() returns while the number is ringing. In synchronous mode voiceCall() will not return until the call is either established or cancelled.

The first argument is a string containing the number to call. A country extension can be used or not. The buffer should not be released or used until voiceCall() is complete (the command is finished). The timeout argument is given in milliseconds, and is used only in synchronous mode. If set to 0, then voiceCall() will wait indefinitely for the other end to pick up.

int voiceCall(const char* to, unsigned long timeout=30000);

gsmvc.voiceCall(to);           // use default timeout
gsmvc.voiceCall(to, timeout);  // specify a timeout period

answerCall()

Accepts an incoming voice call. In asynchronous mode answerCall() returns 0 if the last command is still executing, 1 on success, and >1 if an error has occurred. In synchronous mode answerCall() returns 1 if the call is answered, and 0 if not.

gsmvc.answerCall();

hangCall()

Hangs up an established call or an incoming ring. In asynchronous mode hangCall() returns 0 if the last command is still executing, 1 on success, and >1 if an error has occurred. In synchronous mode hangCall() returns 1 if the call is answered, and 0 if not.

gsmvc.hangCall();

retrieveCallingNumber()

Retrieves the calling number and puts it into a buffer. The argument buffer is a pointer to a char buffer, and bufsize is the size of the buffer, in bytes. The buffer should be large enough to hold at least 10 characters.

In asynchronous mode retrieveCallingNumber() returns 0 if the last command is still executing, 1 on success, and >1 if an error has occurred. In synchronous mode retrieveCallingNumber() returns 1 if the number is correctly acquired and 0 if not.

int retrieveCallingNumber(char* buffer, int bufsize);

gsmvc.retrieveCallingNumber(buffer, bufsize);

GSM_SMS class

This class provides the capability to send and receive SMS (Short Message Service) messages.

beginSMS()

Defines the telephone number to receive an SMS message. The phone number is a char array. In asynchronous mode the function will return 0 if the last command is still active, 1 if it was successful, and a value >1 if an error occurred. In synchronous mode the function will return 1 if the previous command was successful and 0 if it failed.

int SMS.beginSMS(char *phone_number)

ready()

Returns the status of the last GSM SMS command. In asynchronous mode ready() will return 0 if the last command is still active, 1 if it was successful, and a value >1 if an error occurred. In synchronous mode the function will return 1 if the previous command was successful and 0 if it failed.

int SMS.ready()

endSMS()

Used to inform the modem that the message is complete and ready to send. In asynchronous mode the function returns 0 if it is still executing, 1 if successful, and >1 if an error has occurred. In synchronous mode it returns 1 if successful, and 0 otherwise.

int SMS.endSMS()

available()

If an SMS message is available to read, this function returns the number of characters in the message. If no message is available, it returns 0.

int SMS.available()

remoteNumber()

Extracts the remote phone number from an incoming SMS message and returns it in a char array. The size argument defines the maximum size of the array passed to remoteNumber(). In asynchronous mode the function returns 0 if still executing, 1 if successful, and >1 if an error has occurred. In synchronous mode the function returns 1 if successful, 0 otherwise.

int SMS.remoteNumber(char *remote_phone, int number_size)

read()

Reads a byte (a character) from an SMS message. Returns the byte as an integer, or -1 if no data is available.

int SMS.read()

write()

Writes a byte-sized character to an SMS message.

int write(int character)

print()

Writes a character array to an SMS message. Returns the number of bytes successfully written.

int SMS.print(char *message)

peek()

Returns the next available byte (a character) from an SMS message, without removing the character, or -1 if no data is available.

int SMS.peek()

flush()

Clears the modem of any sent messages after all outbound characters have been sent.

void SMS.flush()

GPRS class

GPRS is the base class for all GPRS functions. This includes Internet client and server functions. This class is also responsible for including the files that are involved with TCP communication.

attachGPRS()

Connects with a given access point name (APN) to initiate GPRS communications. Cellular providers have APNs the act as bridges between the cellular network and the Internet. Returns one of the following strings: ERROR, IDLE, CONNECTING, GSM_READY, GPRS_READY, TRANSPARENT_CONNECTED.

char *GPRS.attachGPRS(char *apn, char *user, char *password)

GSMClient class

This class creates clients that can connect to servers and send and receive data.

ready()

Returns the status of the last command. In asynchronous mode the function returns 0 if still executing, 1 if successful, and >1 if an error has occurred. In synchronous mode the function returns 1 if successful, and 0 otherwise.

int GSMClient.ready()

connect(char *IP, int port)

Connects to a specific port of a specified IP address. Returns true if the connection was successful, or false if not.

bool GSMClient.connect(char *hostip, int port)

beginWrite()

Starts a write operation to the connected server.

void GSMClient.beginWrite()

write()

Writes data to a connected server. Returns the number of bytes written.

int GSMClient.write(char data)
int GSMClient.write(char *data)
int GSMClient.write(char *data, int size)

endWrite()

Stops writing data to a connected server.

void GSMClient.endWrite()

connected()

Returns the connection status of a client. Note that a client is considered to be connected if the connection has been closed but there is still unread data in the buffer. Returns true if the client is connected, or false if not.

bool GSMClient.connected()

read()

Reads the next available byte of data from the server the client is connected with. Returns the next byte, or -1 if no data is available.

int GSMClient.read()

available()

Returns the number of bytes from the connected server that are waiting to be read.

int GSMClient.available()

peek()

Returns the next available byte of an incoming message without removing it from the incoming buffer. Successive calls to peek() will simply return the same byte.

int GSMClient.peek()

flush()

Discards any data currently waiting in the incoming buffer and resets the available data count to zero.

void GSMClient.flush()

stop()

Forces a disconnect from a server.

void GSMClient.stop()

GSMServer class

The GSMServer class creates servers that can send data to and receive data from connected clients. It implements network server functionality, similar to the Ethernet and WiFi libraries. Note that some network operators do not permit incoming network connections from outside their own network.

ready()

Returns the status of the last command. In asynchronous mode this function returns 0 if still executing, 1 if successful, and >1 if an error has occurred. In synchronous mode the function returns 1 if successful, and 0 otherwise.

int GSMServer.ready()

beginWrite()

Starts a write operation to all connected clients.

void GSMServer.beginWrite()

write()

Writes data to connected clients. Returns the number of bytes written.

int GSMServer.write(char data)
int GSMServer.write(char *data)
int GSMServer.write(char *data, int size)

endWrite()

Stops writing data to connected clients.

void GSMServer.endWrite()

read()

Reads the next available byte from a connected client. Returns the byte read, or -1 if no data is available.

int GSMServer.read()

available()

Listens for connection requests from clients. Returns the number of connected clients.

int GSMServer.available()

stop()

Stops the server from listening for client connection requests.

void GSMServer.stop()

GSMModem class

The GSMModem class provides diagnostic support functions for the internal GSM modem.

begin()

Checks the status of the modem and restarts it. This function must be called before a call to getIMEI(). Returns 1 if the modem is working correctly, or an error if it is not.

int GSMModen.begin()

getIMEI()

Queries the modem to retrieve its IMEI (International Mobile Equipment Identifier) number. The IMEI number is returned as a string. This function should only be called after a call to begin().

char *GSMModen.getIMEI()

GSMScanner class

The GSMScanner class provides functions to obtain diagnostic information about the network and carrier.

begin()

Resets the modem. Returns 1 if the modem is operating correctly, or an error code if it is not.

int GSMSScanner.begin()

getCurrentCarrier()

Returns the name of the current network server provider (the carrier) as a string.

char *GSMSScanner.getCurrentCarrier()

getSignalStrength()

Returns the relative signal strength of the network connection as a string with ASCII digits from 0 to 31 (31 indicates that the power is > 51 dBm), or 99 if no signal is detected.

char *GSMSScanner.getSignalStrength()

readNetworks()

Searches for available network carriers. Returns a string containing a list of the carriers detected.

char *GSMSScanner.readNetworks()

GSMPIN class

The GSMPIN class contains utility functions for communicating with the SIM card.

begin()

Resets the modem. Returns 1 if the modem is operating correctly, or an error code if it is not.

int GSMPIN.begin()

isPIN()

Examines the SIM card to determine if it is locked with a PIN or not. Returns 0 if the PIN lock is off, 1 if the lock is on, -1 if the PUK lock is on, and -2 if an error was encountered.

int GSMPIN.isPIN()

checkPIN()

Queries the SIM card with a PIN to determine whether it is valid or not. Returns 0 if the PIN is valid, and -1 if it is not.

int GSMPIN.checkPIN(char *PIN)

checkPUK()

Queries the SIM to determine if the PUK code is valid and establishes a new PIN code. Returns 0 if successful, and -1 if not.

int GSMPIN.checkPUK(char *PUK, char *PIN)

changePIN()

Changes the PIN code of a SIM card after verifying that the old PIN is valid.

void GSMPIN.changePIN(char *oldPIN, char *newPIN)

switchPIN()

Changes the PIN lock status.

void GSMPIN.switchPIN(char *PIN)

checkReg()

Checks to determine if the modem is registered in a GSM/GPRS network. Returns 0 if the modem is registered, 1 if the modem is roaming, and -1 if an error was encountered.

int GSMPIN.checkReg()

getPINUsed()

Checks to determine if the PIN lock is used. Returns true if locked, and false if not.

bool GSMPIN.getPINUsed()

setPINUsed()

Sets the PIN lock status. If the argument is true, then the PIN is locked; if false, it is unlocked.

void GSMPIN.setPINUsed(bool used)

GSMBand class

The GSMBand class provides information about the frequency band the modem connects to. There are also methods for setting the band.

begin()

Resets the modem. Returns 1 if the modem is operating correctly, or an error code if it is not.

int GSMBand.begin()

getBand()

Returns the frequency band the modem is currently using for a connection.

char *GSMBand.getBand()

setBand()

Sets the frequency band for the modem to use.

bool GSMBand.setBand(char *band)

SD class

The SD class provides functions for accessing the SD card and manipulating files and directories.

begin()

Initializes the SD library and the interface with the SD card. The optional argument csPin defines the pin to use as the select. The default is to use pin 10 (SD_CHIP_SELECT_PIN). This function must be called before any other of the SD functions are used. Returns true if successful, or false if not.

bool SD.begin(uint8_t csPin = SD_CHIP_SELECT_PIN);

exists()

Tests for the presence of a file or directory on the SD card. The string filepath may be a fully qualified path name (FQPN). Returns true if the file or directory exists, or false if not.

bool SD.exists(char *filepath);

mkdir()

Creates a directory on the SD card. It will also create any necessary intermediate directories. Returns true if the directory was created successfully, or false if not.

bool SD.mkdir(char *filepath);

open()

Opens a file on an SD card for reading or writing. If the mode argument is not provided, the default is to open the file for reading. Returns a File object that can be tested as a Boolean value. If the file could not be opened, then File will evaluate to false. The available modes are FILE_READ and FILE_WRITE.

File SD.open(const char *filename, uint8_t mode = FILE_READ);

remove()

Deletes (removes) a file from the SD card. filepath is an FQPN. Returns true if the removal succeeded, or false if not.

bool SD.remove(char *filepath);

rmdir()

Removes an empty directory from an SD card. Returns true if the directory was successfully deleted, or false if an error occurred (such as the directory not empty).

bool SD.rmdir(char *filepath);

File class

The File class provides functions for reading and writing individual files on an SD card. Objects of type File are created by the SD.open() function:

fname = SD.open("data.txt", FILE_WRITE);

There are a number of methods in a File object to manipulate the contents of a file:

available()

Returns the number of available bytes to read from a file.

int fname.available()

close()

Closes a file, ensuring that any remaining data is written to the file beforehand.

void fname.close()

flush()

Writes any remaining data in the file buffer to the file. Does not close the file.

void fname.flush()

peek()

Reads a byte from a file without advancing the internal data pointer. Successive calls to peek() will return the same byte.

int fname.peek()

position()

Returns the current position in the file that the next byte will be read from or written to.

uint32_t fname.position()

print()

Writes data to a file that has been opened for writing. Accepts data as char, byte (uint8_t), int, long, or string types. Can also take a base specified. The valid base types are BIN (binary), DEC (base 10), OCT (base 8), and HEX (base 16). Returns the number of bytes written.

int fname.print(data)
int fname.print(char *data, int BASE)

Note: string data is shown in this example.

println()

Writes data to a file that has been opened for writing followed by a carriage return and newline character pair. Accepts data as char, byte (uint8_t), int, long, or string types. Can also take a base specified. The valid base types are BIN (binary), DEC (base 10), OCT (base 8), and HEX (base 16). Returns the number of bytes written.

int fname.println()
int fname.println(data)
int fname.println(data, int BASE)

seek()

Moves the internal pointer to a new position in the file. The position must be between 0 and the size of the file, inclusive. Returns true if successful, or false if an error occurs (seeking beyond the end of the file, for example).

bool fname.seek(uint32_t pos)

size()

Returns the size of the file, in bytes.

uint32_t fname.size()

read()

Reads the next byte from the file, or returns a value of -1 if no data is available.

int fname.read(void *buf, uint16_t nbyte)

write()

Writes data to a file. Accepts either a single byte, or a data object that may be a byte, character, or string. The size argument defines the amount of data to write to the SD card. Returns the number of bytes written.

size_t fname.write(uint8_t)
size_t fname.write(const uint8_t *buf, size_t size)

isDirectory()

Returns true if the fname object refers to a directory, or false otherwise.

bool fname.isDirectory()

openNextFile()

Opens the next file folder in a directory and returns a new instance of a File object.

File openNextFile(uint8_t mode = O_RDONLY)

rewindDirectory()

Used with openNextFile(), this function returns to the first file or subdirectory in a directory.

void fname.rewindDirectory()

TFT class

The TFT class constructor is available in two forms. One is used when the standard Arduino SPI pins are used (the hardware SPI), and the second form allows you to specify which pins to use:

TFT(uint8_t cs, uint8_t dc, uint8_t rst)
TFT(uint8_t cs, uint8_t dc, uint8_t mosi, uint8_t sclk, uint8_t rst)

Where:

Example:

 #define cs  10
 #define dc  9
 #define rst 8
 TFT disp = TFT(cs, ds, rst);

The Esplora version of the TFT library uses predefined pins. All that is necessary is to instantiate the TFT object:

EsploraTFT disp = EsploraTFT;

begin()

Called to initialize the TFT library components. Must be called before any other functions are used. Typically called in the setup() function of a sketch.

void disp.begin()

background()

Overwrites the entire display screen with a solid color. May be used to clear the display. Note that the screen cannot actually display 256 unique levels per color, but instead uses 5 bits for the blue and red colors, and 6 bits for green.

void disp.background(uint8_t red, uint8_t green, uint8_t blue)

stroke()

Called before drawing on the screen, and sets the color of lines and borders. Like the background() function, stroke() uses 5 bits for the blue and red colors, and 6 bits for green.

void disp.stroke(uint8_t red, uint8_t green, uint8_t blue)

noStroke()

Removes all outline stroke color.

void disp.noStroke()

fill()

Sets the fill color of objects and text on the screen. Like the stroke() function, fill() uses 5 bits for the blue and red colors, and 6 bits for green.

void disp.fill(uint8_t red, uint8_t green, uint8_t blue)

noFill()

Disables color fills for objects and text.

void disp.noFill()

setTextSize()

Sets the size of the text written by a call to the text() function. The default text size is 1, or 10 pixels. Each increase in the text size increases the height of the text on the screen by 10 pixels.

void disp.setTextSize(uint8_t size)

text()

Writes text to the display at the specified coordinates. The text color is set by calling the fill() function before calling text().

void disp.text(const char * text, int16_t x, int16_t y),

point()

Draws a point at a specific location on the screen. The point color will be what was specified by a preceding fill() function call.

void disp.point(int16_t x, int16_t y)

line()

Draws a line between start and end coordinates using the color set by the stroke() function.

void disp.line(int16_t x1, int16_t y1, int16_t x2, int16_t y2)

rect()

Draws a rectangle starting at an upper-left point (x, y) with a specified width and height.

void disp.rect(int16_t x, int16_t y, int16_t width, int16_t height)

width()

Reports the width of the TFT screen in pixels.

int disp.width()

height()

Reports the height of the TFT screen in pixels.

int disp.height()

circle()

Draws a circle on the display with a center point of (x, y), and radius of r.

int disp.circle(int16_t x, int16_t y, int16_t r)

image()

Draws an image loaded from an SD card onto the screen at a specified position.

void image(PImage image, int xpos, int yPos)

loadImage()

Creates an instance of a PImage object using the image file name provided. The image file must be a 24-bit BMP type, and it must reside on the root directory of the SD card. Uses the PImage function loadImage().

PImage disp.loadImage(char *imgname)

PImage

The PImage class contains functions to encapsulate and draw a bitmap image on a TFT display.

PImage.height()

Once an image has been encapsulated in a PImage object it may be queried to obtain its height. This function returns the height as an int value.

PImage.width()

Returns the width of an encapsulated image object as an int value.

PImage.isValid()

Returns a Boolean true if the image object contains a valid bitmap file, or false if it does not.

Mouse

The mouse functions allow a Leonardo or Micro to control cursor movement on a host computer. The reported cursor position is always relative to the cursor’s previous location; it is not absolute.

Mouse.begin()
Mouse.click()
Mouse.end()
Mouse.move()
Mouse.press()
Mouse.release()
Mouse.isPressed()

Keyboard

The keyboard functions allow a Leonardo or Micro to send keystrokes to an attached host computer. While not every possible ASCII character, particularly the nonprinting ones, can be sent with the Keyboard library, the library does support the use of modifier keys.

Keyboard.begin()
Keyboard.end()
Keyboard.press()
Keyboard.print()
Keyboard.println()
Keyboard.release()
Keyboard.releaseAll()
Keyboard.write()

Modifier keys change the behavior of another key when pressed simultaneously. Table 7-1 lists the modifier keys supported by the Leonardo.