Development website Libelium website Networking development website

Software

Waspmote libraries

Waspmote WiFi PRO V3 libraries

The files related to the WiFi PRO V3 libraries are:

	/WIFI_PRO_V3/WaspWIFI_PRO_V3.h
	/WIFI_PRO_V3/WaspWIFI_PRO_V3.cpp
	/WIFI_PRO_V3/utility/ati_error_codes.h
	/WIFI_PRO_V3/utility/ati_generator.h

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:

#include <WaspWIFI_PRO_V3.h>

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:

API variables

The main module variables used in the API functions are:

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:

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: 

{
    WIFI_PRO_V3.ON(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: 

{
    WIFI_PRO_V3.resetValues();
}

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: 

{
    WIFI_PRO_V3.OFF(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: 

{
    WIFI_PRO_V3.configureMode(WaspWIFI_v3::MODE_ACCESS_POINT);
}

Once the AP mode has been configured, the configureAP() function will set the ESSID, password and security of the AP.

Example of use: 

{
    WIFI_PRO_V3.configureAp(ssid, passkey, WaspWIFI_v3::AUTH_WPA2);
}

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. 

{
    WIFI_PRO_V3.configureMode(WaspWIFI_v3::MODE_STATION);
}

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: 

{
    WIFI_PRO_V3.configureStation(ssid, passkey, WaspWIFI_v3::AUTOCONNECT_ENABLED);
}

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: 

{
    WIFI_PRO_V3.configureStationSettings(WaspWIFI_v3::DHCP_ENABLED);
}

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: 

{
    WIFI_PRO_V3.configureStationSettings( WaspWIFI_v3::DHCP_DISABLED, STATIC_IP, NETMASK, GATEWAY);
}

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: 

{
    WIFI_PRO_V3.ping(ip_address);
    WIFI_PRO_V3.ping(ip_address, numberofpackets,timeout,interval);
}

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: 

{
	   char TRUSTED_CA[] =\ 
	   "-----BEGIN CERTIFICATE-----\n"\
	   "MIICPDCCAaUCEHC65B0Q2Sk0tjjKewPMur8wDQYJKoZIhvcNAQECBQAwXzELMAkG\n"\
	   "A1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFz\n"\
	   "cyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5MB4XDTk2\n"\
	   "MDEyOTAwMDAwMFoXDTI4MDgwMTIzNTk1OVowXzELMAkGA1UEBhMCVVMxFzAVBgNV\n"\
	   "BAoTDlZlcmlTaWduLCBJbmMuMTcwNQYDVQQLEy5DbGFzcyAzIFB1YmxpYyBQcmlt\n"\
	   "YXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GN\n"\
	   "ADCBiQKBgQDJXFme8huKARS0EN8EQNvjV69qRUCPhAwL0TPZ2RHP7gJYHyX3KqhE\n"\
	   "BarsAx94f56TuZoAqiN91qyFomNFx3InzPRMxnVx0jnvT0Lwdd8KkMaOIG+YD/is\n"\
	   "I19wKTakyYbnsZogy1Olhec9vn2a/iRFM9x2Fe0PonFkTGUugWhFpwIDAQABMA0G\n"\
	   "CSqGSIb3DQEBAgUAA4GBALtMEivPLCYATxQT3ab7/AoRhIzzKBxnki98tsX63/Do\n"\
	   "lbwdj2wsqFHMc9ikwFPwTtYmwHYBV4GSXiHx0bH/59AhWM1pF+NEHJwZRDmJXNyc\n"\
	   "AA9WjQKZ7aKQRUzkuxCkPfAyAw7xzvjoyVGM5mKf5p/AfbdynMk2OmufTqj/ZA1k\n"\
	   "-----END CERTIFICATE-----”;
	
	   WIFI_PRO.setCA(0, TRUSTED_CA);
}

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: 

{
		char HOST[]        = "192.168.5.152";
		char REMOTE_PORT[] = "2000";
		
		WIFI_PRO_V3.tcpSetClient( HOST, REMOTE_PORT);
}

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: 

{
    WIFI_PRO_V3.tcpSetServer(LOCAL_PORT);
    
    WIFI_PRO_V3.tcpWaitClientConnection(15000);
}

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: 

{
		WIFI_PRO_V3.udpSetClient(port);
}

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: 

{
		WIFI_PRO_V3.udpSetServer(port);
}

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: 

{
    WIFI_PRO_V3.tcpSend( WIFI_PRO_V3._tcpSessionId, “this is a message”);
}

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

	{
		WIFI_PRO_V3.tcpReceive(WIFI_PRO_V3._socket_handle, 30000);
	}

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: 

{
    WIFI_PRO_V3.udpSend( WIFI_PRO_V3._udpSessionId, host, remote_port, “this is a message”);
}

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

	{
		WIFI_PRO_V3.udpReceive(WIFI_PRO_V3._socket_handle, 30000);
	}

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: 

	{
		WIFI_PRO_V3.tcpSetSecureClient(HOST, REMOTE_PORT);
	}

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: 

{
		/////////////////////////////////////////////////////////////////
		char HTTP_SERVER[] = "postman-echo.com";
		uint16_t HTTP_PORT = 80;
		/////////////////////////////////////////////////////////////////
		
		WIFI_PRO_V3.httpConfiguration(HTTP_SERVER, HTTP_PORT);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/get?foo1=bar1&foo2=bar2";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpGet(HTTP_PATH);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/post";
    char HTTP_DATA[] = "Data to post";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpPost(HTTP_PATH, HTTP_DATA);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/put";
    char HTTP_DATA[] = "Data";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpPut(HTTP_PATH, HTTP_DATA);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/head";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpHead(HTTP_PATH);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/delete";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpDelete(HTTP_PATH);
}

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: 

{
		/////////////////////////////////////////////////////////////////
		char HTTP_SERVER[] = "postman-echo.com";
		uint16_t HTTP_PORT = 443;
		/////////////////////////////////////////////////////////////////
		
		WIFI_PRO_V3.httpsConfiguration(HTTP_SERVER, HTTP_PORT);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/get?foo1=bar1&foo2=bar2";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpsGet(HTTP_PATH);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/post";
    char HTTP_DATA[] = "Data to post";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpsPost(HTTP_PATH, HTTP_DATA);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/put";
    char HTTP_DATA[] = "Data";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpsPut(HTTP_PATH, HTTP_DATA);
}

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: 

{
    /////////////////////////////////////////////////////////////////
    char HTTP_PATH[] = "/delete";
    /////////////////////////////////////////////////////////////////
    
    WIFI_PRO_V3.httpsDelete(HTTP_PATH);
}

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: 

	{
		/////////////////////////////
		char type[] = "https"; 
		char host[] = "10.10.10.1”;
		char port[] = "443";
		/////////////////////////////
		
		WIFI_PRO_V3.sendFrameToMeshlium( type, host, port, frame.buffer, frame.length);
	}

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: 

{
    ///////////////////////////////////////
    char HTTP_SERVER[] = "test.mosquitto.org";
    uint16_t HTTP_PORT = 1883;
    char USER[] = "client_id";
    ///////////////////////////////////////

    WIFI_PRO_V3.mqttConfiguration(HTTP_SERVER,USER, HTTP_PORT, WaspWIFI_v3::MQTT_TLS_DISABLED);
}

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: 

{
    char certificate[] =//
    "-----BEGIN CERTIFICATE-----\r\n"\
    "MIIEAzCCAuugAwIBAgIUBY1hlCGvdj4NhBXkZ/uLUZNILAwwDQYJKoZIhvcNAQEL\r\n"\
    "BQAwgZAxCzAJBgNVBAYTAkdCMRcwFQYDVQQIDA5Vbml0ZWQgS2luZ2RvbTEOMAwG\r\n"\
    "A1UEBwwFRGVyYnkxEjAQBgNVBAoMCU1vc3F1aXR0bzELMAkGA1UECwwCQ0ExFjAU\r\n"\
    "BgNVBAMMDW1vc3F1aXR0by5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvZ2VyQGF0Y2hv\r\n"\
    "by5vcmcwHhcNMjAwNjA5MTEwNjM5WhcNMzAwNjA3MTEwNjM5WjCBkDELMAkGA1UE\r\n"\
    "BhMCR0IxFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTES\r\n"\
    "MBAGA1UECgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVp\r\n"\
    "dHRvLm9yZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzCCASIwDQYJ\r\n"\
    "KoZIhvcNAQEBBQADggEPADCCAQoCggEBAME0HKmIzfTOwkKLT3THHe+ObdizamPg\r\n"\
    "UZmD64Tf3zJdNeYGYn4CEXbyP6fy3tWc8S2boW6dzrH8SdFf9uo320GJA9B7U1FW\r\n"\
    "Te3xda/Lm3JFfaHjkWw7jBwcauQZjpGINHapHRlpiCZsquAthOgxW9SgDgYlGzEA\r\n"\
    "s06pkEFiMw+qDfLo/sxFKB6vQlFekMeCymjLCbNwPJyqyhFmPWwio/PDMruBTzPH\r\n"\
    "3cioBnrJWKXc3OjXdLGFJOfj7pP0j/dr2LH72eSvv3PQQFl90CZPFhrCUcRHSSxo\r\n"\
    "E6yjGOdnz7f6PveLIB574kQORwt8ePn0yidrTC1ictikED3nHYhMUOUCAwEAAaNT\r\n"\
    "MFEwHQYDVR0OBBYEFPVV6xBUFPiGKDyo5V3+Hbh4N9YSMB8GA1UdIwQYMBaAFPVV\r\n"\
    "6xBUFPiGKDyo5V3+Hbh4N9YSMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL\r\n"\
    "BQADggEBAGa9kS21N70ThM6/H39D7mbVxKLBjVWe2TPsGfbl3rEDfZ+OKRZ2j6AC\r\n"\
    "6r7jb4TZO3dzF2p6dgbrlU71Y/4K0TdzIjRj3cQ3KSm41JvUQ0hZ/c04iGDg/xWf\r\n"\
    "+pp58nfPAYwuerruPNWmlStWAXf0UTqRtg4hQDWBuUFDJTuWuuBvEXudz74eh/wK\r\n"\
    "sMwfu1HFvjy5Z0iMDU8PUDepjVolOCue9ashlS4EB5IECdSR2TItnAIiIwimx839\r\n"\
    "LdUdRudafMu5T5Xma182OC0/u/xRlEm+tvKGGmfFcN0piqVl8OrSPBgIlb+1IKJE\r\n"\
    "m/XriWr/Cq4h/JfB7NTsezVslgkBaoU=\r\n"\
    "-----END CERTIFICATE-----";
    
    ///////////////////////////////////////
    char HTTP_SERVER[] = "test.mosquitto.org";
    uint16_t HTTP_PORT = 1883;
    char USER[] = "client_id";
    ///////////////////////////////////////
    
    WIFI_PRO_V3.setCA(0, certificate);
    
    WIFI_PRO_V3.mqttConfiguration(MQTT_SERVER,"user", MQTT_PORT, WaspWIFI_v3::MQTT_TLS_ENABLED);
}

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: 

{
    WIFI_PRO_V3.mqttPublishTopic("myTopic",WaspWIFI_v3::QOS_1,WaspWIFI_v3::RETAINED,"Temp:17");
}

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: 

{
    WIFI_PRO_V3.mqttGetTopicData("myTopic",WaspWIFI_v3::QOS_1);
}

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: 

{
    WIFI_PRO_V3.mqttSubscribeTopic("myTopic",WaspWIFI_v3::QOS_1);
}

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: 

{
    WIFI_PRO_V3.mqttReceive(60000);
}

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: 

{
    WIFI_PRO_V3.getFirmwareVersion();
}

Related variable:

WIFI_PRO_V3._firmwareVersion → Stores the firmware version

PreviousHardwareNextCode examples and extended information

Last updated