Firmware Guide

Local operation and GitHub update checks

The local Home Assistant firmware keeps UltimateSensor Mini 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. Thread firmware has no update check.

Use UltimateSensor Mini v2 without internet access

You may block internet access for UltimateSensor Mini v2; its local measurements and Home Assistant connection continue to work. 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 Mini 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 Mini v2 through the SmartHomeShop web flasher before applying this customization.

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

Mini v2 uses the shared SmartHomeShop LD2450 and LD2460 radar packages. The device web interface groups Air Quality and Presence values, cloud telemetry includes CPU temperature and all WiFi builds include the branded setup portal.

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

• SCD41 CO2 / temperature / humidity
• SGP41 VOC / NOx
• BH1750 illuminance
• LD2412 presence radar
• LD2450 target tracking on standard hardware
• WiFi or Ethernet as separate firmware builds

Mini v2 firmware does not include microphone, speaker, media player, PIR, voice assistant or local wake word support.

GitHub Source

• Firmware repository: github.com/smarthomeshop/ultimatesensor-mini
• Mini v2 folder: ultimatesensor-mini-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 Mini 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.

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.
• Mini v2 has no voice firmware variant.

Firmware Controls in Home Assistant

Every WiFi and Ethernet build exposes:

• UltimateSensor Mini V2 Firmware Variant to select Basic/Complete, WiFi/Ethernet and local/cloud firmware while keeping the installed LD2450 or LD2460 hardware family;
• UltimateSensor Mini 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. Thread builds have neither entity: you update them through the ESPHome Device Builder.

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 Mini 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-mini.
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 Mini 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 Mini v2 package URLs, for example:

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

Change only to another ultimatesensor-mini-v2/... package that matches the hardware.

Customize with ESPHome Device Builder

Use this when you want to make a permanent YAML change, such as changing scd41_temperature_offset.

Important distinction:

• ESPHome integration in Home Assistant is how the Mini v2 communicates with Home Assistant.
• ESPHome Device Builder app is the tool used to edit YAML, build firmware and upload it to the device.

Having the integration is not enough for YAML changes. Install and use the ESPHome Device Builder app.

1. Open Home Assistant -> Settings -> Apps.
2. Install and start the ESPHome Device Builder app if it is not installed yet.
3. Open ESPHome Device Builder from the Home Assistant sidebar.
4. If the Mini v2 appears as a discovered device, click Adopt.
5. After adoption, click Edit on the Mini v2 device card.
6. Keep the packages: import in place and change only the needed substitutions.
7. Click Save.
8. Click Install -> Wirelessly to build and upload the changed firmware.
9. Wait for the Mini v2 to reboot and reconnect.

For temperature calibration, the relevant part is:

substitutions:
  scd41_temperature_offset: "10.2"

If you tune temperature through this substitution, keep the Home Assistant Temperature Offset entity at 0 to avoid double correction. If wireless upload fails, use USB-C flashing from the web flasher instead.

For the advanced, self-built Ethernet Basic configuration, see Build a Bluetooth Proxy. This is not included in the standard firmware.

WiFi and Ethernet

• WiFi variants keep the W5500 Ethernet hardware powered off and held in reset.
• Ethernet variants power the W5500 and expose Ethernet network info entities.
• Mini v2 WiFi firmware uses the SmartHomeShop setup portal on top of the captive portal. It can configure WiFi, choose Home Assistant and/or SmartHomeShop App cloud use, and choose the WiFi/Ethernet plus Basic/Complete firmware family.
• BLE Improv remains available as an alternative onboarding method.
• Serial Improv is not included because both available hardware UARTs are reserved for LD2412 and LD2450/LD2460.
• 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

Thread Firmware

UltimateSensor Mini v2 can also join a Thread network instead of WiFi or Ethernet, for local Home Assistant use through a Thread border router. See Connect UltimateSensor Mini v2 via Thread.