Home / Hardware / Legacy Documentation / GSM Library

GSM Library

A library made for the Arduino GSM Shield, allowing you to send/receive text messages, make/receive phone calls and connect to the Internet.

Author Arduino

Last revision 01/25/2022

This library is archived and is no longer being maintained. It can be still be downloaded and used, but is read-only and cannot be contributed to. For more information, you can view this repository on GitHub.

The GSM Library is included with Arduino IDE 1.0.4 and later.

With the Arduino GSM Shield, this library enables an Arduino board to do most of the operations you can do with a GSM phone: place and receive voice calls, send and receive SMS, and connect to the internet over a GPRS network.

The GSM shield has a modem that transfers data from a serial port to the GSM network. The modem executes operations via a series of AT commands. The library abstracts low level communications between the modem and SIM card. It relies on the Software Serial library for communication between the modem and Arduino.

Typically, each individual command is part of a larger series necessary to execute a particular function. The library can also receive information and return it to you when necessary.

To use this library

1#include <GSM.h>

Library structure

As the library enables multiple types of functionality, there are a number of different classes.

The GSM class takes care of commands to the radio modem. This handles the connectivity aspects of the shield and registers your system in the GSM infrastructure. All of your GSM/GPRS programs will need to include an object of this class to handle the necessary low level communication.
Voice call handling, managed by the GSMVoiceCall class.
Send/receive SMS messages, managed by the GSM_SMS class.
The GPRSClass is for connecting to the internet.
GSMClient includes implementations for a client, similar to the Ethernet and WiFi libraries.
GSMServer includes implementations for a server, similar to the Ethernet and WiFi libraries. NB : A number of network operators do not allow for incoming connections from the public internet, but will allow them from inside their own. Check with your operator to see what restrictions there are on data use.
A number of utility classes such as GSMScanner and GSMModem

Ethernet library compatibility

The library tries to be as compatible as possible with the current Ethernet library. Porting a program from an Arduino Ethernet or WiFi library to an Arduino with the GSM Shield should be fairly easy. While it is not possible to simply run Ethernet-compatible code on the GSM shield as-is, some minor, library specific, modifications will be necessary, like including the GSM and GPRS specific libraries and getting network configuration settings from your cellular network provider.

Examples

There are two groups of examples for the GSM shield. There are examples to illustrate the possibilities of the shield, like how to send SMS messages and connect to the internet. There is also set of example tools that you can use to debug the functionality of the library and the hardware at lower level.

Gsm Web Client: Download the content of a website to your Arduino board through GPRS.
Gsm Web Server: Create a wireless web server through GPRS.
Make Voice Call: Get your shield to make phone calls from the Serial Monitor.
Send SMS: Use the Serial Monitor to type in SMS messages to different phone numbers.
Receive Voice Call: Check the status of the modem while getting voice calls.
Receive SMS: Read SMS messages and prompt them to the Serial Monitor.

Tools

Band Management: Manage the band the GSM shield connects to.
GSM Scan Networks: Check for the available networks.
Pin Management: Manage the PIN number of your SIM card.
Test GPRS: Test the proper functionality of the GPRS network using your SIM card.
Test Modem: Read the IMEI of your modem.
Test Web Server: Create a webserver with your GSM shield.

GSM class

GSM constructor

Description

GSM is the base class for all GSM based functions.

Syntax

1GSM GSMAccess
2GSM GSMAccess(debug)

Parameters

debug: boolean (default FALSE) flag for turing on the debug mode. This will print out the AT commands from the modem.

Example

1// libraries
2#include <GSM.h>
3
4// PIN Number
5#define PINNUMBER ""
6
7// initialize the library instance
8GSM gsmAccess;     // include a 'true' parameter for debug enabled
9
10void setup()
11{
12  // initialize serial communications
13  Serial.begin(9600);
14
15  // connection state
16  boolean notConnected = true;
17
18  // Start GSM shield
19  // If your SIM has PIN, pass it as a parameter of begin() in quotes
20  while(notConnected)
21  {
22    if(gsmAccess.begin(PINNUMBER)==GSM_READY){
23      notConnected = false;
24      Serial.println("Connected to network");
25    }
26    else
27    {
28      Serial.println("Not connected");
29      delay(1000);
30    }
31  }
32}
33
34void loop()
35{
36  // Nothing here
37}

begin()

Description

Connects to the GSM network identified on the SIM card.

Syntax

1gsm.begin()
2gsm.begin(pin)
3gsm.begin(pin, restart)
4gsm.begin(pin, restart, sync)

Parameters

pin : character array with the PIN to access a SIM card (default = 0)
restart : boolean, determines whether to restart modem or not (default= true)
sync : boolean, synchronous (true, default) or asynchronous (false) mode

Returns

0 if asynchronous. If synchronous, returns status : ERROR, IDLE, CONNECTING, GSM_READY, GPRS_READY, TRANSPARENT_CONNECTED

Example

1#define PINNUMBER ""
2
3GSM gsm; // include a 'true' parameter for debug enabled
4
5void setup()
6{
7  // initialize serial communications
8  Serial.begin(9600);
9
10  // connection state
11  boolean notConnected = true;
12
13  // Start GSM shield
14  // If your SIM has PIN, pass it as a parameter of begin() in quotes
15  while(notConnected)
16  {
17    if(gsm.begin(PINNUMBER)==GSM_READY)
18      notConnected = false;
19    else
20    {
21      Serial.println("Not connected");
22      delay(1000);
23    }
24  }
25
26  Serial.println("GSM initialized");
27}
28
29void loop()
30{
31// once connected do something interesting
32}

shutdown()

Description

Disconnects from the GSM network identified on the SIM card by powering the modem off.

Syntax

1gsm.shutdown()

Parameters

none

Returns

boolean : 0 while executing, 1 when successful

Example

1#define PINNUMBER ""
2
3GSM gsm; // include a 'true' parameter for debug enabled
4
5void setup()
6{
7  // initialize serial communications
8  Serial.begin(9600);
9
10  // connection state
11  boolean notConnected = true;
12
13  // Start GSM shield
14  // If your SIM has PIN, pass it as a parameter of begin() in quotes
15  while(notConnected)
16  {
17    if(gsm.begin(PINNUMBER)==GSM_READY)
18      notConnected = false;
19    else
20    {
21      Serial.println("Not connected");
22      delay(1000);
23    }
24  }
25
26  Serial.println("GSM initialized");
27
28  gsm.shutdown();
29  Serial.println("GSM terminated");
30
31}
32
33void loop()
34{
35}

GSMVoiceCall class

GSMVoiceCall constructor

Description

GSMVoiceCall is the base class for all GSM functions relating to receiving and making voice calls.

getVoiceCallStatus()

Description

Returns status of the voice call.

Syntax

1voice.getVoiceCallStatus()

Parameters

none

Returns

char : IDLE_CALL, CALLING, RECEIVINGCALL, TALKING

Example

1// libraries
2#include <GSM.h>
3
4// PIN Number
5#define PINNUMBER ""
6
7// initialize the library instance
8GSM gsmAccess; // include a 'true' parameter for debug enabled
9GSMVoiceCall vcs;
10
11
12char numtel[20];           // buffer for the incoming call
13
14void setup()
15{
16  // initialize serial communications
17  Serial.begin(9600);
18  Serial.println("Receive Voice Call");
19
20  // connection state
21  boolean notConnected = true;
22
23  // Start GSM shield
24  // If your SIM has PIN, pass it as a parameter of begin() in quotes
25  while(notConnected)
26  {
27    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
28      notConnected = false;
29    else
30    {
31      Serial.println("Not connected");
32      delay(1000);
33    }
34  }
35
36  // This makes sure the modem notifies correctly incoming events
37  vcs.hangCall();
38
39  Serial.println("Waiting Call");
40}
41
42void loop()
43{
44  // Check the status of the voice call
45  switch (vcs.getvoiceCallStatus())
46  {
47    case IDLE_CALL: // Nothing is happening
48
49      break;
50
51    case CALLING: // This should never happen, as we are not placing a call
52
53      Serial.println("CALLING");
54      break;
55
56    case RECEIVINGCALL: // Yes! Someone is calling us
57
58      Serial.println("RECEIVING CALL");
59
60      // Retrieve the calling number
61      vcs.retrieveCallingNumber(numtel, 20);
62
63      // Print the calling number
64      Serial.print("Number:");
65      Serial.println(numtel);
66
67      // Answer the call, establish the call
68      vcs.answerCall();        
69      break;
70
71    case TALKING:  // In this case the call would be established
72
73      Serial.println("TALKING. Enter line to interrupt.");
74      while(Serial.read()!='\n')
75        delay(100);
76      vcs.hangCall();
77      Serial.println("HANG. Waiting Call.");      
78      break;
79  }
80  delay(1000);
81}

