GSM-Routines

GSM-Routines.cpp

//========================================================================//
//  These are some useful GSM routines or functions written for the Arduino
//  (Due) platform and SIM800L GSM module.
//  It extensively relies on Arduino String class. But it would be easy to
//  port them to a cstring compatible one.
//  The code is straight forward and well commented.
//  
//  Different serial ports are used for GSM and debugging messages.
//  debugPort is your ASCII serial monitor for debugging
//  gsmPort is where you have your GSM module
//  It's on you to decide what kind of ports these are.
//  
//  There are some unused variables and definitions which you can ignore
//  
//  Released by @vishnumaiea (https://github.com/vishnumaiea)
//========================================================================//
//gsm module parameters

#define OP_OK        100  //operation okay
#define OP_NOTOK     101  //operation not okay
#define OP_TIMEOUT   103  //operation times out
#define RST_PIN      2    //GSM module reset pin

#define gsmPort   Serial1   //UART port for GSM module

#ifndef gsmPort
  SoftwareSerial gsmPort (10, 3); //else create a software serial port
  #define DEFAULT_GSM_BAUD 9600 //a slower speed
#else
  #define DEFAULT_GSM_BAUD 115200
#endif

#define SERIALTIMEOUT   3000
#define CRLF_ON                  //comment out if you do not want to terminate AT commands with <CRLF>
#define CARRIAGE_RETURN 0x0D
#define NEWLINE         0x0A
#define CRLF_STRING     String("\r\n")
#define CRLF            "\r\n"
#define CONTEXT_PDP     0
#define CONTEXT_CIP     1
#define CONTEXT_SAP     2

#define MOBILE_NUMBER "\"+91xxxxxxxxxx\"" //add your number here

//========================================================================//
//gsm globals

String gsmReply = ""; //response from GSM module
int gsmBaud = DEFAULT_GSM_BAUD; //GSM module baud rate
int retryCount = 0;

bool gprsStatus = false;  //if GPRS is connected or not
bool simStatus = false;   //if SIM available or not

// bool waitingForResponse = false;

//========================================================================//
//function protos

int gsmInitialize();  //initializes the GSM module
int gsmBegin(); //executes some common AT commands
int gsmSend (String inputString); //send the command to GSM module serial port
int gsmWaitfor (String response1, String response2, unsigned long timeOut); //just wait for two responses from GSM module
int gsmWaitfor (String response1, unsigned long timeOut); //just wait for one response
int gsmCommand (String command, String response1, String response2, unsigned long timeOut, int repetitions);  //send a command wait for two responses
int gsmCommand (String command, String response1, unsigned long timeOut, int repetitions);  //send a command and wait for just one response
String gsmRead(); //read from the GSM serial port
bool findInResponse (String s); //find a string or character in the GSM response
String* extractParameters (String inString);  //extracts parameters from a CRLF mixed string

//example implementations
String getGSMTime();  //gets the netwrok operator time
bool sendSMS(); //send an SMS
bool establishDataPDP();  //establish data connection through PDP context activation
bool establishDataCIP(int muxData); //establish data connection through CIP (TCP/IP), also specify the IP channel
bool establishDataSAP();  //establish data connection through IP application method
bool suspendData(); //suspends data connection
bool reinitializeIPstack();
bool attachGPRS();  //establish a GPRS connection (GPRS connection and protocol (TCP, IP etc) activations are different
bool detachGPRS();  //dismantle a GPRS connection
bool isGPRSActive();  //check is GPRS is active
bool isDataActive (int contextType);  //check if data is active, you need to specify the context type also
String getExternalIP(int contextType);  //get public IP address, you need to specify the context type also

//========================================================================//
//just an initialization function
//do everything to initialize the module here
//it just tests if the GSM module responds to ATtention (AT) commands
//by executing some standard status fetching commands

