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:
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:
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:
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:
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:
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:
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:
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:
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 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:
Related variables:
_4G._buffer → Buffer which stores the information requested
_4G._length → Number of bytes in buffer
Example of getting module info: https://development.libelium.com/4g-02-get-module-info/
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
The data field is very similar as the used in GET method:
Where:
<variable1=value1>: It is a couple with the variable name and value which we want the web service to parse.
All arguments must be separated by "&". The variable name and value must be separated by "=".
Some examples of data field:
Server response
If the web service receives one instance with the appropriate format, some actions will happen:
The web service grabs the string and parses it. So the PHP code creates couples with the variables name and value.
The web service responses to the sender device (to the sender IP) with an HTML-formatted reply.
Remember this PHP code is really simple and is offered with the only purpose of testing, without any warranty. The source code is available here: downloads.libelium.com/waspmote-html-get-post-php-parser-tester.zip
The user may find it interesting to copy this code and make it run on his own server (physical or virtual). If the user wants to go further, he can complete the code. For example, once the couples are parsed, the user can modify the PHP to save data into a txt file, or insert couples into a database, or include a timestamp...
HTTP request methods
The http() function configures HTTP parameters, performs the request selected by the user and handles the data returned from the server.
This function needs several parameters to work properly depending on the method used. The first parameter required by the function is the request method. User can choose among five methods: GET, HEAD, DELETE, POST and PUT:
Wasp4G::HTTP_GETWasp4G::HTTP_HEADWasp4G::HTTP_DELETEWasp4G::HTTP_POSTWasp4G::HTTP_PUT
After choosing the method, the function needs the host URL, port and resource of the HTTP server requested. The data field is only necessary when POST or PUT methods are performed.
Example of use (GET, HEAD and DELETE methods):
Example of use (POST and PUT methods):
Once the request has been sent, the function waits for data from the server and stores it in _buffer. It also stores the HTTP status code from the server in _httpCode.
Related variable:
_4G._httpCode→ Stores the HTTP code from the server._4G._buffer→ Stores data received from server._4G._length→ Stores data length.
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.
16: if error setting URL and port.
17: if error sending the request.
18: if error sending POST / PUT data.
19: if wrong method has been selected.
20: if timeout waiting the URC.
21: if error reading the URC.
22: if error reading the HTTP status.
23: if error reading the HTTP data length.
24: if error reading the HTTP data.
25: if error code from 4G module while waiting for HTTP response.
26: if timeout waiting for HTTP response.
27: if HTTP response data length is zero.
Example of HTTP GET: https://development.libelium.com/4g-06-http-get/
Example of HTTP POST: https://development.libelium.com/4g-07-http-post/
Setting content type
The HTTP protocol uses media types for denoting the type of request. The 4G module allows the use of these media types in HTTP POST requests.
The 4G library defines a default media type for HTTP POST requests. Moreover, the httpSetContentType() function allows the user to select amongst different media types predefined in the 4G module:
“0” : “application/x-www-form-urlencoded”
“1” : “text/plain”
“2” : “application/octet-stream”
“3” : “multipart/form-data”
Example of use:
There is a second prototype of the function that allows to set a different media type by the user as a string.
Example of use:
Related variable:
_4G._contentType → Stores the desired Content-Type for HTTP POST requests.
Sending Waspmote frames to Meshlium via HTTP
Since Meshlium Manager System v4.0.9, HTTPS method is the default method for sending data. HTTPS is the recommended technology because it provides many cyber security services. Therefore, the HTTPS service is always enabled on Meshlium.
However, Meshlium Manager System v4.1.0 and greater versions allow the user to enable the HTTP service in order to be able to receive HTTP non-secure requests. The user must go to: Manager System → System → Security → HTTP Service:
The sendFrameToMeshlium() function has been developed to send Waspmote frames from Waspmote to Meshlium via non-secure HTTP request. Meshlium will parse (chop) the frame and will store it in its internal MySQL database. This function requires the following parameters:
Meshlium's IP address.
Meshlium's remote port.
Data to send:
frame.bufferwill be used from the generated frame.Data length:
frame.lengthwill be used from the generated frame.
After calling the function, the response from Meshlium will be stored in _buffer. Besides, it will store the HTTP status code from server in _httpCode. Please refer to the Data Frame Guide in order to know more about how to create sensor frames with Waspmote libraries.
Example of use:
Related variable:
_4G._httpCode → Stores the HTTP code from the server.
_4G._buffer → Stores data received from server.
_4G._length → Stores data length.
frame.buffer → Stores data frame that will be sent to Meshlium.
frame.length → Stores data frame length.
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.
16: if error setting URL and port.
17: if error sending the request.
18: if error sending POST / PUT data.
19: if wrong method has been selected.
20: if timeout waiting the URC.
21: if error reading the URC.
22: if error reading the HTTP status.
23: if error reading the HTTP data length.
24: if error reading the HTTP data.
25: if error code from 4G module while waiting for HTTP response.
26: if timeout waiting for HTTP response.
27: if HTTP response data length is zero.
Example of sending frames to Meshlium: https://development.libelium.com/4g-08a-send-to-meshlium-http/
Sending Waspmote frames to Meshlium via HTTPS
Since Meshlium Manager System v4.0.9, HTTPS is the default method for sending data.
For HTTPS, the user must keep in mind that the Meshlium's certificate has to be installed in the Waspmote or Plug & Sense! radio prior to opening secure connections. The next picture shows how the user can download the Meshlium's certificate from Manager System → System → Users Manager → Download Certificate:
The downloaded certificate must be installed following the steps explained in the “SSL sockets” section and the proper library function. Also, the example linked at the end of this section shows how to perform the installation.
Example of sending frames to Meshlium via HTTPS: https://development.libelium.com/4g-08b-send-to-mes4g-08b-send-to-meshlium-https-hl/
FTP client
Opening an FTP session
The ftpOpenSession() function configures FTP parameters and opens the connection. Several inputs are needed:
FTP server: IP address or URL.
FTP port number.
Username.
Password.
Example of use:
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.
16: if error opening the FTP connection.
17: if error setting the transfer type.
After successfully calling this function, it will be possible to manage the rest of FTP functions for uploading and downloading files.
FTP upload
The ftpUpload() function uploads a file from the Waspmote's SD card to the FTP server. The FTP session must be already open. This function needs 2 different inputs: the complete path of the file to be created in the FTP server and the complete path of the file in the SD card to be uploaded.
Example of use for files in root directory:
In the case the file should be uploaded into a subdirectory instead of the root directory, the server filename must be accordingly defined. The user must keep in mind that subdirectories have to be already created in order to upload files into them. In other words, it is not possible to create subdirectories in the FTP server.
Example of use for files in subdirectories:
Possible error codes for this function:
1: if no SD present.
2: if file does not exist.
3: if error opening the file.
4: if error setting the pointer of the file.
5: if error getting the file size.
6: if error opening the PUT connection.
7: if error exiting from the data mode.
8: if error sending data.
Example of uploading files: https://development.libelium.com/4g-09-ftp-upload/
FTP download
The ftpDownload() function downloads a file from an FTP server to Waspmote's SD card. The FTP session must be already open. This function needs 2 different inputs: the complete path of the file in the FTP server and the complete path of the file to be created in the SD card.
Example of use for files in root directory:
In the case the file should be downloaded into an SD card's subdirectory instead of the root directory, the SD filename must be accordingly defined. The user must keep in mind that subdirectories have to be already created in the SD card in order to create files into them.
Example of use for files in subdirectories:
Possible error codes for this function:
1: if server file size is zero.
2: if error reading the file size.
3: if SD not present.
4: if error creating the file in SD.
5: if error opening the file.
6: if error setting the pointer of the file.
7: if error opening the GET connection.
8: if the module returns error code after requesting data.
9: if error getting packet size.
10: if error in packet size mismatch.
11: if error writing SD error.
12: if no more retries getting data.
13: if file size mismatch.
Example of downloading files: https://development.libelium.com/4g-10-ftp-download/
FTP delete file
The ftpDelete() function deletes in the FTP server. The FTP session must be already open. The function expects the name of the file to be deleted as input.
Example of deleting a file:
FTP working directory
The ftpGetWorkingDirectory() function requests the current working directory of the previously open FTP session. The function updates the _ftpWorkingDirectory attribute which stores the information.
Example of getting the FTP working directory:
Related variable:
_4G._ftpWorkingDirectory → Stores the current working directory.
The ftpChangeWorkingDirectory() function allows the user to change the current working directory. The user must keep in mind that the directory to access must be already created before attempting to call this function. The function expects the name of the directory to access to as input parameter.
Example of changing the working directory:
Related variable:
_4G._ftpWorkingDirectory → Stores the new working directory if correctly changed
Closing an FTP session
The ftpCloseSession() function allows the user to close an active FTP session.
Example of closing an FTP session:
TCP/UDP connections
Socket identifiers
The 4G module permits to have up to 6 simultaneous TCP/UDP connections. For that purpose, the libraries define the following socket identifiers to be used when handling the multi-socket connections:
Wasp4G::CONNECTION_1Wasp4G::CONNECTION_2Wasp4G::CONNECTION_3Wasp4G::CONNECTION_4Wasp4G::CONNECTION_5Wasp4G::CONNECTION_6
The 4G libraries define different structures in order to store the information related to all socket identifiers. After opening sockets or sending/receiving data, the structures are updated. So this is useful in order to manage the most important settings of the connection.
Socket information structure
The SocketInfo_t structure stores the information to be stored for all sockets. For each one of the connections, the information structure includes:
Socket identifier.
Total number of bytes sent since the socket was opened.
Total number of bytes received since socket was opened.
Total number of pending bytes to read which arrived through the socket.
Total number of bytes sent and not yet acknowledged since the socket was opened.
As there are six possible connections at the same time, the global variable is defined as follows:
The definition of the structure is:
The getSocketInfo() function allows the user to update the socket information structure from the 4G module. It is mandatory to indicate the identifier of the socket to be updated.
Example of use:
Related variables:
_4G.socketInfo[socketId].id → Socket identifier.
_4G.socketInfo[socketId].sent → Total number of bytes sent since the socket was opened.
_4G.socketInfo[socketId].received → Total number of bytes received.
_4G.socketInfo[socketId].size → Total number of pending bytes to read.
_4G.socketInfo[socketId].ack → Total number of bytes sent and not yet acknowledged.
Socket status structure
The SocketStatus_t structure stores the status for all sockets. For each one of the connections, the status structure includes:
Socket identifier.
Current socket status. The API defines several constants to describe it:
Wasp4G::STATUS_CLOSEDWasp4G::STATUS_ACTIVEWasp4G::STATUS_SUSPENDEDWasp4G::STATUS_SUSPENDED_DATAWasp4G::STATUS_LISTENINGWasp4G::STATUS_INCOMINGWasp4G::STATUS_OPENING
Local IP address.
Local port.
Remote IP address.
Remote port.
As it is possible to have up to 6 simultaneous connections, the global variable is defined as follows:
The definition of the structure is:
The getSocketStatus() function allows the user to update the socket status structure from the 4G module. It is mandatory to indicate the identifier of the socket to be updated. It is possible to update all socket status by calling the getAllSocketStatus() function which is faster than iterating through all different identifiers.
Example of use:
Related variables:
_4G.socketInfo[socketId].id → Socket identifier.
_4G.socketInfo[socketId].state → Socket status.
_4G.socketInfo[socketId].localIp → Local IP address.
_4G.socketInfo[socketId].localPort → Local port.
_4G.socketInfo[socketId].remoteIp → Remote IP address.
_4G.socketInfo[socketId].remotePort → Remote port.
Creating a TCP/UDP client socket
The openSocketClient() function configures and opens a socket. This function expects several input parameters:
Socket ID: The first parameter indicates the identifier to be associated to the new TCP/UDP connection. This identifier is needed in order to send or receive data through the corresponding socket after creating it.
Protocol: This parameter indicates whether use TCP or UDP protocol for the new socket. The possibilities are:
Wasp4G::TCPWasp4G::UDP
Host: Address of the remote host, string type. This parameter can be either:
Any valid IP address in the format: “xxx.xxx.xxx.xxx”
Any host name to be solved with a DNS query
Any valid IPv6 address in the format: xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx or xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx.xxx
Remote port: Remote host port to contact from 1 to 65535.
Local port: Parameter is valid for UDP connections only and has no effect (if used) for TCP connections. UDP connections local port from 1 to 65535.
Example of creating a TCP client connection:
Example of creating a UDP client connection:
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.
16: if error getting socket status..
17: Socket with an active data transfer connection.
18: Socket suspended.
19: Socket suspended with pending data.
20: Socket listening.
21: Socket with an incoming connection. Waiting for the user accept or shutdown command.
22: Socket in opening process. The socket is not closed but still not in Active or Suspended.
23: if error in Socket Configuration.
24: if error in Socket Configuration Extended 3.
25: if error sending the open command.
26: if timeout opening the socket.
Example of creating TCP/UDP client sockets: https://development.libelium.com/4g-11-tcp-client/ https://development.libelium.com/4g-13-udp-client/
Creating a TCP/UDP server socket
The openSocketServer() function configures and opens a listening socket. This function expects several input parameters:
Socket ID: The first parameter indicates the identifier to be associated to the new TCP/UDP connection. This identifier is needed in order to send or receive data through the corresponding socket.
Protocol: This parameter indicates whether use TCP or UDP protocol for the new socket. The possibilities are:
Wasp4G::TCPWasp4G::UDP
Local port: Local listening port from 1 to 65535.
Keep-Alive: TCP keep-alive timer timeout -The interval between 2 keep-alive transmissions in idle condition:
0 → TCP keep-alive timer is deactivated (default)
1..240 → TCP keep-alive timer timeout in minutes
Example of creating a TCP server:
Example of creating a UDP server:
Once the server is created, the manageSockets() function permits the user to update all socket status and accept connections if needed. So when setting up a server or listening socket in Waspmote 4G the best way to handle with connections is directly calling this function. If no input parameter is defined the calling is executed instantly. If the timeout is inserted as new input, the function will block until a new incoming connection needs to be managed or timeout. This timeout must be specified in milliseconds units.
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.
16: if error getting socket status.
17: if error in Socket Configuration.
18: if protocol input not valid.
19: if error opening the socket.
Example of creating TCP/UDP server sockets: https://development.libelium.com/4g-12-tcp-server/ https://development.libelium.com/4g-14-udp-server/
Sending data
The send() function allows the user to send TCP/UDP packets once the socket is active. The function needs 2 different inputs parameters:
Socket ID: the socket identifier used for opening the connection.
Data: This is the stream of data to send to the TCP/UDP socket. This stream of data can be defined as a simple string message. On the other hand, the data can be defined as an array of bytes, specifying a third input for the length of the array of bytes to send.
Example for sending a string message:
Example for sending an array of bytes:
Possible error codes for this function:
1: if error checking socket status.
2: if incorrect socket status.
3: if error sending data.
4: if error waiting confirmation from module.
5: if error getting socket status.
6: if timeout getting socket status.
All examples related to TCP/UDP sockets (both client and server) show how to send data: https://development.libelium.com/4g-11-tcp-client/ https://development.libelium.com/4g-12-tcp-server/ https://development.libelium.com/4g-13-udp-client/ https://development.libelium.com/4g-14-udp-server/
Receiving data
The receive() function allows the user to receive TCP/UDP packets once the socket is active. The function needs different inputs:
Socket ID: the socket identifier used for opening the connection.
Timeout (optional input):
If no timeout input is specified, the receive function is a non-blocking function which answers if data has been received.
If the timeout is inserted as new input, the function will block until a new packet is received or time is up in the case no packet is received. This timeout must be specified in milliseconds units.
Example for instant reception:
Example for blocking reception (i.e. 30 seconds):
Related variables:
_4G._buffer → Pointer to the buffer where received data is stored.
_4G._length → Length of the data received.
Possible error codes for this function:
1: if no data received.
2: if error getting socket info.
3: if timeout waiting for data.
4: if error receiving data from module.
5: if error parsing length of data.
6: if error reading incoming bytes.
Closing a socket
The closeSocketClient() function allows the user to close a TCP/UDP client previously open. The function needs an input parameter for the socket identifier.
The closeSocketServer() function allows the user to close a TCP/UDP server previously open. The function needs 2 inputs:
Socket ID: the socket identifier used for opening the connection.
Protocol: This parameter indicates the protocol used by the socket:
Wasp4G::TCPWasp4G::UDP
SSL sockets
The 4G module includes a stack for establishing SSL sockets. For this feature, the user must keep in mind that it is necessary to install the proper security data in the module. For handling the SSL socket new functions are defined for opening the socket, sending data, receiving data and closing the socket.
Currently, for SSL sockets only one single connection is permitted. So, regarding the socket identifiers the only available option is: Wasp4G::CONNECTION_1.
The manageSSL() function allows the user to store, delete and read security data (Certificate, CA certificate, private key) into the non volatile memory of the module. The function expects several inputs:
Socket ID: the socket identifier used for opening the connection.
Action: the action to perform:
Wasp4G::SSL_ACTION_DELETE: Delete data from memoryWasp4G::SSL_ACTION_STORE: Store data into memoryWasp4G::SSL_ACTION_READ: Read data from memory
Data type:
Wasp4G::SSL_TYPE_CERT: CertificateWasp4G::SSL_TYPE_CA_CERT: CA certificateWasp4G::SSL_TYPE_RSA: RSA Private key
Data (optional): this input is needed when the user selects to store a new security data into module's memory.
Possible error codes for this function:
1: if error setting security data.
2: if error waiting module confirmation.
3: if error getting security data.
4: if error deleting security data.
5: if invalid action input.
Due to the architecture of the 4G v2 radio, the maximum size for the certificates is 4000 bytes. That means some certificates just cannot be used with the 4G radio. The user should resize the certificate in the 4G radio and in the server.
(For the v1 of the 4G radio, the size is smaller: 2000 bytes)
The openSocketSSL() function allows the user to open a remote connection via socket secured through SSL. Several inputs are needed for calling this function:
Socket ID: the socket identifier used for opening the connection.
Host: Remote SSL server address.
Remote port: Remote TCP port to contact from 1 to 65535.
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.
16: if error getting SSL Socket Status.
17: if socket disabled.
19: if socket already open.
20: if error opening the socket.
21: if no response from module.
The sendSSL() function allows the user to send data through a secure socket. Several inputs are needed for calling this function:
Socket ID: the socket identifier used for opening the connection.
Data: Data to send.
Possible error codes for this function:
1: if error checking socket status.
2: if incorrect socket status.
3: if error sending data.
4: if no response from module.
5: if error getting socket status.
6: if timeout waiting for correct socket status.
The receiveSSL() function allows the user to receive data through a secure socket. Several inputs are needed for calling this function:
Socket ID: the socket identifier used for opening the connection.
Timeout (optional input):
If no timeout input is specified, the receive function is a non-blocking function which answers if data has been received.
If the timeout is inserted as new input, the function will block until a new packet is received or time is up in the case no packet is received. This timeout must be specified in milliseconds units.
Possible error codes for this function:
1: if no answer from module.
2: if SSL socket disconnected.
3: if error code from module.
4: if no response from module.
5: if error parsing length of received data.
6: if error getting received data.
7: if error waiting module confirmation.
The closeSocketSSL() function allows the user to close a secure socket. The function needs an input parameter for the socket identifier.
Example for SSL socket: https://development.libelium.com/4g-15a-ssl-sockets/
Send Waspmote frames to the Libelium Cloud Hive service
It is possible to send sensor data from Waspmote to the Libelium Cloud Hive using the Waspmote Frame library and a TCP connection. In order to send this kind of data to the Libelium Cloud Hive, you can use a Meshlium device as intermediary hub, or send directly to the Hive.
FIGURE
Figure: Send Waspmote frames to the Libelium Cloud Hive
In order to do that there will be some requirements before uploading the code into the Waspmote:
The device must be registered in the Libelium Cloud Hive. The serial ID must be present in the “Manage Devices” section.
FIGURE
Figure: Libelium Cloud Hive device Serial ID
The user must fill the string which will contain the bearer token defined in the “Manage Devices” section of the Libelium Cloud Hive customer account.
FIGURE
Figure: Libelium Cloud Hive Personal API Key (Token authentication in code)
The send Waspmote frames to the Libelium Cloud Hive feature is available only for customers that are subscribed to the Libelium Cloud Hive service. Please visit the Libelium Cloud Hive web page to get more information.
Example of send to Libelium Cloud Hive: https://development.libelium.com/4g-21-send-to-limbelium-cloud-bridge/
GPS (only v1 models)
Nowadays there are several positioning techniques to provide the localization to end devices. One of them is the A-GPS positioning technique based on the help of a cellular network deploying an A-GPS server.
Remember that the v2 versions does not have a GPS receiver (EU/BR v2, US v2 and AU v2).
At this point, it is advisable to introduce the definition of Time to First Fix (TTFF): TTFF indicates the time and process required for a GPS device to get adequate satellite signals and data to provide accurate navigation.
A-GPS uses the following sets of data to provide accurate position:
GPS satellite signals
Almanac data
Ephemeris data
If a GPS device has been turned off for a long period of time, when it is turned on it will take longer to acquire these data sets and get a "Time to First Fix". One way to speed up TTFF is to use the A-GPS Positioning Technique.
A "cold" start indicates the scenario in which the GPS must get all data in order to start navigation, and may take up to several minutes.
A "warm" start indicates the scenario in which the GPS has most of the data it needs in memory, and will start quickly, a minute or less.
Before dealing with the A-GPS service, a Standalone GPS solution is described. The figure below shows an overview of the involved functional entities.
Standalone or Autonomous GPS (S-GPS)
Standalone or autonomous GPS mode (S-GPS) is a feature that allows the GPS receiver, installed on the 4G module, to perform its First Fixing activity without assistance data coming from cellular network. The GPS receiver estimates its position directly from GPS satellites in its line of sight. The S-GPS is sometime slower to compute its First Fix; this phenomenon is evident in very poor signal conditions, for example in a city where the satellites signals are corrupted by the multipath propagation.
Assisted GPS (A-GPS)
Assisted GPS mode is a feature that allows the GPS receiver, installed on the module, to perform its First Fix using assistance data provided by entities deployed by Cellular Network.
There are a couple of A-GPS standards. Waspmote libraries implement the Secure User Plane Location (SUPL) architecture. This Location Service architecture is composed of 2 basic elements: a SUPL Enabled Terminal (SET) and a SUPL Location Platform (SLP). The SET corresponds to the 4G module. The SLP manages several tasks: authentication, location request, etc. This module supports the SUPL ver. 1.0.
Waspmote libraries manage the SET Initiated Session scenario where the module, on its initiative, connects to an SLP Server through an IP network, 2 modes are available:
MS-Assisted
MS-Based
In MS-Assisted mode, the module receives acquisition assistance, reference time and other optional assistance data from the network. The mobile service provider continuously logs GPS information (mainly the almanac) from the GPS satellites using an A-GPS server in its system. With the help of this data, the A-GPS server calculates the position and sends it back to the module.
In MS-Based mode, the module receives ephemeris, reference location, reference time and other optional assistance data from the A-GPS server. With the help of this data, the module receives signals from the visible satellites and calculates the position.
If the required satellites visibility is not available, no GPS position is provided by the A-GPS receiver.
Get GPS position
The gpsStart() function allows the user to power on the GPS engine. Depending on the input parameter a different GPS mode is selected. The possibilities are:
Wasp4G::GPS_MS_ASSISTED: Assisted GPS in MS-Assisted modeWasp4G::GPS_MS_BASED: Assisted GPS in MS-Based modeWasp4G::GPS_MS_AUTONOMOUS: Standalone or Autonomous GPS mode
Possible error codes for this function:
1: if error setting the reset mode.
2: if error checking current GPS status.
3: if error starting the GPS engine in standalone mode.
4: if error setting NETWORK_UTRAN mode.
5: if error defining the PDP context.
6: if error setting authentication user ID.
7: if error setting authentication password.
8: if error setting socket configuration.
9: if error setting quality of service.
10: if error setting the SLP server.
11: if error setting the supported SUPL version.
12: if error updating terminal information.
13: if error enabling unsolicited response.
14: if error locking context for LCS use.
15: if error enabling GNSS (or GLONASS).
16: if error in GPS Start Location Service Request.
17: if error checking data connection.
18: if incorrect GPS mode.
The waitForSignal() function waits until GPS signal is received for valid data. The input parameter defines the timeout to wait for signal in millisecond units. If the function returns a correct answer means that the GPS attributes have been updated:
Latitude
Latitude indicator: North or South
Longitude
Longitude indicator: East or West
Time
Date
Number of satellites
HDOP: Horizontal Dilution of precision. If this value is less than 1 indicates the highest possible confidence level to be used for applications.
The convert2Degrees() function performs the conversion from the latitude and latitude variables given by the 4G module to degrees so it is more legible and intuitive. The input parameters must be the latitude/longitude and the corresponding indicator. The returning value is the converted value in degrees units.
The gpsStop() function powers down the GPS engine of the 4G module. It is possible to switch from a SUPL session to the autonomous GPS mode. Firstly, the GPS feature must be stopped, and then restart with the autonomous mode.
Example of GPS modes: https://development.libelium.com/4g-16-gps-autonomous-mode/ https://development.libelium.com/4g-17-a-gps-ms-assisted/ https://development.libelium.com/4g-18-a-gps-ms-based/
Indoor tracking using 4G and A-GPS mode (geolocation)
Assisted GPS, also known as A-GPS or AGPS, enhances the performance of standard GPS in devices connected to the cellular network. A-GPS improves the location performance of cell phones (and other connected devices) in two ways:
By helping obtain a faster "time to first fix" (TTFF). A-GPS acquires and stores information about the location of satellites via the cellular network so the information does not need to be downloaded via satellite.
By helping position a phone or mobile device when GPS signals are weak or not available such as indoor locations. GPS satellite signals may be impeded by tall buildings, and do not penetrate building interiors well. A-GPS uses proximity to cellular towers to calculate position when GPS signals are not available.
In this section, the execution of the A-GPS in MS-Based mode is shown. For this purpose, the corresponding example was used: https://development.libelium.com/4g-18-a-gps-ms-based/
In this example, the GPS is started in MS-based mode. Once location is acquired, the GPS is stopped and started again in Standalone mode. In the following figures, it is possible to see how the GPS module gets its first position 41 seconds after switching on the 4G module. The green icon is the true device position. The red icon is the position the 4G module returns along different iterations. Finally, we can see how the module achieves a great location detection after 73 seconds.
The location given by the A-GPS module may vary depending on the spot used to perform the test. The accuracy will improve when the device is situated in a high density or poor cellular antennas area. The location accuracy may vary from 10 to 100 meters so a real test in each case is mandatory before implementing a final application.
e-mail management functions
Reseting e-mail parameters
The emailReset() function resets the current e-mail parameters in the memory of the module to the default ones. The values reset are:
e-mail user name
e-mail password
e-mail sender address
e-mail SMTP server
Example:
Setting the SMTP server
The emailSetServerSMTP() function sets the SMTP server address, used for e-mail sending. The function expects an input parameter for the SMTP server address. This parameter can be either:
Any valid IP address in the format: xxx.xxx.xxx.xxx
Any host name to be solved with a DNS query (factory default is the empty string “”)
Example:
Configuring SMTP parameters
The emailConfigureSMTP() function sets the parameters needed to the SMTP connection. The input parameters for this function are:
Security: parameter indicating if the SSL encryption is enabled. The possibilities are:
Wasp4G::EMAIL_NONSSLWasp4G::EMAIL_SSL
Port: SMTP port to contact (default 25). Range is from 1 to 65535.
Example:
Some servers support an obsolete implementation of SMTPS on port 465. The module only supports the standard implementation of SMTP over SSL/TLS described in RFC 3207. So do not use port 465 on servers with an obsolete implementation of SMTPS: the module will not work properly. Use instead port 25 or port 587.
Setting the sender parameters: address, username and password
The emailSetSender() function sets the sender parameters. The input parameters related are:
Address: the address string to be used for sending the e-mail.
Username: the username string to be used for sending the e-mail.
Password: the authentication password to be used during the authentication step of the SMTP.
Example:
Possible error codes for this function:
1: if error setting the sender address.
2: if error setting the sender user.
3: if error setting the sender password.
Saving e-mail parameters
The emailSave() function saves the actual e-mail parameters in the memory of the module. The values reset are:
e-mail user name
e-mail password
e-mail sender address
e-mail SMTP server
Example:
Sending an e-mail
The emailSend() function sends an e-mail message. The input parameters needed for this function are:
Address: destination address.
Subject: subject of the message. The maximum length is 100 characters.
Body: the main text message of the e-mail.
Example:
Possible error codes for this function:
1: if error sending mail.
2: if error waiting for module confirmation.
Example of sending e-mail: https://development.libelium.com/4g-19-send-email-smtp/
Last updated
