mgl001fw
Stock and modified firmware for the Xiaomi Smart Home Hub 2, with telnet and SSH always open
- Custom firmware
- Stable
- Medium brick risk
- Reversible
This project hasn't been claimed by its maintainer yet, so its details come from the community. Is it yours? Claim it
English
- Bluetooth controller rescue window (gateway side): new
mgl001-hassoptions for a Telink controller image that carries a rescue window: for 300 ms after reset it listens on the UART and opens a small flash session that needs nothing of HCI. An image that boots but never answers HCI can then be rewritten without opening the gateway. Xiaomi's controller image does not have the window, so this does not change anything for a controller running it.-btrescue-info: running bank, flash id and boot marks of both banks.-btrescue-read <file>: a copy of the whole 512 KB flash.-btrescue-write <image>: writes a sealed image into the bank that is not running, reads it back, writes the boot mark last and clears the old one, then checks that HCI answers. A power cut at any point leaves a bootable chip.-bthciand-btrescue-cmd: one raw HCI or rescue command, for diagnosis.
- More native in Home Assistant: the gateway pings Home Assistant after a minute of silence, as ESPHome does; every client is told before a reboot or a stop; the LED applies and reports the brightness set in Home Assistant; a full client queue drops Bluetooth advert batches instead of closing the session; the device's friendly name is fixed the first time; time is asked from Home Assistant every 15 minutes.
- Safer updates: one install at a time, downloads time out after 5 minutes, a bank that is not whole is refused, and a trial boot from Home Assistant is kept only once the Zigbee chip has answered ZHA. A failed update check is retried after 10 minutes.
- Tests: Go tests with a simulated controller and a lie for each fix; boot bench 56/56; API benches 62/62 with Home Assistant's own client; Bluetooth bench with Telink's real code.
- No new firmware build in this release: the firmware list for Home Assistant is unchanged, so no gateway is offered an update.
Español
- Ventana de rescate del chip Bluetooth (lado de la pasarela): opciones nuevas de
mgl001-hasspara una imagen del chip de Telink que lleve ventana de rescate: durante 300 ms tras el reset escucha en el UART y abre una sesión mínima de flash que no necesita nada de HCI. Una imagen que arranca pero nunca contesta a HCI se puede volver a grabar sin abrir la pasarela. La imagen del chip de Xiaomi no tiene la ventana, así que esto no cambia nada para un chip que la lleve.-btrescue-info: banco que corre, id de la flash y marcas de arranque de los dos bancos.-btrescue-read <fichero>: una copia de la flash entera de 512 KB.-btrescue-write <imagen>: escribe una imagen sellada en el banco que no corre, la relee, escribe la marca de arranque la última y baja la vieja, y comprueba que HCI contesta. Un corte de luz en cualquier punto deja un chip que arranca.-bthciy-btrescue-cmd: un comando HCI o de rescate suelto, para diagnóstico.
- Más nativa en Home Assistant: la pasarela hace ping a Home Assistant tras un minuto de silencio, como ESPHome; avisa a cada cliente antes de reiniciar o pararse; el LED aplica y devuelve el brillo puesto en Home Assistant; una cola de cliente llena tira tandas de anuncios Bluetooth en vez de cerrar la sesión; el nombre del dispositivo se fija la primera vez; la hora se pide a Home Assistant cada 15 minutos.
- Actualizaciones más seguras: una instalación a la vez, las descargas caducan a los 5 minutos, se rechaza un banco que no esté entero y el arranque de prueba desde Home Assistant solo se fija cuando el chip Zigbee ha contestado a ZHA. Una comprobación de actualizaciones fallida se repite a los 10 minutos.
- Pruebas: pruebas de Go con un chip simulado y una mentira por arreglo; banco del arranque 56/56; bancos de la API 62/62 con el propio cliente de Home Assistant; banco del Bluetooth con el código real de Telink.
- Esta release no trae compilación nueva del firmware: la lista de firmware para Home Assistant no cambia, así que a ninguna pasarela se le ofrece actualizar.
Before you start
- How hard is it?
- EasyCopy a file or use a web page. No extra software.
- What you need
- Comfort with the command line
- Can it break my device?
- Small chance of trouble, with a way to recover.
- Can I undo it?
- Yes. You can go back to the official software.
Did it work for you?
Did mgl001fw v1.4.0 work on your Xiaomi Smart Home Hub 2?
No reports yet for v1.4.0.
One-tap reports from owners. Bricked reports are checked before they count.
Compatibility
Devices: Xiaomi Smart Home Hub 2.
No compatibility information yet.
Getting started
From the project's README ("📦 Installation"):
Open telnet or SSH on the gateway (for example through the XiaomiGateway3 Home Assistant integration, which opens telnet over the LAN), then run:
cd /tmp printf 'GET /Nebur692/mgl001fw/main/firmware/mgl001update.sh HTTP/1.0\r\nHost: raw.githubusercontent.com\r\n\r\n' | openssl sclient -quiet -connect raw.githubusercontent.com:443 -servername raw.githubusercontent.com -CAfile /etc/ca-certificates.crt -verifyreturnerror -verifyhostname raw.githubusercontent.com 2>/dev/null | sed '1,/^.$/d' > mgl001update.sh sh mgl001update.sh
The stock firmware has no curl and its wget has no HTTPS, so the download uses the gateway's own openssl, checking GitHub's certificate. Pick a firmware from the menu. The gateway reboots when it is done.
> Everything you do, you do at your own risk. Flashing a wrong firmware can leave the gateway recoverable only over UART (opening the case). Do not unplug the gateway while it is flashing.
> Anyone who can reach the gateway over the network gets root on it, with no password. That is how the modified firmware is meant to work: telnet and SSH open on every boot, and adding your own key does not close the passwordless login. Keep the gateway on a network you trust (an IoT VLAN, for example) and never forward ports 22 or 23 to it from the internet.
Risk and recovery
- Brick risk
- Medium
- Reversible
- Yes
- Requires opening the device
- No
From the project's README ("🩹 Recovery — if you lose access"):
With a modified firmware installed you have access on three levels, none needing to open the case:
- On the modified firmware you cannot be left without telnet or SSH: the boot script opens both on every boot, unconditionally and in the background, and a watchdog starts them again within a minute if they stop. A reboot always brings them back.
- If you lose the modified firmware itself (a Xiaomi update overwrote it, or the boot was switched), the XiaomiGateway3 integration reopens telnet over the LAN using your Mi Home token and the gateway key — this also works on stock firmware, including 1.0.8. Save your key somewhere safe.
- If even that is gone, reflash from a full NAND backup you took beforehand (see the installer and firmware/), or from the firmware kept in the other bank.
Releases
| Version | Name | Released |
|---|---|---|
| v1.4.0 | —Latest | 18 October 2026 |
| v1.3.0 | — | 17 October 2026 |
| v1.2.0 | — | 17 October 2026 |
| v1.1.0 | — | 16 October 2026 |
| v1.0.0 | — | 16 October 2026 |