Software
The files related to the 4G module library are:
/Wasp4G/Wasp4G.h/Wasp4G/Wasp4G.cpp/Wasp4G/utility/Wasp4G_constants.h/Wasp4G/utility/Wasp4G_error_codes.h
It is mandatory to include the 4G library when using this module. So the following line must be added at the beginning of the code:
#include <Wasp4G.h>
To start using the Waspmote 4G library, an object from the
Wasp4G class must be created. This object, called _4G, is already created by default inside the Waspmote 4G library. It will be used along this guide to show how Waspmote works. When using the class constructor, all variables are initialized to their default values.
The API constants used in functions are:
Constant | Description |
DEBUG_WASP4G | This definition enables/disables the debug mode via USB port: 0: No debug mode enabled 1: Debug mode enabled for error output messages 2: Debug mode enabled for both error and OK messages |
LE910_RATE | Module's communication baud rate |
LE910_INCOMING_SMS | Constant to set incoming data type when SMS received |
LE910_INCOMING_IP | Constant to set incoming data type when IP received |
LE910_MAX_DL_PAYLOAD | Maximum data payload size to be stored in the data buffer |
The are several enumeration definitions for the function inputs. Please refer to the corresponding section in order to know more about the functions input parameters.
The variables used inside functions and Waspmote codes are:
Variable | Description |
_buffer | The buffer of memory used for storing the responses from the module (512 bytes) |
_length | The length of the contents stored in _buffer |
_def_delay | The time to wait after sending every command until listen for a response |
_baudrate | The baudrate to be used when the module is switched on |
_uart | The selected UART (regarding the socket used: SOCKET0 or SOCKET1) |
_errorCode | It stores the error code returned by the module when calling a function with error response |
_ip | IP address assigned to the 4G module when it is connected to the network |
_temp | It stores temperature from the module |
_tempInterval | It stores temperature interval from the module |
_rssi | It stores the module's RSSI level |
_networkType | It stores the network type which module is connected to |
_incomingType | It stores the incoming data type to be read via serial |
_smsIndex | It stores the SMS index where the incoming message was saved |
_smsStatus | It stores the status of the SMS read from module's memory |
_smsNumber | It stores the phone number of the SMS read from module's memory |
_smsDate | It stores the date of the SMS read from module's memory |
_smsTime | It stores the time of the SMS read from module's memory |
_socketIndex | It stores the socket index which is getting data from UDP or TCP |
_httpCode | It stores the HTTP status code |
_filesize | It stores the size of the file when FTP upload/download is performed |
_ftpWorkingDirectory | It stores the current working directory of the FTP session |
socketInfo | Structure to define the info to be stored for all sockets |
socketStatus | Structure to define the status to be stored for all sockets |
socketStatusSSL | Structure to define the status to be stored for all sockets |
_latitude | It stores latitude from GPS |
_latitudeNS | It stores the north/south indicator from GPS |
_longitude | It stores longitude from GPS |
_longitudeEW | It stores east/west indicator |
_altitude | It stores altitude from GPS |
_time | It stores time from GPS |
_date | It stores date from GPS |
_numSatellites | It stores the number of satellites “in sight” of the GPS |
_fixMode | It stores fix mode set from GPS |
_speedOG | It stores speed over ground from GPS |
_courseOG | It stores course over ground from GPS |
_hdop | It stores the horizontal dilution of precision from GPS |
Through this guide there are lots of examples, showing the use of functions. In these examples, API functions are called to execute the commands, storing in their related variables the parameter value in each case. The functions are called using the predefined object
_4G. All public functions return different possible values:
- 0: OK
- Otherwise: ERROR. See corresponding function error code.
When the 4G module returns an error code, the
_errorCode variable stores the corresponding error meaning. Do not confuse this error code with the returning value from the API functions. There are other types of errors like “no response from the module” which are not included in the next list. For each function answer, please refer to the corresponding error values described for each function within the libraries. The possible module's error codes are described by constants as the table below:
Constant | Value | Error code description |
WASP4G_CME_ERROR_0000 | 0 | Phone failure |
WASP4G_CME_ERROR_0001 | 1 | No connection to phone |
WASP4G_CME_ERROR_0002 | 2 | Phone-adapter link reserved |
WASP4G_CME_ERROR_0003 | 3 | Operation not allowed |
WASP4G_CME_ERROR_0004 | 4 | Operation not supported |
WASP4G_CME_ERROR_0005 | 5 | Phone SIM (Subscriber Identity Module) PIN (Personal Identification Number) required |
WASP4G_CME_ERROR_0010 | 10 | SIM not inserted |
WASP4G_CME_ERROR_0011 | 11 | SIM PIN required |
WASP4G_CME_ERROR_0012 | 12 | SIM PUK (Personal Unlocking Key) required |
WASP4G_CME_ERROR_0013 | 13 | SIM failure |
WASP4G_CME_ERROR_0014 | 14 | SIM busy |
WASP4G_CME_ERROR_0015 | 15 | SIM wrong |
WASP4G_CME_ERROR_0016 | 16 | Incorrect password |
WASP4G_CME_ERROR_0017 | 17 | SIM PIN2 required |
WASP4G_CME_ERROR_0018 | 18 | SIM PUK2 required |
WASP4G_CME_ERROR_0020 | 20 | Memory full |
WASP4G_CME_ERROR_0021 | 21 | Invalid index |
WASP4G_CME_ERROR_0022 | 22 | Not found |
WASP4G_CME_ERROR_0023 | 23 | Memory failure |
WASP4G_CME_ERROR_0024 | 24 | Text string too long |
WASP4G_CME_ERROR_0025 | 25 | Invalid characters in text string |
WASP4G_CME_ERROR_0026 | 26 | Dial string too long |
WASP4G_CME_ERROR_0027 | 27 | Invalid characters in dial string |
WASP4G_CME_ERROR_0030 | 30 | No network service |
WASP4G_CME_ERROR_0031 | 31 | Network time-out |
WASP4G_CME_ERROR_0032 | 32 | Network not allowed - emergency calls only |
WASP4G_CME_ERROR_0040 | 40 | Network personalization PIN required |
WASP4G_CME_ERROR_0041 | 41 | Network personalization PUK required |
WASP4G_CME_ERROR_0042 | 42 | Network subset personalization PIN required |
WASP4G_CME_ERROR_0043 | 43 | Network subset personalization PUK required |
WASP4G_CME_ERROR_0044 | 44 | Service provider personalization PIN required |
WASP4G_CME_ERROR_0045 | 45 | Service provider personalization PUK required |
WASP4G_CME_ERROR_0046 | 46 | Corporate personalization PIN required |
WASP4G_CME_ERROR_0047 | 47 | Corporate personalization PUK required |
WASP4G_CME_ERROR_0100 | 100 | Unknown |
WASP4G_CME_ERROR_0770 | 770 | SIM invalid |
WASP4G_CME_ERROR_0103 | 103 | Illegal Mobile Station (MS) (#3)* |
WASP4G_CME_ERROR_0106 | 106 | Illegal Mobile Equipment (ME) (#6)* |
WASP4G_CME_ERROR_0107 | 107 | GPRS service not allowed (#7)* |
WASP4G_CME_ERROR_0111 | 111 | PLMN not allowed (#11)* |
WASP4G_CME_ERROR_0112 | 112 | Location area not allowed (#12)* |
WASP4G_CME_ERROR_0113 | 113 | Roaming not allowed in this location area (#13)* |
WASP4G_CME_ERROR_0132 | 132 | Service option not supported (#32)* |
WASP4G_CME_ERROR_0133 | 133 | Requested service option not subscribed (#33)* |
WASP4G_CME_ERROR_0134 | 134 | Service option temporarily out of order (#34)* |
WASP4G_CME_ERROR_0148 | 148 | Unspecified GPRS error |
WASP4G_CME_ERROR_0149 | 149 | PDP authentication failure |
WASP4G_CME_ERROR_0150 | 150 | Invalid mobile class |
WASP4G_CME_ERROR_0550 | 550 | Generic undocumented error |
WASP4G_CME_ERROR_0551 | 551 | Wrong state |
WASP4G_CME_ERROR_0552 | 552 | Wrong mode |
WASP4G_CME_ERROR_0553 | 553 | Context already activated |
WASP4G_CME_ERROR_0554 | 554 | Stack already active |
WASP4G_CME_ERROR_0555 | 555 | Activation failed |
WASP4G_CME_ERROR_0556 | 556 | Context not opened |
WASP4G_CME_ERROR_0557 | 557 | Cannot setup socket |
WASP4G_CME_ERROR_0558 | 558 | Cannot resolve DN |
WASP4G_CME_ERROR_0559 | 559 | Time-out in opening socket |
WASP4G_CME_ERROR_0560 | 560 | Cannot open socket |
WASP4G_CME_ERROR_0561 | 561 | Remote disconnected or time-out |
WASP4G_CME_ERROR_0562 | 562 | Connection failed |
WASP4G_CME_ERROR_0563 | 563 | Transmission error |
WASP4G_CME_ERROR_0564 | 564 | Already listening |
WASP4G_CME_ERROR_0568 | 568 | Wrong PDP |
WASP4G_CME_ERROR_0615 | 615 | FTP not connected |
WASP4G_CME_ERROR_0623 | 623 | FTP write data closed |
WASP4G_CME_ERROR_0643 | 643 | FTP communication timeout |
WASP4G_CME_ERROR_0657 | 657 | Network survey error (No Carrier)* |
WASP4G_CME_ERROR_0658 | 658 | Network survey error (Busy)* |
WASP4G_CME_ERROR_0659 | 659 | Network survey error (Wrong request)* |
WASP4G_CME_ERROR_0660 | 660 | Network survey error (Aborted)* |
WASP4G_CME_ERROR_0257 | 257 | Network rejected request |
WASP4G_CME_ERROR_0258 | 258 | Retry operation |
WASP4G_CME_ERROR_0259 | 259 | Invalid deflected to number |
WASP4G_CME_ERROR_0260 | 260 | Deflected to own number |
WASP4G_CME_ERROR_0261 | 261 | Unknown subscriber |
WASP4G_CME_ERROR_0262 | 262 | Service not available |
WASP4G_CME_ERROR_0263 | 263 | Unknown class specified |
WASP4G_CME_ERROR_0264 | 264 | Unknown network message |
WASP4G_CME_ERROR_0680 | 680 | LU processing |
WASP4G_CME_ERROR_0681 | 681 | Network search aborted |
WASP4G_CME_ERROR_0682 | 682 | PTM mode |
WASP4G_CME_ERROR_0683 | 683 | Active call state |
WASP4G_CME_ERROR_0684 | 684 | SSL already activated |
WASP4G_CMS_ERROR_0300 | 300 | ME failure |
WASP4G_CMS_ERROR_0301 | 301 | SMS service of ME reserved |
WASP4G_CMS_ERROR_0302 | 302 | Operation not allowed |
WASP4G_CMS_ERROR_0303 | 303 | Operation not supported |
WASP4G_CMS_ERROR_0304 | 304 | Invalid PDU mode parameter |
WASP4G_CMS_ERROR_0305 | 305 | Invalid text mode parameter |
WASP4G_CMS_ERROR_0310 | 310 | SIM not inserted |
WASP4G_CMS_ERROR_0311 | 311 | SIM PIN required |
WASP4G_CMS_ERROR_0312 | 312 | Phone SIM PIN required |
WASP4G_CMS_ERROR_0313 | 313 | SIM failure |
WASP4G_CMS_ERROR_0314 | 314 | SIM busy |
WASP4G_CMS_ERROR_0315 | 315 | SIM wrong |
WASP4G_CMS_ERROR_0316 | 316 | SIM PUK required |
WASP4G_CMS_ERROR_0317 | 317 | SIM PIN2 required |
WASP4G_CMS_ERROR_0318 | 318 | SIM PUK2 required |
WASP4G_CMS_ERROR_0320 | 320 | Memory failure |
WASP4G_CMS_ERROR_0321 | 321 | Invalid memory index |
WASP4G_CMS_ERROR_0322 | 322 | Memory full |
WASP4G_CMS_ERROR_0330 | 330 | SMSC address unknown |
WASP4G_CMS_ERROR_0331 | 331 | No network service |
WASP4G_CMS_ERROR_0332 | 332 | Network time-out |
WASP4G_CMS_ERROR_0340 | 340 | No +CNMA acknowledgement expected |
WASP4G_CMS_ERROR_0500 | 500 | Unknown error |
WASP4G_CME_ERROR_1001 | 1001 | SSL certs and keys wrong or not stored |
WASP4G_CME_ERROR_1003 | 1003 | SSL already activated |
WASP4G_CME_ERROR_1008 | 1008 | SSL not connected |
WASP4G_ERROR_TIMEOUT | 65534 | Timeout error when running a command |
WASP4G_ERROR_MESSAGE | 65535 | Generic "ERROR" message from module |
The
ON() function switches on the 4G module and it opens the MCU UART for communicating with the module. After this step, the module will be able to receive commands to manage it. Example of use:
{
_4G.ON();
}
The
OFF() function allows the user to switch off the 4G module and close the UART. This function must be called in order to save battery when the module is not going to be used. Example of use:
{
_4G.OFF();
}
The
enterPIN() function allows the user to enter the PIN (Personal Identification Number) of the SIM (Subscriber Identification Module) card. If the SIM card has no PIN (or the PIN was disabled on the SIM card), it is not necessary to use this function. Example for entering the PIN:
{
_4G.enterPIN(“1234”);
}
Besides, there is another function prototype in order to set a new one. It is mandatory to specify the current PIN number and the new one.
Example for setting a new PIN:
{
_4G.enterPIN(“1234”, ”1111”);
}
The
getInfo() function can get more than one information field to the module. This function needs one input to indicate the type of information requested. The resulting information is stored in _buffer, and _length is the number of bytes in the buffer. The information possibilities are: Wasp4G::INFO_HW: To request the hardware revisionWasp4G::INFO_MANUFACTURER_ID: To request the manufacturer identifierWasp4G::INFO_MODEL_ID: To request the model identifierWasp4G::INFO_REV_ID: To request the firmware revisionWasp4G::INFO_IMEI: To request the IMEI (International Mobile Station Equipment Identity), which is the unique identifier of the module, similar to a MAC addressWasp4G::INFO_IMSI: To request the IMSIWasp4G::INFO_ICCID: To request the ICCID
Examples of use:
{
// get IMEI number
_4G.getInfo(Wasp4G::INFO_IMEI);
// get IMSI number
_4G.getInfo(Wasp4G::INFO_IMSI);
// get ICCID number
_4G.getInfo(Wasp4G::INFO_ICCID);
}
Related variables:
_4G._buffer → Buffer which stores the information requested
_4G._length → Number of bytes in bufferThere are 2 functions to check the network connection status:
checkConnection() and checkDataConnection(). The
checkConnection() function checks the module's network connection status and returns whether the module: - is connected to a network
- is not connected to a network
- is searching for a new operator to register to
- registration was denied
This function will wait for the module to be connected to a network for the specified time in second units.
Example of use:
{
_4G.checkConnection(60);
}
Possible error codes for this function:
- 1: not registered, the Mobile Equipment (ME) is not currently searching for a new operator to register to.
- 2: not registered, but ME is currently searching for a new operator to register to.
- 3: registration denied.
- 4: unknown.
The
checkDataConnection() function checks the module's network connection status, connects the module to data service and returns whether the module: - is connected to data service
- is not connected to a network
- is searching for a new operator to register to
- registration was denied
This function will wait for the module to be connected to a network for the specified time in second units.
Example of use:
{
_4G.checkDataConnection(60);
}
Possible error codes for this function:
- 1: not registered, ME is not currently searching for a new operator to register to.
- 2: not registered, but ME is currently searching for a new operator to register to.
- 3: registration denied.
- 4: unknown.
- 6: not registered, ME is not currently searching for a new operator to register to.
- 8: not registered, but ME is currently searching for a new operator to register to.
- 9: registration denied.
- 10: unknown.
- 12: if error setting APN.
- 13: if error setting login.
- 14: if error setting password.
- 15: if error activating GPRS connection.
When the 4G module uses data services like TCP/UDP connections, HTTP services, SMTP or FTP transfers, it is mandatory to configure the parameters provided by the user's Mobile Network Operator (MNO): APN, login and password. The owner of a SIM should be notified with these parameters by the MNO.
The
set_APN() function allows the user to save these parameters into Waspmote memory. Later, when data connection functions are called, Waspmote will configure these parameters into the 4G module. Example of use:
{
_4G.set_APN(“apn”, ”login”, ”password”);
}
The
show_APN() function allows the user to display the current settings stored in Waspmote's memory which are used by the libraries when data connections are performed. Example of use:
{
_4G.show_APN();
}
Related variable:
_4G._apn → Stores the APN name
_4G._apn_login → Stores the APN login
_4G._apn_password → Stores the APN passwordThe
configureSMS() function sets the SMS configuration to: - Correct SMS format to be read from the module.
- Select where SMSs are going to be stored.
- Configure the indication method for new SMS received.
This function must be called before handling SMSs in the main code loop.
Example of use:
{
_4G.configureSMS();
}
The
sendSMS() function sends an SMS to the given phone number. The maximum length of the message to be sent is 164 bytes. Example of use:
{
char phone_number[] = “*********”;
char text_message[] = “This_is_a_text_message”;
_4G.sendSMS(phone_number, text_message);
}
Possible error codes for this function:
- 1: not registered, ME is not currently searching for a new operator to register to.
- 2: not registered, but ME is currently searching for a new operator to register to.
- 3: registration denied.
- 4: unknown connection error.
- 5: if error setting the phone number.
- 6: if error sending the body.
The
readSMS() function reads an SMS from the module storage. The user must give the index of the SMS to be read from memory. In the case a new SMS is received, all SMS related parameters are stored in the Waspmote's library structures: index number, status, sender number, date and time. The SMS text field can be found in _4G._buffer. Example of use:
{
uint8_t index = 5;
_4G.readSMS(index);
}
The
readNewSMS() function reads the last unread SMS received by the module. There are 2 function prototypes: with or without timeout. If the user needs to wait for a new text message for a period of time, the timeout must be specified as input. If no input is defined, the request for new text messages is instantly performed. In the case a new SMS is received, all SMS related parameters are stored in the Waspmote's library structures: index number, status, sender number, date and time. The SMS text field can be found in _4G._buffer. Example of use:
{
_4G.readNewSMS(30000);
}
Related variables:
_4G._smsIndex → Stores the SMS index in memory storage.
_4G._smsStatus → Stores the SMS status:
- "REC UNREAD" - new received message unread
- "REC READ" - received message read
- "STO UNSENT" - message stored not yet sent
- "STO SENT" - message stored already sent
_4G._smsNumber → Stores the sender phone number.
_4G._smsDate → Stores the date SMS was sent.
_4G._smsTime → Stores the time SMS was sent.
_4G._buffer → Stores SMS text field temporary, after calling the read function.
_4G._length → Stores the SMS message length.
Example of receiving and deleting text messages:
https://development.libelium.com/4g-05-receiving-sms/
The
deleteSMS() function deletes an SMS according to the given index number in the memory storage. Examples of use:
{
uint8_t index = 2;
_4G.deleteSMS(index);
}
There is a second
deleteSMS() function prototype which deletes all the SMSs in the storage memory according to several possibilities. For this function, 2 inputs are introduced: the SMS index number and the delete flag. If delete flag is not set to delete one single message, then index is ignored and the module shall follow the rules for delete flag shown below: Wasp4G::SMS_DELETE_MESSAGE: To delete the message specified in index.Wasp4G::SMS_DELETE_ALL_1: To delete all read messages from memory storage, leaving unread messages and stored mobile originated messages (whether sent or not) untouched.Wasp4G::SMS_DELETE_ALL_2: To delete all read messages from memory storage and sent mobile originated messages, leaving unread messages and unsent mobile originated messages untouched.Wasp4G::SMS_DELETE_ALL_3: To delete all read messages from memory storage, sent and unsent mobile originated messages, leaving unread messages untouched.Wasp4G::SMS_DELETE_ALL_4: To delete all messages from memory storage.
Example of use:
{
_4G.deleteSMS(index, Wasp4G::SMS_DELETE_ALL_1);
}
Example of receiving and deleting text messages:
https://development.libelium.com/4g-05-receiving-sms/
HTTP is a great protocol because it is a standard, simple and light way to send information to web servers.
Libelium has created a little web service in order to allow 4G, GPRS or WiFi modules to test the HTTP mode. This web service is a little code, written in PHP, which is continuously listening to the HTTP port (port number 80) of our test server “pruebas.libelium.com”. This is a kind of RESTful service. These communication modules can send HTTP instances to our web service.
HTTP instances should have the following structures so that our web service can understand.
GET method
In GET method the data are sent to the server append to the main URL with the ‘?’ character. The base sentence to perform GET method is shown below:
pruebas.libelium.com/getpost_frame_parser.php?<variable1=value1>&<variable2=value2>&<...>&view=html
getpost_frame_parser.php?: It is the main URL, where the web service is running.<variable1=value1>: It is a couple with the variable name and value which we want the web service to parse.view=html: It is an optional argument. It shows a "pretty" response (HTML formatted).
All arguments must be separated by "&". The variable name and value must be separated by "=".
Some examples:
pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415
pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415&view=html
pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415&var2=123456&var3=hello&view=html
POST method
Unlike GET method, with POST method the data are sent to the server into an extra data field. The URL only includes the site name and the PHP direction:
pruebas.libelium.com/getpost_frame_parser.php
The data field is very similar as the used in GET method:
<variable1=value1>&<variable2=value2>&<...>&view=html