pb_ble.cli

  1"""
  2Command line tools to communicate with Pybricks devices via
  3connectionless Bluetooth messaging:
  4
  5- The [Pybricks BLE broadcaster](#ble-broadcaster) for **sending messages** to a Pybricks device (`pb_ble.cli.broadcast`).
  6- The [Pybricks BLE observer](#ble-observer) for **receiving messages** from a Pybricks device (`pb_ble.cli.observe`).
  7
  8## BLE broadcaster
  9
 10`pb_broadcast` is a CLI tool to send Pybricks BLE broadcasts.
 11
 12### Example
 13
 14To broadcast the values `"pybricks"`, `True` and `1.0` on channel 0:
 15
 16```sh
 17pb_broadcast 0 \"pybricks\" true 1.0
 18```
 19
 20The default timeout is 10 seconds, after which the advertisement is stopped.
 21To broadcast for an unlimited time, use `--timeout 0`.
 22
 23### Usage
 24
 25```
 26usage: pb_broadcast [-h] [--adapter ADAPTER] [--name NAME] [--timeout TIMEOUT] [--debug] data [data ...]
 27
 28Send Pybricks BLE broadcasts
 29
 30positional arguments:
 31  data               Data to broadcast: channel followed by JSON values
 32
 33options:
 34  -h, --help         show this help message and exit
 35  --adapter ADAPTER  Bluetooth adapter name (default: hci0)
 36  --name NAME        Bluetooth device name to use for advertisements (default: pb_vhub)
 37  --timeout TIMEOUT  Broadcast timeout in seconds (default: 10)
 38  --debug            Enable debug logging (default: False)
 39```
 40
 41## BLE observer
 42
 43`pb_observe` is a CLI tool to receive Pybricks BLE broadcasts via `passive` or `active` BLE scanning.
 44
 45- Passive scanning is the default and recommended, but requires BlueZ >= 5.56 with [experimental features enabled][bluez-experimental].
 46- Active scanning is provided as a well-supported fallback. It may negatively impact the power consumption of nearby BLE devices.
 47
 48### Example
 49
 50To observe broadcasts on channel 1 and 2:
 51
 52```sh
 53pb_observe 1 2
 54```
 55
 56To enable active scanning, use `--mode active`.
 57
 58### Usage
 59
 60```
 61usage: pb_observe [-h] [--adapter ADAPTER] [--rssi [-120 to 0]] [--pattern PATTERN] [--mode {active,passive}] [--debug] [N [0 to 255] ...]
 62
 63Observe Pybricks BLE broadcasts
 64
 65positional arguments:
 66  N [0 to 255]          Pybricks channels to observe, or all channels if not given. (default: None)
 67
 68options:
 69  -h, --help            show this help message and exit
 70  --adapter ADAPTER     Bluetooth adapter name (default: None)
 71  --rssi [-120 to 0]    RSSI threshold (default: None)
 72  --pattern PATTERN     Device name pattern filter (default: Pybricks)
 73  --mode {active,passive}
 74                        BLE scanning mode (default: passive)
 75  --debug               Enable debug logging (default: False)
 76```
 77
 78[bluez-experimental]:https://wiki.archlinux.org/title/Bluetooth#Enabling_experimental_features
 79"""
 80
 81import datetime
 82import logging
 83import sys
 84
 85
 86def setup_cli_logging():
 87    """Configure logging for the CLI tools."""
 88    logging.basicConfig(
 89        stream=sys.stdout,
 90        level=logging.INFO,
 91        format="[%(asctime)s] [%(name)-20s] [%(levelname)-8s] %(message)s",
 92    )
 93
 94    # ISO8601 dateformat for logging including milliseconds
 95    logging.Formatter.formatTime = (  # type: ignore [method-assign]
 96        lambda self, record, datefmt=None: datetime.datetime.fromtimestamp(
 97            record.created, datetime.timezone.utc
 98        )
 99        .astimezone()
100        .isoformat(sep="T", timespec="milliseconds")
101    )
102
103
104__all__ = ()