RETIRED - MG2639 Cellular Shield Hookup Guide

Contributors: jimblom

Example 2: GPRS & TCP

One of the most powerful aspects of the MG2639 is its ability to connect to a GPRS network and interact with the Internet. The module supports TCP/IP, DNS lookup, and most of the features you'd expect from a similar WiFi or Ethernet shield.

There are a couple examples demonstrating GPRS and TCP in the SFE_MG2639_CellularShield library. Open up the general example -- MG2639_GPRS -- by going to File > Examples > SFE_MG2639_CellularShield > MG2639_GPRS.

Running the Example

This example demonstrates how to turn the MG2639 into a simple browser client. It shows off most of the GPRS functions, including enabling GPRS, finding local and remote IP addresses, connecting to a server, and sending/receiving data.

A char array near the top of the sketch -- const char server[] = "example.com"; -- defines the remote URL your shield will try to connect to.

As with the other sketches, after uploading the sketch, run it by opening the serial monitor and sending any character. The MG2639 will open GPRS, find its IP, find the destination IP and send an HTTP GET request.

After sending a simple HTTP GET request to the server, the shield will print any response from that server back to the serial monitor.

Using the Library: GPRS

As with SMS, an entirely different class is defined for GPRS capabilities. These functions are preceded by a gprs. object identifier. (This allows us to re-use virtual functions like print and available.)

Opening or Closing GPRS

Before you can use any GPRS functionality, you have to "turn it on" by calling gprs.open(). This function doesn't have any parameters, and simply returns an error code integer.

If open() returns a positive number, the shield successfully connected to GPRS. If it returns -2, the shield failed to connect. If it returns -1 it timed out. This function can take a while to return successfully -- upwards of 30 seconds if the module is just getting warmed up, so be patient.

If you ever need to turn GPRS off, use the gprs.close() function. This function has the opposite effect from open() and returns a similar set of error codes.

Local and Remote IP Address Lookup

If you need to find your IP address, gprs.localIP() should meet your needs. This function returns a variable of type IPAddress, already defined in the Arduino core. Here's an example usage:

language:c
IPAddress myIPAddress;
myIPAddress = gprs.localIP();
Serial.print("My IP address is: ");
Serial.println(myIPAddress);

Given a domain name, the MG2639 supports DNS IP lookup with the hostByName(const char * domain, IPAddress * ipRet) function. Unlike localIP(), this function doesn't return an IP address by value -- instead it'll return the requested IP by reference. For example, if you want to look up the IP address of sparkfun.com:

language:c
const char sparkfunDomain[] = "sparkfun.com"; // Domain we want to look up
IPAddress sparkfunIP; // IPAddress variable where we'll store the domain's IP
gprs.hostByName(sparkfunDomain, &sparkfunIP);
Serial.print("sparkfun.com's IP address is: ");
Serial.println(sparkfunIP);

hostByName() returns an error code as well. It'll be a positive number if the lookup was successful, and a negative number if there was an error or timeout.

Connecting

To connect to a remote IP address, use either gprs.connect(IPAddress ip, unsigned int port) or gprs.connect(const char * domain, unsigned int port) to connect to an IP address or domain string.

For example, to connect to SparkFun on port 80 (the good, old, HTTP port), send this:

language:c
const char sparkFunDomain[] = "sparkfun.com";
int connectStatus;
connectStatus = gprs.connect(sparkFunDomain, 80);
if (connectStatus > 0)
    Serial.println("Connected to SparkFun, port 80");
else if (connectStatus == -1)
    Serial.println("Timed out trying to connect to SparkFun.");
else if (connectStatus == -2)
    Serial.println("Received an error trying to connect.");

Sending and Receiving

As with other stream classes, print(), write(), available(), and read() functions are defined for gprs. You can use print() to send just about any, defined variable type in Arduino to a connected server.

Each print() takes a long-ish time to execute (about 1-2 seconds), so if speed is a factor we recommend using as few separate print() calls as possible. For example, these blocks of code do the same thing:

language:c
// You can do this to send a GET string..
gprs.println("GET / HTTP/1.1");
gprs.print("Host: ");
gprs.print(server);
gprs.println();
gprs.println();

// But this one is faster:
gprs.print("GET / HTTP/1.1\nHost: example.com\n\n");

But the latter finishes about 8 seconds faster.

To check for data coming from a connected server, back to the MG2639, use gprs.available() and gprs.read(). gprs.available() returns the number of bytes currently stored in the library's receive buffer. If it's greater than 0, there's at least one character there -- use gprs.read() to read the first available character in the buffer.

As an example from the sketch:

language:c
// If there's data returned sent to the cell module:
if (gprs.available())
{
    // Print it to the serial port:
    Serial.write(gprs.read());
}

Because the Arduino's memory is very limited, the receive buffer is relatively small (64 bytes). If you're not checking the response often, you'll most likely lose data to buffer overrun.