Metadata-Version: 2.4
Name: g2labs-blester
Version: 0.1.0
Summary: BLE scanner daemon that publishes findings to an MQTT topic
Author-email: Grzegorz Grzęda <grzegorz.grzeda@g2labs.pl>
License: MIT
Project-URL: Homepage, https://github.com/grzegorz-grzeda/g2labs-blester
Project-URL: Issues, https://github.com/grzegorz-grzeda/g2labs-blester/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bleak>=0.21
Requires-Dist: paho-mqtt>=1.6
Dynamic: license-file

# blester

BLE scanner daemon that publishes findings to an MQTT topic.

## Installation

```bash
pip install g2labs-blester
```

## Usage

```bash
blester --mqtt-host localhost --default-topic home/ble/findings
```

### Options

| Flag | Default | Description |
|---|---|---|
| `--mqtt-host` | *(required)* | MQTT broker hostname or IP |
| `--mqtt-port` | `1883` | MQTT broker port |
| `--mqtt-username` | — | MQTT username |
| `--mqtt-password` | — | MQTT password |
| `--scan-duration` | `5.0` | BLE scan window in seconds |
| `--scan-interval` | `0.0` | Pause between scans (0 = continuous) |
| `--log-level` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |

### Filtering

By default, devices with no matching filter are discarded. Set `--default-topic` to publish unmatched devices to a catch-all topic.

#### Inline filters (`--filter`, repeatable)

```bash
blester --mqtt-host localhost \
  --filter AA:BB:CC:DD:EE:FF=home/ble/lamp \
  --filter 11:22:33:44:55:66=home/ble/sensor \
  --default-topic home/ble/unknown
```

#### Filter config file (`--filter-config`)

```bash
blester --mqtt-host localhost --filter-config filters.json
```

`filters.json`:

```json
[
  {"mac": "AA:BB:CC:DD:EE:FF", "topic": "home/ble/lamp"},
  {"mac": "11:22:33:44:55:66", "topic": "home/ble/sensor"}
]
```

> `--filter` and `--filter-config` are mutually exclusive.

## MQTT payload

Each discovered device is published as a JSON object:

```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "name": "MyDevice",
  "rssi": -72,
  "manufacturer_data": {"76": "0215..."},
  "service_uuids": ["0000180f-0000-1000-8000-00805f9b34fb"]
}
```

## Requirements

- Python 3.9+
- Bluetooth adapter with BLE support
- Linux: `bluetoothd` running; may need `CAP_NET_ADMIN` or run as root

## License

MIT © Grzegorz Grzęda
