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

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:

{
    _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

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:

pruebas.libelium.com/getpost_frame_parser.php?variable1=3.141592
pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415&var2=123456&var3=hello

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.

Figure: Operating with the web service from a PC browser

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_GET

• Wasp4G::HTTP_HEAD

• Wasp4G::HTTP_DELETE

• Wasp4G::HTTP_POST

• Wasp4G::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):

{
    char host[] = "test.libelium.com";
    uint16_t port = 80;
    char resource[] = "/test-get-post.php?varA=1&varB=2&varC=3&varD=4";
    _4G.http(Wasp4G::HTTP_GET, host, port, resource);
}

Example of use (POST and PUT methods):

{
    char host[] = "test.libelium.com";
    uint16_t port = 80;
    char resource[] = "/test-get-post.php";
    char data[] = "varA=1&varB=2&varC=3&varD=4&varE=5";
    _4G.http(Wasp4G::HTTP_POST, host, port, resource, data);
}

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:

{
    // Define content to set it to “application/x-www-form-urlencoded”
    uint8_t content = 0;
    _4G.httpSetContentType(content);
}

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:

{
    // Define content to set it to “application/json”
    _4G.httpSetContentType(“application/json”);
}

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:

Figure: Enable HTTP service in Meshlium Manager System

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.buffer will be used from the generated frame.

• Data length: frame.length will be used from the generated frame.

Figure: Send frames to Meshlium via 4G

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:

{
    char host[] = "pruebas.libelium.com";
    uint16_t port = 80;
    // after frame has been created
    _4G.sendFrameToMeshlium(host, port, frame.buffer, frame.length);
}

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:

Figure: Meshlium certificate export process

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:

{
    char ftp_server[] = "pruebas.libelium.com";
    uint16_t ftp_port = 21;
    char ftp_user[] = "[e-mail]";
    char ftp_pass[] = "ftp1234";
    _4G.ftpOpenSession(ftp_server, ftp_port, ftp_user, ftp_pass);
}

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:

{
    char sd_file[] = "FILE1.TXT";
    char server_file[] = "FILE2.TXT";
    
    _4G.ftpUpload(server_file, sd_file);
}

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:

{
    char sd_file[] = "/FOLDER1/FILE1.TXT";
    char server_file[] = "/FOLDER2/FILE2.TXT";
    
    _4G.ftpUpload(server_file, sd_file);
}

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:

{
    char sd_file[] = "FILE1.TXT";
    char server_file[] = "FILE2.TXT";
    
    _4G.ftpDownload(server_file, sd_file);
}

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:

{
    char sd_file[] = "/FOLDER1/FILE1.TXT";
    char server_file[] = "/FOLDER2/FILE2.TXT";
    
    _4G.ftpDownload(server_file, sd_file);
}

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:

{
    _4G.ftpDelete(“FILE_FTP.TXT”);
}

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:

{
    _4G.ftpGetWorkingDirectory();
}

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:

{
    _4G.ftpChangeWorkingDirectory(“NEWDIR”);
}

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:

{
    _4G.ftpCloseSession();
}

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_1

• Wasp4G::CONNECTION_2

• Wasp4G::CONNECTION_3

• Wasp4G::CONNECTION_4

• Wasp4G::CONNECTION_5

• Wasp4G::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:

SocketInfo_t socketInfo[6];

The definition of the structure is:

struct SocketInfo_t
{
    uint8_t id;
    uint16_t sent;
    uint16_t received;
    uint16_t size;
    uint16_t ack;
};

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:

{
    uint8_t socketId = Wasp4G::CONNECTION_1;
    _4G.getSocketInfo(socketId);
}

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_CLOSED

  • Wasp4G::STATUS_ACTIVE

  • Wasp4G::STATUS_SUSPENDED

  • Wasp4G::STATUS_SUSPENDED_DATA

  • Wasp4G::STATUS_LISTENING

  • Wasp4G::STATUS_INCOMING

  • Wasp4G::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:

