Specification

The JOIN_ME packet contains all the information that other nodes can use to determine their best connection partner. The messageId in the header must be set to 1. Future JOIN_ME packets can have a different messageId and different values that can then be used in the Cluster Score Function. The current implementation uses the clusterSize and the number of freeIn and freeOut connections.

Another type of advertising packet used by BlueRange Mesh uses the Service Data Adv Structure. This is important when dealing with mobile devices since some have hardware filtering with no support for manufacturer specific data.

BlueRange Mesh can be used to distribute all advertising packets that conform to the BLE specification. These can be Eddystone, iBeacon or any other kind of advertising messages. These are however not essential for BlueRange Mesh itself and are therefore not documented here. Have a look at the BeaconingModule for more information.

There are two types of module ids: the standard ModuleId has a size of one byte and is solely used by standardized modules. The VendorModuleId on the other hand uses 4 bytes to allow different vendors to develop modules that can run together in a single network without clashing with other modules that were written by different vendors on different nodes in the same mesh network. This is done by including a vendor id as part of the VendorModuleId. This vendor id must be set to the company identifier that can be acquired from the BLE SIG. See this page for instructions on how to get this company identifier and for a complete list of known company identifiers.

VendorModuleIds were not part of BlueRange Mesh prior to version 1.x.x. BlueRange Mesh tries to keep the usage of VendorModuleIds as easy as possible and does most of the work when using VendorModuleIds. Some parts will e.g. use different message types for messages with ModuleId and VendorModuleId and other parts use the ModuleIdWrapper to be able to work with both module id types in the same data structure. As a convention, whenever a ModuleId is printed out as a string, it is printed as a decimal number, e.g. 123. VendorModuleIds on the other hand are printed as a string like this "0xABCD01F0" to make the individual parts easier to read.

To get started, see Implementing a Custom Module.

In the implementation, the ModuleId is either used as a single byte or stored using the 4 byte ModuleIdWrapper with the subId and vendorId set to 0. This depends on the implementation of a feature.

The VendorModuleId is always composed of 4 bytes can be put together using the ModuleIdWrapper.

Modules use an bigger message header to guarantee that there are no collisions between different functionality. The following describes the format of the header:

The connPacketModule differs from the connPacketModuleVendor header in the size of the module id. They can be differentiated by checking the first byte, which is set to ModuleId::VENDOR_MODULE_ID_PREFIX (0xF0) in case of a VendorModuleId. While the connPacketModule has a size of 8 bytes, the connPacketModuleVendor needs 11 bytes.

The serialNumberIndex of this range starts with 0 for the serial number BBBBB and increments up to 0x7FFFFFFF for the serial number D8PJQ8K. This range should not be used without consulting us beforehand because serial numbers will clash otherwise. We assign sub-ranges to our partners which allows them to use serial numbers with 5 characters.

To provide beginners with an easy method for testing BlueRange Mesh, we decided to open source a part of our proprietary range that contains nicely readable serial numbers. This range starts from 2673000 (FMBBB) and ranges until 2699999 (FM999).By default, the serial number is generated randomly (from the unique deviceId stored in the chipset) within this testing range if there is no UICR data available (see generateRandomSerialAndNodeId in the Config class). This makes it easier to start testing BlueRange Mesh. You should not distribute products that use a serial number from this range as it will clash with others.

The open sourced serial number range that you can use for final products uses serial numbers with 7 characters to avoid a clash between different vendors. A serial number is constructed by setting the most significant bit of the serialNumberIndex to 1. The next 16 bits must be set to a two byte company identifier assigned by the Bluetooth SIG. The remaining 15 bits are used to generate the individual serial numbers for this vendorId. This gives each vendor the possibility to generate around 32 thousand unique serial numbers. (See VendorSerial type).

If you do not have a Bluetooth SIG company identifier yet, you can use the manufacturer id from M-Way Solutions (0x024D). This range starts from 0x81268000 (D9HCK3N) and ranges until 0x8126FFFF (D9HDSHW). You should not publicly distribute products that use this serial number range as it could clash with other serial numbers. If you want to distribute a product, you should register with the Bluetooth SIG to get a free company identifier that you can set as the MANUFACTURER_ID in the configuration.

Can only be used if a node is not enrolled and uses a key filled with all 0x00 for encryption.

This key is used for the lifetime of a device and is uniquely generated during production. It must be kept secure because it allows full configuration access, e.g. enrolling and removing the enrollment.

The network key is shared between all nodes that belong to a mesh network. Whoever is in posession of this key can configure all nodes in the network and can send any message. It is important to keep this key secret, but it is possible to change it if it is compromised.

This is a key that can’t be used to connect. It is used to derive all other user keys.

The organization key is shared between all networks of an organization. It allows access to a limited set of functionality, e.g. necessary for tracking assets between differen meshes. If the organization key leaks, it is necessary to reconfigure all meshes of the organization.

The restrained key is generated based on the node key. It is a node key with limited access rights.

The "restrained key" can be derived from the node key by using an AES-128 bit encryption by encrypting the ASCII-String "RESTRAINED_KEY00" (without terminating 0) using the node key as the AES key. Example values are:

The user base key is used to generate millions of user keys that can be given to users or user groups. A user key allows access to a limited set of commands and can be restricted in functionality depending on the use case. If the userBaseKey leaks, all userKeys have to be regenerated and distributed to users.