Mesh Access Module (ID 10)

For the different key types used, refer to the encryption types in the Specification.

Ids Because mesh packets need a sender and receiver id, it would not be possible to connect to another mesh as the nodeIds might clash. When a node connects to another device using a MeshAccessConnection, it will assign a virtualPartnerId to the other device, which is unique in the mesh. This partnerId is temporary (only while the connection lasts) and can be used to address the device during its connection.

The device does not get to know this virtual id and can operate with its own nodeId while using the connection. The node with modify received packets and will replace the devices id by the temporary id. It will also inspect packets before sending them to the other device and will translate the virtual id back into the id of the device before transmitting the packet over the MeshAccessConnection.

A node that connects to another mesh will need to specify the tunnelType, it can be on of the following:

Depending on the key type, certain messages are not allowed to be sent through a MeshAccessConnection. The key type can be any of the EncryptionKeys. To find out which key provides which level of access check CheckmeshAccessPacketAuthorization function. It return access level base on key type. Assuming the key is correct set of access right will be granted for the request with that key. The MeshAccessConnection passes on an incoming message to all modules. The modules can then decide if they want to whitelist or blacklist a message. It is also possible to restrict the message to be sent to the local node only. Blacklisting always has preference over whitelisting. If a message got blacklisted by a module, it cannot get whitelisted by another module. The reason behind is that someone who knows e.g. NodeKey should be able to communicate with given node but not with other nodes from that network. For that use case NetworkKey also exists that allows to communicate with whole network. But this access can be limited and granted to e.g. only 1 person.

All of the MeshAccess data is encoded in little endian.

The Mesh Configuration and Access Service is broadcasted by active nodes that provide mesh access to smartphones or other devices through GATT. The MeshAccessBroadcast also has a scan response that reports the serial number of the node as the "Short Local Name". This is helpful for identifying devices when using 3rd party applications.

The Mesh Access Service is offered under a different UUID (a 128-bit UUID) in order to seperate different services from each other.

After a connection is made, it is necessary to register notifications on the TX characteristic in order to receive data from the node. Do not send any data before notifications are enabled!

To establish a connection, the following steps need to be performed:

Encryption and MIC calculation uses three AES encryptions at the moment to prevent a discovered packet forgery attack under certain conditions. Future versions of the handshake may employ different encryption.

Once a connection is set to encrypted state - during the initial encryption handshake - all messages must be encrypted with a trailing Message Integrity Check (MIC). The data has the following format:

Because an encrypted packet has only 16 bytes of payload, message splitting must account for this. A connection with an MTU of 20 will first split packets into chunks of 20 bytes (2 byte splitting overhead, 18 byte content). After encryption is activated, the chunks have a size of 16 bytes.

If the first message were to be encrypted with a nonce of 1, then the mic would have been generated with a nonce of 2. The next message to be sent must by encrypted with a nonce of 3.

A session key (sessionKey) is generated by creating a 16-byte plaintext message padded with 0x00. The first two bytes (1-2) must contain the nodeId of the central device. Bytes 3-10 must contain the nonce. This plaintext is then encrypted using the chosen key. In case the key is a user key, the key must first be derived from the userBaseKey. This works by creating a 0x00 padded 16-byte cleartext, storing the keyId in the first 4 bytes of the message and encrypting the cleartext with the userBaseKey. The resulting ciphertext is the derived user key.

Instructs a node to build a MeshAccessConneciton to another node. The connection state will be notified back to the requester. Refer to Specification for the key types.

The node responds with information about the connection state changes. In this message, the node provides the virtual partner ID that was assigned to the node connected over the MeshAccessConnection.

Instructs a node to build a MeshAccessConneciton to another node. The connection state will be notified back to the requester. Refer to Specification for the key types. If no BLE address is given, the node will first scan for broadcast messages and will try to connect after it receives a matching one. If the BLE address is given, the connection will be established without any additional scanning, which is faster. Even if the BLE address given does not match, the node will still try to scan for the serial number as a fallback.

serial number is the serial number of the other device that the connection will be established to.

keyId should start at 1.

nodeId_of_partner_after_connect must be inside the range of organization wide unique nodeIds [33000, 57999].

initial_keep_alive is merely a suggestion to the node. There are a lot of cases where a connection can also be prematurely disconnected.

forceMode is merely a suggestion to the node. The node is supposed to use parameters for the connection which lead to faster connections and connect more reliably.

Once the connection was established or cancelled, it is answered with the following JSON:

where code can have the following values:

If the connection state changes, the sender of this message is informed about the new state with this message. In this message, the node provides the virtual partner ID that was assigned to the node connected over the MeshAccessConnection.

Disconnect from a device if it is connected via a MeshAccessConnection to that node.

The central starts the encryption process by sending the following unencrypted packet:

The peripheral will generate a random nonce with a length of 8 bytes and answer with an unencrypted packet. The peripheral can also start to generate the session decryption key at this time (cf. Session Key Generation generation chapter). After sending this packet, the peripheral only accepts encrypted packets.

The central must now generate a random 8 byte nonce as well. It is then able to calculate both session keys, the key for encryption and the key for decryption. It will then send the following packet, but in encrypted form. The ANonce is used to generate the session encryption key for sending packets and the SNonce is used to calculate the session decryption key for receiving packets.

The peripheral answers with the final handshake packet to confirm that the handshake was completed successfully. This packet is encrypted before transmission.

If a connection receives undecryptable data it informs the connection partner by sending this unencrypted message and resets the handshake. After this happens, the connection does not process any data other than a new handshake. To send more data, the handshake has to be completed successfully. This is done in case the Nonces run out of sync between the connection partners. This can happen if the stack, e.g. of a mobile device silently drops packets and does not inform the application.