WiFi PRO Networking Guide
Development website
Search…
Initial page
Introduction
Hardware
Software
Certifications
Code examples and extended information
API changelog
Documentation changelog
Powered By GitBook
Software

Waspmote libraries

Waspmote WiFi PRO libraries

The files related to the WiFi PRO libraries are:
1
/WIFI_PRO/WaspWIFI_PRO.h
2
/WIFI_PRO/WaspWIFI_PRO.cpp
3
/WIFI_PRO/utility/ati_error_codes.h
4
/WIFI_PRO/utility/ati_generator.h
Copied!
It is mandatory to include the WiFi PRO library when using this module. So the following line must be added at the beginning of the code:
1
#include <WaspWIFI_PRO.h>
Copied!

Class constructor

To start using the Waspmote WiFi PRO library, an object from the ‘WaspWIFI_PRO’ class must be created. This object, called WIFI_PRO, is already created by default inside Waspmote WIFI_PRO 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
DEBUG_WIFI
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
WIFI_PRO_SCANFILE
This constant defines the file name where the scanned APs are stored
WIFI_PRO_LISTFILE
This constant defines the file name where the FTP listed directories and files are stored
OPEN
Security mode: no security enabled
WEP64
Security mode: WEP 64-bit security enabled
WEP128
Security mode: WEP 128-bit security enabled
WPA
Security mode: WPA security enabled
WPA2
Security mode: WPA2 security enabled
PROFILE_0
PROFILE_1
PROFILE_2
PROFILE_3
PROFILE_4
PROFILE_5
PROFILE_6
PROFILE_7
PROFILE_8
PROFILE_9
Profile definition for multiple SSIDs

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
_length
The useful length of the buffer
_def_delay
The time to wait after sending every command until listen for a response
_baudrate
The baud rate 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
_rtt
It stores the last round trip time performed by a ping call
_ip
It stores the module's IP address when the proper function is called
_gw
It stores the gateway's IP address when the proper function is called
_netmask
It stores the netmask's IP address when the proper function is called
_dns1
It stores the DNS #1 server's IP address when the proper function is called
_dns2
It stores the DNS #2 server's IP address when the proper function is called
_socket_handle
It stores the handle number for a new TCP/UDP socket
_ftp_handle
It stores the handle number for a new FTP session
_filesize
It stores the FTP server file size when the proper function is called
_essid
It stores the ESSID of the AP where the module is connected to
_bssid
It stores the BSSID of the AP where the module is connected to
_channel
It stores the channel used by the module in the current connection
_rate
It stores the transmission rate used by the module in the current connection

API functions

Through 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.
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 _errorCode variable stores the corresponding error meaning. This error value is described by constants as the table below:
Constant
Value
Error code description
ERROR_CODE_0000
0
Waspmote API timeout error
ERROR_CODE_0010
10
SD not present
ERROR_CODE_0011
11
SD file not created
ERROR_CODE_0012
12
SD error opening file
ERROR_CODE_0013
13
SD error setting file offset
ERROR_CODE_0014
14
SD error writing
ERROR_CODE_0020
20
RX buffer full
ERROR_CODE_0021
21
Error downloading UPGRADE.TXT
ERROR_CODE_0022
22
Filename in UPGRADE.TXT is not a 7-byte name
ERROR_CODE_0023
23
No FILE label is found in UPGRADE.TXT
ERROR_CODE_0024
24
NO_FILE is defined as FILE in UPGRADE.TXT
ERROR_CODE_0025
25
No PATH label is found in UPGRADE.TXT
ERROR_CODE_0026
26
No SIZE label is found in UPGRADE.TXT
ERROR_CODE_0027
27
No VERSION label is found in UPGRADE.TXT
ERROR_CODE_0028
28
Version indicated in UPGRADE.TXT is lower/equal to Waspmote's version
ERROR_CODE_0029
29
File size does not match the indicated in UPGRADE.TXT
ERROR_CODE_0030
30
Error downloading binary file
ERROR_CODE_0031
31
Invalid data length
ERROR_CODE_0041
41
Illegal delimiter

Switch on

The ON() function allows to switch on the WiFi PRO 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:
1
{
2
WIFI_PRO.ON(SOCKET0);
3
}
Copied!

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:
1
{
2
WIFI_PRO.resetValues();
3
}
Copied!

Switch off

The OFF() function allows the user to switch off the WiFi PRO 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:
1
{
2
WIFI_PRO.OFF(SOCKET0);
3
}
Copied!

How to configure and join an Access Point

In order to configure the module to join an Access Point (AP), it is mandatory to define the ESSID of the AP, the password of the security enabled in that link and finally perform a software reset so as to apply the changes.
Once these parameters have been set, they are permanently stored in the non-volatile memory of the module. So, it is not necessary to re-configure these parameters anymore, unless the user needs to change the AP settings.

