From 7ca5d1b54c7f8aa566db0f1cebb7507be453271d Mon Sep 17 00:00:00 2001 From: "holocron.so" Date: Tue, 6 Aug 2024 15:01:39 +0000 Subject: [PATCH 1/4] Update `docs/index.md` --- docs/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 0d10b6f46..88191c0b1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,2 +1 @@ -# Homepage - +# Homepage \ No newline at end of file From 17951abe7b56ebc359e3b2cfb542660a5503e98e Mon Sep 17 00:00:00 2001 From: "holocron-so[bot]" <140954071+holocron-so[bot]@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:04:15 +0000 Subject: [PATCH 2/4] Update `setup.mdx` --- setup.mdx | 1 + 1 file changed, 1 insertion(+) create mode 100644 setup.mdx diff --git a/setup.mdx b/setup.mdx new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/setup.mdx @@ -0,0 +1 @@ + From 6a177b10fb3e1322ef112af9a8279621d6267b98 Mon Sep 17 00:00:00 2001 From: "holocron-so[bot]" <140954071+holocron-so[bot]@users.noreply.github.com> Date: Tue, 6 Aug 2024 15:04:31 +0000 Subject: [PATCH 3/4] Update `docs/setup.mdx` --- setup.mdx => docs/setup.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename setup.mdx => docs/setup.mdx (100%) diff --git a/setup.mdx b/docs/setup.mdx similarity index 100% rename from setup.mdx rename to docs/setup.mdx From 26a53701e1661de8d6c8733599fbee10123cda27 Mon Sep 17 00:00:00 2001 From: Trevor Schirmer Date: Tue, 6 Aug 2024 11:46:03 -0400 Subject: [PATCH 4/4] New Nav System --- docs/contact.md | 7 + docs/sensors/bluetoothtracking.md | 359 ++++++++++++++++++++++++++++++ docs/sensors/gettingstarted.md | 64 ++++++ docs/sensors/msr1/updating.md | 19 ++ docs/setup.mdx | 1 - mkdocs.yml | 17 +- 6 files changed, 463 insertions(+), 4 deletions(-) create mode 100644 docs/contact.md create mode 100644 docs/sensors/bluetoothtracking.md create mode 100644 docs/sensors/gettingstarted.md create mode 100644 docs/sensors/msr1/updating.md delete mode 100644 docs/setup.mdx diff --git a/docs/contact.md b/docs/contact.md new file mode 100644 index 000000000..7dace4de3 --- /dev/null +++ b/docs/contact.md @@ -0,0 +1,7 @@ +# Contact Us + +## Our Team + +## Shop + +## Support \ No newline at end of file diff --git a/docs/sensors/bluetoothtracking.md b/docs/sensors/bluetoothtracking.md new file mode 100644 index 000000000..b198b0cd6 --- /dev/null +++ b/docs/sensors/bluetoothtracking.md @@ -0,0 +1,359 @@ +# Bluetooth Tracking + +#### **Apple iPhone/iWatch** + + +##### Alternative HACS Integration: [iPhone Detect](https://github.com/mudape/iphonedetect) + +[https://community.home-assistant.io/t/implement-espresense-fuctionality-in-home-assistant-taking-advantage-of-ble-proxy-of-esphome/524019/6](https://community.home-assistant.io/t/implement-espresense-fuctionality-in-home-assistant-taking-advantage-of-ble-proxy-of-esphome/524019/6) + +Thanks to user [Jacob Pfeifer](https://discord.com/channels/1126966963206361199/1126966963755819080/1202032228050419732)! +Ok, so looks like I've got signal strength tracking working for Apple watches by getting the mac address from the home assistant private ble device integration. Here's a quick write-up if anyone else is interested. The end of the doc has a complete configuration file example. + +``` +# Tracking an Apple Watch in esphome +Using esphome on an Apollo msr-1 to track an Apple Watch + +## Acknowledgements: +The following github repo was used as a starting point for this configuration: https://github.com/dalehumby/ESPHome-Apple-Watch-detection + +## RSSI Tracking +1.) Setup your apple watch in the "Private BLE Device" integration by following the instructions on the integration page: https://www.home-assistant.io/integrations/private_ble_device/ + +2.) Create a text sensor in the esphome config that grabs the apple watch current mac address from home assistant: +```yaml +text_sensor: + - platform: homeassistant + name: "Apple Watch Current MAC Address" + id: apple_watch_mac + entity_id: device_tracker.your_apple_watch_home_assistant_id + attribute: current_address +``` + +3.) Create a template sensor for storing and transmitting the rssi value: +```yaml +sensor: + - platform: template + id: apple_watch_rssi + name: "Apple Watch RSSI" + device_class: signal_strength + unit_of_measurement: dBm + accuracy_decimals: 0 + filters: + - exponential_moving_average: + alpha: 0.3 + send_every: 1 +``` + +4.) Create a custom ble tracker that uses the mac address from home assistant to match the device: +```yaml +esp32_ble_tracker: + scan_parameters: + interval: 1.2s + window: 500ms + active: false + on_ble_advertise: + - then: + - lambda: |- + for (auto data : x.get_manufacturer_datas()) { + if(x.address_str() == id(apple_watch_mac).state) { + id(apple_watch_rssi).publish_state(x.get_rssi()); + } + } +``` + +5) Ensure the power save mode for wifi is set to light (msr-1 defaults to using none which does not work with bluetooth tracking): +```yaml +wifi: + power_save_mode: light +``` + +At this point if you install the changes on the device you should be successfully tracking the rssi for your apple watch. If you want you can optionally add some configuration for a basic presence detection sensor by doing the following: + +## OPTIONAL PRESENCE DETECTION SECTION + +6) Create configuration values for detection signal strength: +```yaml +number: + - platform: template + name: "RSSI Presence Level" + id: rssi_present + icon: "mdi:arrow-collapse-right" + optimistic: true + min_value: -100 + max_value: -35 + initial_value: -60 + step: 1 + entity_category: CONFIG + restore_value: true + update_interval: never + - platform: template + name: "RSSI Absence Level" + id: rssi_not_present + icon: "mdi:arrow-collapse-right" + optimistic: true + min_value: -100 + max_value: -35 + initial_value: -70 + step: 1 + entity_category: CONFIG + restore_value: true + update_interval: never +``` + +7) Create a sensor for storing and filtering the presence value: +```yaml +sensor: + - platform: template + id: room_presence_debounce + filters: + - sliding_window_moving_average: + window_size: 3 + send_every: 1 +``` + +8) Create a sensor for transmitting the filtered presence state: +```yaml +binary_sensor: + - platform: template + id: room_presence + name: "Apple Watch Presence" + device_class: occupancy + lambda: |- + if (id(room_presence_debounce).state > 0.99) { + return true; + } else if (id(room_presence_debounce).state < 0.01) { + return false; + } else { + return id(room_presence).state; + } +``` + +9) Update the rssi value to set the presence value when it receives a new rssi value: +```yaml +sensor: + - platform: template + id: apple_watch_rssi + name: "Apple Watch RSSI" + device_class: signal_strength + unit_of_measurement: dBm + accuracy_decimals: 0 + filters: + - exponential_moving_average: + alpha: 0.3 + send_every: 1 + on_value: + then: + - lambda: |- + if (id(apple_watch_rssi).state > id(rssi_present).state) { + id(room_presence_debounce).publish_state(1); + } else if (id(apple_watch_rssi).state < id(rssi_not_present).state) { + id(room_presence_debounce).publish_state(0); + } + - script.execute: presence_timeout # Publish 0 if no rssi received +``` + +Now once you install the esphome changes you should be able to go to the device and set db values for the presence detection and also should see a presence sensor state. + +## COMPLETE CONFIGURATION +A complete example of a configuration: +```yaml +substitutions: + name: apollo-msr-1-6c7a64 + friendly_name: Living Room Multisensor + roomname: Living Room + yourname: Jacob + +packages: + ApolloAutomation.MSR-1: github://ApolloAutomation/MSR-1/Integrations/ESPHome/MSR-1.yaml +esphome: + name: ${name} + name_add_mac_suffix: false + friendly_name: ${friendly_name} +api: + encryption: + key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + + +esp32_ble_tracker: + scan_parameters: + interval: 1.2s + window: 500ms + active: false + on_ble_advertise: + - then: + - lambda: |- + for (auto data : x.get_manufacturer_datas()) { + if(x.address_str() == id(jacobs_watch_mac).state) { + id(apple_watch_rssi).publish_state(x.get_rssi()); + } + } +text_sensor: + - platform: homeassistant + name: "Apple Watch Current MAC Address" + id: jacobs_watch_mac + entity_id: device_tracker.jacob_s_apple_watch + attribute: current_address + +sensor: + - platform: template + id: apple_watch_rssi + name: "$yourname Apple Watch $roomname RSSI" + device_class: signal_strength + unit_of_measurement: dBm + accuracy_decimals: 0 + filters: + - exponential_moving_average: + alpha: 0.3 + send_every: 1 + on_value: + then: + - lambda: |- + if (id(apple_watch_rssi).state > id(rssi_present).state) { + id(room_presence_debounce).publish_state(1); + } else if (id(apple_watch_rssi).state < id(rssi_not_present).state) { + id(room_presence_debounce).publish_state(0); + } + - script.execute: presence_timeout # Publish 0 if no rssi received + + - platform: template + id: room_presence_debounce + filters: + - sliding_window_moving_average: + window_size: 3 + send_every: 1 + + +binary_sensor: + - platform: template + id: room_presence + name: "$yourname $roomname Presence" + device_class: occupancy + lambda: |- + if (id(room_presence_debounce).state > 0.99) { + return true; + } else if (id(room_presence_debounce).state < 0.01) { + return false; + } else { + return id(room_presence).state; + } + +script: + # Publish event every 30 seconds when no rssi received + id: presence_timeout + mode: restart + then: + - delay: 30s + - lambda: |- + id(room_presence_debounce).publish_state(0); + - script.execute: presence_timeout + +number: + - platform: template + name: "RSSI Presence Level" + id: rssi_present + icon: "mdi:arrow-collapse-right" + optimistic: true + min_value: -100 + max_value: -35 + initial_value: -60 + step: 1 + entity_category: CONFIG + restore_value: true + update_interval: never + - platform: template + name: "RSSI Absence Level" + id: rssi_not_present + icon: "mdi:arrow-collapse-right" + optimistic: true + min_value: -100 + max_value: -35 + initial_value: -70 + step: 1 + entity_category: CONFIG + restore_value: true + update_interval: never + +wifi: + power_save_mode: light + ssid: !secret wifi_ssid + password: !secret wifi_password +``` + +``` + +##### **Android** Helpful links: +[ESP32 Bluetooth Low Energy Tracker Hub](https://esphome.io/components/esp32_ble_tracker.html) +[iBeacon support for ble\_presence](https://github.com/esphome/esphome/pull/1627) +[ESP32 Bluetooth Low Energy Beacon](https://esphome.io/components/esp32_ble_beacon.html) +[iBeacon Region](https://owntracks.org/booklet/features/beacons/) + +1. Install the iBeacon integration in HA + [iBeacon Install Guide](https://www.home-assistant.io/integrations/ibeacon/) +2. Install the Home Assistant App on your device + [Android](https://play.google.com/store/apps/details?id=io.homeassistant.companion.android&hl=en_US&gl=US&pli=1) + [Apple](https://apps.apple.com/us/app/home-assistant/id1099568401) +3. Navigate to the HA settings + + [![Screenshot_20231109_235524_Photos.jpg](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/scaled-1680-/screenshot-20231109-235524-photos.jpg)](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/screenshot-20231109-235524-photos.jpg) +4. Select Companion app + + [![Screenshot_20231109_235557_Photos.jpg](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/scaled-1680-/screenshot-20231109-235557-photos.jpg)](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/screenshot-20231109-235557-photos.jpg) +5. Select Manage sensors + + [![Screenshot_20231109_235621_Photos.jpg](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/scaled-1680-/screenshot-20231109-235621-photos.jpg)](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/screenshot-20231109-235621-photos.jpg) +6. Turn on the "BLE Transmitter" + + [![Screenshot_20231109_235702_Photos.jpg](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/scaled-1680-/screenshot-20231109-235702-photos.jpg)](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/screenshot-20231109-235702-photos.jpg) +7. After opening BLE transmitter and turning it on, then scroll down to get the iBeacon unique ID + + [![Screenshot_20231109_235757_Photos.jpg](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/scaled-1680-/screenshot-20231109-235757-photos.jpg)](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/screenshot-20231109-235757-photos.jpg) +8. Add it to the ESPHome yaml config for the MSR-1 + + [![ESPHome YAML Edit.png](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/scaled-1680-/esphome-yaml-edit.png)](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-11/esphome-yaml-edit.png) +9. Be sure to add "power\_save\_mode: LIGHT" to the wifi section + + ``` + # Example config.yaml + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + power_save_mode: LIGHT + + esp32_ble_tracker: + + binary_sensor: + - platform: ble_presence + ibeacon_uuid: '77a6438d-ea95-4522-b46c-cb2b4412076f' + ibeacon_major: 100 + ibeacon_minor: 1 + name: "Jane's Phone" + + ``` +10. Should be all set! + +##### Thanks to our Discord user albuquerquefx for the information below! + + + +For those interested in using their MSR-1 as a Bluetooth proxy while also actively scanning for BLE devices, you'll need to add the following to your ESP32 YAML file (I'm using a 1.5-second scan interval with a 750ms window for sensing BLE beacons): + +esp32\_ble\_tracker: + id: ${name}\_ble\_tracker + scan\_parameters: + interval: 1500ms + window: 750ms + active: true + +bluetooth\_proxy: + active: true + +Additionally, you need to include this entry in your existing Wi-Fi section: + +power\_save\_mode: light + +
Once complete, after a few minutes within the presence of any iBeacon device within listening distance of your MSR-1, Home Assistant should announce the presence of an iBeacon Tracker integration on your settings page. While I didn't capture a screenshot of it, it's now installed and sensing things. + +If you encounter a device with a blank name (e.g., anything Android), you'll need to click "Configure" and enter the UUID manually. This is because Home Assistant does not allow devices with empty names (interestingly, their own companion app permits forcing an Android to become an iBeacon but then doesn't require a name field). + +For devices where you don't know the IRK, you may have to wait about 300 seconds for your iBeacon Tracker to process 10 different iterations of the same UUID but with the last four characters randomly changed. Once ten instances have appeared, the iBeacon Tracker integration should recognize they're all the same device and combine them into a single tracker element. Just be patient, though it can be a bit frustrating. \ No newline at end of file diff --git a/docs/sensors/gettingstarted.md b/docs/sensors/gettingstarted.md new file mode 100644 index 000000000..edec496dc --- /dev/null +++ b/docs/sensors/gettingstarted.md @@ -0,0 +1,64 @@ +# Getting Started + +This will walk you through the process of connecting your new Apollo Multisensor (MSR-1) to Home Assistant through ESPHome. If at any point you get stuck, join our [Discord](https://discord.gg/mMNgQPyF94) for some help. + +### Connecting Through Hotspot + +To connect through the sensor's onboard hotspot follow the below: + +1. Plug the sensor into a quality power brick. They require 5v and under an amp so most phone chargers will be fine. ESP devices are sensitive to power fluctuations and users have had some issues with really cheap power bricks. If your device is restarting or unavailable please try a different power brick. +2. On your phone or PC, open the wifi settings and connect to "Apollo MSR-1 Hotspot", it might take a minute for the wifi network to show up +3. Once connected it should automatically open a dashboard for your sensor + - If this does not automatically open the dashboard, please open your web browser and go to [http://192.168.4.1](http://192.168.4.1) +4. Select the wifi network that you would like your sensor to connect to +5. Input the wifi password. After connecting, the sensor's dashboard will automatically close. You've successfully connected your sensor, please check out the "Connecting Sensor To Home Assistant" section for the next steps. + +### Connecting To ESPHome Addon + +You can connect to the ESPHome addon in Home Assistant to easily update your device. If you don't have ESPHome addon installed you can follow the steps here: [Installing ESPHome Dashboard](https://esphome.io/guides/getting_started_hassio.html) + +1. Once installed you'll have the addon's icon on the left side of your HA instance: + 1. [![Screenshot 2024-06-06 at 2.57.55 PM.png](https://wiki.apolloautomation.com/uploads/images/gallery/2024-06/scaled-1680-/screenshot-2024-06-06-at-2-57-55-pm.png)](https://wiki.apolloautomation.com/uploads/images/gallery/2024-06/screenshot-2024-06-06-at-2-57-55-pm.png) + 2. Click on adopt for your sensor[![Screenshot 2024-06-06 at 4.06.20 PM.png](https://wiki.apolloautomation.com/uploads/images/gallery/2024-06/scaled-1680-/screenshot-2024-06-06-at-4-06-20-pm.png)](https://wiki.apolloautomation.com/uploads/images/gallery/2024-06/screenshot-2024-06-06-at-4-06-20-pm.png) + 3. Then adopt again + +