int gsmInitialize() {
  debugPort.println("Initializing GSM module..");
  debugPort.println();
  int initStatus = -1;
  do {
    initStatus = gsmBegin();
    if(initStatus != OP_OK) {
      debugPort.print("Error initializing GSM module - ");
      debugPort.println(initStatus);
      debugPort.println("Retrying...");
    }
    delay(1000);
  }
  while(initStatus != OP_OK);

  if(initStatus == OP_OK) {
    debugPort.println("GSM module initialized.");
    debugPort.println();
    // debugPort.println("Waiting for command");
    // debugPort.println();
  }
}

//========================================================================//
//executes some simple AT commands

int gsmBegin() {
  gsmCommand("AT", "OK", 2000, 3);  //test for AT command response
  gsmCommand("AT", "OK", 2000, 3);
  // gsmCommand("AT&F0", "OK", 3000, 2);
  gsmCommand("AT+CREG?", "OK", 3000, 3);  //network registration status
  // int networkStatus = gsmWaitfor("0,", "1,", 1500);

  // while (networkStatus != OP_OK) {
  //   gsmSend("AT+CREG?");
  //   networkStatus = gsmWaitfor("0,", "1,", 1500);
  // }

  if (gsmCommand("AT+CMEE=2", "OK", 5000, 2) == OP_OK) {  //detailed error messages
    if (gsmCommand("ATE0&W", "OK", 5000, 2) == OP_OK) // disable Echo
      return OP_OK;  // enable better error messages
    else
      return OP_NOTOK;
  }

  // if (gsmCommand("AT&F0", "OK", "yy", 5000, 2) == OP_OK) {   // Reset to factory settings
  //   if (gsmCommand("ATE0", "OK", "yy", 5000, 2) == OP_OK) {  // disable Echo
  //     if (gsmCommand("AT+CMEE=2", "OK", "yy", 5000, 2) == OP_OK)
  //       return OP_OK;  // enable better error messages
  //     else
  //       return OP_NOTOK;
  //   }
  // }
}

//========================================================================//
//sends a string to the GSM module
//if CRLF_ON is defined, println() function will be used
//print() otherwise

int gsmSend (String inputString) {
  #ifdef CRLF_ON
    gsmPort.println(inputString);
  #else
    gsmPort.print(inputString);
  #endif
}

//========================================================================//
//wait for two responses from GSM module
//you can also specifiy the time to wait for
//remember we are not executing any commands here,
//means you can wait for anything
//it uses active delay

int gsmWaitfor (String response1, String response2, unsigned long timeOut) {
  unsigned long entryTime = millis(); //starting time
  int returnValue = 255;  //you might wonder why we need this : this is because sometimes we need to run the loop multiple times before we can return anything
  bool response1Found = false;
  bool response2Found = false;

  do {
    gsmReply = gsmRead();  //read the response from the GSM module if any
    if(gsmReply != "") { //if the reply is not empty
      if(findInResponse("ERROR") || findInResponse("+CME:")) {  //check if any error status is returned
          debugPort.println();
          debugPort.print("Error (");
          debugPort.print(gsmReply.length());
          debugPort.println(") --");
          debugPort.print(gsmReply);
          debugPort.println("-- end");
          debugPort.println();
          entryTime = 100;  //exit when there's an error encountered
      }
     
      else if(findInResponse(response1) && findInResponse(response2)) { //check if both of our expected responses are found
        debugPort.print("Finished in ");
        debugPort.print((millis() - entryTime));  //print the time taken
        debugPort.print(" ms -- ");
        response1Found = true;
        response2Found = true;
        debugPort.print(gsmReply);
        debugPort.println("-- end");
        debugPort.println();
      }

      else if(findInResponse(response1)) {  //check if one of the expected response is found
        response1Found = true;  //update the status
        if(response1Found && response2Found) {  //if both are found
          debugPort.print("Finished in ");
          debugPort.print((millis() - entryTime));
          debugPort.print(" ms -- ");
          debugPort.print(gsmReply);
          debugPort.println("-- end");
          debugPort.println();
        }
        else {
          debugPort.print(gsmReply);
        }
      }

      else if(findInResponse(response2)) {  //check if one of the expected response is found
        response2Found = true;
        if(response1Found && response2Found) {  //if both are found
          debugPort.print("Finished in ");
          debugPort.print((millis() - entryTime));
          debugPort.print(" ms -- ");
          debugPort.print(gsmReply);
          debugPort.println("-- end");
          debugPort.println();
        }
        else {
          debugPort.print(gsmReply);
        }
      }

      else {  //any unexpected responses
        debugPort.println();
        debugPort.print("Unsolicited (");
        debugPort.print(gsmReply.length());
        debugPort.println(") --");
        debugPort.print(gsmReply);
        debugPort.println("-- end");
        debugPort.println();
      }
    }
  } while (((response1Found == false) || (response2Found == false)) && ((millis() - entryTime) < timeOut)); //wait until we find our responses or the loop timed out

  // debugPort.print("GSM Reply = ");
  // debugPort.println(gsmReply);
  // debugPort.println("--");

  if ((millis() - entryTime) >= timeOut) {  //time out
    returnValue = OP_TIMEOUT;
  }
  else {
    if (response1Found && response2Found) { //indexOf returns -1 if a string is not found
      // debugPort.print("Index sum = ");
      // debugPort.println(gsmReply.indexOf(response1) + gsmReply.indexOf(response2));
      returnValue = OP_OK;
    }
    else {
      returnValue = OP_NOTOK;
    }
  }
  //  debugPort.print("retVal = ");
  //  debugPort.println(retVal);
  return returnValue;
}

