Running ESPHome Firmware on Dongle-M

This guide is intended for SONOFF Dongle users who are familiar with ESPHome. It explains how to run ESPHome firmware on the ESP32 SoC of SONOFF Dongle Max (Dongle-M), covering YAML configuration, firmware flashing, and remote management of Zigbee and Thread firmware on the MG24 SoC using the Universal Silicon Labs Flasher over TCP.

Note: For users who prefer an out-of-the-box experience, we recommend continuing to use the stock Dongle-M firmware.


Advantages and Disadvantages of Running ESPHome Firmware on Dongle-M #

Dongle-M uses a dual-chip architecture consisting of an ESP32 (Wi-Fi SoC) and an MG24 (Zigbee/Thread SoC). The ESP32 handles functions such as Wi-Fi and Ethernet, and provides a TCP port for transmitting and receiving serial data from the MG24. The MG24 serves as a Zigbee NCP (Zigbee Coordinator), Zigbee Router, OpenThread RCP, or Multiprotocol RCP.

Note: ESPHome firmware runs exclusively on Dongle-M's ESP32 Wi-Fi SoC. Flashing ESPHome firmware onto Dongle-M will not affect the functionality of the firmware on the MG24 SoC.

The advantages of running ESPHome firmware include:

  1. Open source and mature: ESPHome is 100% open source and is a project of Open Home Foundation. Many commercial products now ship with ESPHome firmware pre-installed. For details, please refer to the Made for ESPHome device list.
  2. Extensive component library: ESPHome offers over 40 functional components, with many more developed by third parties available on GitHub. If the stock firmware of Dongle-M lacks a feature you need, ESPHome may provide it.
  3. Custom-tailored firmware: You can customize firmware functionality to suit your specific use case by writing a YAML configuration file—no programming required. In most cases, custom-tailored firmware uses less RAM and flash memory and runs more efficiently.
  4. Home Assistant integration: Home Assistant includes built-in ESPHome integration. ESPHome devices can be automatically discovered and configured by Home Assistant. You can use ESPHome Home Assistant app (ESPHome Device Builder) to manage YAML configurations, compile new firmware versions, and perform over-the-air (OTA) updates.

The disadvantages of running ESPHome firmware include:

  1. No web console: The stock Dongle-M firmware comes with a built-in web console, which makes it easy to configure and manage the firmware's various features. ESPHome firmware, by contrast, is managed primarily through YAML configuration files and the ESPHome Device Builder.
  2. No official SONOFF technical support: Features of ESPHome firmware are not developed by SONOFF team. For the various issues you may encounter while using ESPHome firmware, SONOFF team is unlikely to be able to provide effective technical support. In most cases, you will need to search online for solutions or post in forums for help.

Note: Running ESPHome firmware will not void your Dongle-M's warranty. You can flash the latest version of stock firmware onto Dongle-M at any time using SONOFF Dongle Flasher.


Dongle-M GPIO Pinout #

FunctionESP32 GPIODirectionNotes
EFR32MG24 UART RXGPIO13InputData from EFR32MG24 to ESP32
EFR32MG24 UART TXGPIO17OutputData from ESP32 to EFR32MG24
EFR32MG24 ResetGPIO15OutputActive LOW
EFR32MG24 BootloaderGPIO12OutputUsed to enter radio bootloader mode
RGB LED - RedGPIO4Output / PWMLEDC PWM
RGB LED - GreenGPIO14Output / PWMLEDC PWM
RGB LED - BlueGPIO2Output / PWMLEDC PWM
User ButtonGPIO34InputActive LOW
Ethernet MDCGPIO23OutputIP101 PHY management clock
Ethernet MDIOGPIO18I/OIP101 PHY management data
Ethernet REF_CLKGPIO0InputExternal 50 MHz RMII clock

ESPHome Firmware YAML Examples and Corresponding Functions #

The Most Basic: UART over Ethernet, Uptime #

esphome:
  name: dongle-m
  friendly_name: "Dongle Max"

  on_boot:
    - priority: -100
      then:
        - text_sensor.template.publish:
            id: uart_tcp_connection_status
            state: "Disconnected"

esp32:
  variant: esp32
  flash_size: 16MB
  cpu_frequency: 240MHz
  framework:
    type: esp-idf

