SmartHomeShop Docs

Firmware Guide

Local operation and GitHub update checks

The local Home Assistant firmware keeps UltimateSensor v1 measurements on your own network. Sensor readings go directly to Home Assistant and are not sent to GitHub or the SmartHomeShop cloud.

Wi-Fi and Ethernet firmware includes an ESPHome update entity. It periodically reads a small firmware manifest from SmartHomeShop GitHub Pages to compare the installed version with the latest release. Only firmware metadata is requested; the firmware file is downloaded only when you install an update.

Cloud firmware intentionally communicates with the SmartHomeShop app as part of its cloud features. Disabling the GitHub update check does not convert cloud firmware into local firmware.

Use UltimateSensor v1 without internet access

You may block internet access for UltimateSensor v1; its local measurements and Home Assistant connection continue to work. To prevent a blocked check from triggering the red status LED, take control of the device in the ESPHome Device Builder app/add-on, open its YAML and add this at the bottom:

update:
  - id: !extend firmware_update
    update_interval: never

Save the YAML, select Validate, and install the build using Install > Wirelessly. This disables scheduled checks only; it does not remove the update component or change any UltimateSensor v1 sensors.

The adopted YAML continues to contain a packages: link to the SmartHomeShop GitHub repository. ESPHome uses that link on the Home Assistant host when it compiles your firmware. The device itself no longer polls for firmware versions after the customized build is installed.

To restore automatic checks, remove the added update: block and install the firmware again. If ESPHome cannot find the firmware_update ID, update UltimateSensor v1 through the SmartHomeShop web flasher before applying this customization.

UltimateSensor runs on ESPHome, an open-source firmware platform that works with Home Assistant. ESPHome allows you to customize every aspect of your device's behavior while maintaining full local control, no cloud required.

Version 2.0 requires USB-C once: UltimateSensor V1 firmware 2.0 moves the device from Arduino to ESP-IDF. Devices running firmware 1.13 or older must install version 2.0 once through USB-C. Do not install this framework migration through Home Assistant or OTA. After version 2.0 has been installed through USB-C, future 2.x firmware updates work wirelessly again. Follow the dedicated Version 2.0 Upgrade Guide.

Version 2.0 Architecture

Version 2.0 uses ESP-IDF for all eight V1 firmware variants and retains the native LD2450 tracking platform introduced in firmware 1.11:

  • native LD2450 tracking for up to three people;
  • four polygon zones and two exclusion zones;
  • two virtual entry lines and people counting;
  • Home Assistant actions for sending zones from the SmartHomeShop Room Designer.

Existing rectangular zone settings from firmware older than 1.11 are not converted automatically. Save your current settings before the USB-C installation and configure the polygon zones afterwards.

If you have questions about the update, join the SmartHomeShop Discord community.

Firmware on GitHub

All UltimateSensor firmware is public on GitHub under the CC BY-NC 4.0 license:

🔗 github.com/smarthomeshop/ultimatesensor

The repository includes:

  • Complete ESPHome configurations for all variants
  • Modular package system for easy customization
  • Customer-facing release notes in CHANGELOG.md
  • Community contributions welcome (PRs & issues)

You can view, modify, and customize the firmware to suit your needs, from adjusting sensor thresholds to adding completely new features.

Firmware Variants

UltimateSensor V1 offers four network/hardware combinations. Each combination is available as local Home Assistant firmware or as SmartHomeShop App cloud firmware, for a total of 8 firmware variants:

Network Types

  • WiFi: Standard 2.4GHz wireless connectivity
  • Ethernet: Wired connection with optional PoE support

Sensor Levels

  • Basic: CO₂, Temp, Humidity, Light, VOC, NOx, mmWave, PIR
  • Complete: All Basic sensors + Particulate Matter (PM) monitoring

Variant names:

  • ultimatesensor-wifi-basic - Basic sensors with WiFi
  • ultimatesensor-wifi-complete - All sensors with WiFi
  • ultimatesensor-ethernet-basic - Basic sensors with Ethernet/PoE
  • ultimatesensor-ethernet-complete - All sensors with Ethernet/PoE
  • Add -cloud to the variant name when SmartHomeShop App support is required

