Links

Software

Waspmote library

Waspmote 4G library

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>

Class constructor

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.

API constants

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.

API variables

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

API functions

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.

Error codes

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

Switching on

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();
}

Switching off

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();
}

SIM card

Entering PIN

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);
}
Example of entering the PIN number: https://development.libelium.com/4g-01-enter-pin-code/

Getting IMEI, IMSI and ICCID

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 revision
  • Wasp4G::INFO_MANUFACTURER_ID: To request the manufacturer identifier
  • Wasp4G::INFO_MODEL_ID: To request the model identifier
  • Wasp4G::INFO_REV_ID: To request the firmware revision
  • Wasp4G::INFO_IMEI: To request the IMEI (International Mobile Station Equipment Identity), which is the unique identifier of the module, similar to a MAC address
  • Wasp4G::INFO_IMSI: To request the IMSI
  • Wasp4G::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 buffer

Checking network connection status

There 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.

Setting operator parameters

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 password

SMS

Setting SMS configuration

The 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();
}

Sending SMSs

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.
Example of sending a text message: https://development.libelium.com/4g-04-sending-sms/

Reading SMSs

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/

Deleting SMSs

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 client

HTTP connections

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