psram:
  mode: quad
  speed: 80MHz

logger:

api:
  encryption:
    key: # Specify the encryption key. Leave empty to let ESPHome generate one
ota:
  - platform: esphome
    allow_partition_access: true
    encryption:

external_components:
  - source: github://SONOFF-Technologies/esphome-stream-server

ethernet:
  id: ethernet_network
  type: IP101
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 1
  power_pin:
    number: GPIO5

preferences:
  flash_write_interval: 1s

uart:
  id: radio_uart
  rx_pin: GPIO13
  tx_pin: GPIO17
  baud_rate: 115200

stream_server:
  - id: radio_stream_server
    uart_id: radio_uart
    port: 6638

binary_sensor:
  - platform: stream_server
    stream_server: radio_stream_server
    connected:
      id: radio_tcp_connected
      internal: true
      on_press:
        - text_sensor.template.publish:
            id: uart_tcp_connection_status
            state: "Connected"
      on_release:
        - text_sensor.template.publish:
            id: uart_tcp_connection_status
            state: "Disconnected"

text_sensor:
  - platform: template
    id: uart_tcp_connection_status
    name: "UART over TCP"
    icon: mdi:lan-connect
    update_interval: never

sensor:
  - platform: uptime
    name: "Uptime"
    entity_category: diagnostic
YAML

Add Feature: UART over Wi-Fi, Fallback Access Point, RSSI #

network:
  priority: # Order of preference for network interfaces when more than one is configured.
    - ethernet # Prefer ethernet over Wi-Fi.
    - wifi

wifi:
  id: wifi_network
  ssid: # Specify the WLAN that your Dongle Max should connect to.
  password: # Specify the password of that WLAN.
  ap: # Fallback Access Point provided by Dongle Max.
    ssid: "Dongle-M_ESPHome" # Name of the access point to create.
    password: # Password for the access point. Leave empty for an open network.

captive_portal:

# ESPHome doesn't allow `sensor` to appear twice,
# so make sure to merge it with existing one after `Copy and Paste`.
sensor:  
  - platform: wifi_signal
    name: "RSSI"
    entity_category: diagnostic
YAML

Add Feature: Bluetooth Proxy #

esp32_ble_tracker:
bluetooth_proxy:
YAML

Add Feature: MG24 SoC Management #

# ESPHome doesn't allow `esphome` and `on_boot` to appear twice,
# so make sure to merge them with existing ones after `Copy and Paste`.
esphome:
  on_boot:
    - priority: 600
      then:
        - switch.turn_off: radio_bootloader
        - delay: 100ms
        - switch.turn_on: radio_reset
        - delay: 100ms
        - switch.turn_off: radio_reset

globals:
  - id: mg24_bootloader_active
    type: bool
    restore_value: no
    initial_value: 'false'

switch:
  - platform: gpio
    id: radio_reset
    restore_mode: ALWAYS_OFF
    pin:
      number: GPIO15
      mode: OUTPUT
      inverted: true

  - platform: gpio
    id: radio_bootloader
    restore_mode: ALWAYS_OFF
    pin:
      number: GPIO12
      mode: OUTPUT
      inverted: false

  - platform: template
    id: mg24_bootloader_switch
    name: "MG24 bootloader mode"
    icon: mdi:memory
    lambda: |-
      return id(mg24_bootloader_active);
    turn_on_action:
      - script.execute: enter_radio_bootloader
    turn_off_action:
      - script.execute: reset_radio_to_app

button:
  - platform: template
    id: radio_reset_button
    name: "MG24 restart"
    icon: mdi:restart
    on_press:
      - script.execute: reset_radio_to_app

# The selected value is persisted across restarts.
# Bootloader communication always uses 115200 baud.
select:
  - platform: template
    id: radio_baud_rate
    name: "MG24 baud rate"
    icon: mdi:swap-horizontal
    entity_category: config
    options:
      - "115200"
      - "460800"
      - "921600"

    initial_option: "115200"
    optimistic: true
    restore_value: true

    on_value:
      - if:
          condition:
            lambda: |-
              return !id(mg24_bootloader_active);
          then:
            - script.execute: apply_radio_app_baud_rate

