Introduction: Arduino GSM Shield

Picture of Arduino GSM Shield

This is a very low cost and simple Arduino GSM and GPRS shield. We use the module SIMCom SIM900 . It’s the cheaper module now avalaible in the market. The module is not simple to mount by an hobbyst, so we use the Breakboard TDGGSM_900 that we presented here .

You can buy the GSM module premounted here .

To connect this module to Arduino we make a PCB that include a LM317 some capacitor filter and no more.

The LM317 give to module about 3.9V.
There is a switch to select the way to comunicate with arduino:
- throw serial hardware (pin 0 and 1)
- throw serial software (pin 4 and 5)

Step 1: The GSM Library




This is the GSM_shield library documentation:



Here is a GSM_shield Library intended for GSM Shield by Futura Elettronica (www.futurashop.it).

This Library is derived from Hwkitchen’s GSM Library http://www.hwkitchen.com and include the NewSoftSerial library to comunicate using the pin 4 (RX) and 5 (TX).

You can also use the pin 0 and 1 (RX and TX) but you must disconnect the module to upload the sketch (so it’s not very nice), and you must modify the library.

How install the library for Arduino

After downloading of the GSM_Shield Library unzip the GSM_Shield folder to Arduino

Folder\libraries\ (es. C:\Programs\arduino-0022\libraries\GSM_Shield)

In the GSM_Shield.zip you can find the library to comunicate with gsm module and the file for use the NewSoftSerial.

Basic description

GSM_Shield library is created as standard class with the Gsm_Shield.cpp and Gsm_Shield.h source files. GSM_Shield class is based mainly on the serial communication

between the Arduino board and the GSM module placed on the GSM Shield. There are used standard AT commands for the communication with the GSM Module.

The Current version of library uses blocking version of communication.

It means that the program is blocked until the communication function is finished – so until required data are sent and required answer is received. The Advantage of that blocking approach is that it is easy to

understand the program flow. On the other hand there is also disadvantage that we can’t use the processor resources in the time when the program just waits for the incoming data.

Note: please pay attention to serial comunication mode. With the serial hardware (pin 0 and 1) you can reach the default baudrate of the module SIM900 (115200). But if you use the pin 4 and 5 the NewSoftSerial library can’t support (receive) the baudrate, so you must chose a lower baudrate.

With the command TurnOn(baudrate) you turn on the module and fix the baudrate. e.g. TurnOn(9600);

Methods

There are described important functions for the end user in this document.

The GSM_Shield Library contains also some functions that are used internally

and are not described in the document. It is also possible to use these

functions by the end user of course as they are defined as public but there

is needed to check the library source code with notes.


int LibVer(void)

returns library version in format XYY -it means X.YY (e.g. 100 means vers. 1.00)

Sample: GSM_Shield_LibVer


void TurnOn(baud)

turns on the GSM module in case module is off and sends some initialization AT commands which are possible to send before registration -> InitParam(PARAM_SET_0)

Should be used at the beginning of the sketch in the setup() function.

Set also the module baudrate (Note: if you use the hardware serial, there are no limit to the baudrate, 115200 is possibile. But using the pin 4 and 5 the NewSoftSerial must be use and the baud limit is 57600).

baud value possibile: 4800, 9600, 19200, 38400, 57600, 115200(no use with this library which include NewSoftSerial)

void setup()

{

gsm.TurnOn(9600);

}

Sample: GSM_Shield_LibVer



void InitParam(byte group)

Sends parameters for initialization of GSM module
group: 0 – parameters of group 0 – not necessary to be registered in the GSM

AT&F

1 – parameters of group 1 – it is necessary to be registered

AT+CLIP=1

AT+CMEE=0

AT+CMGF=1

Sample: GSM_Shield_LibVer

void Echo(byte state)
Function to enable or disable echo

Echo(1) enable GSM echo mode

Echo(0) disable GSM echo mode

Sample: GSM_Shield_LibVer