Configure ESSID

The setESSID() function allows the user to configure the ESSID to join.
The getESSID() function allows the user to request the current ESSID setting. The _essid attribute permits to read the settings of the module.
Example of use:
1
{
2
WIFI_PRO.setESSID(“libelium_AP”);
3
WIFI_PRO.getESSID();
4
}
Copied!
Related variable:
WIFI_PRO._essid → Stores the current ESSID of the module

Configure the password

The setPassword() function allows the user to configure the password to the module. It takes several seconds to generate the keys. This function needs two inputs:
  • Authentication mode:
    • OPEN: No security
    • WEP64: WEP 64-bit
    • WEP128: WEP 128-bit
    • WPA: WPA-PSK
    • WPA2: WPA2-PSK
  • Password:
    • If Security Mode = WPA/WPA2: This is the pass-phrase to be used in generating the PSK encryption key. The allowed value for pass is an ASCII string containing 8 to 63 characters.
    • If Security Mode = WEP64: This key must be defined by 10 hexadecimal digits. Each byte of the 5-byte key is defined by two ASCII characters in the ranges ['0' to '9'], ['A' to 'F'] or ['a' to 'f'].
    • If Security Mode = WEP128: This key must be defined by 26 hexadecimal digits. Each byte of the 13-byte key is defined by two ASCII characters in the ranges ['0' to '9'], ['A' to 'F'] or ['a' to 'f'].
Example of use:
1
{
2
WIFI_PRO.setPassword(WPA2, “password”);
3
}
Copied!

Software reset

Once the module has been set to the correct settings they are kept in the non volatile memory of the module. Besides, it is mandatory to restart the module in order to force the module to use the new settings. For that purpose, the softReset() function is used to perform a software reset to the module. After calling this function, the new setting takes effect.

Join the Access Point

Once the module has valid settings in the non volatile memory, it automatically starts searching to join the Access Point. The isConnected() function permits to know if the WiFi PRO module is already connected to the Access Point. This function returns true or false values in order to provide the status information.
Examples of configuring the module and joining the AP:
WiFi PRO 01: Configure ESSID
WiFi PRO 01: Configure ESSID
WiFi PRO 02: join AP
WiFi PRO 02: join 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 module uses the DHCP client, so when it joins the AP, an IP address is assigned to the module. The getIP() function permits to request the current IP address of the module.
Example of use:
1
{
2
WIFI_PRO.getIP();
3
}
Copied!
Related variable:
WIFI_PRO._ip → Stores the current IP address assigned to the module
Example of getting the module's IP address:
WiFi PRO 03: Get IP
WiFi PRO 03: Get IP

Static IP address

It is possible to set up a default IP address for the WiFi PRO module. Besides, it is possible to set other network parameters: DNS address, Gateway address and Netmask. The functions for all these settings are shown below:
The setIP() function allows the user to set the IP address to the module in the network.
The setDNS() function allows the user to set the DNS address to the WiFi PRO module.
The setGateway() function allows the user to set the Gateway address to the WiFi PRO module.
The setNetmask() function allows the user to set the netmask address to the WiFi PRO module.
Remember that a software reset is needed in order to apply all these changes in the WiFi PRO module.
Example of use:
1
{
2
WIFI_PRO.setIP(“192.168.5.248”);
3
WIFI_PRO.setDNS(“8.8.8.8”);
4
WIFI_PRO.setGateway(“192.168.1.2”);
5
WIFI_PRO.setNetmask(“255.255.128.0”);
6
}
Copied!
Example of using static IP address:
WiFi PRO 04: Static IP
WiFi PRO 04: Static IP

Ping

The ping() function sends a two-byte ICMP PING request packet to the remote host defined as input argument. The input of the function can be a logical name of the target host or a host IP address. Upon successfully receiving an ICMP PING reply from the host, the round trip time in milliseconds is returned (RTT) and stored in the _rtt attribute.
Example of use:
1
{
2
WIFI_PRO.ping(“www.google.com”);
3
}
Copied!
Related variable:
WIFI_PRO._rtt → Stores the last round trip time performed by a ping call
Example of performing a ping from the module:

Power level