script:
  - id: enter_radio_bootloader
    mode: restart
    then:
      - lambda: |-
          id(mg24_bootloader_active) = true;

          id(radio_uart).flush();
          if (id(radio_uart).get_baud_rate() != 115200) {
            id(radio_uart).set_baud_rate(115200);
            id(radio_uart).load_settings();
          }

          id(mg24_bootloader_switch).publish_state(true);

      - delay: 100ms
      - switch.turn_on: radio_bootloader
      - delay: 100ms
      - switch.turn_on: radio_reset
      - delay: 100ms
      - switch.turn_off: radio_reset

  - id: reset_radio_to_app
    mode: restart
    then:
      - switch.turn_off: radio_bootloader
      - delay: 100ms
      - switch.turn_on: radio_reset
      - delay: 100ms
      - switch.turn_off: radio_reset
      - lambda: |-
          id(mg24_bootloader_active) = false;
          id(mg24_bootloader_switch).publish_state(false);
      - script.execute: apply_radio_app_baud_rate

  - id: apply_radio_app_baud_rate
    mode: restart
    then:
      - lambda: |-
          const auto option = id(radio_baud_rate).current_option();

          uint32_t baud_rate = 115200;
          if (option == "460800")
            baud_rate = 460800;
          else if (option == "921600")
            baud_rate = 921600;

          if (id(radio_uart).get_baud_rate() != baud_rate) {
            id(radio_uart).flush();
            id(radio_uart).set_baud_rate(baud_rate);
            id(radio_uart).load_settings();
          }
YAML

Add Feature: LED Indicator Management #

output:
  - platform: ledc
    id: status_led_red
    pin: GPIO4
    frequency: 5000Hz
    channel: 0

  - platform: ledc
    id: status_led_green
    pin: GPIO14
    frequency: 5000Hz
    channel: 2

  - platform: ledc
    id: status_led_blue
    pin: GPIO2
    frequency: 5000Hz
    channel: 4

light:
  - platform: rgb
    id: status_rgb
    name: "LED"
    icon: mdi:led-on
    red: status_led_red
    green: status_led_green
    blue: status_led_blue
    gamma_correct: 2.0
    default_transition_length: 0s
    flash_transition_length: 0s
    restore_mode: ALWAYS_OFF
    effects:
      - pulse:
          name: "Blink 500ms"
          transition_length: 0s
          update_interval: 500ms
          min_brightness: 0%
          max_brightness: 100%
      - pulse:
          name: "Breathing"
          transition_length: 500ms
          update_interval: 500ms
          min_brightness: 0%
          max_brightness: 100%
YAML

Add Feature: Button Events #

# ESPHome doesn't allow `globals`, `binary_sensor` and `script` to appear twice,
# so make sure to merge them with existing ones after `Copy and Paste`.

globals:
  - id: button_long_active
    type: bool
    restore_value: no
    initial_value: 'false'

event:
  - platform: template
    id: user_button_event
    name: "Button"
    icon: mdi:gesture-tap-button
    event_types:
      - "single click"
      - "double click"
      - "long press"
      - "long release"

binary_sensor:
  - platform: gpio
    id: user_button
    icon: mdi:gesture-tap-button
    pin:
      number: GPIO34
      mode:
        input: true
      inverted: true
    filters:
      - delayed_on_off: 20ms
    on_press:
      then:
        - lambda: |-
            id(button_long_active) = false;
        - script.execute: button_long_press_detector
    on_release:
      then:
        - script.stop: button_long_press_detector
        - if:
            condition:
              lambda: |-
                return id(button_long_active);
            then:
              - event.trigger:
                  id: user_button_event
                  event_type: "long release"
              - lambda: |-
                  id(button_long_active) = false;
    on_multi_click:
      - timing:
          - ON for 40ms to 800ms
          - OFF for 40ms to 400ms
          - ON for 40ms to 800ms
          - OFF for at least 500ms
        then:
          - event.trigger:
              id: user_button_event
              event_type: "double click"

      - timing:
          - ON for 40ms to 800ms
          - OFF for at least 500ms
        then:
          - event.trigger:
              id: user_button_event
              event_type: "single click"
          - script.execute: single_click_indicator

script:
  - id: button_long_press_detector
    mode: restart
    then:
      - delay: 5s
      - if:
          condition:
            binary_sensor.is_on: user_button
          then:
            - lambda: |-
                id(button_long_active) = true;
            - event.trigger:
                id: user_button_event
                event_type: "long press"