ready()

Description

Reports if the previous voice command has executed successfully

Syntax

1voice.ready()

Parameters

none

Returns

int In asynchronous mode, ready() returns 0 if the last command is still executing, 1 if there is success, and >1 in case of an error. In synchronous mode, it returns 1 if it executed successfully, 0 if not.

voiceCall()

Description

Places a voice call to a specified number. The methods returns different information depending on the GSM connection mode (synchronous or asynchronous). See below for details.

Syntax

1voice.voiceCall(number)

Parameters

number : char array. The number to call.

Returns

int In asynchronous mode, voiceCall() returns 0 if last command is still executing, 1 if successful, and >1 in case of an error. In synchronous mode, it returns 1 if the call is placed, 0 if not.

Example

1// PIN Number
2#define PINNUMBER ""
3
4// initialize the library instance
5GSM gsmAccess; // include a 'true' parameter for debug enabled
6GSMVoiceCall vcs;
7
8String remoteNumber = "";  // the number you will call
9char charbuffer[20];
10
11void setup()
12{
13
14  // initialize serial communications
15  Serial.begin(9600);
16
17  Serial.println("Make Voice Call");
18
19  // connection state
20  boolean notConnected = true;
21
22  // Start GSM shield
23  // If your SIM has PIN, pass it as a parameter of begin() in quotes
24  while(notConnected)
25  {
26    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
27      notConnected = false;
28    else
29    {
30      Serial.println("Not connected");
31      delay(1000);
32    }
33  }
34
35  Serial.println("GSM initialized.");
36  Serial.println("Enter phone number to call.");
37
38}
39
40void loop()
41{
42
43  // add any incoming characters to the String:
44  while (Serial.available() > 0)
45  {
46    char inChar = Serial.read();
47    // if it's a newline, that means you should make the call:
48    if (inChar == '\n')
49    {
50      // make sure the phone number is not too long:
51      if (remoteNumber.length() < 20)
52      {
53        // let the user know you're calling:
54        Serial.print("Calling to : ");
55        Serial.println(remoteNumber);
56        Serial.println();
57
58        // Call the remote number
59        remoteNumber.toCharArray(charbuffer, 20);
60
61
62        // Check if the receiving end has picked up the call
63        if(vcs.voiceCall(charbuffer))
64        {
65          Serial.println("Call Established. Enter line to end");
66          // Wait for some input from the line
67          while(Serial.read() !='\n' && (vcs.getvoiceCallStatus()==TALKING));          
68          // And hang up
69          vcs.hangCall();
70        }
71        Serial.println("Call Finished");
72        remoteNumber="";
73        Serial.println("Enter phone number to call.");
74      }
75      else
76      {
77        Serial.println("That's too long for a phone number. I'm forgetting it");
78        remoteNumber = "";
79      }
80    }
81    else
82    {
83      // add the latest character to the message to send:
84      if(inChar!='\r')
85        remoteNumber += inChar;
86    }
87  }
88}

answerCall()

Description

Accepts an incoming voice call. The method returns are different depending on the modem mode (asynchronous or synchronous), see below for details.

Syntax

1voice.answerCall()

Parameters

none

Returns

int In asynchronous mode, answerCall() returns 0 if last command is still executing, 1 if successful, and >1 in case of an error. In synchronous mode, it returns 1 if the call is answered, 0 if not.

Example

1// PIN Number
2#define PINNUMBER ""
3
4// initialize the library instance
5GSM gsmAccess; // include a 'true' parameter for debug enabled
6GSMVoiceCall vcs;
7
8char numtel[20];           // buffer for the incoming call
9
10void setup()
11{
12  // initialize serial communications
13  Serial.begin(9600);
14  Serial.println("Receive Voice Call");
15
16  // connection state
17  boolean notConnected = true;
18
19  // Start GSM shield
20  // If your SIM has PIN, pass it as a parameter of begin() in quotes
21  while(notConnected)
22  {
23    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
24      notConnected = false;
25    else
26    {
27      Serial.println("Not connected");
28      delay(1000);
29    }
30  }
31
32  // This makes sure the modem notifies correctly incoming events
33  vcs.hangCall();
34
35  Serial.println("Waiting Call");
36}
37
38void loop()
39{
40  // Check the status of the voice call
41  switch (vcs.getvoiceCallStatus())
42  {
43    case IDLE_CALL: // Nothing is happening
44
45      break;
46
47    case CALLING: // This should never happen, as we are not placing a call
48
49      Serial.println("CALLING");
50      break;
51
52    case RECEIVINGCALL: // Yes! Someone is calling us
53
54      Serial.println("RECEIVING CALL");
55
56      // Retrieve the calling number
57      vcs.retrieveCallingNumber(numtel, 20);
58
59      // Print the calling number
60      Serial.print("Number:");
61      Serial.println(numtel);
62
63      // Answer the call, establish the call
64      vcs.answerCall();        
65      break;
66
67    case TALKING:  // In this case the call would be established
68
69      Serial.println("TALKING. Enter line to interrupt.");
70      while(Serial.read()!='\n')
71        delay(100);
72      vcs.hangCall();
73      Serial.println("HANG. Waiting Call.");      
74      break;
75  }
76  delay(1000);
77}

hangCall()

Description

Hang up an established call or during incoming rings. Depending on the modems mode (synchronous or asynchronous) the method will return differently, see below for more detail.

Syntax

1voice.hangCall()

Parameters

none

Returns

int In asynchronous mode, hangCall() returns 0 if the last command is still executing, 1 if there is success, and >1 in case of an error. In synchronous mode, it returns 1 if the call is hung, 0 if not.

Example

1// libraries
2#include <GSM.h>
3
4// PIN Number
5#define PINNUMBER ""
6
7// initialize the library instance
8GSM gsmAccess; // include a 'true' parameter for debug enabled
9GSMVoiceCall vcs;
10
11
12char numtel[20];           // buffer for the incoming call
13
14void setup()
15{
16  // initialize serial communications
17  Serial.begin(9600);
18  Serial.println("Receive Voice Call");
19
20  // connection state
21  boolean notConnected = true;
22
23  // Start GSM shield
24  // If your SIM has PIN, pass it as a parameter of begin() in quotes
25  while(notConnected)
26  {
27    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
28      notConnected = false;
29    else
30    {
31      Serial.println("Not connected");
32      delay(1000);
33    }
34  }
35
36  // This makes sure the modem notifies correctly incoming events
37  vcs.hangCall();
38
39  Serial.println("Waiting Call");
40}
41
42void loop()
43{
44  // Check the status of the voice call
45  switch (vcs.getvoiceCallStatus())
46  {
47    case IDLE_CALL: // Nothing is happening
48
49      break;
50
51    case CALLING: // This should never happen, as we are not placing a call
52
53      Serial.println("CALLING");
54      break;
55
56    case RECEIVINGCALL: // Yes! Someone is calling us
57
58      Serial.println("RECEIVING CALL");
59
60      // Retrieve the calling number
61      vcs.retrieveCallingNumber(numtel, 20);
62
63      // Print the calling number
64      Serial.print("Number:");
65      Serial.println(numtel);
66
67      // Answer the call, establish the call
68      vcs.answerCall();        
69      break;
70
71    case TALKING:  // In this case the call would be established
72
73      Serial.println("TALKING. Enter line to interrupt.");
74      while(Serial.read()!='\n')
75        delay(100);
76      vcs.hangCall();
77      Serial.println("HANG. Waiting Call.");      
78      break;
79  }
80  delay(1000);
81}

retrieveCallingNumber()

Description

Retrieves the calling number, and stores it.

Syntax

1voice.retrieveCallingNumber(number, size)

Parameters

number : char array to hold the number
size : the size of the array

Returns