Don't change the name at this step. If you'd like to change the name please refer to [this article](https://wiki.apolloautomation.com/books/general/page/renaming-apollo-devices) after you've completed these steps.

+ +[![image.png](https://wiki.apolloautomation.com/uploads/images/gallery/2024-06/scaled-1680-/image.png)](https://wiki.apolloautomation.com/uploads/images/gallery/2024-06/image.png) + +### Connecting Sensor To Home Assistant + +1. **Once you connect your sensor to wifi through the above process, open up Home Assistant. Then in the bottom left click on “Settings”** + +![homeassistantsettings.png](https://beautiful-cheetah.pikapod.net/uploads/images/gallery/2023-10/homeassistantsettings.png) + +2. **From there click on “Devices And Services”** + +![homeassistant_deviceandservices.png](https://beautiful-cheetah.pikapod.net/uploads/images/gallery/2023-10/homeassistant-deviceandservices.png) + +3. **Look for the discovered sensor. It should be named “apollo-msr-mk1” with some random letters and numbers (Those come from the device's mac address). Click on “Configure” and then “Submit”.** + + + 1.

**If you do not see the device as discovered, make sure you have the ESPHome integration installed to Home Assistant you can find [their instructions here](https://esphome.io/guides/getting_started_hassio.html#connecting-your-device-to-home-assistant)**

+ +![img4_optimized.png](https://beautiful-cheetah.pikapod.net/uploads/images/gallery/2023-10/img4-optimized.png) + +4. **Add the sensor to ESPHome. It will now show up in the ESPHome integration** + +![img5_optimized.png](https://beautiful-cheetah.pikapod.net/uploads/images/gallery/2023-10/img5-optimized.png) + +5. **The sensor has now been added to Home Assistant and you can use it as you please. For ideas please visit our ideas section or join our [Discord](https://discord.gg/mMNgQPyF94)** + +![img6_optimized.png](https://beautiful-cheetah.pikapod.net/uploads/images/gallery/2023-10/img6-optimized.png) + +### Sensors + +You should now have the sensor added! If you have any problems or need help please join our [Discord](https://discord.gg/mMNgQPyF94) and post in the #support channel. Or just join to check out product development and community spotlights. Our team monitors that and can quickly respond there. Or visit our [ideas section](https://wiki.apolloautomation.cloud/Ideas/MultisensorMk1) to find cool ways to display the information + +### Looking For Ideas On How To Use Your Sensor? + +- Graph Co2 Over Time +- Turn The LED Red When C02 Is Over 1000 ppm +- Send You An Alert When Motion Is Detected After 11pm + +Or check out our #show-off channel in the Apollo [Discord](https://discord.gg/mMNgQPyF94) for community submissions \ No newline at end of file diff --git a/docs/sensors/msr1/updating.md b/docs/sensors/msr1/updating.md new file mode 100644 index 000000000..b90a9bb1f --- /dev/null +++ b/docs/sensors/msr1/updating.md @@ -0,0 +1,19 @@ +## Updating Through ESPHome Addon + +1. **In HomeAssistant open the [ESPHome addon](https://esphome.io/guides/getting_started_hassio.html)** +2. **Or click this to [Open your Home Assistant instance and show the dashboard of the ESPHome add-on.](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon "Open your Home Assistant instance and show the dashboard of the ESPHome add-on.")** +3. **Make sure you are running the latest version of ESPHome** +4. **On older hardware, it will not auto-update so you will have to uninstall and reinstall ESPHome** +5. **Find the sensor you want to update and click the three dots in the bottom right** + +**[![Firmware1.png](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-10/scaled-1680-/firmware1.png)](https://help.apolloautomation.cloud/uploads/images/gallery/2023-10/firmware1.png)** + +**5. Select “Validate” from the list** + +[![Firmware2.png](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-10/scaled-1680-/firmware2.png)](https://help.apolloautomation.cloud/uploads/images/gallery/2023-10/firmware2.png) + +**6. Once the validation completes, click “Install” in the bottom right** + +[![Firmware3.png](https://wiki.apolloautomation.cloud/uploads/images/gallery/2023-10/scaled-1680-/firmware3.png)](https://help.apolloautomation.cloud/uploads/images/gallery/2023-10/firmware3.png) + +**7. Complete!** \ No newline at end of file diff --git a/docs/setup.mdx b/docs/setup.mdx deleted file mode 100644 index 8b1378917..000000000 --- a/docs/setup.mdx +++ /dev/null @@ -1 +0,0 @@ - diff --git a/mkdocs.yml b/mkdocs.yml index ebda5ef3e..48794e233 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,13 +1,15 @@ extra_css: - stylesheets/extra.css - site_name: Apollo Docs +site_url: https://wiki.apolloautomation.com theme: logo: assets/Apollo_Square.png name: material features: - - navigation.tabs - navigation.sections + - navigation.path + - navigation.instant + - navigation.instant.progress - toc.integrate - navigation.top - search.suggest @@ -58,4 +60,13 @@ markdown_extensions: - attr_list copyright: | - © 2023 Apollo Automation LLC \ No newline at end of file + © 2023 Apollo Automation LLC + +nav: + - Home: + - Sensors: + - Getting Started: sensors/gettingstarted.md + - Bluetooth Tracking: sensors/bluetoothtracking.md + - MSR-1: + - Updating: sensors/msr1/updating.md + - Contact Us: contact.md \ No newline at end of file