Tip: Use our web flasher at smarthomeshop.io/en/firmware?product=ultimatesensor to easily select and install the right variant.

🔍 How to identify your variant: If your device measures PM1.0, PM2.5, PM4.0, PM10 → you have Complete. Otherwise → Basic.

Switching Variants

Every UltimateSensor V1 with firmware 1.12 or newer has a UltimateSensor Firmware Variant selector in Home Assistant with all eight variants. The setup page of WiFi firmware lets you choose WiFi or Ethernet and SmartHomeShop Cloud on or off.

  • On WiFi firmware: select the new variant. The device downloads and installs it over WiFi by itself and restarts. Allow at least 2 minutes and keep it powered. If you chose Ethernet, the Ethernet port works after the restart.
  • On Ethernet firmware: the selector only changes the update source. The update entity offers the other variant when that has a newer version than the installed one. To switch right away, use USB-C (Method 3).

Only select a Complete variant if your device has the PM sensor.

Quick Update Methods

Method 1: Home Assistant (Easiest)

For regular firmware updates after version 2.0 has been installed via USB-C:

  1. Go to Settings → Devices & Services → Devices
  2. Select your UltimateSensor device
  3. Enable the UltimateSensor Firmware update entity, it is disabled by default
  4. Open that entity and click Check for updates
  5. Click Install to download and apply the update
  6. The device will reboot automatically

Method 2: ESPHome Device Builder

For updates with custom configurations after the version 2.0 USB-C migration:

⚠️ Important: This method requires the ESPHome Device Builder app, version 2026.10.0 or newer, not just the ESPHome integration. If you haven't installed it yet, see the ESPHome Integration Guide section below for step-by-step installation instructions.

  1. Open the ESPHome Device Builder in Home Assistant (from the sidebar)
  2. Click on your UltimateSensor device card
  3. Click Install → choose Wirelessly
  4. Wait for the OTA update to complete

Method 3: USB-C Web Flasher

Required for the version 2.0 migration, for recovering devices and for leaving Ethernet firmware:

⚠️ Hardware step: Before flashing via USB-C, you must remove the LD2450 mmWave sensor because it can stop the device from entering flash mode. See the preparation steps below.

Preparation:

  1. Disconnect USB-C, Ethernet/PoE and all other power
  2. Open the case: locate the small cutout at the bottom for a flat screwdriver
  3. Note the orientation of the blue LD2450 sensor
  4. Remove the blue LD2450 sensor: gently pull it straight out from the front of the main PCB

Flashing steps:

  1. Connect UltimateSensor via USB-C data cable to your computer
  2. Open the flasher in Chrome or Edge: smarthomeshop.io/en/firmware?product=ultimatesensor&hardware=v1
  3. Choose how you use the device, then your firmware variant (WiFi/Ethernet + Basic/Complete)
  4. Click Install firmware and choose the USB port
  5. Wait until the website confirms that flashing is complete, then disconnect the USB-C cable
  6. Reassemble: reinsert the LD2450 sensor in exactly the same orientation and close the case

Warning: Installing the LD2450 in the wrong orientation can damage the hardware. Never remove or reinstall it while the UltimateSensor is powered.

Note: Flashing from this page returns the device to its factory settings. WiFi variants start the setup hotspot again, Ethernet variants get an IP address through DHCP. You may need to add the device to Home Assistant again.

ESPHome Integration Guide

Want to customize your UltimateSensor firmware? Follow this step-by-step guide to adopt your device in ESPHome and make modifications.

🚨 Critical: Understanding the Difference

Many users get confused between two different things:

  • ESPHome Integration (Settings → Devices & Services → Integrations) - This is how your UltimateSensor communicates with Home Assistant. You probably already have this. ✅
  • ESPHome Device Builder app (Settings → Apps) - This is the tool you need to edit, build, and flash firmware. You need to install this separately! 🔧