The setPower() function allows the user to configure the transmission power of the chipset. The getPower() function allows the user to request the transmission power of the chipset which is stored in the _power attribute. After a hardware or software reset, the power level parameter returns to its default value. This parameter is in the range 1 to 14 dBm. The default value is 14 dBm.
Example of use:
1
{
2
WIFI_PRO.setPower(14);
3
WIFI_PRO.getPower();
4
}
Copied!
Related variable:
WIFI_PRO._power → Stores the power level setting
Example of setting the transmission power level:
https://development.libelium.com/wifi-pro-06-set-power
development.libelium.com

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 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 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 <CR>, 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:
1
{
2
char TRUSTED_CA[] =\
3
"-----BEGIN CERTIFICATE-----\r"\
4
"MIICPDCCAaUCEHC65B0Q2Sk0tjjKewPMur8wDQYJKoZIhvcNAQECBQAwXzELMAkG\r"\
5
"A1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFz\r"\
6
"cyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5MB4XDTk2\r"\
7
"MDEyOTAwMDAwMFoXDTI4MDgwMTIzNTk1OVowXzELMAkGA1UEBhMCVVMxFzAVBgNV\r"\
8
"BAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFzcyAzIFB1YmxpYyBQcmlt\r"\
9
"YXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GN\r"\
10
"ADCBiQKBgQDJXFme8huKARS0EN8EQNvjV69qRUCPhAwL0TPZ2RHP7gJYHyX3KqhE\r"\
11
"BarsAx94f56TuZoAqiN91qyFomNFx3InzPRMxnVx0jnvT0Lwdd8KkMaOIG+YD/is\r"\
12
"I19wKTakyYbnsZogy1Olhec9vn2a/iRFM9x2Fe0PonFkTGUugWhFpwIDAQABMA0G\r"\
13
"CSqGSIb3DQEBAgUAA4GBALtMEivPLCYATxQT3ab7/AoRhIzzKBxnki98tsX63/Do\r"\
14
"lbwdj2wsqFHMc9ikwFPwTtYmwHYBV4GSXiHx0bH/59AhWM1pF+NEHJwZRDmJXNyc\r"\
15
"AA9WjQKZ7aKQRUzkuxCkPfAyAw7xzvjoyVGM5mKf5p/AfbdynMk2OmufTqj/ZA1k\r"\
16
"-----END CERTIFICATE-----”;
17
18
WIFI_PRO.setCA(TRUSTED_CA);
19
}
Copied!
Note: Firmware versions ID811d15 and greater use SSL3/TLS1.2 protocol only.

TCP/UDP sockets

TCP client

The setTCPclient() 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 three 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.
  • Local port: This is the local port when opening the TCP socket.
Upon successfully opening and connecting the TCP socket to the <Host>:<Remote port>, a socket handle is returned. The socket handle is stored in the _socket_handle attribute. This handle is in the range 0 to 9. This handle is needed to reference the socket in all following socket commands.
Example of use:
1
{
2
char HOST[] = "192.168.5.152";
3
char REMOTE_PORT[] = "2000";
4
char LOCAL_PORT[] = "3000";
5
6
WIFI_PRO.setTCPclient( HOST, REMOTE_PORT, LOCAL_PORT);
7
}
Copied!
Related variable:
WIFI_PRO._socket_handle → Stores the TCP socket handle
Example of use for TCP sockets:
WiFi PRO 07: TCP client
WiFi PRO 07: TCP client
Figure: TCP client in Waspmote vs TCP server in laptop

TCP server

The setTCPserver() function opens a TCP listening socket on the local IP address and the specified port. The second input parameter specifies the maximum number of remote concurrent connections allowed through the listening socket. Thus, this function needs 2 different inputs:
  • Local port: The listening port to be used by a remote system when connecting to the WiFi PRO module.
  • Max number of clients: Specifies the maximum number of active connections that may be concurrently established through the listening socket.
Once the listening socket is open, it automatically accepts remote connect requests up to the maximum allowed. When a remote system connects through the listening socket, a new TCP socket is spawned internally ready to send and receive data.
The getAllSocketStatus() function allows the user to update the information of all active sockets connected through a listening socket. The information for each one of the active sockets is stored in a structure called listen_socket_t. There are ten structures defined in the Waspmote libraries for permitting up to ten connections simultaneously.
The definition of the array of sockets structures is:
1
listen_socket_t socket[10];
Copied!
The definition of the structure is:
1
struct listen_socket_t
2
{
3
uint16_t handle; // socket handle
4
int8_t status; // 0: active; -1: non-active
5
char ip[16]; // xxx.xxx.xxx.xxx
6
uint16_t port; // remote connection port
7
int size; // size of pending bytes
8
};
Copied!
Example of use for TCP server:
WiFi PRO 08: TCP server
WiFi PRO 08: TCP server

UDP

The setUDP() function opens a UDP (User Datagram Protocol) socket and sets the remote system’s <Host>:<port> address. Therefore, this function needs three different inputs:
  • Host: Logical name of the target server or a host IP address. The remote system’s name may be any legal Internet server name that can be resolved by module's DNS (Domain Name Server) settings. The server name may also be specified as an absolute IP address given in dot-decimal notation. When the <Host> is defined, the resulting UDP socket is created and connected. If <Host>=0.0.0.0, the socket is created but remains unconnected. The first UDP packet to arrive automatically latches the sender’s IP port, in effect connecting the socket. <Host> may be a subnet directed Broadcast address which allows to broadcast packets to the immediate subnet, not crossing gateways. For example, to broadcast to subnet 192.168.x.x on destination port 1234: Host=”192.168.255.255” and Remote port=“1234”. <Host> may be a multicast IP address in the range 224.0.0.0 to 239.255.255.255. IP multicast datagrams will not cross gateways. In this case, data is sent and received on <Remote port>. <Local port> is ignored.
  • Remote port: Specifies the remote system’s port.
  • Local port: Specifies the local port to use.