YAML

The All-in-One: Which Works Like the Stock Firmware #

esphome:
  name: dongle-m
  friendly_name: "Dongle Max"
  includes:
    - <esp_wifi.h>

  # Initialize runtime state, reset the MG24 radio, and indicate booting.
  on_boot:
    - priority: 600
      then:
        - switch.turn_off: radio_bootloader
        - delay: 100ms
        - switch.turn_on: radio_reset
        - delay: 100ms
        - switch.turn_off: radio_reset
        - light.turn_on:
            id: status_rgb
            brightness: 100%
            red: 0%
            green: 0%
            blue: 100%
            effect: "Blink 500ms"

    # Initialize connection status after ESPHome components are ready.
    - priority: -100
      then:
        - text_sensor.template.publish:
            id: uart_tcp_connection_status
            state: "Disconnected"
        - script.execute: update_status_led

# ESP32 hardware and framework configuration.
esp32:
  variant: esp32
  flash_size: 16MB
  cpu_frequency: 240MHz
  framework:
    type: esp-idf

psram:
  mode: quad
  speed: 80MHz

logger:

api:
  encryption:
    key: # Specify the encryption key. Leave empty to let ESPHome generate one

ota:
  - platform: esphome
    allow_partition_access: true
    encryption:

external_components:
  - source: github://SONOFF-Technologies/esphome-stream-server

network:
  priority: # Order of preference for network interfaces when more than one is configured.
    - ethernet # Prefer ethernet over Wi-Fi.
    - wifi

wifi:
  id: wifi_network

  ssid: # Specify the WLAN that your Dongle Max should connect to.
  password: # Specify the password of that WLAN.
  ap: # Fallback Access Point provided by Dongle Max.
    ssid: "Dongle-M_ESPHome" # Name of the access point to create.
    password: # Password for the access point. Leave empty for an open network.
  on_connect:
    - script.execute: update_status_led
  on_disconnect:
    - script.execute: update_status_led

captive_portal:

# Ethernet PHY configuration.
# The PHY type, clock mode, and GPIO assignments are hardware-specific.
ethernet:
  id: ethernet_network
  type: IP101
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 1
  power_pin:
    number: GPIO5
  on_connect:
    then:
      - script.execute: update_status_led
  on_disconnect:
    then:
      - script.execute: update_status_led

# Enable ESPHome Bluetooth Proxy for BLE device discovery and forwarding.
esp32_ble_tracker:
  scan_parameters:
    interval: 320ms
    window: 160ms
    active: true

bluetooth_proxy:
  active: true

preferences:
  flash_write_interval: 1s

# UART interface connected to the MG24 radio.
# The application baud rate can be changed at runtime below.
uart:
  id: radio_uart
  rx_pin: GPIO13
  tx_pin: GPIO17
  baud_rate: 115200

# Expose the MG24 UART over TCP.
stream_server:
  - id: radio_stream_server
    uart_id: radio_uart
    port: 6638
    buffer_size: 4096

# RGB status LED driven by three PWM channels.
output:
  - platform: ledc
    id: status_led_red
    pin: GPIO4
    frequency: 5000Hz
    channel: 0

  - platform: ledc
    id: status_led_green
    pin: GPIO14
    frequency: 5000Hz
    channel: 2

  - platform: ledc
    id: status_led_blue
    pin: GPIO2
    frequency: 5000Hz
    channel: 4

# Status LED indications:
# - Blinking blue: network disconnected
# - Solid blue: network connected
# - Blinking orange: temporary single-click indication
light:
  - platform: rgb
    id: status_rgb
    name: "LED"
    icon: mdi:led-on
    red: status_led_red
    green: status_led_green
    blue: status_led_blue
    gamma_correct: 2.0
    default_transition_length: 0s
    flash_transition_length: 0s
    restore_mode: ALWAYS_OFF
    effects:
      - pulse:
          name: "Blink 500ms"
          transition_length: 0s
          update_interval: 500ms
          min_brightness: 0%
          max_brightness: 100%
      - pulse:
          name: "Breathing"
          transition_length: 500ms
          update_interval: 500ms
          min_brightness: 0%
          max_brightness: 100%