int In asynchronous mode, retrieveCallingNumber() returns 0 if the last command is still executing, 1 if success, and >1 if there is an error. In synchronous mode, it returns 1 if the number is obtained 0 if not.

Example

1// PIN Number
2#define PINNUMBER ""
3
4// initialize the library instance
5GSM gsmAccess; // include a 'true' parameter for debug enabled
6GSMVoiceCall vcs;
7
8char numtel[20];           // buffer for the incoming call
9
10void setup()
11{
12  // initialize serial communications
13  Serial.begin(9600);
14  Serial.println("Receive Voice Call");
15
16  // connection state
17  boolean notConnected = true;
18
19  // Start GSM shield
20  // If your SIM has PIN, pass it as a parameter of begin() in quotes
21  while(notConnected)
22  {
23    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
24      notConnected = false;
25    else
26    {
27      Serial.println("Not connected");
28      delay(1000);
29    }
30  }
31
32  // This makes sure the modem notifies correctly incoming events
33  vcs.hangCall();
34
35  Serial.println("Waiting Call");
36}
37
38void loop()
39{
40  // Check the status of the voice call
41  switch (vcs.getvoiceCallStatus())
42  {
43    case IDLE_CALL: // Nothing is happening
44
45      break;
46
47    case CALLING: // This should never happen, as we are not placing a call
48
49      Serial.println("CALLING");
50      break;
51
52    case RECEIVINGCALL: // Yes! Someone is calling us
53
54      Serial.println("RECEIVING CALL");
55
56      // Retrieve the calling number
57      vcs.retrieveCallingNumber(numtel, 20);
58
59      // Print the calling number
60      Serial.print("Number:");
61      Serial.println(numtel);
62
63      // Answer the call, establish the call
64      vcs.answerCall();        
65      break;
66
67    case TALKING:  // In this case the call would be established
68
69      Serial.println("TALKING. Enter line to interrupt.");
70      while(Serial.read()!='\n')
71        delay(100);
72      vcs.hangCall();
73      Serial.println("HANG. Waiting Call.");      
74      break;
75  }
76  delay(1000);
77}

GSM_SMS class

GSM_SMS constructor

Description

GSM_SMS is the base class for all GSM functions relating to receiving and sending SMS messages.

beginSMS()

Description

Identifies the telephone number to send an SMS message to.

Syntax

1SMS.beginSMS(number)

Parameters

number : char array, the phone number to send the SMS to

Returns

int In asynchronous mode, beginSMS() returns 0 if the last command is still executing, 1 if success, and >1 if there is an error. In synchronous mode, it returns 1 if it successfully executes, and 0 if it does not.

Example

1#define PINNUMBER ""
2
3// initialize the library instance
4GSM gsmAccess; // include a 'true' parameter for debug enabled
5GSM_SMS sms;
6
7void setup()
8{
9  // initialize serial communications
10  Serial.begin(9600);
11
12  Serial.println("SMS Messages Sender");
13
14  // connection state
15  boolean notConnected = true;
16
17  // Start GSM shield
18  // If your SIM has PIN, pass it as a parameter of begin() in quotes
19  while(notConnected)
20  {
21    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
22      notConnected = false;
23    else
24    {
25      Serial.println("Not connected");
26      delay(1000);
27    }
28  }
29
30  Serial.println("GSM initialized");
31}
32
33void loop()
34{
35
36  Serial.print("Enter a mobile number: ");
37  char remoteNumber[20];  // telephone number to send sms
38  readSerial(remoteNumber);
39  Serial.println(remoteNumber);
40
41  // sms text
42  Serial.print("Now, enter SMS content: ");
43  char txtMsg[200];
44  readSerial(txtMsg);
45  Serial.println("SENDING");
46  Serial.println();
47  Serial.println("Message:");
48  Serial.println(txtMsg);
49
50  // send the message
51  sms.beginSMS(remoteNumber);
52  sms.print(txtMsg);
53  sms.endSMS();
54  Serial.println("\nCOMPLETE!\n");
55}
56
57/*
58  Read input serial
59 */
60int readSerial(char result[])
61{
62  int i = 0;
63  while(1)
64  {
65    while (Serial.available() > 0)
66    {
67      char inChar = Serial.read();
68      if (inChar == '\n')
69      {
70        result[i] = '\0';
71        Serial.flush();
72        return 0;
73      }
74      if(inChar!='\r')
75      {
76        result[i] = inChar;
77        i++;
78      }
79    }
80  }
81}

ready()

Description

Gets the status if the last GSMSMS command.

Syntax

1SMS.ready()

Parameters

none

Returns

int In asynchronous mode, ready() returns 0 if the last command is still executing, 1 if it was successful, and >1 if there is an error. In synchronous mode, it returns 1 if the previous successfully executed, and 0 if it has not.

endSMS()

Description

Tells the modem that the SMS message is complete and sends it.

Syntax

1SMS.endSMS()

Parameters

none

Returns

int In asynchronous mode, endSMS() returns 0 if it is still executing, 1 if successful, and >1 if there is an error. In synchronous mode, it returns 1 if the previous successfully executed, and 0 if it has not.

Example

1#define PINNUMBER ""
2
3// initialize the library instance
4GSM gsmAccess; // include a 'true' parameter for debug enabled
5GSM_SMS sms;
6
7void setup()
8{
9  // initialize serial communications
10  Serial.begin(9600);
11
12  Serial.println("SMS Messages Sender");
13
14  // connection state
15  boolean notConnected = true;
16
17  // Start GSM shield
18  // If your SIM has PIN, pass it as a parameter of begin() in quotes
19  while(notConnected)
20  {
21    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
22      notConnected = false;
23    else
24    {
25      Serial.println("Not connected");
26      delay(1000);
27    }
28  }
29
30  Serial.println("GSM initialized");
31}
32
33void loop()
34{
35
36  Serial.print("Enter a mobile number: ");
37  char remoteNumber[20];  // telephone number to send sms
38  readSerial(remoteNumber);
39  Serial.println(remoteNumber);
40
41  // sms text
42  Serial.print("Now, enter SMS content: ");
43  char txtMsg[200];
44  readSerial(txtMsg);
45  Serial.println("SENDING");
46  Serial.println();
47  Serial.println("Message:");
48  Serial.println(txtMsg);
49
50  // send the message
51  sms.beginSMS(remoteNumber);
52  sms.print(txtMsg);
53  sms.endSMS();
54  Serial.println("\nCOMPLETE!\n");
55}
56
57/*
58  Read input serial
59 */
60int readSerial(char result[])
61{
62  int i = 0;
63  while(1)
64  {
65    while (Serial.available() > 0)
66    {
67      char inChar = Serial.read();
68      if (inChar == '\n')
69      {
70        result[i] = '\0';
71        Serial.flush();
72        return 0;
73      }
74      if(inChar!='\r')
75      {
76        result[i] = inChar;
77        i++;
78      }
79    }
80  }
81}

available()

Description

Checks to see if there is a SMS messages on the SIM card to be read, and reports back the number of characters in the message.

Syntax

1SMS.available()

Parameters

none

Returns

int : the number of characters in the message

Example

1// initialize the library instance
2GSM gsmAccess; // include a 'true' parameter for debug enabled
3GSM_SMS sms;
4
5char remoteNumber[20];  // Holds the emitting number
6
7void setup()
8{
9  // initialize serial communications
10  Serial.begin(9600);
11
12  Serial.println("SMS Messages Receiver");
13
14  // connection state
15  boolean notConnected = true;
16
17  // Start GSM shield
18  // If your SIM has PIN, pass it as a parameter of begin() in quotes
19  while(notConnected)
20  {
21    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
22      notConnected = false;
23    else
24    {
25      Serial.println("Not connected");
26      delay(1000);
27    }
28  }
29
30  Serial.println("GSM initialized");
31  Serial.println("Waiting for messages");
32}
33
34void loop()
35{
36  char c;
37
38  // If there are any SMSs available()  
39  if (sms.available())
40  {
41    Serial.println("Message received from:");
42
43    // Get remote number
44    sms.remoteNumber(remoteNumber, 20);
45    Serial.println(remoteNumber);
46
47    // This is just an example of message disposal    
48    // Messages starting with # should be discarded
49    if(sms.peek()=='#')
50    {
51      Serial.println("Discarded SMS");
52      sms.flush();
53    }
54
55    // Read message bytes and print them
56    while(c=sms.read())
57      Serial.print(c);
58
59    Serial.println("\nEND OF MESSAGE");
60
61    // delete message from modem memory
62    sms.flush();
63    Serial.println("MESSAGE DELETED");
64  }
65
66  delay(1000);
67
68}

