Turn your M5Stack Atom Lite, AtomS3 or NanoC6 into a Bluetooth proxy for Home Assistant
Pick the config for your hardware:
| Board | Device Builder package | CLI |
|---|---|---|
| M5Stack NanoC6 | esphome-m5-btproxy-m5stack-nanoc6.dashboard.yml |
BOARD=m5stack-nanoc6 |
| M5Stack AtomS3 | esphome-m5-btproxy-m5stack-atoms3.dashboard.yml |
BOARD=m5stack-atoms3 |
| M5Stack Atom Lite | esphome-m5-btproxy-m5stack-atom.dashboard.yml |
BOARD=m5stack-atom |
| AtomS3 + I2C sensor | esphome-m5-btproxy-m5stack-atoms3-i2c.dashboard.yml |
BOARD=m5stack-atoms3-i2c |
| NanoC6 + I2C sensor | esphome-m5-btproxy-m5stack-nanoc6-i2c.dashboard.yml |
BOARD=m5stack-nanoc6-i2c |
Prebuilt firmware for the Atom Lite, AtomS3 and NanoC6 (not the I2C variants) can be flashed directly from your browser: https://yoziru.github.io/esphome-m5-btproxy/.
If you run the ESPHome add-on in Home Assistant:
- For a new, unflashed board, select Create configuration → Create new project and complete the name and Wi-Fi setup. For a board already running this project's firmware, use Adopt instead.
- Open the device's YAML editor. Keep the generated
esphome,api, andwifisections, but remove the generatedesp32:section. The board package below supplies the correct target and framework settings. - Add these entries to the
secrets.yamlused by your ESPHome configuration:
wifi_ssid: "your-wifi-ssid"
wifi_password: "your-wifi-password"
wifi_hotspot_password: "12345678"
ota_password: "a-unique-high-entropy-password"
api_encryption_key: "your-api-encryption-key"- Add the OTA password to the top-level
substitutionssection:
substitutions:
# The left-hand name is fixed. Change only the secret name on the right.
# Set this to main, a branch, a release tag, or a commit SHA.
m5_btproxy_ref: main
ota_password: !secret ota_password- Add the board package under the top-level
packagessection. It provides the matchingesp32:target and the required current ESPHome OTA configuration (ota: - platform: esphome). Do not add separateesp32:orota:sections. For an M5Stack NanoC6:
packages:
yoziru.esphome-m5-btproxy:
url: https://github.com/yoziru/esphome-m5-btproxy.git
ref: ${m5_btproxy_ref}
files: [esphome-m5-btproxy-m5stack-nanoc6.dashboard.yml]- Save and Install. Future firmware updates are applied from this same device card with Update.
Use the matching .dashboard.yml file from the board table above for other hardware.
Wrong board? If the upload reaches 100% but ends with Finishing update failed, the board file doesn't match your chip (e.g. NanoC6 firmware on an AtomS3). Switch files: to the .dashboard.yml for your hardware and install again.
Set m5_btproxy_ref once to test a branch, tag, or commit SHA. It selects the YAML package version. Local CLI builds need no override because they use the current checkout's packages/ directory.
For example, an adopted NanoC6 with the YAML generated by current ESPHome Device Builder should look like this. Preserve the generated name, friendly name, API key, and Wi-Fi secrets from your device.
substitutions:
name: m5-btproxy-a1b2c3
friendly_name: M5 BTProxy a1b2c3
m5_btproxy_ref: main
ota_password: !secret ota_password
packages:
yoziru.esphome-m5-btproxy:
url: https://github.com/yoziru/esphome-m5-btproxy.git
ref: ${m5_btproxy_ref}
files: [esphome-m5-btproxy-m5stack-nanoc6.dashboard.yml]
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
api:
encryption:
key: !secret api_encryption_key
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
password: !secret wifi_hotspot_passwordNo pre-made file for your board? Point files: at packages/dashboard.yml and supply the chip settings yourself: board/variant/flash_size matching the physical chip (flash_size at most the actual flash), the full esp32: framework block from the closest boards/*.yml (see boards/m5stack-nanoc6.yml), plus your own status LED/button if wanted.
substitutions:
board: esp32-c6-devkitm-1
variant: esp32c6
flash_size: 4MB
m5_btproxy_ref: main
ota_password: !secret ota_password
packages:
yoziru.esphome-m5-btproxy:
url: https://github.com/yoziru/esphome-m5-btproxy.git
ref: ${m5_btproxy_ref}
files: [packages/dashboard.yml]
esp32:
framework:
sdkconfig_options:
CONFIG_OPENTHREAD_ENABLED: n
# + the rest from the closest boards/*.ymlCopy secrets.yaml.example → secrets.yaml, fill in WiFi + OTA + API key, then build for your board:
BOARD=m5stack-nanoc6 make compile && BOARD=m5stack-nanoc6 make uploadSee make help for all targets (validate-config, validate-dashboard-config, logs, clean).