Firmware Guide

Local operation and GitHub update checks

The local Home Assistant firmware keeps UltimateSensor v2 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 v2 without internet access

You may block internet access for UltimateSensor v2; its local measurements and Home Assistant connection continue to work. Night Light and SPS30 quiet hours get the time from public NTP servers, so allow NTP if you use them. 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 v2 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 v2 through the SmartHomeShop web flasher before applying this customization.

This page matches the current ultimatesensor-v2 firmware in the SmartHomeShop GitHub repository.

UltimateSensor v2 is ESP32-S3 based and every v2 firmware variant includes:

• SCD41 CO2 / temperature / humidity
• SGP41 VOC / NOx
• BH1750 illuminance
• LD2412 presence radar
• LD2450 target tracking on standard hardware
• PIR motion
• microphone, speaker, media player and local wake word voice assistant
• WiFi or Ethernet as separate firmware builds

GitHub Source

• Firmware repository: github.com/smarthomeshop/ultimatesensor
• V2 folder: ultimatesensor-v2

Package Layout

Standard Firmware Variants

These are for the product as shipped with LD2412 + LD2450.

LD2460 Upgrade Variants

Use these only after physically replacing/removing the LD2450 module and installing the optional LD2460 upgrade. Leave LD2412 installed.

Read the UltimateSensor v2 LD2460 Upgrade Guide before installation.

Cloud Build Variants

Cloud variants add SmartHomeShop cloud registration/sync entities on top of the matching standard or LD2460 build, and use SmartHomeShop Cloud Voice instead of Home Assistant voice.

Variant Rules

• Basic omits complete.yaml; no SPS30 PM entities are exposed.
• Complete includes complete.yaml; SPS30 PM entities and PM Sensor controls are exposed.
• WiFi and Ethernet are separate firmware builds. ESPHome does not run WiFi and Ethernet at the same time.
• LD2450 is factory default.
• LD2460 is an upgrade firmware only. Do not flash it unless the LD2460 hardware has been installed.
• Voice assistant support is always included on UltimateSensor v2. Local firmware uses Home Assistant voice, cloud firmware uses SmartHomeShop Cloud Voice.

Firmware Controls in Home Assistant

Every UltimateSensor v2 firmware exposes:

• UltimateSensor V2 Firmware Variant to select Basic/Complete, WiFi/Ethernet and local/cloud firmware while keeping the installed LD2450 or LD2460 hardware family;
• UltimateSensor V2 Firmware, a disabled-by-default update entity that checks and installs the selected manifest.

Enable the update entity first. Changing the selector only changes the update source. The other firmware is installed when you run the update through the Firmware entity.

Flashing

Web Flasher

Note: The web flasher returns the device to its factory settings. WiFi credentials and settings saved on the device, such as offsets, are erased.

1. Connect UltimateSensor v2 to your computer with a USB-C cable that carries data, and use Chrome or Edge.
2. Open smarthomeshop.io/en/firmware?product=ultimatesensor.
3. Choose V2 (Hardware version 2) and how you use the device: Local with Home Assistant or SmartHomeShop app + local use.
4. Select the matching v2 variant:
   • WiFi or Ethernet
   • Basic or Complete
   • LD2450 standard or LD2460 upgrade
5. Click Install firmware and choose the USB port of your device.

ESPHome Device Builder

After adoption, the device imports one of the v2 package URLs, for example:

dashboard_import:
  package_import_url: github://smarthomeshop/ultimatesensor/ultimatesensor-v2/ultimatesensor-v2-wifi-complete.yaml@main

Change only to another ultimatesensor-v2/... package that matches the hardware. Building the firmware yourself requires ESPHome 2026.10.0 or newer.

WiFi and Ethernet

• WiFi variants keep the W5500 Ethernet hardware powered off.
• Ethernet variants power the W5500 and expose Ethernet network info entities.
• If switching from WiFi to Ethernet, connect the network cable first and keep USB-C connected until the Ethernet firmware runs. PoE only works with Ethernet firmware.
• To switch from Ethernet back to WiFi, use USB-C flashing. Do not rely on OTA, because the network can drop before the WiFi firmware is installed.

Firmware Entity Names

See Sensor Definitions for the exact entity names and ESPHome IDs used by the current firmware.

Need Help?

• Support portal
• Discord
• GitHub repository