//------------------------------------------------------------------------//
//overloaded version
//wait for only one response here

int gsmWaitfor (String response1, unsigned long timeOut) {
  unsigned long entryTime = millis(); //starting time
  int returnValue = 255;
  bool response1Found = false;

  do {
    gsmReply = gsmRead();  //read the response from the GSM module if any

    if(gsmReply != "") { //if the reply is not empty
      if(findInResponse("ERROR") || findInResponse("+CME:")) {
          debugPort.println();
          debugPort.print("Error (");
          debugPort.print(gsmReply.length());
          debugPort.println(") --");
          debugPort.print(gsmReply);
          debugPort.println("-- end");
          debugPort.println();
          entryTime = 100;
      }
      else if(findInResponse(response1)) {
        debugPort.print("Finished in ");
        debugPort.print((millis() - entryTime));
        debugPort.print(" ms -- ");
        response1Found = true;
        debugPort.print(gsmReply);
        debugPort.println("-- end");
        debugPort.println();
      }
      else {
        debugPort.println();
        debugPort.print("Unsolicited (");
        debugPort.print(gsmReply.length());
        debugPort.println(") --");
        debugPort.print(gsmReply);
        debugPort.println("-- end");
        debugPort.println();
      }
    }
  } while ((response1Found == false) && ((millis() - entryTime) < timeOut));

  // debugPort.print("GSM Reply = ");
  // debugPort.println(gsmReply);
  // debugPort.println("--");

  if ((millis() - entryTime) >= timeOut) {
    returnValue = OP_TIMEOUT;
  }
  else {
    if (gsmReply.indexOf(response1) > -1) { //indexOf returns -1 if a string is not found
      // debugPort.print("Index sum = ");
      // debugPort.println(gsmReply.indexOf(response1) + gsmReply.indexOf(response2));
      returnValue = OP_OK;
    }
    else {
      returnValue = OP_NOTOK;
    }
  }
  //  debugPort.print("retVal = ");
  //  debugPort.println(retVal);
  return returnValue;
}

//========================================================================//
//send an AT command, two expected responses, timeout and how many times you want
//to send the command after a timeout or error
//eg. gsmCommand("AT&F0", "OK", "yy", 5000, 2)

int gsmCommand (String command, String response1, String response2, unsigned long timeOut, int repetitions) {
  int returnValue = OP_NOTOK;
  uint8_t count = 0;

  while ((count < repetitions) && (returnValue != OP_OK)) { //loop until reries exhausted or operation succeeds
    gsmSend(command); //send the command
    debugPort.print("Command: ");
    debugPort.println(command);

    if(gsmWaitfor(response1, response2, timeOut) == OP_OK) {  //wait for response
      // debugPort.println("OK");
      returnValue = OP_OK;
    }
    else {
      returnValue = OP_NOTOK;
    }
    count++;  //retry count
  }

  return returnValue;
}

