Getting Started with the Arduino GSM

Shield
The first steps to setting up the Arduino GSM Shield
The Arduino GSM shield allows an Arduino board to connect to the internet,
send and receive SMS, and make voice calls using the GSM library.

The shield will work with the Arduino Uno out of the box. The shield will
work with the Mega, Mega ADK, Yun, and Leonardo boards with a minor
modification. The Due is not supported at this time.

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

What is GSM

GSM is an international standard for mobile telephones. It is an acronym

that stands for Global System for Mobile Communications. It is also
sometimes referred to as 2G, as it is a second-generation cellular network.

To use GPRS for internet access, and for the Arduino to request or serve
webpages, you need to obtain the Access Point Name (APN) and a
username/password from the network operator. See the information in
Connecting to the Internet for more information about using the data
capabilities of the shield.

Among other things, GSM supports outgoing and incoming voice calls,
Simple Message System (SMS or text messaging), and data communication
(via GPRS).

The Arduino GSM shield is a GSM modem. From the mobile operator
perspective, the Arduino GSM shield looks just like a mobile phone. From
the Arduino perspective, the Arduino GSM shield looks just like a modem.

What is GPRS
GPRS is a packet switching technology that stands for General Packet Radio
Service. It can provide idealized data rates between 56-114 kbit per second.

A number of technologies such as SMS rely on GPRS to function. With the

GSM shield, it is also possible to leverage the data communication to access
the internet. Similar to the Ethernet and WiFi libraries, the GSM library
allows the Arduino to act as a client or server, using http calls to send and
receive web pages.

Network operator requirements

To access a network, you must have a subscription with a mobile phone

operator (either prepaid or contract), a GSM compliant device like the GSM
shield or mobile phone, and a Subscriber Identity Module (SIM) card. The
network operator provides the SIM card, which contains information like the
mobile number, and can store limited amounts of contacts and SMS
messages.

To use GPRS for internet access, and for the Arduino to request or serve
webpages, you need to obtain the Access Point Name (APN) and a
username/password from the network operator. See the information
in Connecting to the Internet for more information about using the data
capabilities of the shield.

SIM cards

In addition to the GSM shield and an Arduino, you need a SIM card. The SIM
represents a contract with a communications provider. The communications
provider selling you the SIM has to either provide GSM coverage where you
are, or have a roaming agreement with a company providing GSM coverage
in your location.

It's common for SIM cards to have a four-digit PIN number associated with
them for security purposes. Keep note of this number, as it's necessary for
connecting to a network. If you lose the PIN associated with your SIM card,
you may need to contact your network operator to retrieve it. Some SIM
cards become locked if an incorrect PIN is entered too many times. If you're unsure of
what the PIN is, look at the documentation that came with your SIM.

Using a PUK (PIN Unlock Code), it is possible to reset a lost PIN with the
GSM shield and an Arduino. The PUK number will come with your SIM card
documentation.

Look at the PIN Management example in the "tools" folder, bundled with the
GSM library for an example of how to manage your PIN number with the
PUK.

There are a few different sizes of SIM cards; the GSM shield accepts cards in
the mini-SIM format (25mm long and 15mm wide).

Notes on the Telefonica/Movilforum SIM included with the shield

The GSM shield comes bundled with a SIM from Telefonica/Movilforum that
will work well for developing machine to machine (M2M) applications. It is
not necessary to use this specific card with the shield. You may use any SIM
that works on a network in your area.

The Movilforum SIM card includes a roaming plan. It can be used on any
supported GSM network. There is coverage throughout the Americas and
Europe for this SIM, check the Movilforum service availability page for
specific countries that have supported networks.

Activation of the SIM is handled by Movilforum. Detailed instructions on how

to register and activate your SIM online and add credit are included on
a small pamphlet that comes with your shield. The SIM must be inserted
into a powered GSM shield that is mounted on an Arduino for activation.

