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-scan

Install 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-scan

If 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
}