//------------------------------------------------------------------------//
//overloaded version
//same as before but wait for only one response
//eg. gsmCommand("AT", "OK", 2000, 3)

int gsmCommand (String command, String response1, unsigned long timeOut, int repetitions) {
  int returnValue = OP_NOTOK;
  uint8_t count = 0;

  while ((count < repetitions) && (returnValue != OP_OK)) {
    gsmSend(command);
    debugPort.print("Command: ");
    debugPort.println(command);

    if (gsmWaitfor(response1, timeOut) == OP_OK) {
      // debugPort.println("OK");
      returnValue = OP_OK;
    }
    else {
      returnValue = OP_NOTOK;
    }
    count++;
  }

  return returnValue;
}

//========================================================================//
//reads the reply from GSM module

String gsmRead() {
  if (gsmPort.available())  {
    String readString = gsmPort.readString();
    
    //sh!
    if(readString.indexOf("AST_POWERON") != -1) {
      debugPort.println();
      debugPort.println("= = = = = = = = = = = = = = = =");
      debugPort.println("Module restarted. Reinitializing...");
      debugPort.println("= = = = = = = = = = = = = = = =");
      debugPort.println();
      gsmInitialize();
      return "";
    }
    else {
      return readString;
    }
  }
  else {
    return "";
  }
}

//========================================================================//
//search the GSM response for a string

bool findInResponse (String s) {
  if(gsmReply.indexOf(s) != -1)
    return true;
  else
    return false;
}

//========================================================================//
//extracts parameters from CRLF terminated strings
//at command replies are terminated with  CRLF by default
//eg. <CR><LF>100.10.55.111<CR><LF><CR><LF>OK<CR><LF>

String* extractParameters (String inString) {
  int inStringLength = inString.length();
  int paramCount = 0;
  int crCount = 0;  //CR of LF count
  int paramPos = 1; //index to each parameter string. 1 is because 0th will be parameter count
  String* paramArray; //to hold an array of strings

  //first find the no. of parameters so that we can declare an array of strings to hold all parameters
  for(int i = 0; i < inStringLength; i++) {  //gets the parameter count
    if(inString[i] == CARRIAGE_RETURN) { //check for CR
      if(crCount != 2)  //do not increment if two CRLF are found consecutively
        crCount++;
    }
    else if(inString[i] == NEWLINE) { //TODO : this might be redundant
      if(crCount != 2)  //do not increment if two CRLF are found consecutively
        crCount++;
    }
    else {  //for all other chars
      if(crCount == 2) {  //if preceded by CRLF
        if(i > 3) { //do not increment if CRLF is at the start
          paramCount++;
        }
        crCount = 0;  //reset
      }
    }
    if((i == (inStringLength-1)) && (crCount == 2)) {  //if there is no more CRLF
      paramCount++;
    }
  }

  paramArray = new String[paramCount+1];  //parameter count + one for total no. of parameters
  paramArray[0] = String(paramCount); //save the no. of parameters as string

  crCount = 0;  //reset

  for(int i = 0; i < inStringLength; i++) {  //fetch each parameter
    if(inString[i] == CARRIAGE_RETURN) {  //check for CR
      if(crCount != 2)  //do not increment if two CRLF are found consecutively
        crCount++;
    }
    else if(inString[i] == NEWLINE) { //check for LF
      if(crCount != 2)  //do not increment if two CRLF are found consecutively
        crCount++;
    }
    else {  //for all other chars
      if(crCount == 2) {  //if the char is preceded by CRLF
        if(i > 3) { //do not increment if CRLF is at thr start
          paramPos++; //increment otherwise
        }
        crCount = 0;
      }
      paramArray[paramPos] += inString[i];  //save the char to the string
    }
  }

  // for(int i=0; i <= paramCount; i++) { //display all parameters
  //   debugPort.print("Parameter ");
  //   debugPort.print(i);
  //   debugPort.print(" : ");
  //   debugPort.println(paramArray[i]);
  // }

  //if paramCount is 0, then only a single string with value "0" will be returned
  return paramArray;
}

