General

Setup

Setup

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 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
  2. On your phone or PC, open the wifi settings and connect to "Apollo MSR-1", 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 it does not automatically open the dashboard, please open your web browser and go to 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 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

  1. From there click on “Devices And Services”

homeassistant_deviceandservices.png

  1. 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”.

img4_optimized.png

  1. Add the sensor to ESPHome. It will now show up in the ESPHome integration

img5_optimized.png

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

img6_optimized.png

Sensors

You should now have the sensor added! If you have any problems or need help please join our Discord 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 to find cool ways to display the information

Looking For Ideas On How To Use Your Sensor?

Or check out our #show-off channel in the Apollo Discord for community submissions

Setup

Bluetooth Tracking

Apple iPhone/iWatch

Alternative HACS Integration: iPhone Detect

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!
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
iBeacon support for ble_presence
ESP32 Bluetooth Low Energy Beacon
iBeacon Region
  1. Install the iBeacon integration in HA
    iBeacon Install Guide
  2. Install the Home Assistant App on your device
    Android
    Apple
  3. Navigate to the HA settings

    Screenshot_20231109_235524_Photos.jpg

  4. Select Companion app

    Screenshot_20231109_235557_Photos.jpg

  5. Select Manage sensors

    Screenshot_20231109_235621_Photos.jpg

  6. Turn on the "BLE Transmitter"

    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

  8. Add it to the ESPHome yaml config for the MSR-1

    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.

Setup

Renaming Apollo Devices

ESPHome Integration

1. Go to settings and select Devices & services

Easy Renaming 3.png

 2. Select ESPHome

Easy Renaming 4.png

3. Select the three dots next to the device and select Rename

Easy Renaming 5.png

4. Rename the device and select OK

Easy Renaming 6.png

ESPHome Addon

1. Select the ESPHome addon in the sidebar

2. Select Edit on the device you want to rename

Easy Renaming 1.png

3. Chane the friendly_name and save it

Easy Renaming 2.png

These new names can be used in automations.

Easy Renaming 7.png

Full Renaming

Thanks to Panzer from our Discord.

  1. Install the first MSR-1 using the standard method to get a default ESPHome configuration.
  2. Edit this configuration to update the "name" and "friendly name" as desired.
  3. SSH into the ESPHome directory and copy this configuration six times, then modify each copy with unique names, friendly names, and API keys. (Can also use VSCode/File Editor to copy the configuration from the ESPHome folder)
    1. Screenshot 2024-01-08 at 5.29.41 PM.png
  4. Delete the initially defined sensor in ESPHome and devices (if added there), and possibly reboot.
  5. Now with six distinct configs, use the 'install' option in ESPHome, select "plug into this computer", and connect the MSR-1 to your computer.
  6. Download the generated "factory-image" from ESPHome on Home Assistant (HA) and flash it. This will install the sensors without MAC-based names.
  7. Repeat the process for the remaining sensors.
  8. Add the sensors to devices if they are discovered.
  9. Can now update the sensors wirelessly again.

Renaming sensors 2.png

Renaming sensors 1.png

Alternative Method 

Thanks to lpbaud from our Discord.

Instead of changing the name as your document suggests, you can go to System > Devices and Services > Devices, then click the device you want to rename. Next, click the pencil icon in the upper right corner of the screen and rename the device there. Doing it this way, after you click "Update," it will ask if you want to change the entity ID, as shown in the picture above. If you click "Update" here, it will change all the entity IDs, like in the other picture above.

Renaming devices using pencil.png

Here's another tip for using this naming scheme or a similar one in Node-RED: In the Entity State node dialog, if you click the empty box labeled "Entity," a small box will open beneath it displaying a list of all the available entity names, in no particular order. If you start typing in that box, it filters the list based on what you type. So, if my kitchen MSR is named msr-k and I want to trigger an event based on the value of radar target, I would type "-k target." The space between words acts as a wildcard, so the list is filtered by everything containing "-k" and "target," allowing you to select the one you need. Quite handy.

Setup

How To Change The Update Frequency Of Sensors

    1. Navigate to the ESPHome addon

    2. Select the Edit button under the desired device

ESPHome Edit Button.png

   3. Insert your code (The example below is for our AIR-1 SEN55 sensor)   

sensor:
  - platform: sen5x
    id: !extend sen55
    update_interval: 5s

SEN55 update interval.png    
    4. In the top right of the same screen Select Save and then Install 

    5. If it compiles correctly then you should see a green Success

Install Success.png

    6. When you see the sensor logs, you are finished and can select Stop

Sensor Log Stop.png

    7. Now your sensor value should update!

Calibrating And Updating

Calibrating And Updating

Updating Firmware

Updating Through ESPHome Addon

  1. In HomeAssistant open the ESPHome addon
  2. Make sure you are running the latest version of ESPHome
    1. On older hardware, it will not auto-update so you will have to uninstall and reinstall ESPHome
  3. Find the sensor you want to update and click the three dots in the bottom right

Firmware1.png

3. Select “Validate” from the list

Firmware2.png

4. Once the validation completes, click “Install” in the bottom right

Firmware3.png

5. Complete!

Calibrating And Updating

CO2 Calibration

1. Take your sensor outside (for a walk :D) and plug it in. Make sure it is connected to Home Assistant and let it sit powered on for 3-5 minutes outside before starting the calibration.

CO2_1.png

2. Navigate to your Home Assistant Dashboard and select settings

CO2_2.png

3. Select Devices & Services

CO2_3.png

4. Select ESPHome

CO2_4.png

5. Find your sensor and click on the blue “1 device” link

