Connecting Waspmote to other BLE devices

Besides advertising data, there is a more robust and reliable way of transmitting data. The data sent using connections processes can be acknowledged and encrypted.

When a BLE device acting as scanner detects advertisements of a BLE node in advertiser role, the scanner can try to connect the advertiser sending a connection request with the function connectDirect(). If the connection is successful, the scanner will become the master (or central) of the connection, and the advertiser will be the slave (or peripheral).

According to the Bluetooth standard, a slave can be connected only to a single master, while a master can be connected to multiple slaves.

Configuring a connection

The user can easily connect using the connecDirect() function and providing the MAC address of the BLE node to be connected. If this option is used, default connection parameters will be used.

Example of use:

{
    BLE.connectDirect(\"0007806AF308\") ;
}

However, the connection parameters can be also configured, as explained below. It is important to say that connection parameters can be updated during the connection.

Connection intervals

The minimum and maximum connection intervals can be specified also with the connectDirect() function, but using other prototype defined for that purpose. The lowest connection interval is 7.5 ms, and the maximum is 4 s. The maximum connection interval must be equal or greater than the minimum.

Supervision timeout

This is the timeout to wait till drop the connection, in units of 10 ms. Range between 10ms and 32 seconds.

Connection latency

This parameter configures how many connection intervals can be skipped by the slave. It is useful in scenarios where data is not needed every connection interval, to save power on the slave side. Latency range goes from 0 to 500.

For example, if the user sets a connection interval of 10 ms and a latency of 9, then the slave will communicate with the master each 100 ms, but it can communicate each 10 ms if needed.

On the other hand, slave latency * connection interval can not be bigger than supervision timeout.

Example of use:

{
    BLE.connectDirect(BLEAddress,
                      conn_interval_min,
                      conn_interval_max,
                      timeout,
                      latency)
}

Connection handle

When the master opens a connection, each connection is identified by a handler, saved on variable connection_handle.

Connection RSSI

The RSSI of the connection can be known by the function getRSSI(). The range is the same then the defined for the scanned devices.

Disconnection

When the user wants to terminate a connection manually, it can be done using the disconnect() function and the corresponding connection handle.

Example of use:

{
    BLE.disconnect(BLE.connection_handle);
}

Besides that, the user can now in every moment the status of the BLE module with the getStatus() function.

Example of use:

{
    BLE.getStatus();
}

The connection parameters are illustrated in the diagram below:

Figure: Connection parameters

In the Waspmote Development section you can find a complete example about using this function.

Go to: https://development.libelium.com/ble-06-configuring-a-connection/

Sending data

There are two terms used when talking about the two members of a connection.

• Client: Device which accesses a remote BLE. Usually the master is also the client. Clients are usually smart phones, tablets or PCs.

• Server: Device with a local database that can be accessed by the remote client. The slave can be also the server. Servers are usually sensor nodes, like thermometers or hear rate sensors.

When a connection is established, there are four operations to move data between clients and servers. All of them are based of moving data of the characteristics defined inside the slave profile.

• Read: This operation is requested by the client, on a specific server attribute. The server responds with the requested data.

• Write: This operation is requested by the client, on a specific server attribute. The server stores the value sent by the client and it can optionally confirm the operation if notify / indicate properties are enabled.

• Notify: This operation is started by the server. When a client is subscribed to notifications on a certain characteristic, it will be informed immediately when a new value is written by the server on this attribute. The figure below shows the process.

• Indicate: This operation is equal to notify, but the entire process is acknowledged with a client message to the server.

In resume, the client can use read, write, notify and indicate operations to access data on a remote server, while the server stores the data locally and provides data access methods to a remote client. Next figure illustrates the process during a write operation when notifications and indications are enabled. Each step is also described.

Step 1

Once the connection is established, the master subscribe to a certain slave characteristic with a Notify / Indicate subscription.

Step 2

Waspmote writes into the BLE module (Slave) a new value on a local characteristic, using the function writeLocalAttribute(), and this change is notified to the master automatically.

Step 3

The difference between notify and indicate operations resides on this step. An acknowledge event is sent to the slave to indicate that the change on the value has been received. In this way, Waspmote can know if the master has received the information.

Figure: Notification and indication processes

Simple Read / write operations are thought when data is not needed to be acknowledged. However, It has to be clarified that read/write operations can be performed in two different ways: under own attributes and under slave attributes (through a connection).

In the first way, the node can read/write its own attributes defined in its profile, using the functions readLocalAttribute() and writeLocalAttribute(). In case of indicated writes (acknowledged) another prototype of writeLocalAttribute() has been defined. Maximum data size for local read /write operations is 32 bytes.

Example of use:

{
    // write a local attribute
    BLE.writeLocalAttribute(handle, data);
    // write a local attribute with indication.
    BLE.writeLocalAttribute(handle, BLE_ENABLE_INDICATE, data);
}

The other way consist of establish a connection with a slave and read/write its attributes remotely, therefore the local attributes will not be changed. It can be done using the functions attributeRead() and attributeWrite(). Maximum data size for remote read operations is 22 bytes, while write, notify and indicate are 20 bytes. The user can use these functions to subscribe to Notifiable / Indicable characteristics.

Example of use:

{
    // a connection with the device is required.
    if(BLE.connectDirect(\"0007806AF308\") == 1)
    {
        // read an attribute
        BLE.attributeRead();
        // save the read attribute
        (..)
        // write an attribute
        BLE.attributeWritte(connection, handle, data);
    }
}

When a read operation (local or remote) is done, the attribute value read is stored in the global variable attributeValue(). The user should save this value before reading or writing other attribute, otherwise it will be lost.

In the Waspmote Development section you can find some complete examples about using these functions.

Go to: http://www.libelium.com/development/waspmote/examples/?cat=communication-examples&subcat=bluetooth-low-energy

Encryption and bonding

In older Bluetooth standards, the user needed to pair with a remote device before connecting it. On the Bluetooth 4.0 standard, the user can connect to other remote BLE devices without any pairing process. Even the user can use advertisements to send a few amount of data, as it has been described in previous sections. However, these processes are not secure.

The Bluetooth 4.0 standard uses AES-128 link layer encryption. The encryption can be used in the connection processes to make them secure. The encryption of the connection can be started using the function encryptConnection(), providing the handler of the established connection. The handler is usually zero, unless other connections are enabled.

Example of use:

{
    BLE. encryptConnection(handler);
}

By default, Man In The Middle (MITM) is set to the "just works" mode, but the user can change this parameter with the function setSecurityParameters(), besides than key size and I/O capabilities. More information is provided on the manufacturer documentation.

Example of use:

{
    // setSecurityParameters( mitm, min_key_size, io_capabilities)
    // enable MITM, set key size to 7 and IO capabilities to display only.
    BLE.setSecurityParameters(BLE_ENABLE_MITM, 7, 0);
}

The bonding processes are the long term storage of encryption keys used by each BLE module. To enable bonding in a BLE device, the function setBondableMode() should be used.

Example of use:

{
    BLE.setBondableMode(BLE_ENABLE_BONDING);
}

Starting a connection with bonding will imply next steps:

1. Node 1 advertises

2. Node 2 detects advertisements of node 1

3. Node 2 starts a connection with node 1

4. Node 2 request bonding

5. Both nodes exchange keys

6. Both nodes store keys for future usage

The 6 digit key can be set using the setKey() function. Besides that, the number of bonded devices can be listed with getBonding() function. On the other hand, the function deleteBonding() erases from memory all bonded devices.

Finally, there is a specific characteristic property which enables authenticated read / write operations. When this property is enabled, both devices involved in the connection needs to be bonded and the link encrypted. Refer to the module manufacturer documentation for more information.

WhiteList

The Whitelist is a list of BLE devices with special permissions. It is thought to save trusted BLE devices, allowed to establish a connection or write certain attributes. It is also used in active scans (see advertisement policy and scan policy).

A new member can be added using the whiteListAppend() function, providing its MAC address. It also can be removed with the whiteListRemove() function. If the user wants to clear all whitelist, the function whiteListClear() should be used.

Example of use:

{
    // add new member
    BLE.whiteListAppend(\"001122334455\");
    //remove new member
    BLE.whiteListRemove(\"001122334455\");
    // clear all members
    BLE.whiteListClear();
}

This functions will not have effect while advertising, scanning or being connected, so the Whitelist should be managed in the right moment.

In the Waspmote Development section you can find a complete example about using this function.

Go to: https://development.libelium.com/ble-14-managing-whitelist/