These SIM card come without a PIN, but it is possible to set one using the
GSM library's GSMPIN class.

You cannot use the included SIM to place or receive voice calls.
You can only place and receive SMS with other SIMs on the Movilforum
network.

It's not possible to create a server that accepts incoming requests from the
public internet. However, the Movilforum SIM will accept incoming requests
from other SIM cards on the Movilforum network.

For using the voice, and other functions of the shield, you'll need to find a
different network provider and SIM. Operators will have different policies for
their SIM cards, check with them directly to determine what types of
connections are supported.

Connecting the Shield

If you are using an Arduino Uno, follow the instructions below. If you are
using an Arduino Mega, Mega ADK, Yun, or Leonardo, you must follow these
instructions. The GSM shield is not currently supported on the Due.

To use the shield, you'll need to insert a SIM card into the holder. Slide the
metal bracket away from the edge of the shield and lift the cradle up.

Insert the SIM in the plastic holder so the metal contacts are facing the
shield, with the notch of the card at the top of the bracket.
Slide the SIM all the way into the bracket

Push the SIM to the board and slide the metal bracket towards the edge of
the shield to lock it in place.
Once the SIM is inserted, mount it on top of an Arduino board.
To upload sketches to the board, connect it to your computer with a USB
cable and upload your sketch with the Arduino IDE. Once the sketch has
been uploaded, you can disconnect the board from your computer and
power it with an external power supply.

Digital pins 2, 3 and 7 are reserved for communication between the Arduino
and modem and cannot be used by your sketches. Communication between
the moden and Arduino is handled by the Software Serial library on pins 2
and 3. Pin 7 is used for the modem reset.

When the yellow status LED turns on, it means the modem is powered, and
you can try connecting to the network.
Developer versions of the GSM shield required you to press press
the Power button on the shield for a few moments to turn the modem on. If
you have an early version of the shield, and it does not turn on
automatically, you can solder a jumper to the CTRL/D7 pad on the reverse
side of the board, and it will turn on when an attached Arduino receives
power.

The shield should work in any area with GSM coverage. Before buying the
shield please verify that there is this kind of coverage where you plan to
use it.

GSM Library

The GSM library handles communication between Arduino and the GSM
shield. The majority of functions are for managing data, voice, and SMS
communication. There are also a number of utilities for managing
information about the modem and the SIM card's PIN. See the library
reference pages for more information and a complete set of examples.
Testing the modem and network connection

This sketch will check the modem's IMEI number. This number is unique to
each modem, and is used to identify valid devices that can connect to a
GSM network. Once the number has been read from the modem, the
Arduino will print out the network carrier it is connected to, and the signal
strength of the network over the serial port.

COPY

1// import the GSM library

2#include <GSM.h>

4// PIN Number

5#define PINNUMBER ""

7// initialize the library instance

9GSM gsmAccess(true); // include a 'true' parameter for debug enabled

10

11GSMScanner scannerNetworks;

12

13GSMModem modemTest;

14

15// Save data variables

16

17String IMEI = "";

18

19// serial monitor result messages

20
21String errortext = "ERROR";

22

23void setup()

24{

25

26 // initialize serial communications

27

28 Serial.begin(9600);

29

30 Serial.println("GSM networks scanner");

31

32 scannerNetworks.begin();

33

34 // connection state

35

36 boolean notConnected = true;

37

38 // Start GSM shield

39

40 // If your SIM has PIN, pass it as a parameter of begin() in quotes

41

42 while(notConnected)

43

44 {

45

46 if(gsmAccess.begin(PINNUMBER)==GSM_READY)

47
48 notConnected = false;

49

50 else

51

52 {

53

54 Serial.println("Not connected");

55

56 delay(1000);

57

58 }

59

60 }

61

62 // get modem parameters

63

64 // IMEI, modem unique identifier

65

66 Serial.print("Modem IMEI: ");

67

68 IMEI = modemTest.getIMEI();

69

70 IMEI.replace("\n","");

71

72 if(IMEI != NULL)

73

74 Serial.println(IMEI);
75

76 // currently connected carrier

77

78 Serial.print("Current carrier: ");

79

80 Serial.println(scannerNetworks.getCurrentCarrier());

81

82 // returns strength and ber

83

84 // signal strength in 0-31 scale. 31 means power > 51dBm

85

86 // BER is the Bit Error Rate. 0-7 scale. 99=not detectable

87

88 Serial.print("Signal Strength: ");

89

90 Serial.print(scannerNetworks.getSignalStrength());

91

92 Serial.println(" [0-31]");

93}