globals:
  - id: button_long_active
    type: bool
    restore_value: no
    initial_value: 'false'

  - id: mg24_bootloader_active
    type: bool
    restore_value: no
    initial_value: 'false'

event:
  - platform: template
    id: user_button_event
    name: "Button"
    icon: mdi:gesture-tap-button
    event_types:
      - "single click"
      - "double click"
      - "long press"
      - "long release"

binary_sensor:
  - platform: stream_server
    stream_server: radio_stream_server
    connected:
      id: radio_tcp_connected
      internal: true
      on_press:
        - text_sensor.template.publish:
            id: uart_tcp_connection_status
            state: "Connected"
      on_release:
        - text_sensor.template.publish:
            id: uart_tcp_connection_status
            state: "Disconnected"

  # Physical user button.
  #
  # Actions:
  # - Single click: emit an event and enable the access point
  # - Double click: emit a double-click event
  # - Long press (5 s): emit a long-press event
  # - Release after long press: emit a long-release event
  - platform: gpio
    id: user_button
    icon: mdi:gesture-tap-button
    pin:
      number: GPIO34
      mode:
        input: true
      inverted: true
    filters:
      - delayed_on_off: 20ms
    on_press:
      then:
        - lambda: |-
            id(button_long_active) = false;
        - script.execute: button_long_press_detector
    on_release:
      then:
        - script.stop: button_long_press_detector
        - if:
            condition:
              lambda: |-
                return id(button_long_active);
            then:
              - event.trigger:
                  id: user_button_event
                  event_type: "long release"
              - lambda: |-
                  id(button_long_active) = false;
    on_multi_click:
      - timing:
          - ON for 40ms to 800ms
          - OFF for 40ms to 400ms
          - ON for 40ms to 800ms
          - OFF for at least 500ms
        then:
          - event.trigger:
              id: user_button_event
              event_type: "double click"

      - timing:
          - ON for 40ms to 800ms
          - OFF for at least 500ms
        then:
          - event.trigger:
              id: user_button_event
              event_type: "single click"
          - script.execute: force_ap_on
          - script.execute: single_click_indicator

sensor:
  - platform: wifi_signal
    id: wifi_rssi
    name: "RSSI"
    update_interval: 30s
    entity_category: diagnostic

  - platform: uptime
    id: device_uptime
    name: "Uptime"
    type: seconds
    update_interval: 60s
    entity_category: diagnostic

text_sensor:
  - platform: template
    id: uart_tcp_connection_status
    name: "UART over TCP"
    icon: mdi:lan-connect
    update_interval: never

switch:
  # Internal MG24 reset control.
  - platform: gpio
    id: radio_reset
    restore_mode: ALWAYS_OFF
    pin:
      number: GPIO15
      mode: OUTPUT
      inverted: true

  # Internal MG24 bootloader control.
  - platform: gpio
    id: radio_bootloader
    restore_mode: ALWAYS_OFF
    pin:
      number: GPIO12
      mode: OUTPUT
      inverted: false

  # User-facing control for entering or leaving the MG24 bootloader.
  - platform: template
    id: mg24_bootloader_switch
    name: "MG24 bootloader mode"
    icon: mdi:memory
    lambda: |-
      return id(mg24_bootloader_active);
    turn_on_action:
      - script.execute: enter_radio_bootloader
    turn_off_action:
      - script.execute: reset_radio_to_app

  # Runtime Access Point control.
  #
  # ESP-IDF Wi-Fi APIs are used here to enable or disable AP mode
  # without restarting the device.
  - platform: template
    id: ap_control
    name: "Access Point"
    icon: mdi:access-point
    lambda: |-
      wifi_mode_t mode = WIFI_MODE_NULL;
      const esp_err_t err = esp_wifi_get_mode(&mode);

      if (err == ESP_ERR_WIFI_NOT_INIT) {
        return {};
      }

      if (err != ESP_OK) {
        ESP_LOGW("ap_control", "esp_wifi_get_mode failed: %s", esp_err_to_name(err));
        return {};
      }

      return mode == WIFI_MODE_AP || mode == WIFI_MODE_APSTA;

    turn_on_action:
      - script.execute: force_ap_on

    turn_off_action:
      - script.execute: force_ap_off