Upon successfully opening and connecting the UDP socket to <Host>:<Remote port>, a socket handle is returned. The socket handle is stored in the _socket_handle attribute. The socket handle is in the range 0 to 9 and is used to reference the socket in all following socket commands.
Note: The WiFi PRO will only be able to receive UDP packets from the specified <Host> IP address to the specified <Local port>. In the case other connections are needed it is possible to establish new UDP sockets with different hosts.
Example of use:
1
{
2
char HOST[] = "192.168.5.152";
3
char REMOTE_PORT[] = "2000";
4
char LOCAL_PORT[] = "3000";
5
6
WIFI_PRO.setUDP( HOST, REMOTE_PORT, LOCAL_PORT);
7
}
Copied!
Related variable:
WIFI_PRO._socket_handle → Stores the UDP socket handle
Examples of use for UDP sockets:
WiFi PRO 09: UDP client
WiFi PRO 09: UDP client
WiFi PRO 10: UDP listener
WiFi PRO 10: UDP listener

Send data to a TCP/UDP socket

The send() function sends a byte stream to the socket specified by the socket handle input. This function needs two different inputs:
  • Socket handle: A TCP/UDP socket handle of a previously open socket.
  • 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. Or an array of bytes, specifying a third input for the length of the array of bytes to send.
Example of use for the string message:
1
{
2
WIFI_PRO.send( WIFI_PRO._socket_handle, “this is a message”);
3
}
Copied!
Example of use for the array of bytes (it is mandatory to specify the length):
1
{
2
uint8_t data[] = {0x31, 0x32, 0x33, 0x34, 0x35}
3
WIFI_PRO.send( WIFI_PRO._socket_handle, data, 6);
4
}
Copied!

Receive data from a TCP/UDP socket

The receive() function receives a byte stream from the TCP/UDP socket specified by the socket handle. Received data is valid only if it already resides in the module's socket input buffer at the time this command is issued. There are different receiving function prototypes depending on the time the user needs to listen for a new incoming packet. 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 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:
1
{
2
WIFI_PRO.receive(WIFI_PRO._socket_handle);
3
}
Copied!
Example for time elapsed reception (i.e. 30 seconds):
1
{
2
WIFI_PRO.receive(WIFI_PRO._socket_handle, 30000);
3
}
Copied!

Closing a socket

The closeSocket() function allows the user to close a TCP/UDP client previously open. The function needs an input parameter for the socket identifier:
  • Socket handle: the socket identifier used for opening the connection.

SSL sockets

The WiFi PRO module includes a software stack for establishing SSL sockets. 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 module.
The setCA() function sets the certificate of the trusted certificate authority. The WiFi PRO module accepts a server’s identity only if its certificate is signed by one of these certificate authorities.
The sslHandshake() function negotiates an SSL connection on a given socket handle. This function requires an input to select the socket handle:
  • Socket handle: A TCP/UDP socket handle of a previously opened socket. This input is always mandatory.
Example for SSL connection:
1
{
2
WIFI_PRO.sslHandshake(WIFI_PRO._socket_handle);
3
}
Copied!
Related variable:
WIFI_PRO._socket_handle → Stores the TCP socket handle
Examples of use for SSL sockets:
WiFi PRO 26: SSL sockets
WiFi PRO 26: 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.
Figure: Send Waspmote frames to the Libelium Cloud Bridge
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.
Figure: Libelium Cloud Bridge 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 Bridge customer account.
Figure: Libelium Cloud Bridge Personal API Key (Token authentication in code)
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 GET

The getURL() function retrieves a file from a URL. This function needs two different 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.
  • Link: Absolute link to retrieve on the designated host
Upon the successful retrieving, the answer from the host is stored in the _buffer attribute. Besides, the _length attribute defines the length of the answer stored.
Example of use for HTTP GET to this link:
1
{
2
/////////////////////////////////////////////////////////////////
3
char type[] = "http";
4
char host[] = "pruebas.libelium.com";
5
char port[] = "80";
6
char link[] = "getpost_frame_parser.php?counter=1&varA=1&varB=2";
7
/////////////////////////////////////////////////////////////////
8
9
WIFI_PRO.getURL( type, host, port, link);
10
}
Copied!
Related variable:
WIFI_PRO._buffer → Pointer to the buffer where the answer from host is stored
WIFI_PRO._length → Length of the response stored in _buffer
Example of HTTP GET request:
WiFi PRO 12: HTTP GET
WiFi PRO 12: HTTP GET

