Software
Waspmote libraries
Waspmote WiFi PRO V3 libraries
The files related to the WiFi PRO V3 libraries are:
It is mandatory to include the WiFi PRO V3 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 WiFi PRO V3 library, an object from the ‘WaspWIFI_v3’ class must be created. This object, called WIFI_PRO_V3, is already created by default inside Waspmote WIFI PRO V3 library. It will be used through this guide to show how Waspmote works.
When using the class constructor, all variables are initialized to a default value.
API constants
The API constants used in functions are:
Constant | Description |
| 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 |
API variables
The main module variables used in the API functions are:
Variable | Description |
| The buffer of memory used for storing the responses from the module |
| The useful length of the buffer |
| The baud rate to be used when the module is switched on |
| The time to wait after sending every command until listen for a response |
| The selected UART (regarding the socket used: SOCKET0 or SOCKET1) |
| It stores the module's IP address when the proper function is called |
| It stores the gateway's IP address when the proper function is called |
| It stores the netmask's IP address when the proper function is called |
| It stores the DNS #1 server's IP address when the proper function is called |
| It stores the DNS #2 server's IP address when the proper function is called |
| It stores the ESSID of the AP where the module is connected to |
| It stores the channel used by the module in the current connection |
| It stores the transmission power level of the module (dBm) |
| It stores the authentication method used to connect to the AP |
| It stores the modules MAC address |
| It stires the modules firmware version |
API functions
Thorugh this guide there are lots of examples of using 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 WIFI_PRO_V3.
All public functions return one of these possible values:
0: OK
1: ERROR. See corresponding error code
Error codes
When a function returns error, the _cmeerror variable stores the corresponding error meaning. This error value is described by constants as the table below:
Constant | Value | Error code description |
ERROR_CODE_3 | 3 | Not allowed |
ERROR_CODE_902 | 902 | No more sockets available |
ERROR_CODE_903 | 903 | Memory problem |
ERROR_CODE_904 | 904 | DNS error |
ERROR_CODE_905 | 905 | TCP disconnection by |
ERROR_CODE_906 | 906 | TCP UDP connection error |
ERROR_CODE_907 | 907 | Generic error |
ERROR_CODE_908 | 908 | Failed to accept client requests |
ERROR_CODE_909 | 909 | Sent data incoherent |
ERROR_CODE_910 | 910 | Bad session ID |
ERROR_CODE_911 | 911 | Session running |
ERROR_CODE_912 | 912 | No more sessions |
ERROR_CODE_913 | 913 | Socket timeout |
ERROR_CODE_914 | 914 | Control socket timeout |
ERROR_CODE_915 | 915 | Unexpected parameter |
ERROR_CODE_916 | 916 | Invalid parameter |
ERROR_CODE_917 | 917 | Parameter missing |
ERROR_CODE_918 | 918 | Feature not supported |
ERROR_CODE_919 | 919 | Feature not available |
ERROR_CODE_920 | 920 | Protocol not supported |
ERROR_CODE_921 | 921 | Invalid bearer connection state |
ERROR_CODE_922 | 922 | Invalid session state |
ERROR_CODE_923 | 923 | Invalid terminal port data mode |
ERROR_CODE_924 | 924 | Session busy |
ERROR_CODE_925 | 925 | HTTP header missing colion |
ERROR_CODE_926 | 926 | HTTP header missing CRLF |
ERROR_CODE_927 | 927 | HTTP header name empty |
ERROR_CODE_928 | 928 | HTTP header value empty |
ERROR_CODE_929 | 929 | Invalid input data format |
ERROR_CODE_930 | 930 | Invalid input data content |
ERROR_CODE_931 | 931 | Invalid parameter length |
ERROR_CODE_932 | 932 | Invalid parameter format |
ERROR_CODE_933 | 933 | Session exists |
Switch on
The ON() function allows to switch on the WiFi PRO V3 module and it opens the MCU's UART for communicating with the module. After this step the module will be able to receive commands to manage it. It is necessary to indicate the socket that it is being used: SOCKET0 or SOCKET1.
Example of use for SOCKET0:
Restore to factory defaults
The resetValues() function allows to restore the module's non-volatile parameter database values to factory defaults. Each one of the module's non-volatile parameters has an associated default value. This function restores all parameters to their factory default values.
Example of use:
Switch off
The OFF() function allows the user to switch off the WiFi PRO V3 module and close the UART. This function must be called in order to keep battery level when the module is not going to be used. It is necessary to indicate the socket that it is being used: SOCKET0 or SOCKET1.
Example of use for SOCKET0:
How to create an Access Point
In order to configure the module as an Access Point (AP), it is mandatory to call the configurMode() function with the WaspWIFI_v3::MODE_ACCESS_POINTconstant.
Example of use:
Once the AP mode has been configured, the configureAP() function will set the ESSID, password and security of the AP.
Example of use:
Example of configuring the module as an AP:
How to configure and join an Access Point
In order to configure the module to join an Access Point (AP) the module uses the station mode. It is mandatory to call the configurMode() function with the WaspWIFI_v3::MODE_STATIONconstant.
Once the station mode has been configured, the configureStation() function will set the ESSID, password and connection mode (WaspWIFI_v3::AUTOCONNECT_DISABLED or WaspWIFI_v3::AUTOCONNECT_ENABLED). The module will detect automatically the authentication method used by the AP.
Example of use:
Examples of configuring the module as an AP:
IP addressing
When joining an AP it is possible to use the DHCP client of the module or configure a static IP address.
DHCP client
By default, the WiFi PRO V3 module uses the DHCP client, so when it joins the AP, an IP address is assigned to the module. The connect() and isConnected() functions store into the library variables the IP address of the module once the module is connected to the AP.
Example of use:
Static IP address
It is possible to set up a default IP address for the WiFi PRO V3 module. Besides, it is possible to set other network parameters: DNS address, Gateway address and Netmask. The function to set all these settings is the configureStationSettings() function.
Example of use:
Ping
The ping() function sends 3 PING request packets to the remote host IP defined as input argument. Upon successfully receiving an PING reply from the host, the function stores into the library variables the number of sent packets, number of recieved packets, number of lost packets, total ping time, minimum ping time and maximum ping time.
By default the ping funtion sends 3 PING packets with a timeout of 1000 milliseconds and an interval of 1000 milliseconds between packets.
Related variables:
WIFI_PRO_V3._pingSent → Number of sent packets
WIFI_PRO_V3._pingReceived → Number of received packets
WIFI_PRO_V3._pingLost → Number of lost packets
WIFI_PRO_V3._pingTime → Total time
WIFI_PRO_V3._pingMinTime → Minimum ping time
WIFI_PRO_V3._pingMaxTime → Maximum ping time
Example of use:
Certificate management for SSL connections
How SSL works
Secure Sockets Layer (SSL) technology provides data encryption, server authentication and message integrity for a TCP/IP connection. The server authenticates the client using the client’s Public Key Certificate (PKC). So, it will be necessary to install the corresponding certificate, created by a CA (Certification Authority), to the module. These CA certificates are usually provided by the browsers.
For more information, refer to the tutorial related to SSL connections:
Set the CA certificate
The setCA() function sets the certificate of the trusted certificate authority. The WiFi PRO V3 module accepts a server’s identity only if its certificate is signed by one of these certificate authorities.
The certificate is a PEM format X509 certificate (DER format, Base-64 encoded with header and footer lines). The certificate is referenced as the trusted certificate authority’s certificate during SSL socket connection establishment (handshake). The WiFi PRO V3 module establishes an SSL socket connection only to servers having a certificate authenticated by this certificate authority. The certificate must be defined by multiple lines separated by , beginning with: -----BEGIN CERTIFICATE----- and terminating with: -----END CERTIFICATE-----. The certificate should include an RSA encryption public key of 1024 or 2048 bits. The signature algorithm may be MD2, MD5 or SHA1. The maximum size of the certificate is 1500 characters.
Example of valid certificate setting:
TCP/UDP sockets
TCP client
The tcpSetClient() function opens a Transmission Control Protocol (TCP) client socket and attempts to connect to the specified port on a server defined as input. Therefore, this function needs 2 different inputs:
Host: The server name may be any legal Internet server name that can be resolved by module's DNS (Domain Name Server) settings. The server name can also be specified as an absolute IP address given in dot-decimal notation.
Remote port: It is assumed that the server system is listening on the specified port.
Upon successfully opening and connecting the TCP socket to the <Host>:<Remote port>, a session ID is returned. The session ID is stored in the _tcpSessionId attribute. This ID is in the range 1 to 64. This ID is needed to reference the session in all following socket commands. It is highly recommended to use the tcpCloseAllSockets() function before opening a TCP session.
Related variable:
_tcpSessionId → Stores the TCP session ID
Example of use:
TCP server
The tcpSetServer() function opens a TCP listening socket on the local IP address and the specified port. Thus, this function needs one input:
Local port: The listening port to be used by a remote system when connecting to the WiFi PRO V3 module.
Once the listening socket is open, it automatically accepts remote connect requests. When a remote system connects through the listening socket, a new TCP socket is spawned internally ready to send and receive data. It is highly recommended to use the tcpCloseAllSockets() function before opening a TCP session.
The tcpWaitClientConnection() waits for a client to connect to the module. Once a connection is done, the function stores incoming connection information into library attributes. The _tcpClientSessionId is needed to reference the session in all following send and receive commands.
Related variables:
_tcpSessionId → Session ID number
_tcpClientSessionId → TCP child session ID
_tcpClientIp → Client IP address
_tcpClientPort → Remote client TCP port
Example of use:
UDP client
The udpSetClient() function opens a User Datagram Protocol (UDP) client socket indicating a local port. and attempts to connect to the specified port on a server defined as input. Therefore, this function needs one input:
Local port: Specified local port.
Upon successfully configuration, a session ID is returned. The session ID is stored in the _udpSessionId attribute. This ID is in the range 1 to 64. This ID is needed to reference the session in all following socket commands. It is highly recommended to use the udpCloseAllSockets() function before opening a TCP session.
Related variable:
_udpSessionId →Stores the UDP session ID
Example of use:
UDP server
The udpSetServer() function opens a User Datagram Protocol (UDP) client socket indicating a local port. and attempts to connect to the specified port on a server defined as input. Therefore, this function needs one input:
Local port: Specified local port.
Upon successfully configuration, a session ID is returned. The session ID is stored in the _udpSessionId attribute. This ID is in the range 1 to 64. This ID is needed to reference the session in all following socket commands. It is highly recommended to use the udpCloseAllSockets() function before opening a TCP session.
Related variable:
_udpSessionId → Stores the UDP session ID
Example of use:
Send and receive data via TCP
The tcpSend() function sends a byte stream to the socket specified by the session ID input. This function needs 2 different inputs:
Session ID: A TCP socket handle of a previously open session.
Data: This is the stream of data to send to the TCP socket. This stream of data can be defined as a simple string message.
Example of use:
The tcpReceive() function receives a byte stream from the TCP socket specified by the session ID. A timeout can be specified as a parameter, therefore, this function could need more than one input:
Socket handle: A TCP/UDP socket handle of a previously opened socket. This input is always mandatory.
Timeout (optional input):
If no timeout input is specified, the function will block until a new packet is received or a 10 seconds timeout is up.
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 time elapsed reception (i.e. 30 seconds):
Examples of use for TCP send and receive:
Send and receive data via UDP
The udpSend() function sends a byte stream to the socket specified by the session ID input. This function needs 4 different inputs:
Session ID: A UDP socket handle of a previously open session.
Host: UDP server remote address.
Remote port: It is assumed that the server system is listening on the specified port.
Data: This is the stream of data to send to the TCP socket. This stream of data can be defined as a simple string message.
This function works only when the modlue is configured as a UDP client.
Example of use:
The udpReceive() function receives a byte stream from the TCP socket specified by the session ID. A timeout can be specified as a parameter, therefore, this function could need more than one input:
Socket handle: A TCP/UDP socket handle of a previously opened socket. This input is always mandatory.
Timeout (optional input):
If no timeout input is specified, the function will block until a new packet is received or a 10 seconds timeout is up.
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 time elapsed reception (i.e. 30 seconds):
Examples of use for TCP send and receive:
Closing a socket
The tcpClose() and udpClose() functions allow the user to close a TCP/UDP connection previously open. The function needs an input parameter for the session identifier:
Session id: the socket identifier used for opening the connection.
SSL sockets
The WiFi PRO V3 module includes a software stack for establishing TLS connections. For using this feature, it is mandatory to insert a certificate of a trusted certificate authority (CA). The user must implement their own secure server and define the certificate to be used with the WiFi PRO V3 module.
The setCA() function sets the certificate of the trusted certificate authority. The WiFi PRO V3 module accepts a server’s identity only if its certificate is signed by one of these certificate authorities.
The tcpSetSecureClient() function opens a Transmission Control Protocol (TCP) using TLS and attempts to connect to the specified port on a server defined as inputs:
Host: The server name may be any legal Internet server name that can be resolved by module's DNS (Domain Name Server) settings. The server name can also be specified as an absolute IP address given in dot-decimal notation.
Remote port: It is assumed that the server system is listening on the specified port.
Upon successfully opening and connecting the TCP socket to the <Host>:<Remote port>, a session ID is returned. The session ID is stored in the _tcpSessionId attribute. This ID is in the range 1 to 64. This ID is needed to reference the session in all following socket commands. It is highly recommended to use the tcpCloseAllSockets() function before opening a TCP session.
Example for SSL connection:
Related variable:
WIFI_PRO._socket_handle → Stores the TCP socket handle
Examples of use for SSL sockets:
Send Waspmote frames to the Libelium Cloud Bridge
It is possible to send sensor data from Waspmote to the Libelium Cloud Bridge using the Waspmote Frame library and a TCP connection. In order to send this kind of data to the Libelium Cloud Bridge, you can use a Meshlium device as WiFi Access Point or use a regular WiFi Access Point (router). In any case, make sure you have internet connection.
In order to do that there will be some requirements before uploading the code to Plug & Sense!:
The device must be registered in the Libelium Cloud Bridge. The serial ID must be present in the “Manage Devices” section.
The user must fill the string which will contain the bearer token defined in the “Manage Devices” section of the Libelium Cloud Bridge customer account.
The send Waspmote frames to the Libelium Cloud Bridge feature is available only for customers that are subscribed to the Libelium Cloud Bridge service. Please visit the Libelium Cloud Bridge web page to get more information.
Example of send to Libelium Cloud Bridge:
HTTP client
HTTP configuration
The httpConfiguration() configures the module to open a connection to a server. The function requires 2 parameters:
HTTP server: The server name may be any legal Internet server name that can be resolved by module's DNS (Domain Name Server) settings. The server name can also be specified as an absolute IP address given in dot-decimal notation.
HTTP port: This is the Host name or IP address
Example of use:
HTTP GET
The httpGet() function connects the module to the HTTP server and performs a GET request to a specific path.
Example of use for HTTP GET:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTP POST
The httpPost() function connects the module to the HTTP server and performs a POST request to a specific path and transfers data.
Example of use for HTTP POST:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTP PUT
The httpPut() function connects the module to the HTTP server and performs a PUT request to a specific path and transfers data.
Example of use for HTTP PUT:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTP HEAD
The httpHead() function connects the module to the HTTP server and performs a HEAD request to a specific path.
Example of use for HTTP HEAD:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTP DELETE
The httpDelete() function connects the module to the HTTP server and performs a DELETE request to a specific path.
Example of use for HTTP DELETE:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTPS client
HTTPS configuration
The httpsConfiguration() function configures the module to open a connection to a server. The function requires 2 parameters:
HTTP server: The server name may be any legal Internet server name that can be resolved by module's DNS (Domain Name Server) settings. The server name can also be specified as an absolute IP address given in dot-decimal notation.
HTTP port: This is the Host name or IP address
Example of use:
Before performing the HTTPS request it must be set the SSL certificate into the module
HTTPS GET
The httpsGet() function connects the module to the HTTP server and performs a GET request to a specific path.
Example of use for HTTPS GET:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTPS POST
The httpsPost() function connects the module to the HTTP server and performs a POST request to a specific path and transfers data.
Example of use for HTTPS POST:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTPS PUT
The httpsPut() function connects the module to the HTTP server and performs a PUT request to a specific path and transfers data.
Example of use for HTTPS PUT:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
HTTPS DELETE
The httpsDelete() function connects the module to the HTTP server and performs a DELETE request to a specific path.
Example of use for HTTPS DELETE:
Related variable:
WIFI_PRO_V3._httpResponseStatus → HTTP status code received from server
Send Waspmote frames to Meshlium via HTTP or HTTPS
It is possible to send sensor data from Waspmote to Meshlium using the Waspmote Frame library and HTTP or HTTPS requests. In order to send this kind of data to Meshlium, you can use a Meshlium device as Access Point or use the Internet to access to a remote Meshlium address through a different AP (via a router, for example).
All data sent using the Waspmote Frame to Meshlium is stored in the Meshlium’s database using the Frame Parser. Therefore, it is possible to access to this database or synchronize it to an external Cloud Partner.
Since Meshlium Manager System v4.0.9, HTTPS 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:
For HTTPS, the user must keep in mind that the Meshlium's certificate has to be installed on 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 “HTTPS” section and the proper library function. Also, the example linked at the end of this section shows how to perform the installation.
The sendFrameToMeshlium() function sends the HTTP GET request to the specified host and port. This function needs 5 inputs:
Type: Protocol type must be “http” for simple HTTP or “https” for HTTPS
Host: This is the Host name or IP address
Port: From 0 to 65535. HTTP default port is 80. HTTPS default port is 443.
frame.buffer: This is the pointer to the Frame structure buffer which contains the sensor data
frame.length: This is the length of the Frame structure buffer
Example of sending a frame to Meshlium:
Example of sending frames to Meshlium via HTTP (HTTP service in Meshlium Manager System is required):
Example of sending frames to Meshlium via HTTPS:
MQTT
MQTT configuration
The mqttConfiguration() function configures into the module the MQTT server and messaging protocol parameters. The function requires 4 parameters:
MQTT server: The server name may be any legal Internet server name that can be resolved by module's DNS (Domain Name Server) settings. The server name can also be specified as an absolute IP address given in dot-decimal notation.
Client ID: Identifier for the client once connected to the broker.
MQTT port: MQTT broker server port. The default unencrypted MQTT port is 1883.
Security: MQTT connection security method can be non-secured or TLS.
Example of use:
MQTT using TLS
To configure TLS in MQTT the security parameter must be set to WaspWIFI_v3::MQTT_TLS_ENABLED. Before configuring the connection the proper certificate must be set into the module.
Example of use:
MQTT publish topic
The mqttPublishTopic() function connects to the MQTT broker and publishes data to a topic. The function requires 4 parameters:
Topic: Topic name to associate with the payload.
QOS: Message QoS (Quality of Service) configuration. The options are: 0 <at most once>, 1 <at least once> and 2 <exactly once>.
Retained flag: this flag determines whether data is retained or not. Reteined data updates newly-connected subscribers to the topic. Non retained data will keep in the dark new suscribers between publish intervals.
Data: payload to add to the topic.
Example of use for publish topic:
MQTT subscribe to topic
The mqttGetTopicData() opens a connection with a MQTT broke and subscribes to a topic. If data was retained it will automatically be read by the module and stored into _mqtt_topic_data. After this, the function will close the connection.
The function requires 2 parameters:
Topic: Topic name ot subscribe to.
QoS: Message QoS (Quality of Service) configuration. The options are: 0 <at most once>, 1 <at least once> and 2 <exactly once>.
Example of use:
The mqttSubscribeTopic() function opens a connection with a MQTT broke and subscribes to a topic. The connection remains open after calling this function. The function requires 2 parameters:
Topic: Topic name ot subscribe to.
QoS: Message QoS (Quality of Service) configuration. The options are: 0 <at most once>, 1 <at least once> and 2 <exactly once>.
Example of use:
After subscribing to a topic the mqttReceive() function waits for the module generate a topic data update event. A timeout can be specified as a parameter, therefore, this function could need more than one input:
Timeout: 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 of use:
Firmware version
The getFirmwareVersion() function allows the user to query the device firmware version. The attribute _firmwareVersion permits to access to the string that stores the firmware version of the module.
Example of use:
Related variable:
WIFI_PRO_V3._firmwareVersion → Stores the firmware version
Last updated
