Network Concepts
Network Tree
The Meshtech BLE network uses a tree structure with the gateway as the root.
There are three types of network devices:
- Gateway
- Extender
- Node (or Temporary)
The gateway is the root of the network and functions as a gateway for relaying traffic between the BLE network and the backend/cloud. A gateway can have up to 7 (nRF51) or 18 (nRF52) child connections. The maximum number of connections is device dependent.
An extender is used to extend the range and capacity of the network. The extender has one parent connection and up to 6 (nRF51) or 18 (nRF52) child connections. The maximum number of connections is device dependent and the exact configuration of the downlinks is dictated by the 0x8210 - Downlink Configuration property. A child can be an extender or a node. In addition to relaying traffic to/from its children, an extender will scan for advertisement packages from Unconnected devices that are not part of the network. This is typically devices operating in Unconnected mode reporting information, but can also be extenders or nodes that wants to join the network. The extender will also establish connection to devices operating in Unconnected mode in order to write or read properties. Such connections are made on request from the gateway/top-level system and are short-lived request-response sessions.
A node is a leaf node in the network tree, it cannot have children. These devices are typically low-power sensors. Some node devices also have the capability to scan for advertisement packages from Unconnected devices, however, a node cannot establish connection to devices other than its parent.
The maximum depth of the network tree is 11. The depth of gateway/root is defined as 0.
All network devices operate in Connected mode, which means they try to maintain a connection to a parent device.
A device that does not support Connected mode, i.e. being part of the network tree, can make a temporary connection to the network to download new firmware. The device will then operate similar to a node. A device firmware update request must be written to the device before it will establish a temporary connection to an extender and download firmware.
Network Lock
Network Lock is a byte that must match to establish a permanent connection between the devices which support Connected mode. However, the devices in Unconnected mode can establish a temporary connection even though they don't have a Network Lock feature. Setting Network Lock allows to make two or more logical network side-by-side at the same location. Network lock can be set in Storage mode to make sure the network lock match with desired network after switching to Connected mode.
Temporary Connection
Temporary connection is used to upgrade firmware if a device doesn't support Connected mode.
Example
MT Wristband 211 has to establish a temporary connection to upgrade firmware because it doesn't support Connected mode.
A temporary connection is established between the devices for time of upgrade.
Example
If device firmware update takes 5 minutes, a temporary connection remains established for 5 minutes.
A device establishes a temporary connection by itself on a firmware update request.
Device Modes
Storage Mode
A device's default mode. The devices may be in a Storage mode when not used. Such devices seldom send MT messages in order to only notify that they're ready to connect. Storage mode is used as a sleep mode to reduce the device's resources usage and save battery life.
When a device is advertising in storage mode, Storage Mode Events (0x8112 - Storage Mode Event) are generated. This can be looked upon as a storage mode "heartbeat".
Connected Mode
Connected mode indicates a permanent connection between the devices. The devices send MT messages constantly in Connected mode.
Unconnected Mode
In Unconnected mode, the devices send the MT messages only if they need to send them.
Channels and frequency
The 40 channels are divided into three advertising channels and 37 data channels.
The three advertising channels are:
-
37 channel at frequency 2402 MHz
-
38 channel at frequency 2426 MHz
-
39 channel at frequency 2480 MHz
Each single packet is sent three times from each sensor, one time on each of these advertising channels. The receiver should be able to listen to the frequency and receive the package.
The other 37 channels are used to exchange data packets.
In Connected mode, the other 37 channels use frequency jumping mode as default by Bluetooth 4.x.
DFU Mode
A device switches to DFU mode for a device firmware update over-the-air.
When a device advertises in DFU mode the gateway can generate a custom event upstream if supported by the backend APIs. This can be looked upon as a DFU mode "heartbeat".
Properties
Properties typically represent state for a device. Most of them are reported automatically by the device itself, some must be explicitly requested.
A property can also be used to trigger a command. In this case, there is no value associated with the write operation since the write operation itself triggers the command.
The documentation for each device will list the identifiers for the properties the device supports. A firmware update may add support for new properties and in some cases remove deprecated properties.
A backend/top-level system will normally only store the latest value of properties. The properties will normally be stored in a shadow representation of the device on the server-side for easy access by the frontend/application.
Measurements
Identifiers are also used when reporting measurements. The identifier for a measurement will typically at least have a value.
Measurements are normally done at regular intervals and are often logged by the backend.
Each measurement has a sequence number byte.
Events
Identifiers are also used when reporting events.
Events are similar to measurements, but normally happen any time (not periodically). They typically have no data associated.
Each event has a sequence number byte.
A button click is an example of an event.
Sequence Number
Sequence number (seq) is the sequence number for the event/packet from the
device. The sequence number is a value in the range 0 - 255. When a packet is
picked up by multiple gateways, the backend server can identify duplicates using
the sequence number. The sequence number can be used to check if samples arrive
in order. If a device sends two packets (sequence number 10 and 11) with very
short interval, the last packet (11) could follow a faster route than (10) and
arrive earlier to the backend server. Sequence number only applies to devices
operating in Unconnected mode. If device does not support sequence number, -1
is used.
Heartbeat
Heartbeat is common for all devices. For example, if the device is removed from the network or if the battery runs out, heartbeat is used to detect if the device still works. When property throttling is enabled, nothing will be heard from the device except the heartbeat when nothing changes. Overall, heartbeat is needed to make sure that the device is still working.
Network Mode
A network can operate in various modes. This is configured by the 0x8228 - Network Mode property on the gateway.
In the default mode (Scan), the extenders will always scan.
In Power Saving mode, the gateway will turn off scan on all extenders when the network structure has been stable for 5 minutes. If there is a change in the network structure, the gateway will turn on scan again for the entire network.
In Power Saving mode an extender will automatically restart scanning temporarily to allow devices to reconnect. Power Saving mode is ideal for networks with battery powered extenders and connected sensors.
Power Saving mode cannot be used in combination with unconnected sensors. Enabling/provisioning of devices in storage mode must be done in the default Scan mode.
Note
To use this feature all the extenders in the network must support the 0xFF00 - Scan Mode property.
Priority
All packets that are sent through the Meshtech BLE network has a priority associated with it. This priority is used to determine which packets will be discarded if at any point through the network there is not enough bandwidth to forward all packets, both up and downstream. Packets with lower priority will be discarded first.
| Priority value | Priority |
|---|---|
| 4 | Highest |
| 3 | High |
| 2 | Medium |
| 1 | Low |
| 0 | Lowest |