94

95void loop()

96{

97

98 // scan for existing networks, displays a list of networks

99

100 Serial.println("Scanning available networks. May take some seconds.");

101
102 Serial.println(scannerNetworks.readNetworks());

103

104 // currently connected carrier

105

106 Serial.print("Current carrier: ");

107

108 Serial.println(scannerNetworks.getCurrentCarrier());

109

110 // returns strength and ber

111

112 // signal strength in 0-31 scale. 31 means power > 51dBm

113

114 // BER is the Bit Error Rate. 0-7 scale. 99=not detectable

115

116 Serial.print("Signal Strength: ");

117

118 Serial.print(scannerNetworks.getSignalStrength());

119

120 Serial.println(" [0-31]");

121

122}

Sending a SMS message

Once you have connected to your network with the sketch above, you can
test some of the other functionality of the board. This sketch will connect to
a GSM network and send a SMS message to a phone number of your
choosing.

COPY
1#include <GSM.h>

3#define PINNUMBER ""

5// initialize the library instance

7GSM gsmAccess; // include a 'true' parameter for debug enabled

9GSM_SMS sms;

10

11// char array of the telephone number to send SMS

12// change the number 1-212-555-1212 to a number

13// you have access to

14char remoteNumber[20]= "12125551212";

15

16// char array of the message

17char txtMsg[200]="Test";

18

19void setup()

20{

21

22 // initialize serial communications

23

24 Serial.begin(9600);

25

26 Serial.println("SMS Messages Sender");

27
28 // connection state

29

30 boolean notConnected = true;

31

32 // Start GSM shield

33

34 // If your SIM has PIN, pass it as a parameter of begin() in quotes

35

36 while(notConnected)

37

38 {

39

40 if(gsmAccess.begin(PINNUMBER)==GSM_READY)

41

42 notConnected = false;

43

44 else

45

46 {

47

48 Serial.println("Not connected");

49

50 delay(1000);

51

52 }

53

54 }
55

56 Serial.println("GSM initialized");

57

58 sendSMS();

59}

60

61void loop()

62{

63// nothing to see here

64}

65

66void sendSMS(){

67

68 Serial.print("Message to mobile number: ");

69

70 Serial.println(remoteNumber);

71

72 // sms text

73

74 Serial.println("SENDING");

75

76 Serial.println();

77

78 Serial.println("Message:");

79

80 Serial.println(txtMsg);

81
82 // send the message

83

84 sms.beginSMS(remoteNumber);

85

86 sms.print(txtMsg);

87

88 sms.endSMS();

89

90 Serial.println("\nCOMPLETE!\n");

91}

Connecting to the internet

In addition to the SIM card and a data plan, you will need some additional
information from your cellular provider to connect to the internet. 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 Movilforum APN is sm2ms.movilforum.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.

The sketch below will connect to arduino.cc/latest.txt and print out its
contents.

NB: Some network operators block incoming IP traffic. You should be able to run
client functions, such as the sketch below, with no issues.
COPY

1// include the GSM library

2#include <GSM.h>
3

4// PIN number if necessary

5#define PINNUMBER ""

7// APN information obrained from your network provider

8#define GPRS_APN "GPRS_APN" // replace with your GPRS APN

9#define GPRS_LOGIN "login" // replace with your GPRS login

10#define GPRS_PASSWORD "password" // replace with your GPRS password

11

12// initialize the library instances

13

14GSMClient client;

15

16GPRS gprs;

17

18GSM gsmAccess;

19

20// This example downloads the URL "http://arduino.cc/latest.txt"

21

22char server[] = "arduino.cc"; // the base URL

23char path[] = "/latest.txt"; // the path

24int port = 80; // the port, 80 for HTTP

25

26void setup()

27{

28

29 // initialize serial communications

30

31 Serial.begin(9600);

32

33 Serial.println("Starting Arduino web client.");

34

35 // connection state

36

37 boolean notConnected = true;

38

39 // Start GSM shield

40

41 // pass the PIN of your SIM as a parameter of gsmAccess.begin()

42

43 while(notConnected)

44

45 {

46

47 if((gsmAccess.begin(PINNUMBER)==GSM_READY) &

48

49 (gprs.attachGPRS(GPRS_APN, GPRS_LOGIN, GPRS_PASSWORD)==GPRS_READY))

50

51 notConnected = false;

52

53 else

54

55 {

56
57 Serial.println("Not connected");

58

59 delay(1000);

60

61 }

62

63 }

64

65 Serial.println("connecting...");

66

67 // if you get a connection, report back via serial:

68

69 if (client.connect(server, port))

70

71 {

72

73 Serial.println("connected");

74

75 // Make a HTTP request:

76

77 client.print("GET ");

78

79 client.print(path);

80

81 client.println(" HTTP/1.0");

82

83 client.println();
84

85 }

86

87 else

88

89 {

90

91 // if you didn't get a connection to the server:

92

93 Serial.println("connection failed");

94

95 }

96}

97

98void loop()

99{

100

101 // if there are incoming bytes available

102

103 // from the server, read them and print them:

104

105 if (client.available())

106

107 {

108

109 char c = client.read();

110
111 Serial.print(c);

112

113 }

114

115 // if the server's disconnected, stop the client:

116

117 if (!client.available() && !client.connected())

118

119 {

120

121 Serial.println();

122

123 Serial.println("disconnecting.");

124

125 client.stop();

126

127 // do nothing forevermore:

128

129 for(;;)

130

131 ;

132

133 }

134}

Making voice calls

Through the modem, it is possible to make voice calls. In order to speak to

and hear the other party, you will need to add a speaker and microphone.
On the underside of the shield, there are through-holes labeled M1P and
M1N. These are the positive and negative voice input pins for a microphone.
The through-holes labeled S1P and S1N are the positive and negative voice
output pins, to which you need to connect a speaker.

On page 43 of the modem documentation, there is an example voice and

sound circuit that will connect to an earphone:
The following sketch allows you to place a voice call. Using the serial
monitor, you can enter the remote phone number and terminate the call.
When you see the READY message, type a phone number. Make sure the
serial monitor is set to send a just newline when you press return.

COPY

1#include <GSM.h>

3// PIN Number

4#define PINNUMBER ""

6// initialize the library instance

8GSM gsmAccess; // include a 'true' parameter for debug enabled

10GSMVoiceCall vcs;

11

12String remoteNumber = ""; // the number you will call

13char charbuffer[20];

14

15void setup()

16{

17

18 // initialize serial communications

19

20 Serial.begin(9600);

21

22 Serial.println("Make Voice Call");

23

24 // connection state
25

26 boolean notConnected = true;

27

28 // Start GSM shield

29

30 // If your SIM has PIN, pass it as a parameter of begin() in quotes

31

32 while(notConnected)

33

34 {

35

36 if(gsmAccess.begin(PINNUMBER)==GSM_READY)

37

38 notConnected = false;

39

40 else

41

42 {

43

44 Serial.println("Not connected");

45

46 delay(1000);

47

48 }

49

50 }

51
52 Serial.println("GSM initialized.");

53

54 Serial.println("Enter phone number to call.");

55

56}

57

58void loop()

59{

60

61 // add any incoming characters to the String:

62

63 while (Serial.available() > 0)

64

65 {

66

67 char inChar = Serial.read();

68

69 // if it's a newline, that means you should make the call:

70

71 if (inChar == '\n')

72

73 {

74

75 // make sure the phone number is not too long:

76

77 if (remoteNumber.length() < 20)

78
79 {

80

81 // show the number you're calling:

82

83 Serial.print("Calling to : ");

84

85 Serial.println(remoteNumber);

86

87 Serial.println();

88

89 // Call the remote number

90

91 remoteNumber.toCharArray(charbuffer, 20);

92

93 // Check if the receiving end has picked up the call

94

95 if(vcs.voiceCall(charbuffer))

96

97 {

98

99 Serial.println("Call Established. Enter line to end");

100

101 // Wait for some input from the line

102

103 while(Serial.read()!='\n' && (vcs.getvoiceCallStatus()==TALKING));

104

105 // And hang up

106

107 vcs.hangCall();

108

109 }

110

111 Serial.println("Call Finished");

112

113 remoteNumber="";

114

115 Serial.println("Enter phone number to call.");

116

117 }

118

119 else

120

121 {

122

123 Serial.println("That's too long for a phone number. I'm forgetting it");

124

125 remoteNumber = "";

126

127 }

128

129 }

130

131 else

132
133 {

134

135 // add the latest character to the message to send:

136

137 if(inChar!='\r')

138

139 remoteNumber += inChar;

140

141 }

142

143 }

144}

Connecting to Yún, Mega & Leonardo

The GSM shield communicates with an attached Arduino through
the Software Serial library . By default, this communication uses digital pins
2 and 3. On the Uno this works without modification, but to use
the Leonardo, Yun, or Mega boards, some slight changes are required.

The GSM_TX pin, pin 2 on the shield, sends information to the Arduino. The
Arduino relies on an interrupt on this pin to know when information is
available to read. On the Uno, this interrupt capability is on pin 2. The
Leonardo, Yun, and Mega have interrupt capabilities on different pins.

You do not need to change any code to program the shield for use with the
Leonardo, Yun, or Mega, as the library will change the Arduino's RX pin
automatically depending on the board selected in the "Tools" menu of the
IDE. You do, however, need to re-route the GSM_TX data to the appropriate
pin on the Arduino.

Arduino Leonardo and Arduino Yun

The GSM library uses digital pin 8 to communicate with the Leonardo or the
Yun. Thus, you need to route the signal from pin 2 of the GSM shield to pin
8 of the Arduino, and at the same time prevent this signal from connecting
to pin 2 of the Arduino. The following two steps accomplish this:

On the GSM shield, connect a jumper wire between digital pins 2 and 8. This
routes the signal from pin 2 of the GSM shield to pin 8 of the Arduino.

To prevent this signal from interfering with or being interfered by pin 2 of

the Arduino, bend the male header attached to pin 2 on the GSM shield to
the side so it does not connect to the Leonardo or Yun.

Arduino Mega

The GSM library uses digital pin 10 to communicate with the Mega. Thus,
you need to route the signal from pin 2 of the GSM shield to pin 10 of the
Arduino, and at the same time prevent this signal from connecting to pin 2
of the Arduino. The following two steps accomplish this:

On the GSM shield, connect a jumper wire between digital pins 2 and 10.
This routes the signal from pin 2 of the GSM shield to pin 10 of the Arduino.

To prevent this signal from interfering with or being interfered by pin 2 of

the Arduino, bend the male header attached to pin 2 on the GSM shield to
the side so it does not connect to the Mega.
Next steps

Now that you have tested the basic functionality of the board, see the GSM
library pages for information about the library's API and additional
examples.

The text of the Arduino getting started guide is licensed under a Creative
Commons Attribution-ShareAlike 3.0 License . Code samples in the guide are
released into the public domain.