HTTP POST

The post() function submits a plain text POST request to a web server defined by the setURL() function. The “Content-type:” field of the POST request is defined by the setContentType() function. A default value of “application/x-www-form-urlencoded” will be used.
This function needs two different 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.
  • Link: Absolute link to retrieve on the designated host
Upon the successful posting, the answer from the host is stored in the _buffer attribute. Besides, the _length attribute defines the length of the answer stored.
Example of use for HTTP POST:
1
{
2
//////////////////////////////////////////
3
char type[] = "http";
4
char host[] = "pruebas.libelium.com";
5
char port[] = "80";
6
char url[] = "getpost_frame_parser.php?";
7
//////////////////////////////////////////
8
9
WIFI_PRO.setURL( type, host, port, link);
10
WIFI_PRO.post("varA=1&varB=2&varC=3&varD=4&varE5=5");
11
}
Copied!
Related variable:
WIFI_PRO._buffer → Pointer to the buffer where the answer from host is stored
WIFI_PRO._length → Length of the response stored in _buffer
Example of HTTP POST request:
WiFi PRO 13: HTTP POST
WiFi PRO 13: HTTP POST

HTTPS

It is possible to use HTTPS calls. For that purpose it is mandatory to insert a certificate of a trusted certificate authority. The user must implement their own secure server and define the certificate to be used with the WiFi PRO module.
The setCA() function sets the certificate of the trusted certificate authorities. The WiFi PRO module accepts a server’s identity only if its certificate is signed by one of these authorities.
After successfully setting the certificate, the module will be able to perform secure socket connections. Therefore, it will be possible to use the well-known getURL() and post() functions to perform HTTPS operations.
Example of HTTPS requests:
WiFi PRO 14: HTTPS GET
WiFi PRO 14: HTTPS GET
WiFi PRO 15: HTTPS POST
WiFi PRO 15: HTTPS POST

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.
Figure: Send Waspmote frames to Meshlium
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:
Figure: Enable HTTP service in Meshlium Manager System
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:
Figure: Meshlium certificate export process
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 five 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:
1
{
2
/////////////////////////////
3
char type[] = "https";
4
char host[] = "10.10.10.1”;
5
char port[] = "443";
6
/////////////////////////////
7
8
WIFI_PRO.sendFrameToMeshlium( type, host, port, frame.buffer, frame.length);
9
}
Copied!
Example of sending frames to Meshlium via HTTP (HTTP service in Meshlium Manager System is required):
https://development.libelium.com/wifi-pro-16-send-to-meshlium
development.libelium.com
Example of sending frames to Meshlium via HTTPS:
WiFi PRO 16b: Send to Meshlium (HTTPS)
WiFi PRO 16b: Send to Meshlium (HTTPS)

FTP client

In order to use the FTP client stack of the WiFi PRO module, different functions must be called. Firstly, the FTP session must be opened. Then it will be possible to upload/download files, list directories, move through directories, etc. Let's look to all different steps:

Open FTP session

The ftpOpenSession() function opens an FTP link to an FTP server. This function needs different inputs:
  • Server: The server name may be any legal Internet-server name, which can be resolved by the module's DNS (Domain Name Server) settings. The server name may also be specified as an absolute IP address given in dot-decimal notation.
  • Port: Optional FTP port in the range 0 to 65535. Default port: 21.
  • User: FTP user's name. This must be a registered user on the FTP server.
  • Pass: FTP user's password to authenticate the user.
Upon successfully connecting to the FTP Server and authenticating the user, a socket handle is returned. The FTP handle is stored in the _ftp_handle attribute. This handle is used to reference the FTP session in all following FTP commands.
Example of use:
1
{
2
///////////////////////////////////////////
3
char SERVER[] = "pruebas.libelium.com";
4
char PORT[] = "21";
5
char USER[] = "[email protected]";
6
char PASSWORD[] = "ftp1234";
7
///////////////////////////////////////////
8
9
WIFI_PRO.ftpOpenSession( SERVER, PORT, USER, PASSWORD);
10
}
Copied!
Related variable:
WIFI_PRO._ftp_handle → Stores the FTP handle

FTP directory listing

The ftpListing() function retrieves a full FTP directory listing. The Waspmote SD card is needed for storing all the incoming data on the listing process. There are two function prototypes for this function depending on the inputs:
  • FTP handle: The FTP handle must be always specified for the FTP session to be considered.
  • Path: The second input is optional and refers to the directory name or filename wildcard. If <path> is a directory, that directory’s files are listed. If it is a filename wildcard, only matching filenames in the current directory are listed. If <path> is not specified, the current directory is listed in full.