To customize firmware, you MUST install the ESPHome Device Builder app below. Having just the integration is not enough!

Step 1: Install ESPHome Device Builder

If you haven't installed the ESPHome Device Builder app yet:

  1. Open Home Assistant → Settings → Apps
  2. Click Install app
  3. Search for ESPHome Device Builder
  4. Click ESPHome Device Builder → Install
  5. Enable Start on boot and Show in sidebar
  6. Click Start

Step 2: Adopt Your UltimateSensor

Adopting allows ESPHome to manage your device's configuration:

  1. Open ESPHome from the Home Assistant sidebar
  2. Your UltimateSensor should appear as a discovered device
  3. Click Take control or Adopt on the UltimateSensor card
  4. Give it a name (e.g., "Living Room UltimateSensor")
  5. Confirm

ESPHome now creates a small YAML file that points to the firmware on GitHub.

What does the adopted configuration look like?

After adoption, you'll see a YAML configuration that looks like this:

substitutions:
  name: ultimatesensor-1a2b3c
  friendly_name: UltimateSensor 1a2b3c

packages:
  smarthomeshop.ultimatesensor: github://smarthomeshop/ultimatesensor/ultimatesensor-v1/ultimatesensor-wifi-complete.yaml@main

esphome:
  name: ${name}
  name_add_mac_suffix: false
  friendly_name: ${friendly_name}

api:
  encryption:
    key: YOUR_UNIQUE_ENCRYPTION_KEY

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Understanding this structure:

  • substitutions: The name of your device.
  • packages: Links to the base configuration on GitHub. ESPHome downloads it each time you install the firmware.
  • api/wifi: Your device's unique encryption key and WiFi credentials.

This modular approach means: ✅ You get the latest configuration from GitHub each time you install ✅ Your customizations stay separate from the base configuration ✅ You don't need to copy/paste the entire configuration

Step 3: Customize the Configuration

After adoption, you can modify the YAML configuration:

  1. Click Edit on your adopted UltimateSensor device
  2. The YAML editor opens with your current configuration
  3. Make your desired changes (see examples below)
  4. Click Save

Step 4: Upload Modified Firmware

After making changes:

  1. Click Install on your device card
  2. Choose Wirelessly (recommended) or Plug into this computer
  3. ESPHome will compile and upload your custom firmware
  4. Wait for the device to reboot and reconnect

✅ Done! Your UltimateSensor is now running custom firmware.

Advanced Customization

Example 1: Adjust CO₂ Sensor Settings

Customize the CO₂ measurement interval and temperature offset by extending the existing sensor:

sensor:
  - id: !extend scd41
    update_interval: 60s  # Default: 30s
    temperature_offset: 4.0  # ESPHome default
    automatic_self_calibration: true  # ESPHome default

Example 2: Configure mmWave Radar Zones

You do not need YAML for zones. Draw polygon zones, exclusion zones and entry lines in the Room Designer of the SmartHomeShop integration. See the Calibration Guide.

Example 3: Add Bluetooth Proxy

Turn your UltimateSensor into a Bluetooth proxy for other devices:

esp32_ble_tracker:
  scan_parameters:
    interval: 1100ms
    window: 1100ms
    active: true

bluetooth_proxy:
  active: true

Example 4: Custom Air Quality Alerts

Add automations directly on the device:

binary_sensor:
  - platform: template
    name: "Poor Air Quality Alert"
    lambda: |-
      if (id(scd41_co2).state > 1000 || id(PM_2_5).state > 25) {  // PM_2_5: Complete only
        return true;
      }
      return false;

Example 5: Adjust Ambient Pressure

For improved CO₂ accuracy based on your altitude:

# Set via a Home Assistant action:
# Action: esphome.<your_device_name>_set_ambient_pressure
# Data: { pressure_mbar: 1013 }

# Or set your altitude in YAML:
sensor:
  - id: !extend scd41
    altitude_compensation: 100m

Learn More: Check the ESPHome documentation for complete configuration reference.

Modular Configuration Structure