//========================================================================//
//following are some example implementaions of the above routines

//========================================================================//
//get network operator time

String getGSMTime () {
  if(gsmCommand("AT+CCLK?", "OK", 2000, 1) == OP_OK) {
    String timeString = gsmReply.substring((gsmReply.indexOf("\"")+1), (gsmReply.lastIndexOf("\"")));
    timeString.replace("/", "-");
    debugPort.print("Time string : ");
    debugPort.println(timeString);
    return timeString;
  }
}

//========================================================================//
//send SMS text message

bool sendSMS() {
  gsmCommand("AT+CMGF=1", "OK", 2000, 2); //Because we want to send the SMS in text mode
  delay(100);
  gsmCommand("AT+CMGS=" + String(MOBILE_NUMBER), ">", 3000, 2); //send sms message, be careful need to add a country code before the cellphone number
  delay(100);
  gsmPort.print("Trump is an idiot.");//the content of the message
  gsmPort.write(26);//the ASCII code of the ctrl+z is 26 which terminates a message

  if(gsmWaitfor("+CMGS:", 15000) == OP_OK) {
    debugPort.println("Sending SMS success!");
    debugPort.println();
    return true;
  }
  debugPort.println("Sending SMS failed!");
  debugPort.println();
  return false;
}

//========================================================================//
//establish a connection to the internet through manual context activation method

bool establishDataPDP() {
  if(gsmCommand("AT+CPIN?", "OK", "READY", 4000, 1) == OP_OK) {
    // gsmCommand("AT+CSQ", "OK", "+CSQ:", 4000, 1); //get signal quality
    bool gprsState = isGPRSActive();
    bool dataState = isDataActive(CONTEXT_PDP);

    if(!(dataState && gprsState)) { //if one of them are not active
      if(!gprsState) {
        if(attachGPRS()) {
          gprsState = true;
        }
      }

      if(gprsState) {
        if(!dataState) {
          if(gsmCommand("AT+CGACT=1,1", "OK", 50000, 2) == OP_OK) {
            if(gsmCommand("AT+CGDCONT?", "OK", 10000, 1) == OP_OK) {
              gsmCommand("AT+CGPADDR=1", "OK", 5000, 1);
              // gsmCommand("AT+CIPSTATUS", "OK", 2000, 1);

              if(isDataActive(CONTEXT_PDP)) {  //check if the returned IP is not zero
                reinitializeIPstack();
                debugPort.println("Data is now active.");
                dataState = true;
                retryCount = 0;
                debugPort.print("IP address : ");
                debugPort.println(getExternalIP(CONTEXT_PDP));
                return true;
              }
              else {
                dataState = false;
                debugPort.println("Couldn't establish data connection.");
                if(retryCount == 0) {
                  debugPort.println("Retrying...");
                  retryCount = 1;
                  if(establishDataPDP()) {
                    debugPort.println("Data is now active.");
                    dataState = true;
                    retryCount = 0;
                    debugPort.print("IP address : ");
                    debugPort.println(getExternalIP(CONTEXT_PDP));
                    return true;
                  }
                  else {
                    return false;
                  }
                }
                else {
                  return false;
                }
              }
            }
            else {
              return false;
            }
          }
          else {
            debugPort.println("PDP context activation failed. Try again");
            return false;
            // gsmCommand("AT+CGDCONT=1,IP,bsnlstream", "OK", 5000, 1);
            // establishDataPDP();
          }
        }
      }
    }
    else {  //if both are active
      debugPort.println("GPRS and data are already active. Try \"/get ip\" command.");
      return true;
    }
  }
  // debugPort.println("SIM not available");
  return false;
}

//========================================================================//
//establish a connection to the internet through TCP/IP stack method