Upon successfully retrieving the directory list, the information is stored in an SD file called "LISTFILE.TXT" and is referenced by the WIFI_PRO_LISTFILE label in the libraries. So it is possible to access to this file, display it or extract data from it. Regarding the contents of this file: It contains a list of filenames with file attributes. Each file is listed on a separate line, terminated by <CR/LF>. The file data line syntax is FTP server-dependent.
Example of use for current working directory:
1
{
2
WIFI_PRO.ftpListing( WIFI_PRO._ftp_handle);
3
}
Copied!
Example of use for specific directory path:
1
{
2
WIFI_PRO.ftpListing( WIFI_PRO._ftp_handle, “DIRECTORY”);
3
}
Copied!
Related variable:
WIFI_PRO_LISTFILE → The filename where listing info is stored

FTP make directory

The ftpMakeDir() function allows the user to create a new directory on the FTP server’s file system. This function needs two inputs:
  • FTP handle: Must have been obtained by a previous execution of a ftpOpenSession() function during the current Internet mode session.
  • Path: Directory name. A new directory will be created under the current directory, as indicated by path. If path includes nonexistent subdirectories, some FTP servers will create them as well.
Example of use:
1
{
2
WIFI_PRO.ftpMakeDir( WIFI_PRO._ftp_handle, “DIRECTORY”);
3
}
Copied!
Example of sending frames to Meshlium:
WiFi PRO 19: FTP make directory
WiFi PRO 19: FTP make directory

FTP change working directory

The ftpChangeCWD() function allows the user to change the FTP current working directory. This function needs two inputs:
  • FTP handle: Must have been obtained by a previous execution of a ftpOpenSession() function during the current Internet mode session.
  • Path: Absolute or relative path name of the new directory. The special directory “..” means “one directory up”.
Example of use:
1
{
2
WIFI_PRO.ftpChangeCWD( WIFI_PRO._ftp_handle, “DIRECTORY”);
3
}
Copied!

FTP file size in server

The ftpFileSize() function allows the user to get the size of an FTP server’s file. This function needs two inputs:
  • FTP handle: Must have been obtained by a previous execution of a ftpOpenSession() function during the current Internet mode session.
  • Path: Absolute or relative path name of the remote file.
Example of use:
1
{
2
WIFI_PRO.ftpFileSize( WIFI_PRO._ftp_handle, “FILE.TXT”);
3
}
Copied!
Related variable:
WIFI_PRO._filesize → The size in bytes of the file in the FTP server

FTP upload

The ftpUpload() function allows the user to upload a file from the Waspmote's SD card to the FTP server. This function performs different steps: it opens a file in server for storage, uploads a stream of data from the SD card file and finally closes the file in server. This function needs different inputs:
  • FTP handle: Must have been obtained by a previous execution of a ftpOpenSession() function during the current Internet mode session.
  • Server path: Absolute or relative path name of the remote destination file.
  • SD path: Absolute or relative path name of the file in Waspmote's SD card.
Example of use:
1
{
2
///////////////////////////////////////////
3
uint16_t handle = WIFI_PRO._ftp_handle;
4
char SERVER_FILE[] = “/FILE1.TXT”;
5
char SD_FILE[] = “/FILE2.TXT”;
6
///////////////////////////////////////////
7
8
WIFI_PRO.ftpUpload( handle, SERVER_FILE, SD_FILE);
9
}
Copied!
Example of FTP upload:
WiFi PRO 17: FTP upload
WiFi PRO 17: FTP upload

FTP download

The ftpDownload() function allows the user to download a file from the FTP server to Waspmote's SD card. This function needs different inputs:
  • FTP handle: Must have been obtained by a previous execution of a ftpOpenSession() function during the current Internet mode session.
  • Server path: Absolute or relative path name of the remote destination file.
  • SD path: Absolute or relative path name of the file in Waspmote's SD card.
Example of use:
1
{
2
///////////////////////////////////////////
3
uint16_t handle = WIFI_PRO._ftp_handle;
4
char SERVER_FILE[] = “/FILE1.TXT”;
5
char SD_FILE[] = “/FILE2.TXT”;
6
///////////////////////////////////////////
7
8
WIFI_PRO.ftpDownload( handle, SERVER_FILE, SD_FILE);
9
}
Copied!
Example of FTP download:
WiFi PRO 18: FTP download
WiFi PRO 18: FTP download

Close FTP session

The ftpCloseSession() function closes the FTP link. This function needs the following input:
  • FTP handle: Must have been obtained by a previous execution of a ftpOpenSession() function during the current Internet mode session.
Example of use:
1
{
2
WIFI_PRO.ftpCloseSession( WIFI_PRO._ftp_handle);
3
}
Copied!