button:
  - platform: template
    id: radio_reset_button
    name: "MG24 restart"
    icon: mdi:restart
    on_press:
      - script.execute: reset_radio_to_app

# Select the MG24 application baud rate.
# The selected value is persisted across restarts.
# Bootloader communication always uses 115200 baud.
select:
  - platform: template
    id: radio_baud_rate
    name: "MG24 baud rate"
    icon: mdi:swap-horizontal
    entity_category: config
    options:
      - "115200"
      - "460800"
      - "921600"

    initial_option: "115200"
    optimistic: true
    restore_value: true

    on_value:
      - if:
          condition:
            lambda: |-
              return !id(mg24_bootloader_active);
          then:
            - script.execute: apply_radio_app_baud_rate

script:
  - id: button_long_press_detector
    mode: restart
    then:
      - delay: 5s
      - if:
          condition:
            binary_sensor.is_on: user_button
          then:
            - lambda: |-
                id(button_long_active) = true;
            - event.trigger:
                id: user_button_event
                event_type: "long press"

  - id: update_status_led
    mode: restart
    then:
      - if:
          condition:
            lambda: |-
              return network::is_connected();
          then:
            - light.turn_on:
                id: status_rgb
                effect: none
            - light.turn_on:
                id: status_rgb
                brightness: 100%
                red: 0%
                green: 0%
                blue: 100%
                transition_length: 0s
          else:
            - light.turn_on:
                id: status_rgb
                brightness: 100%
                red: 0%
                green: 0%
                blue: 100%
                effect: "Blink 500ms"

  - id: single_click_indicator
    mode: restart
    then:
      - light.turn_on:
          id: status_rgb
          brightness: 100%
          red: 100%
          green: 50%
          blue: 0%
          effect: "Blink 500ms"
      - delay: 10s
      - script.execute: update_status_led

  - id: force_ap_on
    mode: restart
    then:
      - lambda: |-
          wifi_mode_t current_mode = WIFI_MODE_NULL;
          esp_err_t err = esp_wifi_get_mode(&current_mode);

          if (err != ESP_OK) {
            ESP_LOGE("ap_control", "esp_wifi_get_mode failed: %s", esp_err_to_name(err));
            return;
          }

          wifi_mode_t target_mode = current_mode;

          if (current_mode == WIFI_MODE_STA) {
            target_mode = WIFI_MODE_APSTA;
          } else if (current_mode == WIFI_MODE_NULL) {
            target_mode = WIFI_MODE_AP;
          }

          if (target_mode != current_mode) {
            err = esp_wifi_set_mode(target_mode);
            if (err != ESP_OK) {
              ESP_LOGE("ap_control", "Enable AP failed: %s", esp_err_to_name(err));
              return;
            }
          }

      # Allow the Wi-Fi mode change to take effect before applying
      # the AP configuration.
      - delay: 100ms

      - lambda: |-
          wifi_mode_t current_mode = WIFI_MODE_NULL;
          esp_err_t err = esp_wifi_get_mode(&current_mode);

          if (err != ESP_OK) {
            ESP_LOGE("ap_control", "esp_wifi_get_mode failed after enabling AP: %s", esp_err_to_name(err));
            return;
          }

          if (current_mode != WIFI_MODE_AP && current_mode != WIFI_MODE_APSTA) {
            ESP_LOGE("ap_control", "AP mode is not active");
            return;
          }

          const auto ap = id(wifi_network).get_ap();
          const auto ssid = ap.get_ssid();
          const auto password = ap.get_password();

          wifi_config_t config = {};

          const size_t ssid_len = std::min(ssid.size(), sizeof(config.ap.ssid));
          std::memcpy(config.ap.ssid, ssid.c_str(), ssid_len);
          config.ap.ssid_len = ssid_len;

          const size_t password_len = std::min(password.size(), sizeof(config.ap.password) - 1);

          if (password_len > 0) {
            std::memcpy(config.ap.password, password.c_str(), password_len);
            config.ap.password[password_len] = '\0';
            config.ap.authmode = WIFI_AUTH_WPA2_PSK;
          } else {
            config.ap.authmode = WIFI_AUTH_OPEN;
          }

          config.ap.channel = ap.has_channel() ? ap.get_channel() : 1;
          config.ap.ssid_hidden = ap.get_hidden() ? 1 : 0;
          config.ap.max_connection = 5;
          config.ap.beacon_interval = 100;

          err = esp_wifi_set_config(WIFI_IF_AP, &config);

          if (err != ESP_OK) {
            ESP_LOGE("ap_control", "esp_wifi_set_config(AP) failed: %s", esp_err_to_name(err));
            return;
          }

          if (captive_portal::global_captive_portal != nullptr &&
              !captive_portal::global_captive_portal->is_active()) {
            captive_portal::global_captive_portal->start();
          }

          ESP_LOGI("ap_control", "Access Point enabled");

  - id: force_ap_off
    mode: restart
    then:
      - lambda: |-
          wifi_mode_t current_mode = WIFI_MODE_NULL;
          esp_err_t err = esp_wifi_get_mode(&current_mode);

          if (err != ESP_OK) {
            ESP_LOGE("ap_control", "esp_wifi_get_mode failed: %s", esp_err_to_name(err));
            return;
          }

          if (current_mode == WIFI_MODE_APSTA) {
            err = esp_wifi_set_mode(WIFI_MODE_STA);
          } else if (current_mode == WIFI_MODE_AP) {
            err = esp_wifi_set_mode(WIFI_MODE_NULL);
          } else {
            if (captive_portal::global_captive_portal != nullptr &&
                captive_portal::global_captive_portal->is_active()) {
              captive_portal::global_captive_portal->end();
            }
            return;
          }

          if (err != ESP_OK) {
            ESP_LOGE("ap_control", "Disable AP failed: %s", esp_err_to_name(err));
            return;
          }

          if (captive_portal::global_captive_portal != nullptr &&
              captive_portal::global_captive_portal->is_active()) {
            captive_portal::global_captive_portal->end();
          }

          ESP_LOGI("ap_control", "Access Point disabled");

  - id: apply_radio_app_baud_rate
    mode: restart
    then:
      - lambda: |-
          const auto option = id(radio_baud_rate).current_option();

          uint32_t baud_rate = 115200;
          if (option == "460800")
            baud_rate = 460800;
          else if (option == "921600")
            baud_rate = 921600;

          if (id(radio_uart).get_baud_rate() != baud_rate) {
            id(radio_uart).flush();
            id(radio_uart).set_baud_rate(baud_rate);
            id(radio_uart).load_settings();
          }

  # Enter the MG24 bootloader.
  # Bootloader communication always uses 115200 baud without
  # changing the saved application baud rate.
  - id: enter_radio_bootloader
    mode: restart
    then:
      - lambda: |-
          id(mg24_bootloader_active) = true;

          id(radio_uart).flush();
          if (id(radio_uart).get_baud_rate() != 115200) {
            id(radio_uart).set_baud_rate(115200);
            id(radio_uart).load_settings();
          }

          id(mg24_bootloader_switch).publish_state(true);

      - delay: 100ms
      - switch.turn_on: radio_bootloader
      - delay: 100ms
      - switch.turn_on: radio_reset
      - delay: 100ms
      - switch.turn_off: radio_reset

  # Reset the MG24 back into normal application mode and restore
  # the configured application baud rate.
  - id: reset_radio_to_app
    mode: restart
    then:
      - switch.turn_off: radio_bootloader
      - delay: 100ms
      - switch.turn_on: radio_reset
      - delay: 100ms
      - switch.turn_off: radio_reset
      - lambda: |-
          id(mg24_bootloader_active) = false;
          id(mg24_bootloader_switch).publish_state(false);
      - script.execute: apply_radio_app_baud_rate
