-
Notifications
You must be signed in to change notification settings - Fork 77
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
9283138
commit 3f7daa3
Showing
5 changed files
with
432 additions
and
93 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| --- | ||
| layout: page | ||
| title: Configuration | ||
| parent: Companion | ||
| nav_order: 2 | ||
| --- | ||
|
|
||
| # Configuration | ||
|
|
||
| ## GPS Coordinates | ||
| Find your home's coordinates: | ||
| - **Google Maps**: Search your address and click the street in front of your house | ||
| - **Google Earth**: Search your address and hover over your house - coordinates and elevation show in bottom right | ||
|
|
||
| ## Room Measurement Guide | ||
|
|
||
| Start at the **bottom left corner** of your building/area - this serves as the **origin (0,0)**. All measurements are taken from this south-west corner. When plotting, use either clockwise or counter-clockwise direction consistently. | ||
|
|
||
| Example measurements (clockwise): | ||
|
|
||
| ### Room 1 | ||
| 1. Start point: `(0,0)` | ||
| 2. North wall: `(3,0)` (9 feet/3 meters) | ||
| 3. East wall: `(3,4)` (12 feet/4 meters) | ||
| 4. South wall: `(0,4)` | ||
|
|
||
| ### Room 2 | ||
| 1. Start point: `(3,0)` | ||
| 2. Width: `(5,0)` (6 feet/2 meters) | ||
| 3. Depth: `(5,3.5)` (10.5 feet/3.5 meters) | ||
| 4. Final corner: `(3,3.5)` | ||
|
|
||
| ## Creating Your Floorplan | ||
|
|
||
| There are three ways to create your floorplan: | ||
| 1. Use [MagicPlan](https://www.magicplan.app/) to create a free home plan | ||
| 2. Use the [ESPresense Floorplan Creator](https://espresense.com/Floorplan-Creator/) to convert measurements to YAML | ||
| 3. Directly edit the YAML coordinates in the config file - changes update live thanks to hot reloading | ||
|
|
||
| ## Node Placement | ||
|
|
||
| For optimal device location accuracy: | ||
| - Place base station nodes at the corners of your floorplan | ||
| - Add an additional node within 1-3 meters | ||
| - Aim for 5 fixes minimum - more fixes improve accuracy | ||
| - The algorithm prioritizes closest distances (40% weight using gaussian distribution) | ||
|
|
||
| ## Configuration File | ||
|
|
||
| Navigate to `/config/espresense/config.yaml` and configure: | ||
|
|
||
| ### MQTT Connection | ||
| ```yaml | ||
| # For Home Assistant's MQTT addon | ||
| mqtt: | ||
| username: your_username | ||
| password: your_password | ||
| ssl: false | ||
|
|
||
| # For external MQTT, also include: | ||
| host: your_host | ||
| port: 1883 | ||
| ``` | ||
| ### GPS Settings | ||
| ```yaml | ||
| gps: | ||
| latitude: your_decimal_latitude | ||
| longitude: your_decimal_longitude | ||
| elevation: your_elevation_in_meters | ||
| ``` | ||
| ### Floor Configuration | ||
| ```yaml | ||
| floors: | ||
| - id: ground | ||
| name: Ground Floor | ||
| bounds: [left, bottom, z, right, top, z] # Centers your diagram | ||
| ``` | ||
| ### Rooms | ||
| ```yaml | ||
| # Paste output from floorplan creator or measure manually | ||
| rooms: | ||
| - id: living-room | ||
| name: Living Room | ||
| floor: ground | ||
| points: [[0,0], [3,0], [3,4], [0,4]] | ||
| ``` | ||
| ### Nodes | ||
| ```yaml | ||
| nodes: | ||
| - id: esp32-1 | ||
| name: Living Room Node | ||
| room: living-room | ||
| coords: [2,2,1] # x,y,z coordinates within room | ||
| ``` | ||
| Note: Multiple nodes can be mapped to one room, but each needs a unique name. | ||
| ### Devices | ||
| ```yaml | ||
| devices: | ||
| # Specific device | ||
| - id: darrels-watch | ||
| name: "Darrell's Watch" | ||
|
|
||
| # Using wildcards | ||
| - id: "tile:*" # Track all tiles | ||
| - id: "irk:*" # Track all IRKs | ||
| - id: "apple:*" # Track all Apple devices | ||
| - id: "ibeacon:*" # Track all iBeacon devices | ||
| - name: "*" # Track all named devices | ||
| ``` | ||
| ## Live Updates | ||
| The configuration file supports hot reloading, which means: | ||
| - Changes to the config file update in real-time | ||
| - You can adjust room coordinates and see immediate results | ||
| - Fine-tune node positions while watching the effects live | ||
| - No need to restart the companion after changes | ||
| ## Help write this documentation! Click the edit this page below. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| --- | ||
| layout: page | ||
| title: Installation | ||
| parent: Companion | ||
| nav_order: 1 | ||
| --- | ||
|
|
||
| # Installation | ||
|
|
||
| ## Home Assistant OS (HAOS) | ||
|
|
||
| ### Step 1: Add Repository | ||
| <div style="display: flex; align-items: center; gap: 10px; margin-bottom: 20px;"> | ||
| <a href="https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FESPresense%2Fhassio-addons"> | ||
| <img src="https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg" alt="Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled." /> | ||
| </a> | ||
| <span>Click <code>Add</code></span> | ||
| </div> | ||
|
|
||
| ### Step 2: Install | ||
| <div style="display: flex; align-items: center; gap: 10px;"> | ||
| <a href="https://my.home-assistant.io/redirect/supervisor_store/"> | ||
| <img src="https://my.home-assistant.io/badges/supervisor_store.svg" alt="Open your Home Assistant instance and show the Supervisor add-on store." /> | ||
| </a> | ||
| <span>Click <code>Install</code>, <code>Start</code>, then <code>Show in Sidebar</code></span> | ||
| </div> | ||
|
|
||
| ## Home Assistant Container | ||
|
|
||
| Example docker-compose configuration: | ||
| ```yaml | ||
| version: '3.7' | ||
| services: | ||
| espresense: | ||
| image: espresense/espresense-companion | ||
| ports: | ||
| - 8267:8267 | ||
| volumes: | ||
| - ./data/espresense:/config/espresense | ||
| ``` | ||
| ## MQTT Setup | ||
| ESPresense and ESPresense Companion require MQTT to function. Here's how 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 | ||
| 3. ESPresense Companion will automatically use these settings | ||
| ### Using External MQTT Broker | ||
| 1. Install [Mosquitto](https://mosquitto.org/) or your preferred MQTT broker | ||
| 2. Note your configuration: | ||
| - Host | ||
| - Port (default 1883) | ||
| - Username | ||
| - Password | ||
| 3. You'll need these details for the configuration step | ||
| ### MQTT Discovery | ||
| - Enable MQTT Discovery ("auto-discovered") in your MQTT configuration | ||
| - If disabled, you'll need to manually configure MQTT settings in the Companion's MQTT tab | ||
| ### Node Configuration | ||
| After installation, configure your ESPresense nodes by setting maximum distance to zero: | ||
| ```markdown | ||
| key: espresense/rooms/*/max_distance/set | ||
| value: 0 | ||
| ``` | ||
| This ensures you get all distance readings without filtering. | ||
| ## Next Steps | ||
| Once installation is complete: | ||
| 1. Move on to [Configuration](/companion/configuration) to set up your floorplan | ||
| 2. Place your nodes according to the [Node Placement Guide](/companion/configuration#node-placement--configuration) | ||
| 3. Start tracking your devices! | ||
| ## Troubleshooting Installation | ||
| ### Common Issues: | ||
| 1. **Can't see the add-on in Home Assistant:** | ||
| - Refresh your browser | ||
| - Verify the repository was added successfully | ||
| - Check the add-on store logs | ||
| 2. **MQTT Connection Failed:** | ||
| - Verify MQTT broker is running | ||
| - Check credentials are correct | ||
| - Ensure MQTT port (1883) is not blocked | ||
| 3. **Docker Container Won't Start:** | ||
| - Check port 8267 is not in use | ||
| - Verify volume mount permissions | ||
| - Review container logs |
Oops, something went wrong.