docs: add ESP32 proxy to getting started guide#67
Conversation
Adds quick setup instructions, config.yaml example, and simplified Docker compose reference. Also bumps Node.js version to v20.19+ in prerequisites and fixes currency/formatting.
There was a problem hiding this comment.
Pull request overview
Updates the Getting Started guide to document using an ESP32 as a remote BLE-to-MQTT “proxy” for deployments where the host has no Bluetooth adapter, and aligns prerequisites/hardware info with recent project changes.
Changes:
- Adds an “ESP32 BLE Proxy” section with quick setup steps, example
config.yaml, and a simplified Docker Compose invocation. - Bumps the documented Node.js minimum version to
v20.19+. - Adjusts some formatting/punctuation and updates hardware pricing to €.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```yaml | ||
| # config.yaml | ||
| ble: | ||
| handler: mqtt-proxy | ||
| mqtt_proxy: | ||
| broker: mqtt://your-broker:1883 | ||
| ``` |
There was a problem hiding this comment.
The fenced YAML block is not indented under list item 3, so in CommonMark/VitePress it will render as a separate block and can break/reset the ordered list numbering. Indent the code fence (and its contents) to keep it within the list item.
| ```yaml | |
| # config.yaml | |
| ble: | |
| handler: mqtt-proxy | |
| mqtt_proxy: | |
| broker: mqtt://your-broker:1883 | |
| ``` | |
| ```yaml | |
| # config.yaml | |
| ble: | |
| handler: mqtt-proxy | |
| mqtt_proxy: | |
| broker: mqtt://your-broker:1883 |
| ```bash | ||
| # No BlueZ, no D-Bus, no NET_ADMIN needed | ||
| docker compose -f docker-compose.mqtt-proxy.yml up -d | ||
| ``` |
There was a problem hiding this comment.
This fenced bash block is not indented under list item 4, which can cause Markdown renderers to treat it as outside the ordered list (breaking numbering/formatting). Indent the fence and command so it stays part of the list item.
| ```bash | |
| # No BlueZ, no D-Bus, no NET_ADMIN needed | |
| docker compose -f docker-compose.mqtt-proxy.yml up -d | |
| ``` | |
| ```bash | |
| # No BlueZ, no D-Bus, no NET_ADMIN needed | |
| docker compose -f docker-compose.mqtt-proxy.yml up -d |
| Or set the handler via environment variable: | ||
|
|
||
| ```bash | ||
| BLE_HANDLER=mqtt-proxy npm start | ||
| ``` |
There was a problem hiding this comment.
The BLE_HANDLER=mqtt-proxy env var only takes effect if ble.mqtt_proxy is configured (otherwise it is ignored with a warning). This example reads like setting the env var alone is sufficient; consider clarifying that the broker/topic config still needs to be present in config.yaml (or provided via whatever supported config mechanism).
| ble: | ||
| handler: mqtt-proxy | ||
| mqtt_proxy: | ||
| broker: mqtt://your-broker:1883 |
There was a problem hiding this comment.
The example configuration uses broker: mqtt://your-broker:1883, which connects to the MQTT broker without TLS, exposing BLE-derived data and control messages to interception or tampering by any on-path attacker on the network. In environments where the broker is reachable by untrusted clients (e.g., shared WiFi or non-isolated networks), this can lead to disclosure of weight/health data and forged MQTT commands controlling BLE interactions. Consider updating the example to demonstrate a secure mqtts:// endpoint and document TLS/authentication expectations, or clearly constrain plaintext MQTT usage to tightly controlled networks only.
Summary