bool establishDataCIP(int muxData) {
  if(gsmCommand("AT+CPIN?", "OK", "READY", 4000, 1) == OP_OK) {
    // gsmCommand("AT+CSQ", "OK", "+CSQ:", 4000, 1); //get signal quality
    bool gprsState = isGPRSActive();
    bool dataState = isDataActive(CONTEXT_CIP);

    if(!(dataState && gprsState)) { //if one of them are not active
      if(!gprsState) {
        if(attachGPRS()) {
          gprsState = true;
        }
      }

      if(gprsState) { //if GPRS is active
        if(!dataState) {  //if data is not already active
          gsmCommand("AT+CIPSHUT", "OK", 5000, 1);

          if(muxData == 0)
            gsmCommand("AT+CIPMUX=0", "OK", 3000, 1);
          else
            gsmCommand("AT+CIPMUX=1", "OK", 3000, 1);

          gsmCommand("AT+CSTT=\"bsnlstream\"", "OK", 3000, 1);
          gsmCommand("AT+CIICR", "OK", 20000, 2);
          gsmCommand("AT+CIPSTATUS", "OK", 2000, 1);

          if(gsmCommand("AT+CIFSR", "OK", 3000, 2) == OP_OK) {
            dataState = true;
            debugPort.print("IP address : ");
            debugPort.println(getExternalIP(CONTEXT_CIP));
          }
          else {  //if data is still not active, retry once more
            dataState = false;
            debugPort.println("Couldn't establish data connection. Resetting and reattaching...");
            if(gsmBegin() == OP_OK) { //try reinitializing the module
              if(establishDataCIP(muxData)) {
                debugPort.println("Data is now active.");
                return true;
              }
              else {
                debugPort.println("Couldn't establish data connection. Resetting didn't work.");
                return false;
              }
            }
            else
              return false;
          }
        }
      }
      else {  //if GPRS is not active
        debugPort.println("Activating GPRS failed. Try again.");
        return false;
      }
    }
    else {  //if both are active
      debugPort.println("GPRS and data are already active. Try \"/get ip\" command.");
      return true;
    }
  }
  else
    return false;
}

//========================================================================//
//establish a connection to the internet through bearer config method

bool establishDataSAP() {
  if(gsmCommand("AT+CPIN?", "OK", "READY", 4000, 1) != OP_OK) {
    debugPort.println("SIM card is not available.");
    return false;
  }

  // gsmCommand("AT+CSQ", "OK", "+CSQ:", 4000, 1); //get signal quality
  bool gprsState = isGPRSActive();
  bool dataState = isDataActive(CONTEXT_SAP);

  if(!(dataState && gprsState)) { //if one of them are not active
    if(!gprsState) {
      if(attachGPRS()) {
        gprsState = true;
      }
    }

    if(gprsState) { //if GPRS is active
      if(!dataState) {  //if data is not already active
        gsmCommand("AT+SAPBR=3,1,CONTYPE,GPRS", "OK", 5000, 1);
        gsmCommand("AT+SAPBR=3,1,APN,bsnlstream", "OK", 3000, 1);
        // gsmCommand("AT+SAPBR=3,1,USER,\"\"", "OK", 20000, 1);
        // gsmCommand("AT+SAPBR=3,1,PWD,\"\"", "OK", 2000, 1);

        if(gsmCommand("AT+SAPBR=1,1", "OK", 10000, 2) == OP_OK) {
          if(gsmCommand("AT+SAPBR=2,1", "OK", 3000, 1) == OP_OK) {
            dataState = true;
            debugPort.println("Data is now active.");
            // String ipString = getExternalIP(CONTEXT_SAP);
            // debugPort.print("IP address : ");
            // debugPort.println(ipString);
            return true;
          }
          else {  //if data is still not active, retry once more
            dataState = false;
            debugPort.println("Couldn't establish data connection. Resetting and reattaching...");
            if(gsmBegin() == OP_OK) { //try reinitializing the module
              if(establishDataSAP()) {
                debugPort.println("Data is now active.");
                return true;
              }
              else {
                debugPort.println("Couldn't establish data connection. Resetting didn't work.");
                return false;
              }
            }
            else
              return false;
          }
        }
        else {
          debugPort.println("Couldn't establish data connection. Try again.");
          return false;
        }
      }
    }
    else {  //if GPRS is not active
      debugPort.println("Activating GPRS failed. Try again.");
      return false;
    }
  }
  else {  //if both are active
    debugPort.println("GPRS and data are already active. Try \"/get ip\" command.");
    return true;
  }
  return false;
}