remoteNumber()

Description

Retrieves the phone number an from an incoming SMS message and stores it in a named array.

Syntax

1SMS.remoteNumber(number, size)

Parameters

number : char array, a named array that will hold the sender's number
size : int, the size of the array

Returns

int In asynchronous mode, remoteNumber() returns 0 if the last command is still executing, 1 if success, and >1 if there is an error. In synchronous mode, it returns 1 if it successfully executes, and 0 if it does not.

Example

1// PIN Number
2#define PINNUMBER ""
3
4// initialize the library instance
5GSM gsmAccess; // include a 'true' parameter for debug enabled
6GSM_SMS sms;
7
8char remoteNumber[20];  // Holds the emitting number
9
10void setup()
11{
12  // initialize serial communications
13  Serial.begin(9600);
14
15  Serial.println("SMS Messages Receiver");
16
17  // connection state
18  boolean notConnected = true;
19
20  // Start GSM shield
21  // If your SIM has PIN, pass it as a parameter of begin() in quotes
22  while(notConnected)
23  {
24    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
25      notConnected = false;
26    else
27    {
28      Serial.println("Not connected");
29      delay(1000);
30    }
31  }
32
33  Serial.println("GSM initialized");
34  Serial.println("Waiting for messages");
35}
36
37void loop()
38{
39  char c;
40
41  // If there are any SMSs available()  
42  if (sms.available())
43  {
44    Serial.println("Message received from:");
45
46    // Get remote number
47    sms.remoteNumber(remoteNumber, 20);
48    Serial.println(remoteNumber);
49
50    // This is just an example of message disposal    
51    // Messages starting with # should be discarded
52    if(sms.peek()=='#')
53    {
54      Serial.println("Discarded SMS");
55      sms.flush();
56    }
57
58    // Read message bytes and print them
59    while(c=sms.read())
60      Serial.print(c);
61
62    Serial.println("\nEND OF MESSAGE");
63
64    // delete message from modem memory
65    sms.flush();
66    Serial.println("MESSAGE DELETED");
67  }
68
69  delay(1000);
70
71}

read()

Description

Reads a byte from an SMS message. read() inherits from the Stream utility class.

Syntax

1SMS.read()

Parameters

none

Returns

int - the first byte of incoming serial data available (or -1 if no data is available)

Example

1// PIN Number
2#define PINNUMBER ""
3
4// initialize the library instance
5GSM gsmAccess; // include a 'true' parameter for debug enabled
6GSM_SMS sms;
7
8char remoteNumber[20];  // Holds the emitting number
9
10void setup()
11{
12  // initialize serial communications
13  Serial.begin(9600);
14
15  Serial.println("SMS Messages Receiver");
16
17  // connection state
18  boolean notConnected = true;
19
20  // Start GSM shield
21  // If your SIM has PIN, pass it as a parameter of begin() in quotes
22  while(notConnected)
23  {
24    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
25      notConnected = false;
26    else
27    {
28      Serial.println("Not connected");
29      delay(1000);
30    }
31  }
32
33  Serial.println("GSM initialized");
34  Serial.println("Waiting for messages");
35}
36
37void loop()
38{
39  char c;
40
41  // If there are any SMSs available()  
42  if (sms.available())
43  {
44    Serial.println("Message received from:");
45
46    // Get remote number
47    sms.remoteNumber(remoteNumber, 20);
48    Serial.println(remoteNumber);
49
50    // This is just an example of message disposal    
51    // Messages starting with # should be discarded
52    if(sms.peek()=='#')
53    {
54      Serial.println("Discarded SMS");
55      sms.flush();
56    }
57
58    // Read message bytes and print them
59    while(c=sms.read())
60      Serial.print(c);
61
62    Serial.println("\nEND OF MESSAGE");
63
64    // delete message from modem memory
65    sms.flush();
66    Serial.println("MESSAGE DELETED");
67  }
68
69  delay(1000);
70
71}

write()

Description

Writes a character to a SMS message.

Syntax

1SMS.write(val)

Parameters

val: a character to send in the message

Returns

byte - write() will return the number of bytes written, though reading that number is optional

Example

1#define PINNUMBER ""
2
3// initialize the library instance
4GSM gsmAccess; // include a 'true' parameter for debug enabled
5GSM_SMS sms;
6
7void setup()
8{
9  // initialize serial communications
10  Serial.begin(9600);
11
12  Serial.println("SMS Messages Sender");
13
14  // connection state
15  boolean notConnected = true;
16
17  // Start GSM shield
18  // If your SIM has PIN, pass it as a parameter of begin() in quotes
19  while(notConnected)
20  {
21    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
22      notConnected = false;
23    else
24    {
25      Serial.println("Not connected");
26      delay(1000);
27    }
28  }
29
30  Serial.println("GSM initialized");
31}
32
33void loop()
34{
35
36  Serial.print("Enter a mobile number: ");
37  char remoteNumber[20];  // telephone number to send sms
38  readSerial(remoteNumber);
39  Serial.println(remoteNumber);
40
41  // sms text
42  Serial.print("Now, enter SMS content: ");
43  char txtMsg[200];
44  readSerial(txtMsg);
45  Serial.println("SENDING");
46  Serial.println();
47  Serial.println("Message:");
48  Serial.println(txtMsg);
49
50  // send the message
51  sms.beginSMS(remoteNumber);
52  sms.print(txtMsg);
53  sms.endSMS();
54  Serial.println("\nCOMPLETE!\n");
55}
56
57/*
58  Read input serial
59 */
60int readSerial(char result[])
61{
62  int i = 0;
63  while(1)
64  {
65    while (Serial.available() > 0)
66    {
67      char inChar = Serial.read();
68      if (inChar == '\n')
69      {
70        result[i] = '\0';
71        Serial.flush();
72        return 0;
73      }
74      if(inChar!='\r')
75      {
76        result[i] = inChar;
77        i++;
78      }
79    }
80  }
81}

print()

Description

Writes a char array as a SMS message.

Syntax

1SMS.print(message)

Parameters

message - char array, the message to send

Returns

int : the number of bytes printed

Example

1#define PINNUMBER ""
2
3// initialize the library instance
4GSM gsmAccess; // include a 'true' parameter for debug enabled
5GSM_SMS sms;
6
7void setup()
8{
9  // initialize serial communications
10  Serial.begin(9600);
11
12  Serial.println("SMS Messages Sender");
13
14  // connection state
15  boolean notConnected = true;
16
17  // Start GSM shield
18  // If your SIM has PIN, pass it as a parameter of begin() in quotes
19  while(notConnected)
20  {
21    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
22      notConnected = false;
23    else
24    {
25      Serial.println("Not connected");
26      delay(1000);
27    }
28  }
29
30  Serial.println("GSM initialized");
31}
32
33void loop()
34{
35
36  Serial.print("Enter a mobile number: ");
37  char remoteNumber[20];  // telephone number to send sms
38  readSerial(remoteNumber);
39  Serial.println(remoteNumber);
40
41  // sms text
42  Serial.print("Now, enter SMS content: ");
43  char txtMsg[200];
44  readSerial(txtMsg);
45  Serial.println("SENDING");
46  Serial.println();
47  Serial.println("Message:");
48  Serial.println(txtMsg);
49
50  // send the message
51  sms.beginSMS(remoteNumber);
52  sms.print(txtMsg);
53  sms.endSMS();
54  Serial.println("\nCOMPLETE!\n");
55}
56
57/*
58  Read input serial
59 */
60int readSerial(char result[])
61{
62  int i = 0;
63  while(1)
64  {
65    while (Serial.available() > 0)
66    {
67      char inChar = Serial.read();
68      if (inChar == '\n')
69      {
70        result[i] = '\0';
71        Serial.flush();
72        return 0;
73      }
74      if(inChar!='\r')
75      {
76        result[i] = inChar;
77        i++;
78      }
79    }
80  }
81}

