Massive improvements in docs

Author: DTTerastar

companion/companion.md

@@ -2,83 +2,27 @@
 layout: page
 title: Companion
 permalink: /companion
-nav_order: 99
 ---
 
 # Companion
 
-ESPresense Companion attempts to locate your Bluetooth Low Energy (BLE) items in the floorplan of your house. It also allows you to manage ESPresense nodes and settings.
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/ESPresense/ESPresense-companion)
+![Docker Pulls](https://badgen.net/docker/pulls/espresense/espresense-companion)
 
-## How to Use
+The ESPresense-companion attempts to locate your Bluetooth Low Energy (BLE) items in the floorplan of your house. It also allows you to manage ESPresense nodes.
 
-ESPresense Companion provides a visual representation of your devices' locations within your house and helps troubleshoot ESPresense settings to improve automation trigger accuracy.
+![image](https://user-images.githubusercontent.com/1491145/208942192-d8716e50-c822-48a7-a6d3-46b53ab9373e.png)
 
-The more accurate your house plan and the more base stations you include, the higher the location accuracy will be.
+## Quick Start
+1. [Install ESPresense Companion](/companion/installation)
+2. [Configure your floorplan](/companion/configuration)
+3. Place nodes at room corners plus one nearby (1-3m)
+4. Set node maximum distance to zero using:
+   ```markdown
+   key: espresense/rooms/*/max_distance/set
+   value: 0
+   ```
+5. Fine tune by hovering over devices and adjusting RSS@1m values
 
-### Find Your Home's GPS Coordinates
-You can easily find coordinates using Google Maps or Google Earth:
-- Google Maps: Search for your address and click on the street in front of your house to get latitude and longitude
-- Google Earth: Search for your address and hover your mouse over your house - coordinates and elevation will display in the bottom right
-
-### Draw Out Your House
-You'll need accurate interior dimensions for best results. There are several options:
-1. Create a free home plan using [MagicPlan](https://www.magicplan.app/)
-2. Use the [ESPresense Floorplan Creator](https://espresense.com/Floorplan-Creator/) to convert your measurements into YAML format
-3. Directly edit the YAML coordinates in the config file - the website will update in real-time thanks to hot reloading, allowing you to fine-tune your floorplan live
-
-After using any of these methods, you'll want to save your YAML configuration. If using the Floorplan Creator, click "Convert to YAML Code" and save the generated code.
-
-### Setup MQTT
-ESPresense and ESPresense Companion require MQTT to function. If you haven't set up MQTT yet:
-1. Install and configure [Mosquitto](https://mosquitto.org/)
-2. Note your MQTT host, port (default 1883), username, and password
-3. If using Home Assistant's MQTT addon, Companion will use those settings automatically
-4. Ensure MQTT Discovery is enabled ("auto-discovered") or you'll need to manually configure MQTT settings
-
-### Install ESPresense Companion
-1. Add this repository to your Home Assistant add-on store: `https://github.com/ESPresense/hassio-addons`
-2. Reload the add-on store
-3. Find and install ESPresense Companion
-4. Don't start the add-on yet - configure it first
-
-### Edit Config File
-Navigate to `/config/espresense/config.yaml` and configure:
-
-MQTT Connection:
-- For Home Assistant's MQTT addon: Only username and password needed
-- For external MQTT: Include host and port
-- Set SSL to false
-
-GPS Settings:
-- Enter latitude and longitude in decimal format
-- Enter elevation in meters
-
-Floor Configuration:
-- Set ID and name as desired
-- Bounds: First three numbers are left/bottom starting points, second three are top/right endpoints
-- These bounds center your diagram
-
-Rooms:
-- Paste the YAML from the floorplan creator
-
-Nodes:
-- List each base station's approximate location
-- Each node needs a unique name
-- Multiple nodes can be mapped to one room
-
-Devices:
-```yaml
-- id: darrels-watch
-  name: "Darrell's Watch"
-```
-
-Use wildcards to include multiple devices:
-```yaml
-- 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
-```
-
-## Help write this documentation!  Click the edit this page below.
+## Need Help?
+Check our [Troubleshooting Guide](/companion/troubleshooting) or contribute to this documentation by clicking "Edit this page" below.

companion/configuration.md

@@ -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.

companion/installation.md

@@ -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