CXBTH Command - Bluetooth BLE Configuration
Configures the usage mode of the Bluetooth (BLE) module.
What is it for?
| Use case | Description |
|---|---|
| 📱 Wireless configuration | Send commands from smartphone |
| 🔧 Diagnostics | Access the device wirelessly |
| 📊 Data download | Get logs via Bluetooth |
| 📡 Report destination | Send reports to BLE device |
Description
It is very important to update the device with the appropriate version that includes this functionality. It can be updated via FOTA, replacing the update file extension with .nimble.ota.
Enabling the device to connect via BLE in SPP mode, with a master device. This master device will be able to send and receive commands through the generated virtual serial port as if it were another serial port of the device.
Commands
Configure
SCXBTHa,nombre,pin,timeout,peerQuery
QCXBTHResponse
RCXBTHa,nombre,pin,timeout,peerParameters
| Field | Description | Values |
|---|---|---|
| a | Enable | 0=Disabled, 1=Enabled |
| nombre | BLE device name (displayed) | Up to 16 characters |
| pin | Bluetooth access PIN | Up to 16 characters |
| timeout | Seconds to authenticate before the session is closed | 0 = 10 s (default) |
| peer | Remote device to connect to as master | Up to 16 characters. Empty = slave (classic behavior) |
Fields are cumulative: an SCXBTH with fewer fields leaves the ones it does not send untouched. >SCXBTH1,Name,1234< keeps the current timeout and peer.
Examples
Enable Bluetooth module
>SCXBTH1,MiDispositivo,1234<Enables the Bluetooth module to be enabled, display the name MiDispositivo, and allow device connections using PIN 1234.
Disable reading
>SCXBTH0<Link between two devices (master mode)
Since firmware v1.09.26 a device can actively connect to another device over BLE, instead of waiting for a phone or gateway to connect to it. This lets a device with no connection of its own report through one that has it.
Typical example: a device mounted on a trailer measures angles with the accelerometer and has no SIM. It links over BLE to the tractor’s device, which forwards the data to the platform over its cellular channel.
Configuration defines the role
peer | Role | Behavior |
|---|---|---|
| Empty | Slave | Advertises and waits for connections (the usual behavior) |
| A name | Master | Looks for that device and connects to it |
Set peer on one side only of the pair. Both devices must share the same PIN: the master uses it to authenticate against the slave.
peer accepts up to 16 characters, including the * used by roaming mode.
// On the tractor's device (slave): no peer
>SCXBTH1,TRACTOR_01,1234,10,<
// On the trailer's device (master): points at the tractor
>SCXBTH1,TRAILER_07,1234,10,TRACTOR_01<The master finds the name, connects, authenticates and stays linked. If the link drops — distance, a reboot of the other device, or an update — it reconnects on its own.
Remote device pinning
On the first successful authentication the master remembers the physical address of the remote device. From then on it only reconnects to that device, even if another one advertises the same name. The memory is cleared when peer is reconfigured.
This prevents a foreign device with the same name from taking over the link. Do the first link during installation, with both devices close together.
Roaming mode
If the remote device changes — for example a trailer that works with different tractors — prefix the name with *:
>SCXBTH1,TRAILER_07,1234,10,*TRACTOR<With * the physical address is not pinned: the master connects to the device with that name and the strongest signal, which is the one towing it. Every device in the fleet shares the name and PIN. Since the * takes up one slot, the name can be up to 15 characters long.
Roaming mode does not pin the remote device, so it does not protect against a foreign device advertising the same name. Use it only when the remote really does change.
Reaching the master while it is linked
On devices that support a single simultaneous BLE connection, the master stops advertising while it is linked: you will not be able to connect to it with a phone or the configuration app. It advertises again only when the link drops and it is retrying. To configure it with the link up, use another channel (serial, cellular) or clear peer first.
Reports over the link
With the link up, the BTH destination works as always: reports sent to ;@BTH travel to the remote device. If the link is down they are queued and delivered on reconnect — nothing is lost.
On the receiving device, incoming data can be captured with a CXXB capturer using medium B (Bluetooth) and forwarded to the platform as a user report. Each frame carries the ID of the device that produced it, so the platform can tell them apart.
Link status
QBTH exposes the role and the link status in fields 8 and 9.
BTH Destination for Reports
When the BTH module is enabled, the BTH destination is also enabled to generate reports to that destination.
For example, the command:
>SG1CQ000,BTH<Will generate a CQ report to the master device.
Connection Variable
The BTH_CONNECTED variable will be available for use in the event engine. When true, it will indicate an ongoing connection.
Compatibility
See Also
- BTH Command (IOT) - Connection and device-to-device link status
- BS Command (IOT) - BLE Scan
- BE Command (IOT) - BLE Beacons