peek()

Description

Returns the next byte (character) of an incoming SMS without removing it from the message. That is, successive calls to peek() will return the same character, as will the next call to read(). peek() inherits from the Stream utility class.

Syntax

1SMS.peek()

Parameters

none

Returns

int - the first byte available of a SMS message (or -1 if no data is available)

Example

1SMS receiver
2
3 This sketch, for the Arduino GSM shield, waits for SMS messages
4 and displays them through the Serial port.
5
6 Circuit:
7 * GSM shield
8
9 created 25 Feb 2012
10 by Javier Zorzano / TD
11
12 This example is in the public domain.
13*/
14
15// libraries
16#include <GSM.h>
17
18// PIN Number
19#define PINNUMBER ""
20
21// initialize the library instance
22GSM gsmAccess; // include a 'true' parameter for debug enabled
23GSM_SMS sms;
24
25char remoteNumber[20];  // Holds the emitting number
26
27void setup()
28{
29  // initialize serial communications
30  Serial.begin(9600);
31
32  Serial.println("SMS Messages Receiver");
33
34  // connection state
35  boolean notConnected = true;
36
37  // Start GSM shield
38  // If your SIM has PIN, pass it as a parameter of begin() in quotes
39  while(notConnected)
40  {
41    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
42      notConnected = false;
43    else
44    {
45      Serial.println("Not connected");
46      delay(1000);
47    }
48  }
49
50  Serial.println("GSM initialized");
51  Serial.println("Waiting for messages");
52}
53
54void loop()
55{
56  char c;
57
58  // If there are any SMSs available()  
59  if (sms.available())
60  {
61    Serial.println("Message received from:");
62
63    // Get remote number
64    sms.remoteNumber(remoteNumber, 20);
65    Serial.println(remoteNumber);
66
67    // This is just an example of message disposal    
68    // Messages starting with # should be discarded
69    if(sms.peek()=='#')
70    {
71      Serial.println("Discarded SMS");
72      sms.flush();
73    }
74
75    // Read message bytes and print them
76    while(c=sms.read())
77      Serial.print(c);
78
79    Serial.println("\nEND OF MESSAGE");
80
81    // delete message from modem memory
82    sms.flush();
83    Serial.println("MESSAGE DELETED");
84  }
85
86  delay(1000);
87
88}

flush()

Description

flush() clears the modem memory of any sent messages once all outgoing characters have been sent. flush() inherits from the Stream utility class.

Syntax

1SMS.flush()

Parameters

none

Returns

none

Example

1SMS receiver
2
3 This sketch, for the Arduino GSM shield, waits for SMS messages
4 and displays them through the Serial port.
5
6 Circuit:
7 * GSM shield
8
9 created 25 Feb 2012
10 by Javier Zorzano / TD
11
12 This example is in the public domain.
13*/
14
15// libraries
16#include <GSM.h>
17
18// PIN Number
19#define PINNUMBER ""
20
21// initialize the library instance
22GSM gsmAccess; // include a 'true' parameter for debug enabled
23GSM_SMS sms;
24
25char remoteNumber[20];  // Holds the emitting number
26
27void setup()
28{
29  // initialize serial communications
30  Serial.begin(9600);
31
32  Serial.println("SMS Messages Receiver");
33
34  // connection state
35  boolean notConnected = true;
36
37  // Start GSM shield
38  // If your SIM has PIN, pass it as a parameter of begin() in quotes
39  while(notConnected)
40  {
41    if(gsmAccess.begin(PINNUMBER)==GSM_READY)
42      notConnected = false;
43    else
44    {
45      Serial.println("Not connected");
46      delay(1000);
47    }
48  }
49
50  Serial.println("GSM initialized");
51  Serial.println("Waiting for messages");
52}
53
54void loop()
55{
56  char c;
57
58  // If there are any SMSs available()  
59  if (sms.available())
60  {
61    Serial.println("Message received from:");
62
63    // Get remote number
64    sms.remoteNumber(remoteNumber, 20);
65    Serial.println(remoteNumber);
66
67    // This is just an example of message disposal    
68    // Messages starting with # should be discarded
69    if(sms.peek()=='#')
70    {
71      Serial.println("Discarded SMS");
72      sms.flush();
73    }
74
75    // Read message bytes and print them
76    while(c=sms.read())
77      Serial.print(c);
78
79    Serial.println("\nEND OF MESSAGE");
80
81    // delete message from modem memory
82    sms.flush();
83    Serial.println("MESSAGE DELETED");
84  }
85
86  delay(1000);
87
88}

GPRS class

GPRS constructor

Description

GPRS is the base class for all GPRS functions, such as internet client and server behaviors.

attachGPRS()

Description

Connects to the specified Access Point Name (APN) to initiate GPRS communication.

Every cellular provider has an Access Point Name (APN) that serves as a bridge between the cellular network and the internet. Sometimes, there is a username and password associated with the connection point. For example, the Bluevia APN is bluevia.movistar.es, but it has no password or login name.

This page lists a number of carrier's information, but it may not be up to date. You may need to get this information from your service provider.

Syntax

1grps.attachGPRS(APN, user, password)

Parameters

APN : char array, the Access Point Name (APN) provided by the mobile operator
user : char array, the username for the APN
password : char array, the password to access the APN

Returns

ERROR, IDLE, CONNECTING, GSM_READY, GPRS_READY, TRANSPARENT_CONNECTED

Example

1// PIN Number
2#define PINNUMBER ""
3
4// APN data
5#define GPRS_APN       "GPRS_APN" // replace your GPRS APN
6#define GPRS_LOGIN     "login"    // replace with your GPRS login
7#define GPRS_PASSWORD  "password" // replace with your GPRS password
8
9
10// initialize the library instance
11GPRS gprs;
12GSM gsmAccess;     // include a 'true' parameter for debug enabled
13GSMServer server(80); // port 80 (http default)
14
15// timeout
16const unsigned long __TIMEOUT__ = 10*1000;
17
18void setup()
19{
20  // initialize serial communications
21  Serial.begin(9600);
22
23  // connection state
24  boolean notConnected = true;
25
26  // Start GSM shield
27  // If your SIM has PIN, pass it as a parameter of begin() in quotes
28  while(notConnected)
29  {
30    if((gsmAccess.begin(PINNUMBER)==GSM_READY) &
31        (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD)==GPRS_READY))
32      notConnected = false;
33    else
34    {
35      Serial.println("Not connected");
36      delay(1000);
37    }
38  }
39
40  Serial.println("Connected to GPRS network");
41
42  // start server
43  server.begin();
44
45  //Get IP.
46  IPAddress LocalIP = gprs.getIPAddress();
47  Serial.println("Server IP address=");
48  Serial.println(LocalIP);
49}
50
51void loop() {
52
53
54  // listen for incoming clients
55  GSM3MobileClientService client = server.available();
56
57
58
59  if (client)
60  {  
61    while (client.connected())
62    {
63      if (client.available())
64      {
65        Serial.println("Receiving request!");
66        bool sendResponse = false;
67        while(char c=client.read()) {
68          if (c == '\n') sendResponse = true;
69        }
70
71     // if you've gotten to the end of the line (received a newline
72     // character)
73       if (sendResponse)
74       {
75          // send a standard http response header
76          client.println("HTTP/1.1 200 OK");
77          client.println("Content-Type: text/html");
78          client.println();
79          client.println("<html>");
80          // output the value of each analog input pin
81          for (int analogChannel = 0; analogChannel < 6; analogChannel++) {
82            client.print("analog input ");
83            client.print(analogChannel);
84            client.print(" is ");
85            client.print(analogRead(analogChannel));
86            client.println("<br />");      
87          }
88          client.println("</html>");
89          //necessary delay
90          delay(1000);
91          client.stop();
92        }
93      }
94    }
95  }
96}

GSMClient class

Client

Description

Client is the base class for all GPRS client based calls. It is not called directly, but invoked whenever you use a function that relies on it.

ready()

Description

Gets the status of the last command

Syntax

1client.ready()

Parameters

none

Returns

In asynchronous mode, ready() returns 0 if the last command is still executing, 1 if it was successful, and >1 if there is an error. In synchronous mode, it returns 1 if the previous successfully executed, and 0 if it has not.

connect()

Description