YAML

Flashing ESPHome Firmware #

Note: Before flashing ESPHome firmware, you can use the web console of the stock firmware, accessible via Firmware -> EFR32MG24 page to flash Zigbee NCP, Zigbee Router, OpenThread RCP, or Multiprotocol RCP firmware onto the MG24 SoC. Alternatively, after flashing ESPHome firmware, you can manage the firmware of MG24 SoC using Universal Silicon Labs Flasher tool. Please refer to Section 5 for further details.

OTA through Dongle-M's built-in Web Console #

Downloading OTA firmware #

After the firmware has been compiled in ESPHome Device Builder, select OTA update to download the OTA firmware, and ensure that the OTA firmware file has the .ota.bin extension.

Flashing OTA firmware #

Visit the Dongle-M's built-in web console, go to Firmware -> ESP32-D0WDR2-V3 page, and click Upload & Flash Firmware. Follow the on-screen prompts to upload the previously downloaded OTA firmware. Dongle-M will then restart automatically and run the ESPHome firmware.

Connecting Dongle-M to Your Computer with a USB Cable #

Connect Dongle-M to your computer or Home Assistant server using a USB cable. Launch the ESPHome Device Builder, locate the Dongle Max device, click Install under More options, select appropriate installation method, and then follow the on-screen prompts to flash the ESPHome firmware.


