GSM GPRS Shield for Arduino Uno

For informations and support: http://code.google.com/p/gsm-shield-arduino/ http://www.open-electronics.org/arduino-gsm-shield/ http://www.futurashop.it/

The below functions are always available in the library.

int attachGPRS(char domain, char dom1, char* dom2) establishes a GPRS connection with domain using authentication (if needed) parameters and return values: domain: pointer to a string that contains the domain address of GPRS connection dom1: pointer to the username string (don't use if not needed) dom2: pointer to the password string (don't use if not needed) return: 0 - unable to establish a GPRS connection 1 - connection successfully established

int dettachGPRS() disconnects the GPRS connection

int connectTCP(const char* server, int port) starts a socket connection to the server at specific port parameters and return values: server: pointer to the server address string, it can be the IP or normal address port: port used to establish a connection e.g. gsm.connectTCP("www.google.it",80) e.g. gsm.connectTCP("74.125.39.106",80) return: 0 - unable to start the TCP connection 1 - connected to the server as client Sample: GSM_GPRSLibrary_Client

int disconnectTCP() stops the TCP connection to the server

int connectTCPServer(int port) puts the SIM900 into server mode, waiting for TCP client connection on the specified port. parameters and return values: port: port used for establish a connection return: 0 - unable to start server connection 1 - server started successfully, waiting for client connection Sample: GSM_GPRSLibrary_Server

void SimpleRead() simple way to read from the newsoftserial and print the value on the hardware serial Sample: GSM_GPRSLibrary_AT

void SimpleWrite(char *comm) simple way to write a string on newsoftserial parameters and return values: comm: pointer to the string to write Sample: GSM_GPRSLibrary_AT

For memory saving, next functions are included in a class, so before use them is needed to include the header and to create the class.

For calling functions is necessary to include the next two lines include "call.h"; CallGSM call_classname; //the name you choose must be the same in the functions below

void Call(char *number_string) calls the specific number e.g. call_classname.Call(“+390123456789″);

void Call(int sim_position) calls the number stored at the specified SIM position e.g. call_classname.Call(1); // call to the number stored at the 1st SIM position

void HangUp(void) hangs up call(incoming or active) e.g. call_classname.HangUp();

void PickUp(void) picks up the incoming call e.g. call_classname.PickUp();

For using SMS functions is necessary to include the next two lines include "sms.h"; SMSGSM sms_classname; //the name you choose must be the same in the functions below

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: sms_classname.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; include "sms.h"; SMSGSM sms_classname; sms_classname.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 = sms_classname.IsSMSPresent(SMS_UNREAD); if (position) { // read new SMS sms_classname.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; include "sms.h"; SMSGSM sms_classname; char position; char phone_num[20]; // array for the phone number string char sms_text[100]; // array for the SMS text string position = sms_classname.IsSMSPresent(SMS_UNREAD); if (position) { // there is new SMS => read it sms_classname.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;
include "sms.h";
SMSGSM sms_classname;
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 == sms_classname.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 == sms_classname.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

For HTTP functions is necessary to include the next two lines include "inetGSM.h"; inetGSM inet_classname; //the name you choose must be the same in the functions below

int httpGET(const char server, int port, const char path, char* result, int resultlength) Send a GET request to server, at specified port, for the requested path and save the reply in a string parameters and return values: server: the name or IP address of the server port: number of port used for the connection path: pointer to the string that contains the requested path e.g. / or /test/test.html result: pointer to the reply string from the server resultlength: size of the string with result return: 0 - nothing received, maybe there is an error other - number of byte received Sample: GSM_GPRSLibrary_Client