Connects to a specified IP address and port. The return value indicates success or failure.

Syntax

1client.connect(ip, port)

Parameters

ip: the IP address that the client will connect to (array of 4 bytes)
port: the port that the client will connect to (int)

Returns

boolean : Returns true if the connection succeeds, false if not.

Example

1Web client
2
3 This sketch connects to a website through a GSM shield. Specifically,
4 this example downloads the URL "http://arduino.cc/" and prints it
5 to the Serial monitor.
6
7 Circuit:
8 * GSM shield attached to an Arduino
9 * SIM card with a data plan
10
11 created 8 Mar 2012
12 by Tom Igoe
13
14 http://arduino.cc/en/Tutorial/GSMExamplesWebClient
15
16 */
17
18// libraries
19#include <GSM.h>
20
21// PIN Number
22#define PINNUMBER ""
23
24// APN data
25#define GPRS_APN       "GPRS_APN" // replace your GPRS APN
26#define GPRS_LOGIN     "login"    // replace with your GPRS login
27#define GPRS_PASSWORD  "password" // replace with your GPRS password
28
29// initialize the library instance
30GSMClient client;
31GPRS gprs;
32GSM gsmAccess;
33
34// URL, path & port (for example: arduino.cc)
35char server[] = "arduino.cc";
36char path[] = "/";
37int port = 80; // port 80 is the default for HTTP
38
39void setup()
40{
41  // initialize serial communications
42  Serial.begin(9600);
43  Serial.println("Starting Arduino web client.");
44  // connection state
45  boolean notConnected = true;
46
47  // After starting the modem with GSM.begin()
48  // attach the shield to the GPRS network with the APN, login and password
49  while(notConnected)
50  {
51    if((gsmAccess.begin(PINNUMBER)==GSM_READY) &
52        (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD)==GPRS_READY))
53      notConnected = false;
54    else
55    {
56      Serial.println("Not connected");
57      delay(1000);
58    }
59  }
60
61  Serial.println("connecting...");
62
63  // if you get a connection, report back via serial:
64  if (client.connect(server, port))
65  {
66    Serial.println("connected");
67    // Make a HTTP request:
68    client.print("GET ");
69    client.print(path);
70    client.println(" HTTP/1.0");
71    client.println();
72  }
73  else
74  {
75    // if you didn't get a connection to the server:
76    Serial.println("connection failed");
77  }
78}
79
80void loop()
81{
82  // if there are incoming bytes available
83  // from the server, read them and print them:
84  if (client.available())
85  {
86    char c = client.read();
87    Serial.print(c);
88  }
89
90  // if the server's disconnected, stop the client:
91  if (!client.available() && !client.connected())
92  {
93    Serial.println();
94    Serial.println("disconnecting.");
95    client.stop();
96
97    // do nothing forevermore:
98    for(;;)
99      ;
100  }
101}

beginWrite()

Description

Tells the client to start writing to the server it is connected to.

Syntax

1client.beginWrite()

Parameters

none

Returns

none

write()

Description

Write data to the server the client is connected to.

Syntax

1client.write(data)
2client.write(buffer)
3client.write(buffer, size)

Parameters

data: the value to write (byte or char)
buffer : an array of data (byte or char) to write
size : size of the buffer to write (byte)

Returns

byte - write() returns the number of bytes written. It is not necessary to read this.

endWrite()

Description

Stops writing data to a server

Syntax

1client.endWrite()

Parameters

none

Returns

none

connected()

Description

Returns whether or not the client is connected. A client is considered connected if the connection has been closed but there is still unread data.

Syntax

1client.connected()

Parameters

none

Returns

boolean - Returns true if the client is connected, false if not.

Example

1Web client
2
3 This sketch connects to a website through a GSM shield. Specifically,
4 this example downloads the URL "http://arduino.cc/" and prints it
5 to the Serial monitor.
6
7 Circuit:
8 * GSM shield attached to an Arduino
9 * SIM card with a data plan
10
11 created 8 Mar 2012
12 by Tom Igoe
13
14 http://arduino.cc/en/Tutorial/GSMExamplesWebClient
15
16 */
17
18// libraries
19#include <GSM.h>
20
21// PIN Number
22#define PINNUMBER ""
23
24// APN data
25#define GPRS_APN       "GPRS_APN" // replace your GPRS APN
26#define GPRS_LOGIN     "login"    // replace with your GPRS login
27#define GPRS_PASSWORD  "password" // replace with your GPRS password
28
29// initialize the library instance
30GSMClient client;
31GPRS gprs;
32GSM gsmAccess;
33
34// URL, path & port (for example: arduino.cc)
35char server[] = "arduino.cc";
36char path[] = "/";
37int port = 80; // port 80 is the default for HTTP
38
39void setup()
40{
41  // initialize serial communications
42  Serial.begin(9600);
43  Serial.println("Starting Arduino web client.");
44  // connection state
45  boolean notConnected = true;
46
47  // After starting the modem with GSM.begin()
48  // attach the shield to the GPRS network with the APN, login and password
49  while(notConnected)
50  {
51    if((gsmAccess.begin(PINNUMBER)==GSM_READY) &
52        (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD)==GPRS_READY))
53      notConnected = false;
54    else
55    {
56      Serial.println("Not connected");
57      delay(1000);
58    }
59  }
60
61  Serial.println("connecting...");
62
63  // if you get a connection, report back via serial:
64  if (client.connect(server, port))
65  {
66    Serial.println("connected");
67    // Make a HTTP request:
68    client.print("GET ");
69    client.print(path);
70    client.println(" HTTP/1.0");
71    client.println();
72  }
73  else
74  {
75    // if you didn't get a connection to the server:
76    Serial.println("connection failed");
77  }
78}
79
80void loop()
81{
82  // if there are incoming bytes available
83  // from the server, read them and print them:
84  if (client.available())
85  {
86    char c = client.read();
87    Serial.print(c);
88  }
89
90  // if the server's disconnected, stop the client:
91  if (!client.available() && !client.connected())
92  {
93    Serial.println();
94    Serial.println("disconnecting.");
95    client.stop();
96
97    // do nothing forevermore:
98    for(;;)
99      ;
100  }
101}

read()

Description

Read the next byte received from the server the client is connected to (after the last call to read()).

read() inherits from the Stream utility class.

Syntax

1client.read()

Parameters

none

Returns

int - The next byte (or character), or -1 if none is available.

Example

1Web client
2
3 This sketch connects to a website through a GSM shield. Specifically,
4 this example downloads the URL "http://arduino.cc/" and prints it
5 to the Serial monitor.
6
7 Circuit:
8 * GSM shield attached to an Arduino
9 * SIM card with a data plan
10
11 created 8 Mar 2012
12 by Tom Igoe
13
14 http://arduino.cc/en/Tutorial/GSMExamplesWebClient
15
16 */
17
18// libraries
19#include <GSM.h>
20
21// PIN Number
22#define PINNUMBER ""
23
24// APN data
25#define GPRS_APN       "GPRS_APN" // replace your GPRS APN
26#define GPRS_LOGIN     "login"    // replace with your GPRS login
27#define GPRS_PASSWORD  "password" // replace with your GPRS password
28
29// initialize the library instance
30GSMClient client;
31GPRS gprs;
32GSM gsmAccess;
33
34// URL, path & port (for example: arduino.cc)
35char server[] = "arduino.cc";
36char path[] = "/";
37int port = 80; // port 80 is the default for HTTP
38
39void setup()
40{
41  // initialize serial communications
42  Serial.begin(9600);
43  Serial.println("Starting Arduino web client.");
44  // connection state
45  boolean notConnected = true;
46
47  // After starting the modem with GSM.begin()
48  // attach the shield to the GPRS network with the APN, login and password
49  while(notConnected)
50  {
51    if((gsmAccess.begin(PINNUMBER)==GSM_READY) &
52        (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD)==GPRS_READY))
53      notConnected = false;
54    else
55    {
56      Serial.println("Not connected");
57      delay(1000);
58    }
59  }
60
61  Serial.println("connecting...");
62
63  // if you get a connection, report back via serial:
64  if (client.connect(server, port))
65  {
66    Serial.println("connected");
67    // Make a HTTP request:
68    client.print("GET ");
69    client.print(path);
70    client.println(" HTTP/1.0");
71    client.println();
72  }
73  else
74  {
75    // if you didn't get a connection to the server:
76    Serial.println("connection failed");
77  }
78}
79
80void loop()
81{
82  // if there are incoming bytes available
83  // from the server, read them and print them:
84  if (client.available())
85  {
86    char c = client.read();
87    Serial.print(c);
88  }
89
90  // if the server's disconnected, stop the client:
91  if (!client.available() && !client.connected())
92  {
93    Serial.println();
94    Serial.println("disconnecting.");
95    client.stop();
96
97    // do nothing forevermore:
98    for(;;)
99      ;
100  }
101}