Scan APs

The scan() function retrieves a list of all APs available in the surrounding area. The Waspmote SD card is needed for storing all the incoming data on the scanning process.
Upon successfully retrieving the scan list, the information is stored in an SD file called "SCANFILE.TXT" and it is referenced by the WIFI_PRO_SCANFILE label in the libraries. So, it is possible to access to this file, display it or extract data from it. Regarding the contents of this file: It contains a list of up to 16 APs available in the surrounding area. Each line contains the following comma-separated fields:
<SSID>,ADHOC|AP,<BSSID>,<security-type>,<channel>,<RSSI>
Where:
  • <security-type>=NONE|WEP64|WEP128|WPA|WPA2
  • <RSSI> = Value between 0-255 which represents (SNR+NoiseFloor). Higher RSSI values indicate weaker signal strength.
For example:
1
libelium_AP,AP,A8:54:B2:9F:46:6E,WPA2,3,55
2
libelium_teaming,AP,2E:A4:3C:99:2F:B2,WPA2,1,70
3
libelium_formacion,AP,32:A4:3C:99:2F:C3,WPA2,6,64
4
Smart_Libelium_Indoor,AP,60:02:B4:68:74:08,WPA2,9,50
5
libelium_teaming,AP,0E:18:D6:63:E5:2C,WPA2,11,61
6
I/OK
Copied!
Example of use:
1
{
2
WIFI_PRO.scan();
3
}
Copied!
Related variable:
WIFI_PRO_SCANFILE → The filename where scanning info is stored
Example of sending frames to Meshlium:
WiFi PRO 20: Scan | Libelium
WiFi PRO 20: Scan

Set RTC time from NTP server

It is possible to use Network Time Protocol (NTP) servers to synchronize the Waspmote's RTC settings to the servers settings. For that purpose, different functions must be kept in mind.

Time Server setting

The setTimeServer() function allows the user to set the network time server name or IP. The module has two possible network time servers: the primary time server and the alternate time server. So this function has two different inputs:
  • Index: 1 or 2. Use index=1 to define the primary time server. Use index=2 to define an alternate time server.
  • Server: A network timeserver name or IP address. The server will be used to retrieve the current time-of-day.

Time activation flag

The timeActivationFlag() function sets the network time-of-day activation flag. If this flag is enabled, the module will connect to the time server and retrieve an updated time reading each time it connects to the network. From that point on, the module will maintain time internally. While the module is online, the network time will be refreshed every two hours. The input for this function permits two options in order to enable or disable the flag: true or false.

GMT

The setGMT() function allows the user to permanently set the module location’s Greenwich mean time offset, in hours. The range of this parameter is -12 to 12. The default is 0.

Update RTC settings from WiFi PRO module

The setTimeFromWIFI() function allows the user to update the Waspmote's RTC settings when the Time Servers is correctly set and the Activation Flag is enabled.
Example of use:
1
{
2
WIFI_PRO.setTimeServer(1, "time.nist.gov");
3
WIFI_PRO.setTimeServer(2, "wwv.nist.gov");
4
WIFI_PRO.timeActivationFlag(true);
5
WIFI_PRO.setGMT(2);
6
WIFI_PRO.setTimeFromWIFI();
7
}
Copied!
Example of setting the RTC time from NTP server:
https://development.libelium.com/wifi-pro-22-time
development.libelium.com

Multiple SSIDs

The WiFi PRO module permits to set up to 10 different SSID settings so the module is able to connect to one of them.
The setESSID() function allows the user to set the destination Wireless LAN Service Set Identifier (SSID) string into position 'n' in the ten-profile array. The location of an SSID within the list defines its priority, where the first SSID has the top priority. The SSIDs must be configured consecutively. For example, if the first and third SSIDs are set but the second is not, the module ignores the third SSID. For example, if the module is connected to an AP having an SSID value defined by the fourth SSID, and that SSID is set to a different value using this function, the change will take effect immediately and the module will attempt to associate with an AP having the new SSID. On the other hand, if the module is not currently connected to an AP with SSID defined by the fourth SSID and the value of the fourth SSID is changed, the change will take effect only upon the next connection attempt. This function expects two inputs:
  • Profile: There are ten constants in the library used for indexing the different profiles:
    • PROFILE_0
    • PROFILE_1
    • PROFILE_2
    • PROFILE_3
    • PROFILE_4
    • PROFILE_5
    • PROFILE_6
    • PROFILE_7
    • PROFILE_8
    • PROFILE_9
  • ESSID: The destination SSID. It must be configured in the module to successfully communicate with that AP.
