ble-scan
Command-line tool that scans for BLE (Bluetooth Low Energy) peripheral advertisements and publishes them (JSON-encoded) to a MQTT topic, where the data can be processed by other software.
Installation
Prerequisites
- All prerequisites of the the noble library that is being used for BLE communication
- Node.js version 14 or later
Install
To install ble-scan globally (so that you have it on your path), run
$ npm install -g ble-scanInstall on Linux systems
On Linux systems, you will probably need to run this command with sudo and use the --unsafe-perm flag:
$ sudo npm install -g --unsafe-perm ble-scanIf you want to run ble-scan without without sudo/root permissions, you will probably also need to run (see here for more information):
$ sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)Usage
Command-line arguments
$ ble-scan --help
usage: ble-scan [-h] [--interval INTERVAL] [--time TIME] [--host HOST]
[--port PORT] [--client_id CLIENT_ID] [--username USERNAME]
[--password PASSWORD] [--base_topic BASE_TOPIC]
[--advertisements_topic ADVERTISEMENTS_TOPIC]
[--status_topic STATUS_TOPIC] [--online_message ONLINE_MESSAGE]
[--offline_message OFFLINE_MESSAGE]
[--status_retain | --no-status_retain | -sr] [--qos {0,1,2}]
[--keepalive KEEPALIVE]
Scan for BLE (Bluetooth Low Energy) advertisements
optional arguments:
-h, --help show this help message and exit
--interval INTERVAL, -i INTERVAL
The minimum interval between publishing two
advertisements from the same peripheral, in seconds
(0=publish all advertisements) (default: 60)
--time TIME, -t TIME The time to scan for BLE advertisements, in seconds.
After the specified time has passed, the program will
terminate (0=scan forever) (default: 12)
--host HOST, -H HOST The hostname/IP address of the the broker (default:
127.0.0.1)
--port PORT, -p PORT The port number of the the broker (default: 1883)
--client_id CLIENT_ID, -c CLIENT_ID
The client ID to use for connecting to the broker
(default: ble-scan)
--username USERNAME, -u USERNAME
The username required by your broker, if any (default:
null)
--password PASSWORD, -P PASSWORD
The password required by your broker, if any (default:
null)
--base_topic BASE_TOPIC, -bt BASE_TOPIC
The "base" topic. When passing topic names, the
substring "#{base_topic}" will be replaced with this
value (default: ble-scan)
--advertisements_topic ADVERTISEMENTS_TOPIC, -at ADVERTISEMENTS_TOPIC
The topic where scanned BLE advertisement messages
will be published to (default:
#{base_topic}/advertisements)
--status_topic STATUS_TOPIC, -st STATUS_TOPIC
The topic where status messages will be published to
(default: #{base_topic}/status)
--online_message ONLINE_MESSAGE
The message that will be published to the status topic
when going online (default: online)
--offline_message OFFLINE_MESSAGE
The message that will be published to the status topic
when going offline (default: offline)
--status_retain, --no-status_retain, -sr
The retain flag for status (online/offline) messages
(default: true) (default: true)
--qos {0,1,2}, -q {0,1,2}
The QOS (Quality of service) level to use (default: 2)
--keepalive KEEPALIVE, -k KEEPALIVE
The keepalive time, in seconds (default: 60)
The most important argument is the --host argument for setting the hostname/IP address of the MQTT broker.
If you need to authenticate to the MQTT broker, you will also need to --username, --password and maybe the --client_id arguments.
By default, ble-scan will scan for 12 seconds (the maximum advertising interval is 11.24 seconds) and then terminate. With these default settings, ble-scan is intended to be periodically run, for example via a cronjob.
Data format
Here's a sample JSON message (representing one advertisement) with comments:
{
"address": { // The Bluetooth address, in multiple formats
"long": "12:34:56:78:9A:BC", // The Bluetooth address, in "long" format
"short": "123456789ABC" // The Bluetooth address, in "short" format
},
"address_type": "random", // The address type, "public" or "random"
"connectable": true, // Boolean flag that indicates if the device is connectable
"service_uuids": [ // Array with advertised service UUIDs
{ // Service UUID, in multiple formats
"full": "00000AF0-0000-1000-8000-00805F9B34FB", // Service UUID, in "long" (string) format
"short": 2800 // Service UUID, in "short" (integer) format. Only available for services with 16-/32-Bit-UUID, null otherwise
}
],
"solicitation_service_uuids": [ // Array with solicitation service UUIDs (rarely used)
{ // Service UUID, in multiple formats
"full": "00000AF1-0000-1000-8000-00805F9B34FB", // Service UUID, in "long" (string) format
"short": 2801 // Service UUID, in "short" (integer) format. Only available for services with 16-/32-Bit-UUID, null otherwise
}
],
"manufacturer_data": { // The manufacturer data, in multiple formats
"hex": "FE034EA5", // Manufacturer data, as a hexadecimal string
"array": [254,3,78,165] // Manufacturer data, as an array of uint8 numbers
},
"service_datas": [ // Array with service data object
{ // A service data object, contains the UUID and data of the service
"uuid": { // The service UUID, in multiple formats
"long": "0000FE95-0000-1000-8000-00805F9B34FB", // Service UUID, in "long" (string) format
"short": 65173 // Service UUID, in "short" (integer) format. Only available for services with 16-/32-Bit-UUID, null otherwise
},
"data": { // The service data, in multiple formats
"hex": "EF3E7DA74813", // Service data, as a hexadecimal string
"array": [239,62,125,167,72,19] // Service data, as an array of uint8 numbers
}
}
],
"rssi": -86, // The RSSI value (signal quality)
"timestamp": 1612336387228 // Timestamp when the advertisement was received, in milliseconds since the epoch
}