available()

Description

Returns the number of bytes available for reading (that is, the amount of data that has been written to the client by the server it is connected to).

available() inherits from the Stream utility class.

Syntax

1client.available()

Parameters

none

Returns

The number of bytes available.

Example

1Web client
2
3 This sketch connects to a website through a GSM shield. Specifically,
4 this example downloads the URL "http://arduino.cc/" and prints it
5 to the Serial monitor.
6
7 Circuit:
8 * GSM shield attached to an Arduino
9 * SIM card with a data plan
10
11 created 8 Mar 2012
12 by Tom Igoe
13
14 http://arduino.cc/en/Tutorial/GSMExamplesWebClient
15
16 */
17
18// libraries
19#include <GSM.h>
20
21// PIN Number
22#define PINNUMBER ""
23
24// APN data
25#define GPRS_APN       "GPRS_APN" // replace your GPRS APN
26#define GPRS_LOGIN     "login"    // replace with your GPRS login
27#define GPRS_PASSWORD  "password" // replace with your GPRS password
28
29// initialize the library instance
30GSMClient client;
31GPRS gprs;
32GSM gsmAccess;
33
34// URL, path & port (for example: arduino.cc)
35char server[] = "arduino.cc";
36char path[] = "/";
37int port = 80; // port 80 is the default for HTTP
38
39void setup()
40{
41  // initialize serial communications
42  Serial.begin(9600);
43  Serial.println("Starting Arduino web client.");
44  // connection state
45  boolean notConnected = true;
46
47  // After starting the modem with GSM.begin()
48  // attach the shield to the GPRS network with the APN, login and password
49  while(notConnected)
50  {
51    if((gsmAccess.begin(PINNUMBER)==GSM_READY) &
52        (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD)==GPRS_READY))
53      notConnected = false;
54    else
55    {
56      Serial.println("Not connected");
57      delay(1000);
58    }
59  }
60
61  Serial.println("connecting...");
62
63  // if you get a connection, report back via serial:
64  if (client.connect(server, port))
65  {
66    Serial.println("connected");
67    // Make a HTTP request:
68    client.print("GET ");
69    client.print(path);
70    client.println(" HTTP/1.0");
71    client.println();
72  }
73  else
74  {
75    // if you didn't get a connection to the server:
76    Serial.println("connection failed");
77  }
78}
79
80void loop()
81{
82  // if there are incoming bytes available
83  // from the server, read them and print them:
84  if (client.available())
85  {
86    char c = client.read();
87    Serial.print(c);
88  }
89
90  // if the server's disconnected, stop the client:
91  if (!client.available() && !client.connected())
92  {
93    Serial.println();
94    Serial.println("disconnecting.");
95    client.stop();
96
97    // do nothing forevermore:
98    for(;;)
99      ;
100  }
101}

peek()

Description

Returns the next byte (character) of an incoming message removing it from the message. That is, successive calls to peek() will return the same character, as will the next call to read(). peek() inherits from the Stream utility class.

Syntax

1client.peek()

Parameters

none

Returns

int - the next byte in an incoming message.

flush()

Description

Discards any bytes that have been written to the client but not yet read.

flush() inherits from the Stream utility class.

Syntax

1client.flush()

Parameters

none

Returns

none

stop()

Description

Disconnects from the server

Syntax

1client.stop()

Parameters

none

Returns

none

Example

1Web client
2
3 This sketch connects to a website through a GSM shield. Specifically,
4 this example downloads the URL "http://arduino.cc/" and prints it
5 to the Serial monitor.
6
7 Circuit:
8 * GSM shield attached to an Arduino
9 * SIM card with a data plan
10
11 created 8 Mar 2012
12 by Tom Igoe
13
14 http://arduino.cc/en/Tutorial/GSMExamplesWebClient
15
16 */
17
18// libraries
19#include <GSM.h>
20
21// PIN Number
22#define PINNUMBER ""
23
24// APN data
25#define GPRS_APN       "GPRS_APN" // replace your GPRS APN
26#define GPRS_LOGIN     "login"    // replace with your GPRS login
27#define GPRS_PASSWORD  "password" // replace with your GPRS password
28
29// initialize the library instance
30GSMClient client;
31GPRS gprs;
32GSM gsmAccess;
33
34// URL, path & port (for example: arduino.cc)
35char server[] = "arduino.cc";
36char path[] = "/";
37int port = 80; // port 80 is the default for HTTP
38
39void setup()
40{
41  // initialize serial communications
42  Serial.begin(9600);
43  Serial.println("Starting Arduino web client.");
44  // connection state
45  boolean notConnected = true;
46
47  // After starting the modem with GSM.begin()
48  // attach the shield to the GPRS network with the APN, login and password
49  while(notConnected)
50  {
51    if((gsmAccess.begin(PINNUMBER)==GSM_READY) &
52        (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD)==GPRS_READY))
53      notConnected = false;
54    else
55    {
56      Serial.println("Not connected");
57      delay(1000);
58    }
59  }
60
61  Serial.println("connecting...");
62
63  // if you get a connection, report back via serial:
64  if (client.connect(server, port))
65  {
66    Serial.println("connected");
67    // Make a HTTP request:
68    client.print("GET ");
69    client.print(path);
70    client.println(" HTTP/1.0");
71    client.println();
72  }
73  else
74  {
75    // if you didn't get a connection to the server:
76    Serial.println("connection failed");
77  }
78}
79
80void loop()
81{
82  // if there are incoming bytes available
83  // from the server, read them and print them:
84  if (client.available())
85  {
86    char c = client.read();
87    Serial.print(c);
88  }
89
90  // if the server's disconnected, stop the client:
91  if (!client.available() && !client.connected())
92  {
93    Serial.println();
94    Serial.println("disconnecting.");
95    client.stop();
96
97    // do nothing forevermore:
98    for(;;)
99      ;
100  }
101}

GSMServer class

Server

Description

Server is the base class for all GPRS server based calls. It is not called directly, but invoked whenever you use a function that relies on it.

Syntax

1GSMServer server(port);

Parameters

port: int, the port the server will accept connections on. The default web port is 80.

ready()

Description

Get last command status to the server

Syntax

1server.ready()

Parameters

none

Returns

int - 0 if last command is still executing, 1 if success, >1 if an error.

beginWrite()

Description

Begins writing to connected clients.

Syntax

1server.beginWrite()

Parameters

none

Returns

none

write()

Description

Write data to all the clients connected to a server.

Syntax

1server.write(data)
2server.write(buffer)
3server.write(buffer, size)

Parameters

data: the value to write (byte or char)
buffer : an array of data (byte or char) to write
size : size of the buffer to write (byte)

Returns

byte - write() returns the number of bytes written. It is not necessary to read this.

endWrite()

Description

Tells the server to stop writing to connected clients.

Syntax

1server.endWrite()

Parameters

none

Returns

none

read()

Description

Read the next byte received from an attached client (after the last call to read()).

read() inherits from the Stream utility class.

Syntax

1server.read()

Parameters

none

Returns

int - The next byte (or character), or -1 if none is available.

available()

Description

Listens for incoming clients

Syntax

1server.available()

Parameters

none

Returns

int : the number of connected clients

stop()

Description

Tells the server to stop listening for incoming connections.

Syntax

1server.stop()

Parameters

none

Returns

none

GSMModem class

GSMModem Constructor

Description

GSMModem is the base class for calls that have specific diagnostic functionality with the modem. It is not called directly, but invoked whenever you use a function that relies on it.

begin()

Description

Checks the modem status, and restarts it. Call this before GSMModem.getIMEI().

Syntax

1modem.begin()

Parameters

none

Returns