The setPassword() function allows the user to configure the security keys for each one of the defined profiles. This function needs three inputs:
  • Profile: The index of the profile to set.
  • Security Mode:
    • OPEN: No security
    • WEP64: WEP 64-bit
    • WEP128: WEP 128-bit
    • WPA: WPA-PSK
    • WPA2: WPA2-PSK
  • Password:
    • If Security Mode = WPA/WPA2: This is the pass-phrase to be used in generating the PSK encryption key. The allowed value for pass is an ASCII string containing 8 to 63 characters.
    • If Security Mode = WEP64: This key can contain up to 10 characters (defining 5 bytes) where each byte is described by two ASCII characters in the range ['0' to '9'], ['A' to 'F'] or ['a' to 'f'].
    • If Security Mode = WEP128: This key can contain up to 26 characters (defining 13 bytes) where each byte is described by two ASCII characters in the range ['0' to '9'], ['A' to 'F'] or ['a' to 'f'].
In the case of using multiple SSIDs it is mandatory to use the isConnectedMultiple() function to check if the module has joined any of those APs. The user must keep in mind that this process can take several seconds which implies a great waste of energy.
Example of multiple SSIDs:

Roaming mode

When set to operate in Roaming mode, the module can roam seamlessly among Access Points (APs) sharing the same SSID and the same security configuration without interrupting its IP connectivity. The WiFi PRO module also has a monitoring mechanism that is sensitive to drops in AP signal strength. When the module detects such a drop, it automatically starts searching for APs in its vicinity that have a stronger signal, while remaining connected to the current AP.
The following functions are required to set the module to Roaming mode:
  • The roamingMode() function enables or disables the Roaming mode.
  • The setScanInterval() function sets the time interval between consecutive scans that the module performs for APs in its vicinity. The range is 1 to 3600 seconds. The default is 5 seconds.
  • The setLowThreshold() function sets a low SNR threshold for the module in Roaming mode. The range is 0 to 254 dB. The default is 10 dB.
  • The setHighThreshold() function sets a high SNR threshold for the module in Roaming mode. The range is 10 to 255 dB. The default is 30 dB.
Example of Roaming mode:
WiFi PRO 24: Roaming mode
WiFi PRO 24: Roaming mode

Behavior following a hardware or software reset

After power-up, hardware or software reset, the module starts scanning for APs in its vicinity at intervals set by the setScanInterval() function. The module reads the value set in the ESSID parameter and acts accordingly. The module attempts to connect to an AP whose ESSID is listed first in the array of ESSID profiles. If several APs having that same ESSID exist, the module attempts to connect to the one having the strongest signal. If association succeeds, the module stops scanning and activates its DHCP client. It then monitors the SNR level of the AP it is associated with.

Behavior when AP signal becomes weak

When the beacon signal of the AP with which the module is associated becomes weak (SNR drops below the level set by the setLowThreshold() function), the module starts its periodic scan for APs having SNR above the threshold set by the setHighThreshold() function.
The WiFi PRO module attempts to connect to the AP that appears first on the list of ESSIDs specified in the ESSID profile array while remaining connected to the current AP. If association with the new AP fails, the module continues scanning until it succeeds connecting to an AP with a stronger signal.
When in Roaming mode, the module does not restart its DHCP client process for new connections.
When the module is not in Roaming mode, it remains connected to an AP as long as it has an open active socket, or until triggered by a Link Lost event. When not in Roaming mode, the module ignores any decrease in AP signal strength while having open active sockets.
When the module is not in Roaming mode and no active sockets are open, it starts periodic scanning for APs having an SNR level above the high SNR threshold. The module attempts to connect to the AP that has the highest priority. After associating with an AP, it starts its DHCP client and monitors the SNR level of the AP it is associated with.
If the connection is not active, the module starts periodic scanning for APs and attempts to connect to an AP having the highest priority. After associating to an AP, it starts its DHCP client and monitors the SNR level of the AP it is associated with.
If the connection is active, the module waits for an IP activity command from the host. When such a command is sent, it performs a software reset and starts scanning for APs. The module responds with ERROR (074) to indicate that the current connection has been lost.

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:
1
{
2
WIFI_PRO.getFirmwareVersion ();
3
}
Copied!
Related variable:
WIFI_PRO._firmwareVersion → Stores the firmware version
Example of WIFI_PRO firmware version function:
WiFi PRO 25: Firmware version
WiFi PRO 25: Firmware version
Previous
Hardware
Next
Certifications
Last modified 7mo ago
Copy link
Contents
Waspmote libraries
Waspmote WiFi PRO libraries
Class constructor
API constants
API variables
API functions
Error codes
Switch on
Restore to factory defaults
Switch off
How to configure and join an Access Point
Configure ESSID
Configure the password
Software reset
Join the Access Point
IP addressing
DHCP client
Static IP address
Ping
Power level
Certificate management for SSL connections
How SSL works
Set the CA certificate
TCP/UDP sockets
TCP client
TCP server
UDP
Send data to a TCP/UDP socket