diff --git a/.gitignore b/.gitignore index 5e6071b..926f39f 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ node_modules .DS_Store .omc/ .playwright-cli/ +pnpm-lock.yaml diff --git a/astro.config.mjs b/astro.config.mjs index fd76365..0875a83 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -8,8 +8,9 @@ export default defineConfig({ '/beacons/apple': '/apple', '/beacons/other': '/other', '/base-stations': '/nodes', - '/hardware': '/nodes', - '/install': '/firmware', + '/nodes': '/hardware/nodes', + '/install': '/hardware/firmware', + '/firmware': '/hardware/firmware', '/data-flow': '/troubleshooting/data-flow', '/ids': '/troubleshooting/ids', '/terminal': '/troubleshooting/terminal', @@ -41,30 +42,37 @@ export default defineConfig({ ], sidebar: [ { label: 'Home', link: '/' }, - { slug: 'quick-start' }, - { slug: 'nodes' }, - { slug: 'firmware' }, { - label: 'Devices', + label: 'Getting started', items: [ - { slug: 'devices', label: 'Overview' }, - { slug: 'android' }, - { slug: 'apple' }, - { slug: 'other' }, + { slug: 'approach' }, + { slug: 'quick-start' }, ], }, { - label: 'Configuration', + label: 'Hardware', + items: [ + { slug: 'hardware/nodes' }, + { slug: 'hardware/firmware' }, + { slug: 'hardware/enclosures' }, + ], + }, + { + label: 'Node Configuration', items: [ { slug: 'configuration/network' }, { slug: 'configuration/settings' }, { slug: 'configuration/hardware' }, + { slug: 'configuration/mqtt' }, ], }, { - label: 'MQTT', + label: 'Trackable Devices', items: [ - { slug: 'configuration/mqtt' }, + { slug: 'devices', label: 'Overview' }, + { slug: 'android' }, + { slug: 'apple' }, + { slug: 'other' }, ], }, { @@ -103,7 +111,6 @@ export default defineConfig({ { slug: 'troubleshooting/terminal' }, ], }, - { slug: 'enclosures' }, { slug: 'credits' }, ], }), diff --git a/src/content/docs/approach.mdx b/src/content/docs/approach.mdx new file mode 100644 index 0000000..a714e96 --- /dev/null +++ b/src/content/docs/approach.mdx @@ -0,0 +1,62 @@ +--- +title: Approaches +--- + +:::note +These are fundamentally different approaches. mqtt_room uses 1 node per room. Companion needs dense coverage (5-8 per floor) with strategic placement. More nodes doesn't make mqtt_room better - pick one approach and commit. +::: + +## Approach 1: mqtt_room (Simple Room Presence) + +**Best for:** Room-based automations like "turn on kitchen lights when I enter" + +| | mqtt_room | +|:---|:---| +| **Question Answered** | "Which room is my device in?" | +| **Output** | Room name (e.g., "kitchen") | +| **Nodes Needed** | 1 per room | +| **Setup** | Simple | + +Your device connects to the **single nearest ESPresense node**. The node's configured room name is reported to Home Assistant. + +``` +Phone → "I'm 2m from Living Room node" → HA sees "Phone is in Living Room" +``` + +**Requirements:** +- Place **one node per room** where you want detection +- Each node = one room in your automation +- No floor plan required + +**When to use:** Turning lights on/off per room, playing announcements, basic presence detection. **Start here if you're new.** + +[Setup mqtt_room →](/integrations/home-assistant) + +## Approach 2: Companion (Precise Positioning) + +**Best for:** Precise location tracking like "find my phone on the floor plan" + +| | Companion | +|:---|:---| +| **Question Answered** | "Where exactly is my device on the floor?" | +| **Output** | X,Y coordinates on floor plan | +| **Nodes Needed** | 5-8 per floor | +| **Setup** | More complex | + +Multiple nodes measure distance to your device simultaneously. Using **multilateration**, Companion calculates precise coordinates. + +``` +Phone → 3m from Node A, 5m from Node B, 4m from Node C → Companion: Phone is at (X,Y) +``` + +**Additional requirements:** +- **5-8 nodes per floor** (depending on square footage) +- **Perimeter nodes help most** - provide strongest positioning +- **Avoid collinearity** - don't place nodes in straight lines +- Requires accurate floor plan +- Obstacles (walls, furniture) drastically affect accuracy + +**When to use:** Finding exact location on a floor plan, tracking movement paths, room-level presence isn't enough. + +[Setup Companion →](/companion) + diff --git a/src/content/docs/companion/configuration.md b/src/content/docs/companion/configuration.md index 42c729f..020576e 100644 --- a/src/content/docs/companion/configuration.md +++ b/src/content/docs/companion/configuration.md @@ -314,4 +314,6 @@ The configuration file supports hot reloading, which means: - No need to restart the companion after changes - If there is unexpected behavior give the companion add-on a moment to implement the configuration, if unresolved or unresponsive a reboot (not restart of home assistant, a full reboot) of the host device can resolve the issue. -### Help write this documentation! Click 'Edit this page on GitHub' below. +:::tip +Help improve this documentation! Click 'Edit page' below. +::: diff --git a/src/content/docs/companion/installation.md b/src/content/docs/companion/installation.md index 69bef36..f9e49c3 100644 --- a/src/content/docs/companion/installation.md +++ b/src/content/docs/companion/installation.md @@ -4,32 +4,47 @@ sidebar: order: 1 --- +Installing the ESPresense Companion is a combination of the Companion App itself and a MQTT server. -## Home Assistant OS (HAOS) +Companion deployment: -### Step 1: Add Repository -
- - Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled. - - Click Add -
+- Recommended: As an [App](#home-assistant-app) within Home Assistant +- Optional: As a (composed) [container](#containerized-deployment) elsewhere (experienced users) -### Step 2: Install -
- - Open your Home Assistant instance and show the Supervisor add-on store. - - Click Install, Start, then Show in Sidebar -
+MQTT setup: -### Manual Add-on Installation (Alternative) +- Recommended: Home Assistant [MQTT](#home-assistant-mqtt-app) App +- Alternative: [External](#external-mqtt-broker) MQTT broker -If the buttons above don't work for you, follow these steps to add the repository and install the add-on manually within Home Assistant: +## Home Assistant App -1. **Navigate to Add-ons:** Go to `Settings` > `Add-ons` in your Home Assistant UI. +### Two-step Install (Recommended!) + +#### Step 1: Add Repository + + + Add ESPresense App repository to Home Assistant + + +Click **Add** in the dialog. + +#### Step 2: Install + + + Open Home Assistant Supervisor App store + + +Click **Install**, **Start**, then **Show in Sidebar**. + +### Manual App Installation + +If the buttons above don't work for you, follow these steps to add the repository and install the app manually within Home Assistant: + +1. **Navigate to Apps:** Go to `Settings` > `Add-ons` in your Home Assistant UI. 2. **Add Repository:** - * Click the `Add-on Store` button (usually bottom right). + * Click the `Apps Store` button (usually bottom right). * Click the three dots menu in the top right corner and select `Repositories`. * Paste the following URL into the "Add repository" field: ``` @@ -38,18 +53,18 @@ If the buttons above don't work for you, follow these steps to add the repositor * Click `Add`. * Close the repository management dialog. 3. **Install ESPresense Companion:** - * Refresh the Add-on Store page (you might need to wait a moment or refresh your browser). + * Refresh the Apps Store page (you might need to wait a moment or refresh your browser). * Search for `ESPresense Companion`. - * Click on the `ESPresense Companion` add-on. + * Click on the `ESPresense Companion` app. * Click `Install`. * Once installed, click `Start`. * Optionally, enable `Show in sidebar` for easy access. -## DIY Docker Container +### Containerized Deployment Example docker-compose configuration: -```yaml -version: '3.7' + +```yaml title="compose.yaml" services: espresense: image: espresense/espresense-companion @@ -59,18 +74,19 @@ services: volumes: - ./data/espresense:/config/espresense ``` + Port `8268` is required for firmware updates. ## MQTT Setup -ESPresense and ESPresense Companion require MQTT to function. Here's how to set it up: +ESPresense and ESPresense Companion require MQTT to function. Here's two ways to set it up: -### Using Home Assistant's MQTT Addon -1. Install the Mosquitto broker addon from the official add-on store -2. Start the addon +#### Home Assistant MQTT App +1. Install the Mosquitto broker app from the official app store +2. Start the app 3. ESPresense Companion will automatically use these settings -### Using External MQTT Broker +### External MQTT Broker 1. Install [Mosquitto](https://mosquitto.org/) or your preferred MQTT broker 2. Note your configuration: - Host @@ -101,10 +117,10 @@ Once installation is complete: ## Troubleshooting Installation ### Common Issues: -1. **Can't see the add-on in Home Assistant:** +1. **Can't see the app in Home Assistant:** - Refresh your browser - Verify the repository was added successfully - - Check the add-on store logs + - Check the app store logs 2. **MQTT Connection Failed:** - Verify MQTT broker is running diff --git a/src/content/docs/companion/optimization.md b/src/content/docs/companion/optimization.md index ae98b81..ca3d4f3 100644 --- a/src/content/docs/companion/optimization.md +++ b/src/content/docs/companion/optimization.md @@ -115,4 +115,6 @@ If the default values aren't providing accurate distances: - Metal objects, walls, and furniture can affect readings - Note successful RSSI@1m values for your specific devices for future reference -## Help write this documentation! Click the edit this page below. +:::tip +Help improve this documentation! Click 'Edit page' below. +::: diff --git a/src/content/docs/companion/troubleshooting.md b/src/content/docs/companion/troubleshooting.md index 79d1a49..53c35e2 100644 --- a/src/content/docs/companion/troubleshooting.md +++ b/src/content/docs/companion/troubleshooting.md @@ -7,6 +7,10 @@ sidebar: ## Installation Issues +:::note +Also check the [Installation Troubleshooting](/companion/installation/#troubleshooting-installation) section. +::: + ### Add-on Not Appearing - Refresh your browser cache - Re-add the repository using the button on the [Installation page](/companion/installation) @@ -123,4 +127,6 @@ If you're still having issues: - Steps to reproduce - Expected vs actual behavior -## Help write this documentation! Click the edit this page below. +:::tip +Help improve this documentation! Click 'Edit page' below. +::: diff --git a/src/content/docs/configuration/mqtt.md b/src/content/docs/configuration/mqtt.md index 256fefa..f7da73e 100644 --- a/src/content/docs/configuration/mqtt.md +++ b/src/content/docs/configuration/mqtt.md @@ -7,12 +7,17 @@ sidebar: If you end up deploying a fleet of ESP32s in your home, it can quickly become painful to go to each device to update settings. -You can use tools like MQTT explorer or if you are using mosquitto (default for HA), the mosquitto_sub and mosquitto_pub tools to view and manage the settings. +You can use tools like [MQTT explorer](https://mqtt-explorer.com) or if you are using mosquitto (default for HA), the `mosquitto_sub` and `mosquitto_pub` tools to view and manage the settings. + ```bash -mosquitto_sub -h homeassistant.local -u -P -i presensce-information -v -t "espresense/rooms/kitchen/#" +mosquitto_sub -h homeassistant.local -u -P -i presense-information -v -t "espresense/rooms/kitchen/#" ``` +:::note +For configuration of the Companion App also check the [Companion MQTT](/companion/installation/#mqtt-setup) section +::: + ## Reading Current Settings Example output when subscribing to a room: @@ -32,7 +37,7 @@ espresense/rooms/study/arduino_ota OFF You can update the configuration for any of the above topics by publishing to the `/set` endpoint for each topic like so: ```bash -mosquitto_pub -h homeassistant.local -u -P -i presensce-information -t "espresense/rooms/kitchen/auto_update/set" -m "ON" -d +mosquitto_pub -h homeassistant.local -u -P -i presense-information -t "espresense/rooms/kitchen/auto_update/set" -m "ON" -d ``` You can use a room of `*` to update all ESPresense nodes at the same time. If you retain that setting even NEW nodes will upon startup get that configuration set. diff --git a/src/content/docs/devices.md b/src/content/docs/devices.md index caec212..51d8715 100644 --- a/src/content/docs/devices.md +++ b/src/content/docs/devices.md @@ -1,7 +1,7 @@ --- -title: Devices +title: Trackable Devices sidebar: - order: 4 + order: 3 --- @@ -63,3 +63,4 @@ If you have a different BLE-enabled piece of hardware that you have gotten to wo ## Footnotes [^beaconconfig]: These can do eddystone and iBeacon at the same time, just pick iBeacon + diff --git a/src/content/docs/enclosures.md b/src/content/docs/hardware/enclosures.md similarity index 95% rename from src/content/docs/enclosures.md rename to src/content/docs/hardware/enclosures.md index 58d57f5..ff66d11 100644 --- a/src/content/docs/enclosures.md +++ b/src/content/docs/hardware/enclosures.md @@ -4,6 +4,7 @@ sidebar: order: 9 --- +Example enclosures for various ESPs. ## D1 Mini 32 * [ESP32 D1 Mini Case - USB Plug w/ MMWave Sensor](https://www.printables.com/model/335469-usb-outlet-esp32-d1-mini-case-for-espresense-and-m) diff --git a/src/content/docs/firmware.mdx b/src/content/docs/hardware/firmware.mdx similarity index 69% rename from src/content/docs/firmware.mdx rename to src/content/docs/hardware/firmware.mdx index 6225b64..594e5b3 100644 --- a/src/content/docs/firmware.mdx +++ b/src/content/docs/hardware/firmware.mdx @@ -1,10 +1,10 @@ --- title: Install Firmware sidebar: - order: 2 + order: 5 --- -import FirmwareInstaller from '../../components/FirmwareInstaller.astro'; +import FirmwareInstaller from '../../../components/FirmwareInstaller.astro'; ## Browser-Based Installer @@ -12,10 +12,14 @@ Begin by connecting an ESP device to your computer using USB, then click the "Co +:::tip +You must use Edge or Chrome(-based) browser, the above web-based installer does not work on Firefox or Safari. +::: + ## Post-Flashing Steps Upon successful firmware flashing, search for an Access Point (AP) with an SSID beginning with "ESPresense-". Connect to this network to access the configuration portal. For setup instructions, visit [Configuration Settings](/configuration/settings). ## Alpha / Nightly Builds -For those interested in experimental features, you can opt for a nightly/alpha build available [here](/alpha). Please note this is for adventurous users and may not be stable. +For those interested in experimental features, you can opt for a nightly/alpha build available [here](/alpha). Please note this is for experienced and adventurous users and may not be stable. diff --git a/src/content/docs/nodes.md b/src/content/docs/hardware/nodes.md similarity index 99% rename from src/content/docs/nodes.md rename to src/content/docs/hardware/nodes.md index 5f520b2..4c35d1d 100644 --- a/src/content/docs/nodes.md +++ b/src/content/docs/hardware/nodes.md @@ -1,7 +1,7 @@ --- title: Nodes sidebar: - order: 3 + order: 4 --- diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 170eb2a..87eae4a 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -15,85 +15,33 @@ Reasons to use this over other solutions: * Auto-updates by downloading GitHub-released binaries (optional, with a preference to disable if desired) * Filters measured distance with both a median pre-filter and a 1Euro filter (reduces jitter for greater accuracy) -## Two Ways to Use ESPresense +## Ways to Use ESPresense ESPresense supports two fundamentally different approaches. Choosing the right one upfront will save you confusion and hardware costs. -### Approach 1: mqtt_room (Simple Room Presence) - -**Best for:** Room-based automations like "turn on kitchen lights when I enter" - -| | mqtt_room | -|:---|:---| -| **Question Answered** | "Which room is my device in?" | -| **Output** | Room name (e.g., "kitchen") | -| **Nodes Needed** | 1 per room | -| **Setup** | Simple | - -Your device connects to the **single nearest ESPresense node**. The node's configured room name is reported to Home Assistant. - -``` -Phone → "I'm 2m from Living Room node" → HA sees "Phone is in Living Room" -``` - -**Requirements:** -- Place **one node per room** where you want detection -- Each node = one room in your automation -- No floor plan required - -**When to use:** Turning lights on/off per room, playing announcements, basic presence detection. **Start here if you're new.** - -[Setup mqtt_room →](/integrations/home-assistant) - -### Approach 2: Companion (Precise Positioning) - -**Best for:** Precise location tracking like "find my phone on the floor plan" - -| | Companion | -|:---|:---| -| **Question Answered** | "Where exactly is my device on the floor?" | -| **Output** | X,Y coordinates on floor plan | -| **Nodes Needed** | 5-8 per floor | -| **Setup** | More complex | - -Multiple nodes measure distance to your device simultaneously. Using **multilateration**, Companion calculates precise coordinates. - -``` -Phone → 3m from Node A, 5m from Node B, 4m from Node C → Companion: Phone is at (X,Y) -``` - -**Requirements:** -- **5-8 nodes per floor** (depending on square footage) -- **Perimeter nodes help most** - provide strongest positioning -- **Avoid collinearity** - don't place nodes in straight lines -- Requires accurate floor plan -- Obstacles (walls, furniture) drastically affect accuracy - -**When to use:** Finding exact location on a floor plan, tracking movement paths, room-level presence isn't enough. - -[Setup Companion →](/companion) - ### Which Should I Choose? -**Choose mqtt_room if:** +**Choose [mqtt_room](/approaches#approach-1-mqtt_room-simple-room-presence) if:** + - You want simple room-based automations - You have 1 node per room - You don't need a floor plan -**Choose Companion if:** +**Choose [Companion](/approaches#approach-2-companion-precise-positioning) if:** + - You need precise X,Y coordinates - You can deploy 5-8+ nodes per floor - You have/want a floor plan -**Note:** These are fundamentally different approaches. mqtt_room uses 1 node per room. Companion needs dense coverage (5-8 per floor) with strategic placement. More nodes doesn't make mqtt_room better - pick one approach and commit. - ---- +:::note +These are fundamentally different approaches. mqtt_room uses 1 node per room. Companion needs dense coverage (5-8 per floor) with strategic placement. More nodes doesn't make mqtt_room better - pick one approach and commit. +::: -## Required +## Requirements -* [Nodes](/nodes) -* [Beacons/Phones/Watches](/devices) -* [MQTT Server](https://mosquitto.org/) +* One or more ESP [Nodes](/nodes), depending on your approach +* A [Trackable Device](/devices), such as a supported beacons, phone or watch +* A [MQTT Server](https://mosquitto.org/) ## Configuration & Setup diff --git a/src/content/docs/integrations/homebridge.md b/src/content/docs/integrations/homebridge.md index d56dfc1..f72a884 100644 --- a/src/content/docs/integrations/homebridge.md +++ b/src/content/docs/integrations/homebridge.md @@ -5,4 +5,4 @@ sidebar: --- -[ESPresense Homebridge Plugin](https://www.npmjs.com/package/homebridge-espresense) +The [ESPresense Homebridge Plugin](https://www.npmjs.com/package/homebridge-espresense) implements using ESPresense node data as occupancy sensors in HomeKit.