CO2_5.png

6. Press the Calibrate SCD40 button and you are all set!

If you do not see this button, either update your firmware or refer to this older revision


Button CO2 Calibration.png

7. Now your CO2 sensor should be calibrated! Be sure to setup some nice cards on your dashboard so you can monitor the CO2 levels. My bedroom's CO2 levels got dangerously high and I had to run my HVAC more frequently at night to circulate the air. See examples of cards and data below.

Example Home Assistant Card

CO2_7.png

Dangerous CO2 levels in bedroom. Steep decline in level due to opening door, window and running fan.

CO2_8.jpg

Wisconsin Department of Health CO2 Level Chart

CO2 Health Department.png

CO2 levels staying below 1500 ppm after changing HVAC fan schedule to circulate air more frequently. Need to increase air exchange to get below 1000 ppm for a safer environment.

Plotly CO2 Graph.png

Troubleshooting

Troubleshooting

Not Showing Up On Wifi

  1. Try a couple of different power cord and power brick combinations
  2. Check to see if the sensors hotspot is showing up
  3. Check the router's connected devices the device will show up with the Apollo name

Troubleshooting

Manually Uploading Code Through ESPHome

If your device becomes unresponsive and you've exhausted the other troubleshooting methods you can upload a fresh set of firmware by following the below guide. The utility does need to be run from Chrome or Edge.

If your device has already been connected to Home Assistant previously please refer to Removing Device From Home Assistant first before proceeding
  1. Plug your MSR-1 into your computer with a quality USBC cable that supports data transfer

  2. Navigate to our installer page and click connect ** Install Page **

  3. Select your Apollo device, it will show with a similar name to the one below, and click connect. If you aren't sure which device it is, you can unplug the MSR-1 and see which disappears.

ComSelection.png

If no device shows, click cancel and then install the recommended driver that shows on the popup. If you have installed the driver, tried different cables, and it still won't work refer here for putting the MSR-1 in bootloader mode and then retry step 3. Putting MSR-1 In Boot Mode Document

  1. Choose to install the new firmware

  1. Wait for the installer to finish

  1. After finishing, check for the Apollo hotspot and connect. This might not show if you previously had the MSR-1 connected to your wifi

  2. Log into Home Assistant and go to the ESPHome addon check to see if you can adopt the device.

If you encounter the below error, please complete the Putting MSR-1 In Boot Mode Document and go back to step 3.

Troubleshooting

Removing Device From Home Assistant

This will cover how to remove an Apollo device from Home Assistant

  1. Navigate to Home Assistant and open your ESPHome addon

image.png

2. On the device you would like to remove, click the three dots and select "Delete"

image.png

3. Go to Settings --> Devices & Services --> ESPHome

image.png

4. On the device you would like to remove, click the three dots and then "Delete"

image.png

5. Restart your Home Assistant

image.png

 

It can take a few minutes for your Home Assistant instance to start back up

Troubleshooting

Putting The MSR-1 In Boot Mode

This will cover how to put the MSR-1 into boot mode. This is sometimes needed for uploading new firmware if the device is struggling.

  1. Unplug the device
  2. Slide the back case off
  3. Pull the device out of the case
  4. Plug back into your computer
  5. Press and hold the boot button, while holding it press and release the reset button, then release the boot button

MSR-1_Buttons.jpg

6. Continue on with uploading firmware document

Troubleshooting

Connecting To Hidden Wifi Network

Changing your wifi connection to fast connect can have stability problems
  1. Setup your device using a regular wifi network
  2. In Home Assistant go to your ESPHome add-on
  3. On your sensor click on edit
  4. Change the wifi section to look like the below but with your wifi credentials

Screenshot 2023-10-30 at 10.28.50 AM.png

4. Save and install to your device

Troubleshooting

Ubiquiti Unifi mDNS/IGMP Snooping Auto Discover Issue

If mDNS is unchecked then Home Assistant and ESPHome will not auto discover new devices. Also, if you have different networks that Home Assistant and ESPHome devices are on, then you will need mDNS on both networks and firewall rules between them. (Thank you to the Ubiquiti Discord member Blue!) Below are guides for using your PC and the Unifi Network mobile app to fix this issue.

Quick Guide

  1. Settings > Network > Multicast Settings > Select the networks you want mDNS/IGMP Snooping on

mDNS Settings.jpeg

(Thank you to the Ubiquiti Discord member MK!)

Steps for PC

1. Log into your Unifi network through your default IP address which is usually 192.168.1.1
2. Select Network

mdns1.PNG

3. Select Settings

mdns2.PNG

4. Select Networks

mdns3.PNG

5. Select the Default Network

mdns4.PNG

6. Check Multicast DNS

mdns5.PNG

7. Now the Home Assistant/ESPHome auto-discover issue should be fixed!
8. If this does not work then you can also try checking IGMP Snooping (checkbox above Multicast DNS) on your IoT networks.


Steps for the Unifi Network Mobile App

1. Open the Unifi Network app

mmdns1.PNG

2. Tap Settings/Gear Icon

mmdns2.PNG

3. Tap Networks

mmdns3.PNG

4. Tap Default Network

mmdns4.PNG

5. Tap the Multicast DNS slider

mmdns5.PNG

6. Now the Home Assistant/ESPHome auto-discover issue should be fixed!
7. If this does not work then you can also try tapping the IGMP Snooping slider on your IoT networks.

Apollo Automation YouTube Videos

Apollo Automation YouTube Videos

Apollo Automation Workshop Tour

Apollo Automation YouTube Videos

Home Assistant Green Unboxing