SocketStatus_t socketStatus[6];

The definition of the structure is:

struct SocketStatus_t
{
    uint8_t id;
    uint8_t state;
    char localIp[16];
    uint16_t localPort;
    char remoteIp[16];
    uint16_t remotePort;
};

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:

{
    uint8_t socketId = Wasp4G::CONNECTION_1;
    _4G.getSocketStatus(socketId);
}

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::TCP

  • Wasp4G::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:

{
    uint8_t socketId = Wasp4G::CONNECTION_1;
    char host[] = "xxx.xxx.xxx.xxx";
    uint16_t remote_port = 15010;
    _4G.openSocketClient(socketId, Wasp4G::TCP, host, remote_port);
}

Example of creating a UDP client connection:

{
    uint8_t socketId = Wasp4G::CONNECTION_2;
    char host[] = "xxx.xxx.xxx.xxx";
    uint16_t remote_port = 15010;
    uint16_t local_port = 4000;
    _4G.openSocketClient(socketId, Wasp4G::UDP, host, remote_port, local_port);
}

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::TCP

  • Wasp4G::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:

{
    uint8_t socketId = Wasp4G::CONNECTION_1;
    uint16_t local_port = 5000;
    uint8_t keep_alive = 240;
    _4G.openSocketServer(socketId, Wasp4G::TCP, local_port, keep_alive);
}

Example of creating a UDP server:

{
    uint8_t socketId = Wasp4G::CONNECTION_2;
    uint16_t local_port = 5000;
    _4G.openSocketServer(socketId, Wasp4G::UDP, local_port);
}

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:

{
    _4G.send(Wasp4G::CONNECTION_1, “This_is_the_data_payload”);
}

Example for sending an array of bytes:

{
    uint8_t data[] = {0x31, 0x32, 0x33, 0x34, 0x35};
    _4G.send(Wasp4G::CONNECTION_1, data, 6);
}

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:

{
    _4G.receive(Wasp4G::CONNECTION_1);
}

Example for blocking reception (i.e. 30 seconds):

{
    _4G.receive(Wasp4G::CONNECTION_1, 30000);
}

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::TCP

  • Wasp4G::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 memory

  • Wasp4G::SSL_ACTION_STORE: Store data into memory

  • Wasp4G::SSL_ACTION_READ: Read data from memory

• Data type:

  • Wasp4G::SSL_TYPE_CERT: Certificate

  • Wasp4G::SSL_TYPE_CA_CERT: CA certificate

  • Wasp4G::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.

Figure: GPS overview

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 mode

• Wasp4G::GPS_MS_BASED: Assisted GPS in MS-Based mode

• Wasp4G::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.

Figure: First iteration (41 seconds after starting the 4G module). Distance error: 42 meters.

Figure: Second iteration (53 seconds after starting the 4G module): Distance error: 28 meters.

Figure: Third iteration (63 seconds after starting the 4G module): Distance error: 28 meters.

Figure: Fourth iteration (73 seconds after starting the 4G module): Distance error: 7 meters.

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:

{
    _4G.emailReset();
}

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:

{
    _4G.emailSetServerSMTP("smtp.mydomain.com");
}

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_NONSSL

  • Wasp4G::EMAIL_SSL

• Port: SMTP port to contact (default 25). Range is from 1 to 65535.

Example:

{
    _4G.emailConfigureSMTP(Wasp4G::EMAIL_NONSSL, 25);
}

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:

{
    char address[] = “[e-mail]”;
    char user[] = “[e-mail]”;
    char password[] = “myPassword”;
    
    _4G.emailSetSender(address, user, password);
}

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:

{
    _4G.emailSave();
}

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:

{
    char address[] = "[e-mail]";
    char subject[] = "Subject of email";
    char message[] = "This is an e-mail message from Waspmote";
    
    _4G.emailSend(address, subject, message);
}

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/