RETIRED - MG2639 Cellular Shield Hookup Guide

Contributors: jimblom

Example 1: Text Messages

The library includes a fun example sketch the demonstrates how to send and receive text messages. If your cellular plan has SMS-ability, give the MG2639_SMS_Responder example a try!

With the SFE_MG2639_CellularShield library installed, open the sketch by going to File > Examples > SparkFun MG2639 CellShield > MG2639_SMS_Responder.

You shouldn't have to change anything here, simply upload the sketch to your Arduino/shield combo.

Running the Example

The purpose of this example is to demonstrate how to receive text messages, act upon them, and send an SMS of our own. If the Arduino receives an expected text message string, it'll respond with a sensor reading. For example, if you send a text message saying "Read A0" (like that, case-sensitive), the Arduino will send a text message back containing the current analog voltage on A0. "Read D13" will return the digital value of D13 -- 0 or 1.

As with the previous example, to start the sketch, open your serial monitor, and send any character. The Arduino will poll the shield for its phone number, then ask you to send a text message.

Any text messages received will be printed out to the Serial Monitor along with the sending phone number and date.

If the text of the message matches one of the strings we're looking for, the Arduino will send an SMS back to the sender with the desired information.

Using the Library: SMS

To use the SMS functionality of the library, there is a second object defined as sms. There are a variety of functions available to the sms class, here's a quick overview:

Setting SMS Mode

sms.setMode(sms_mode) sets the SMS mode of your cell shield. You can either set the SMS mode to SMS_PDU_MODE (pure data mode) or SMS_TEXT_MODE (text strings). More often than not you'll want to use SMS_TEXT_MODE to read and send SMS. This must be set explicitly before using the sms functions!

Checking for available message

An sms.available(sms_status) function is defined for you to check if any read and/or unread messages have been received. The value returned by this function may not be what you expect, though -- it returns the index of the first requested message. Every message stored in the module is assigned an index number. The index is important because it identifies which message you want to read later on.

sms.available() expects one parameter, it can be any of:

• sms.available(REC_UNREAD) -- Returns the index of the first unread message.
• sms.available(REC_READ) -- Returns the index of the first read message.
• sms.available(REC_ALL) -- Returns the index of the first read or unread message.

If sms.available() doesn't find any of the requested message type, it will return 0.

Reading an SMS

After calling sms.available() and finding a message index to read, use sms.read(index) to read it.

Aside from an error code (1 for success, negative number for an error), sms.read() doesn't return the message. Instead use sms.getMessage(), sms.getSender(), and sms.getDate() to read the message, sending phone, and timestamp the message was sent. These values are only updated after an sms.read().

Here's an example based on the sketch:

language:c
// Get first available unread message:
int messageIndex = sms.available(REC_UNREAD);
// If an index was returned, proceed to read that message:
if (messageIndex > 0)
{
    // Call sms.read(index) to read the message:
    sms.read(messageIndex);
    Serial.print(F("Reading message ID: "));
    Serial.println(messageIndex);
    // Print the sending phone number:
    Serial.print(F("SMS From: "));
    Serial.println(sms.getSender());
    // Print the receive timestamp:
    Serial.print(F("SMS Date: "));
    Serial.println(sms.getDate());
    // Print the contents of the message:
    Serial.print(F("SMS Message: "));
    Serial.println(sms.getMessage());
}

The strings in these "get" functions will remain intact until you call sms.read() on a different index.

Sending an SMS

There are at least three steps to sending an SMS message: sms.start(phoneNumber), sms.print(message), and sms.send(). All three are required to send any message. sms.start(phoneNumber) indicates that you're beginning to write a message and sets the destination phone number. sms.print() can be used to send any data type -- string, integer, float, you name it in the body of the text. Just take care not to send anything besides sms.print() between your start() and send() calls.

Here's an example usage:

language:c
sms.start(sms.getSender());
sms.print("Analog 0 is: ");
sms.print(analogRead(A0));
int8_t status = sms.send();
if (status > 0)
    Serial.println("SMS successfully sent");

Deleting a Stored SMS

Due to limitations of the library and the Arduino's memory, we can only keep track of so many (256 by default) unread messages. If you can stomach letting them go, we recommend using the deleteMessage(index) function to remove a message from a SIM card's memory whenever possible.

To use the deleteMessage() function, simply supply the index of your message as a parameter. For example, to delete a message after you've read it:

language:c
// Get first available unread message:
int messageIndex = sms.available(REC_UNREAD);
// If an index was returned, proceed to read that message:
if (messageIndex > 0)
{
    // Call sms.read(index) to read the message:
    sms.read(messageIndex);
    Serial.println(sms.getMessage());
    // Delete the message after reading:
    sms.deleteMessage(i);
}

A second example in the library -- MG2639_SMS_Read -- allows you to go through the logs of your text messages and delete any or save them.