byte CheckRegistration(void)

checks if the GSM module is registered in the GSM net.

This method communicates directly with the GSM module in contrast to the method IsRegistered() which reads the flag from the module_status

(this flag is set inside this method)

must be called regularly at the one place in the main sketch loop

(recommendation repeat time is from 1sec. to 10 sec.)

return valus:

REG_NOT_REGISTERED – not registered

REG_REGISTERED – GSM module is registered

REG_NO_RESPONSE – GSM doesn’t response

REG_COMM_LINE_BUSY – comm line is not free

Sample: GSM_Shield_Reg



byte IsRegistered(void)

returns flag if the GSM module is registered in the GSM net

this method does not communicate directly with the GSM module,

just reads the flag so it is very fast unlike CheckRegistration()

which takes more than 20msec.

it is recommended to use this function everytime it is necessary to use some GSM function which needs GSM module is registered – checking ingoing SMSs, checking calls etc.

return valus:

0 – not registered

>0 – GSM module is registered

Sample: GSM_Shield_Reg



byte CallStatus(void)

checks call status

return values:

CALL_NONE – no call

CALL_INCOM_VOICE – incoming voice call

CALL_ACTIVE_VOICE – active voice call

CALL_NO_RESPONSE – no response

Sample: GSM_Shield_Call



byte CallStatusWithAuth(char *phone_number, byte first_authorized_pos, byte last_authorized_pos)

checks status of call(incoming or active) and makes authorization with specified SIM positions range

parameters and return values:

phone_number: a pointer where the tel. number string of current call will be placed so the space for the phone number string must be reserved

first_authorized_pos: initial SIM phonebook position where the authorization process starts

last_authorized_pos: last SIM phonebook position where the authorization process finishes

Note(important):

================

In case first_authorized_pos=0 and also last_authorized_pos=0 the received incoming phone number is NOT authorized at all, so every incoming is considered as authorized (CALL_INCOM_VOICE_NOT_AUTH is returned)

return:

CALL_NONE – no call activity

CALL_INCOM_VOICE_AUTH – incoming voice – authorized

CALL_INCOM_VOICE_NOT_AUTH – incoming voice – not authorized

CALL_ACTIVE_VOICE – active voice

CALL_INCOM_DATA_AUTH – incoming data call – authorized

CALL_INCOM_DATA_NOT_AUTH – incoming data call – not authorized

CALL_ACTIVE_DATA – active data call

CALL_NO_RESPONSE – no response to the AT command

CALL_COMM_LINE_BUSY – comm line is not free



void PickUp(void)

picks up the incoming call

Sample: GSM_Shield_Call



void HangUp(void)

hangs up call(incoming or active)

Sample: GSM_Shield_Call



void Call(char *number_string)

calls the specific number

e.g. gsm.Call(“+390123456789″);



void Call(int sim_position)

calls the number stored at the specified SIM position

e.g. gsm.Call(1); // call to the number stored at the 1st SIM position



char SendSMS(char *number_str, char *message_str)

sends SMS to the specific phone number

parameters and return values:

number_str: pointer to the phone number string

message_str: pointer to the SMS text string

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – GSM module has answered “ERROR” string

OK ret val:

———–

0 – SMS was not sent

1 – SMS was sent 9/15

example of use:

gsm.SendSMS(“00XXXYYYYYYYYY”, “SMS text”);



char SendSMS(byte sim_phonebook_position, char *message_str)

sends SMS to the specified SIM phonebook position

parameters and return values:

sim_phonebook_position: SIM phonebook position <1..20>

message_str: pointer to the SMS text string

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – specified position must be > 0

OK ret val:

———–

0 – SMS was not sent

1 – SMS was sent

an example of usage:

GSM gsm;

gsm.SendSMS(1, “SMS text”);



char IsSMSPresent(byte required_status)

finds out if there is present at least one SMS with specified status