UltimateSensor firmware uses a modular architecture with reusable packages:

ultimatesensor-v1/
├── base.yaml                  # Device, sensors, display and controls
├── wifi.yaml                  # WiFi, setup hotspot and Improv
├── ethernet.yaml              # Ethernet
├── complete.yaml              # SPS30 particulate matter sensor
├── tracking-ld2450.yaml       # LD2450 radar and polygon zones
├── led-lighting.yaml          # Automatic back LED
├── firmware-selector.yaml     # Variant selector and update entity
├── cloud*.yaml                # SmartHomeShop App firmware
├── ultimatesensor-wifi-basic.yaml
├── ultimatesensor-wifi-complete.yaml
├── ultimatesensor-ethernet-basic.yaml
├── ultimatesensor-ethernet-complete.yaml
└── the same four files ending in -cloud.yaml

This modular design makes it easy to:

  • Switch between WiFi and Ethernet
  • Add/remove the PM sensor (Basic ↔ Complete)
  • Share configurations across devices
  • Contribute improvements back to the community

Troubleshooting

Device Won't Update OTA

Symptoms: OTA update fails or times out

Solutions:

  1. Ensure the device is powered on and connected to WiFi/Ethernet
  2. Check that the device has strong network signal
  3. Verify ota: is enabled in your YAML configuration
  4. Try restarting the device with the Restart UltimateSensor button on its device page in Home Assistant
  5. If all else fails, flash via USB-C cable

Device Not Discovered After Flashing

Symptoms: UltimateSensor doesn't appear in Home Assistant after USB flashing

Solutions:

  1. The device may have lost WiFi credentials during flashing
  2. Connect via USB-C and check the logs in ESPHome
  3. Use the captive portal:
    • Device creates a WiFi hotspot named ultimatesensor with password ultimatesensor
    • Connect to it and configure WiFi on the setup page
  4. Check your router's DHCP client list for the new device IP

Wrong Variant Flashed

Symptoms: Sensors missing or not working as expected

Solution:

  1. Verify you flashed the correct variant for your hardware
  2. Check if you have the PM sensor (Complete) or not (Basic)
  3. Check if you need WiFi or Ethernet
  4. Flash the correct variant using the web flasher

Sensor Readings Seem Inaccurate

Solutions:

  1. CO₂ sensor: Requires 1-2 weeks of automatic self-calibration for optimal accuracy
  2. Temperature: Device generates internal heat. Allow 15-30 minutes to stabilize after power-on
  3. PM sensor (Complete only): Clean the fan with compressed air if readings seem stuck
  4. mmWave radar: Adjust your zones in the Room Designer
  5. See the Calibration Guide for detailed calibration instructions

Compilation Errors in ESPHome

Symptoms: Custom YAML fails to compile

Solutions:

  1. Check for YAML syntax errors (indentation must be consistent)
  2. Verify you're using ESPHome 2026.10.0 or newer, older versions refuse this firmware
  3. Check the compilation log for specific error messages
  4. Compare your changes against the official configuration
  5. Ask for help on GitHub Issues or our Discord community

Ethernet Not Working

Symptoms: Ethernet connection fails or unstable

Solutions:

  1. Ensure you flashed the Ethernet firmware variant (not WiFi)
  2. Verify your PoE switch provides sufficient power (IEEE 802.3af)
  3. Check Ethernet cable is properly seated in both ends
  4. Test with a known-good Ethernet cable
  5. Check Ethernet port LED is lit (solid or blinking)
  6. See the Network Configuration Guide for detailed troubleshooting

USB-C Flashing Fails

Symptoms: Device not detected or flash fails

Solutions:

  1. Ensure you removed the LD2450 mmWave sensor
  2. Try a different USB-C cable (some are charge-only)
  3. Try a different USB port
  4. Try a different computer/browser (Chrome/Edge recommended)
  5. Check that no other program is using the serial port

Firmware Changelog

Latest changes are announced alongside releases. Major updates will appear here.

Where to find changes:

Additional Resources

Need help? Visit our Support Portal or join our Discord community!