Flashing MG24 Firmware via TCP #

Installing Universal Silicon Labs Flasher #

Install the Universal Silicon Labs Flasher (universal-silabs-flasher) tool on your computer.

Preparing Firmware for the MG24 SoC #

You can download Zigbee NCP, Zigbee Router, OpenThread RCP, or Multiprotocol RCP firmware for the Dongle-M MG24 SoC from SONOFF Dongle Flasher for Web.

You can also download open-source firmware for the Dongle-M MG24 SoC from GitHub. For example, from Nerivec/silabs-firmware-builder.

Turning On MG24 bootloader mode #

Visit Home Assistant frontend, navigate to the device information page of Dongle-M, and turn on MG24 bootloader mode.

Note: Before turning on MG24 bootloader mode, please quit applications such as Zigbee2MQTT, Home Assistant ZHA, or OpenThread Border Router to release TCP port 6638 on Dongle-M.

Flashing Firmware onto the MG24 SoC Remotely #

Open a command-line tool on your computer, such as PowerShell on Windows or Terminal on macOS, and execute the following command to flash the previously downloaded firmware onto the Dongle-M MG24 SoC via the network (TCP socket).

universal-silabs-flasher \
  --device socket://[IP address of your Dongle-M]:6638 \
  --probe-methods bootloader:115200 \
  flash \
  --firmware [File path of the downloaded MG24 firmware]
Zsh

Note: Ensure that you replace [IP address of your Dongle-M] and [File path of the downloaded MG24 firmware] in the command above with the actual values.

Turning Off MG24 bootloader mode #

Navigate to the Dongle-M device information page and turn off MG24 bootloader mode.

Switching MG24 baud rate #

On the Dongle-M device information page, please set the MG24 baud rate under the Configuration section to the baud rate that corresponds to the firmware flashed onto the MG24 SoC in Step 4.

Note: If the baud rates do not match, communication between Dongle-M and the applications such as Zigbee2MQTT, ZHA, or an OpenThread Border Router will fail.

Connecting to MG24 UART over TCP #

When connecting applications such as Zigbee2MQTT, Home Assistant ZHA, or OpenThread Border Router to the Dongle-M MG24 SoC via [IP address of your Dongle-M]:6638, please ensure the following parameters are set correctly:

● Baud Rate (baudrate): 115200, 460800, or 921600—this must match the baud rate of the MG24 SoC firmware.

● Hardware Flow Control (rtscts): Disabled (false).

Optional: Writing IEEE Address to MG24 Zigbee NCP #

If you are using Zigbee2MQTT and intend to migrate from an old Zigbee adapter to a Dongle-M, you will generally need to copy the IEEE address from the old adapter to your Dongle-M MG24 Zigbee NCP firmware. You can use the following command to modify the IEEE address of Dongle-M MG24 Zigbee NCP over the network (via a TCP socket).

universal-silabs-flasher \
  --device socket://[IP address of your Dongle-M]:6638 \
  --probe-methods ezsp:115200 \
  write-ieee \
  --ieee [IEEE address of your old Zigbee adapter]
Zsh

Note: Before modifying the IEEE address, please quit applications such as Zigbee2MQTT, Home Assistant ZHA, or OpenThread Border Router to release TCP port 6638 on Dongle-M. Additionally, ensure that the Dongle-M MG24 SoC is not in bootloader mode.

Reference: How do I migrate from one adapter to another?


Backing to SONOFF Stock Firmware #

At any time, you can flash SONOFF stock firmware onto the Dongle-M ESP32 SoC using:

What are your feelings

Updated on November 2, 2026