int : returns 1 if modem is OK, otherwise returns an error.

getIMEI()

Description

Retrieves the modem's IMEI number. Call this after GSMModem.begin().

Syntax

1modem.getIMEI()

Parameters

none

Returns

String : the modem's IMEI number

Example

1#include <GSM.h>
2
3// modem verification object
4GSMModem modem;
5
6// IMEI variable
7String IMEI = "";
8
9void setup()
10{
11  // initialize serial communications
12  Serial.begin(9600);
13
14  // start modem test (reset and check response)
15  Serial.print("Starting modem test...");
16  if(modem.begin())
17    Serial.println("modem.begin() succeeded");
18  else
19    Serial.println("ERROR, no modem answer.");
20}
21
22void loop()
23{
24  // get modem IMEI
25  Serial.print("Checking IMEI...");
26  IMEI = modem.getIMEI();
27
28  // check IMEI response
29  if(IMEI != NULL)
30  {
31    // show IMEI in serial monitor
32    Serial.println("Modem's IMEI: " + IMEI);
33    // reset modem to check booting:
34    Serial.print("Resetting modem...");
35    modem.begin();
36    // get and check IMEI one more time
37    if(modem.getIMEI() != NULL)
38    {
39      Serial.println("Modem is functioning properly");
40    }
41    else
42    {
43      Serial.println("Error: getIMEI() failed after modem.begin()");
44    }
45  }
46  else
47  {
48    Serial.println("Error: Could not get IMEI");
49  }
50  // do nothing:
51  while(true);
52}

GSMScanner class

GSMScanner Constructor

Description

GSMScanner is the base class for calls that have specific diagnostic functionality relating to scanning for available networks. It is not called directly, but invoked whenever you use a function that relies on it.

begin()

Description

Resets modem hardware.

Syntax

1scanner.begin()

Parameters

none

Returns

int : returns 1 if modem is OK, otherwise returns an error.

getCurrentCarrier()

Description

Gets and returns the name of the current network carrier.

Syntax

1scanner.getCurrentCarrier()

Parameters

none

Returns

String : name of the current network carrier

getSignalStrength()

Description

Gets and returns the strength of the signal of the network the modem is attached to.

Syntax

1scanner.getSignalStrength()

Parameters

none

Returns

String : signal strength in 0-31 scale. 31 means power > 51dBm. 99=not detectable

readNetworks()

Description

Searches for available carriers, and returns a list of them.

Syntax

1scanner.readNetworks()

Parameters

none

Returns

String : A string with list of networks available

GSMPIN class

GSMPIN constructor

Description

GSMPIN is the base class for all GSM based functions that deal with interacting with the PIN on the SIM card.

begin()

Description

Checks the modem status, and restarts it.

Syntax

1GSMPIN.begin()

Parameters

none

Returns

int : returns 1 if modem is OK, otherwise returns an error.

isPIN()

Description

Checks the SIM card to see if it is locked with a PIN.

Syntax

1pin.isPIN()

Parameters

none

Returns

int : 0 if PIN lock is off, 1 if PIN lock is on, -1 if PUK lock is on, -2 if error exists.

checkPIN()

Description

Queries the SIM card with a PIN number to see if it is valid.

Syntax

1pin.checkPIN(PIN)

Parameters

PIN : String with the PIN number to check

Returns

int : Returns 0 if the PIN is valid, returns -1 if it is not.

checkPUK()

Description

Check the SIM if PUK code is correct and establish new PIN code.

Syntax

1pin.checkPUK(puk, pin)

Parameters

puk : String with the PUK number to check -pin : String with the PIN number to check

Returns

int : Returns 0 if successful, -1 if it is not.

changePIN()

Description

Changes the PIN number of a SIM, after verifying the existing one.

Syntax

1pin.changePIN(oldPIN, newPIN)

Parameters

oldPIN : String with the existing PIN number
newPIN : String with the desired PIN number

Returns

none

switchPIN()

Description

Change PIN lock status.

Syntax

1pin.switchPIN(pin)

Parameters

pin : String with the existing PIN number

Returns

none

checkReg()

Description

Check if modem was registered in GSM/GPRS network

Syntax

1pin.checkReg()

Parameters

none

Returns

int : 0 if modem was registered, 1 if modem was registered in roaming, -1 if error exists

getPinUsed()

Description

Check if PIN lock is used.

Syntax

1pin.getPinUsed()

Parameters

none

Returns

boolean : TRUE id locked, FALSE if not

setPinUsed()

Description

Set PIN lock status.

Syntax

1pin.setPinUsed(used)

Parameters

used : boolean, TRUE to lock the PIN, FALSE to unlock.

Returns

none

GSMBand class

GSMBand Constructor

Description

GSMBand is the base class for calls that have specific diagnostic functionality relating to the bands the modem can connect to. It is not called directly, but invoked whenever you use a function that relies on it.

begin()

Description

Checks the modem status, and restarts it.

Syntax

1band.begin()

Parameters

none

Returns

int : returns 1 if modem is OK, otherwise returns an error.

getBand()

Description

Gets and returns the frequency band the modem is currently connected to. Check http://www.worldtimezone.com/gsm.html for general GSM band information. Typical regional configurations are :

Europe, Africa, Middle East: E-GSM(900)+DCS(1800)
USA, Canada, South America: GSM(850)+PCS(1900)
Mexico: PCS(1900)
Brazil: GSM(850)+E-GSM(900)+DCS(1800)+PCS(1900)

Syntax

1band.getBand()

Parameters

none

Returns

String : name of the frequency band the modem connects to

GSM_MODE_UNDEFINED
GSM_MODE_EGSM
GSM_MODE_DCS
GSM_MODE_PCS
GSM_MODE_EGSM_DCS
GSM_MODE_GSM850_PCS
GSM_MODE_GSM850_EGSM_DCS_PCS

setBand()

Description

Sets the frequency band the modem connects to. Check http://www.worldtimezone.com/gsm.html for general GSM band information. Typical regional configurations are :

Europe, Africa, Middle East: E-GSM(900)+DCS(1800)
USA, Canada, South America: GSM(850)+PCS(1900)
Mexico: PCS(1900)
Brazil: GSM(850)+E-GSM(900)+DCS(1800)+PCS(1900)

Syntax

1band.setBand(type)

Parameters

type : String identifying what frequency band the modem should connect to :

GSM_MODE_UNDEFINED
GSM_MODE_EGSM
GSM_MODE_DCS
GSM_MODE_PCS
GSM_MODE_EGSM_DCS
GSM_MODE_GSM850_PCS
GSM_MODE_GSM850_EGSM_DCS_PCS

Returns

boolean : returns true if the process is successful, false if it is not

Suggest changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.

Need support?

Help Center Ask the Arduino Forum Discover Arduino Discord

License

The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.

Boards

Shields

Kits

Other

Archived Libraries

Guides to Retired Products

Library Example

Hacking

GSM Library

Library structure

Ethernet library compatibility

Examples

Tools

GSM class

GSM constructor

Description

Syntax

Parameters

Example

begin()

Description

Syntax

Parameters

Returns

Example

shutdown()

Description

Syntax

Parameters

Returns

Example

GSMVoiceCall class

GSMVoiceCall constructor

Description

getVoiceCallStatus()

Description

Syntax

Parameters

Returns

Example

ready()

Description

Syntax

Parameters

Returns

voiceCall()

Description

Syntax

Parameters

Returns

Example

answerCall()

Description

Syntax

Parameters

Returns

Example

hangCall()

Description

Syntax

Parameters

Returns

Example

retrieveCallingNumber()

Description

Syntax

Parameters

Returns

Example

GSM_SMS class

GSM_SMS constructor

Description

beginSMS()

Description

Syntax

Parameters

Returns

Example

ready()

Description

`GSM constructor`

`begin()`

`shutdown()`

`GSMVoiceCall constructor`

`getVoiceCallStatus()`

`ready()`

`voiceCall()`

`answerCall()`

`hangCall()`

`retrieveCallingNumber()`

`GSM_SMS constructor`

`beginSMS()`

`ready()`

`endSMS()`

`available()`

`remoteNumber()`

`read()`

`write()`

`print()`

`peek()`

`flush()`

`GPRS constructor`

`attachGPRS()`

`Client`

`ready()`

`connect()`