if there is new SMS before IsSMSPresent() is executed this SMS has a status UNREAD and then after calling IsSMSPresent() method status of SMS is automatically changed to READ

parameters and return values:

required_status:

SMS_UNREAD – new SMS – not read yet

SMS_READ – already read SMS

SMS_ALL – all stored SMS

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

OK ret val:

———–

0 – there is no SMS with specified status

1..20 – position where SMS is stored

example of use:

char position;

char phone_number[20]; // array for the phone number string

char *sms_text;

position = gsm.IsSMSPresent(SMS_UNREAD);

if (position) { // read new SMS

gsm.GetGSM(position, tel_number, &sms_text);

}



char GetSMS(byte position, char *phone_number, char *SMS_text, byte max_SMS_len)

reads SMS from specified memory(SIM) position

parameters and return values:

position: SMS position <1..20>

phone_number: a pointer where the phone number string of received SMS will be placed

so the space for the phone number string must be reserved – see example

SMS_text : a pointer where SMS text will be placed

max_SMS_len: maximum length of SMS text excluding also string terminating 0×00 character

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – specified position must be > 0

OK ret val:

———–

GETSMS_NO_SMS – no SMS was found at the specified position

GETSMS_UNREAD_SMS – new SMS was found at the specified position

GETSMS_READ_SMS – already read SMS was found at the specified position

GETSMS_OTHER_SMS – other type of SMS was found an example of usage:

GSM gsm;

char position;

char phone_num[20]; // array for the phone number string

char sms_text[100]; // array for the SMS text string

position = gsm.IsSMSPresent(SMS_UNREAD);

if (position) {

// there is new SMS => read it

gsm.GetGSM(position, phone_num, sms_text, 100);

Serial.println(“DEBUG SMS phone number: “, 0);

Serial.println(phone_num, 0);

Serial.println(“\r\n SMS text: “, 0);

Serial.println(sms_text, 1);

}

char GetAuthorizedSMS( byte position, char *phone_number, char *SMS_text, byte max_SMS_len, byte first_authorized_pos, byte last_authorized_pos)

reads SMS from specified memory(SIM) position and makes authorization -

it means SMS phone number is compared with specified SIM phonebook position(s) and in case numbers match GETSMS_AUTH_SMS is returned, otherwise GETSMS_NOT_AUTH_SMS is returned

parameters and return values:

position: SMS position to be read <1..20>

phone_number: a pointer where the tel. number string of received SMS will be placed so the space for the phone number string must be reserved – see example

SMS_text : a pointer where SMS text will be placed

max_SMS_len: maximum length of SMS text excluding terminating 0×00 character

first_authorized_pos: initial SIM phonebook position where the authorization process starts

last_authorized_pos: last SIM phonebook position where the authorization proces finishes

Note(important):

================

In case first_authorized_pos=0 and also last_authorized_pos=0

the received SMS phone number is NOT authorized at all, so every

SMS is considered as authorized (GETSMS_AUTH_SMS is returned)

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – position must be > 0

OK ret val:

———–

GETSMS_NO_SMS – no SMS was found at the specified position

GETSMS_NOT_AUTH_SMS – NOT authorized SMS found at the specified position

GETSMS_AUTH_SMS – authorized SMS found at the specified position

an example of usage:

GSM gsm;

char phone_num[20]; // array for the phone number string 12/15

char sms_text[100]; // array for the SMS text string

// authorize SMS with SIM phonebook positions 1..3

if (GETSMS_AUTH_SMS == gsm.GetAuthorizedSMS(1, phone_num, sms_text, 100, 1, 3)) {

// new authorized SMS was detected at the SMS position 1

Serial.println(“DEBUG SMS phone number: “, 0);

Serial.println(phone_num, 0);

Serial.println(“\r\n SMS text: “, 0);

Serial.println(sms_text, 1);

}

// don’t authorize SMS with SIM phonebook at all