//========================================================================//
//disconnect data connection

bool suspendData() {
  // if(gsmCommand("AT+CGACT=0,1", "OK", 5000, 1) == OP_OK) {
  //   return true;
  // }
  // else {
  //   if(gsmCommand("AT+CGACT?", "OK", "0,0", 10000, 1) == OP_OK) {
  //     return true;
  //   }
  //   else {
  //     return false;
  //   }
  // }

  return detachGPRS();
}

//========================================================================//
//when PDP is in PDP DEACT mode, CIPSHUT is called to change it to IP INITIAL

bool reinitializeIPstack() {
  if(gsmCommand("AT+CIPSTATUS", "OK", 10000, 1) == OP_OK) {
    // debugPort.println("CIPSHUT must be called.");
    if(gsmCommand("AT+CIPSHUT", "OK", 10000, 1) == OP_OK) {
      gsmCommand("AT+CIPSTATUS", "OK", 10000, 1);
      return true;
    }
    else {
      return false;
    }
  }
}

//========================================================================//
//attach GPRS connections if already not

bool attachGPRS() {
  if(!isGPRSActive()) { //check if GPRS is already attached
    gsmCommand("AT+CGATT=1", "OK", 10000, 2); //try to attach if not
  }

  if(isGPRSActive()) {  //check status again
    return true;
  }
  else {
    return false;
  }
}

//========================================================================//
//attach GPRS connections if already not

bool detachGPRS() {
  if(gsmCommand("AT+CGATT=0", "OK", 10000, 2) == OP_OK) {
    return true;
  }
  else {
    return false;
  }
}

//========================================================================//
//check if GPRS is active

bool isGPRSActive() {
  if(gsmCommand("AT+CGATT?", "+CGATT:", "OK", 2000, 1) == OP_OK) {
    if(findInResponse("1"))
      return true;
    else
      return false;
  }
  else {
    return false;
  }
}

//========================================================================//
//check if internet connection is active
//the connection must be established through CIPSTART

bool isDataActive (int contextType) {
  switch (contextType) {
    //------------------------------------------------------------------------//
    //for PDP contexts
    case 0:
      if(gsmCommand("AT+CGPADDR=1", "OK", 3000, 1) == OP_OK) {
        if(findInResponse("0.0.0.0")) {
          return false;
        }
        else {
          return true;
        }
      }
      else {
        return false;
      }
      break;

    //------------------------------------------------------------------------//
    //CIP initialization
    case 1:
      if(gsmCommand("AT+CIFSR", "OK", 3000, 1) == OP_OK) {
        if(findInResponse("0.0.0.0")) {
          return false;
        }
        else {
          return true;
        }
      }
      else {
        return false;
      }
      break;

    //------------------------------------------------------------------------//
    //for server configuration
    case 2:
      if(gsmCommand("AT+SAPBR=2,1", "OK", 3000, 1) == OP_OK) {
        if(findInResponse("0.0.0.0")) {
          return false;
        }
        else {
          return true;
        }
      }
      else {
        return false;
      }
      break;

    //------------------------------------------------------------------------//

    default:
      return false;
      break;
  }
}

//========================================================================//
//get the external IP address if the GPRS has been successfully
//established

String getExternalIP(int contextType) {
  if(isDataActive(contextType)) {
    String ipString = gsmReply.substring((gsmReply.indexOf("\"")+1), (gsmReply.lastIndexOf("\"")));

    return ipString;
  }
  else {
    return String("Data connection is not active. Try \"/establish data\"");
  }
}