if (GETSMS_AUTH_SMS == gsm.GetAuthorizedSMS(1, phone_num, sms_text, 100, 0, 0)) {

// new SMS was detected at the SMS position 1

// because authorization was not required

// SMS is considered authorized

Serial.println(“DEBUG SMS phone number: “, 0);

Serial.println(phone_num, 0);

Serial.println(“\r\n SMS text: “, 0);

Serial.println(sms_text, 1);

}



char DeleteSMS(byte position)

deletes SMS from specified SMS position

parameters and return values:

position: SMS position <1..20>

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – position must be > 0

OK ret val:

———–

0 – SMS was not deleted

1 – SMS was deleted



char GetPhoneNumber(byte position, char *phone_number)

reads phone number string from specified SIM position

parameters and return values:

position: SMS position <1..20>

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – position must be > 0

phone_number is empty string

OK ret val:

———–

0 – there is no phone number on the position

1 – phone number was found

phone_number is filled by the phone number string finished by 0×00

so it is necessary to define string with at least

15 bytes(including also 0×00 termination character)

an example of usage:

GSM gsm;

char phone_num[20]; // array for the phone number string

if (1 == gsm.GetPhoneNumber(1, phone_num)) {

// valid phone number on SIM pos. #1

// phone number string is copied to the phone_num array

Serial.println(“DEBUG phone number: “, 0);

Serial.println(phone_num, 1);

}

else {

// there is not valid phone number on the SIM pos.#1

Serial.println(“DEBUG there is no phone number”, 1);

}



char WritePhoneNumber(byte position, char *phone_number)

writes phone number string to the specified SIM position

parameters and return values:

position: SMS position <1..20>

phone_number: phone number string for the writing

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – position must be > 0

OK ret val:

———–

0 – phone number was not written

1 – phone number was written 14/15

char DelPhoneNumber(byte position)

del phone number from the specified SIM position

parameters and return values:

position: SIM position <1..20>

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – position must be > 0

OK ret val:

———–

0 – phone number was not deleted

1 – phone number was deleted



char ComparePhoneNumber(byte position, char *phone_number)

compares specified phone number string with phone number stored at the specified SIM position

parameters and return values:

position: SMS position <1..20>

phone_number: phone number string which should be compare

return:

ERROR ret. val:

—————

-1 – comm. line to the GSM module is not free

-2 – GSM module didn’t answer in timeout

-3 – position must be > 0

OK ret val:

———–

0 – phone numbers are different

1 – phone numbers are the same

an example of usage:

if (1 == gsm.ComparePhoneNumber(1, “123456789″)) {

// the phone num. “123456789″ is stored on the SIM pos. #1

// phone number string is copied to the phone_num array

Serial.println(“DEBUG phone numbers are the same”, 1);

}

else {

Serial.println(“DEBUG phone numbers are different”, 1);

}

Download GSM_Shield_Library

Step 2:

Picture of

In this step there are the schematics and PCB.

Step 3: The Sketch

Picture of The Sketch

I wrote some example sketch. You can download them with the library here.
Or visiting my site.

Comments

janamhosein (author)2016-10-30

Hi

I cannot compile sim800l's library with Arduino due,

I guess that the problem is software serial library, too. However, I don't know how to replace this library for arduino due.

please help me.

taifur (author)2015-09-18

Nice work

power000 (author)2015-08-15

Hi , when i try to upload the skech it says "class GSM" has no member names"CallStatus"

what does ti mean?

мткаченко (author)2014-02-24

Which capacitors do you have?

eddevine (author)2013-10-08

What SIM card are you using? The ones I've seen require an expensive plan with a provider

dnicol1 (author)2013-08-19

Hi there. I'm working on a prototype for something and need input on a tech level. Are you intetested?

About This Instructable

164,052views

152favorites

License:

More by technolando:Arduino DDNS (Dynamic DNS) by Open-Electronics.orgArduino GSM shieldSimple Relay Shield for Arduino
Add instructable to: