External integration - Magic Home

Development
1

Hello everyone,

As announced in the thread about integrations to develop, here is an external integration for Magic Home Wi-Fi bulbs, LED strips, and plugs, controlled locally.

What it does

It brings Magic Home Pro, Zengge, or Surplife app devices into Gladys: bulbs, strip controllers, addressable strips, garlands, plugs. Everything stays on the local network (local transport): no account, no cloud. Gladys finds the devices on its own (UDP 48899 network discovery), then the integration talks to them via TCP.

Gladys doesn’t have a native Magic Home integration: no need for the MQTT bridge (thread) or Matterbridge (thread).

Features

  • Devices: on/off, brightness, color, and color temperature depending on the model; plugs as switches. Changes made on the remote control are automatically updated on most models.
  • 2 scene triggers: a device stops responding (after 30 seconds), a device responds again.
  • 4 scene actions: built-in effect (23 to choose from), up to 16 colors in loop, flashing then returning to the previous state, stopping the effect.
  • 2 widgets: « Magic Home Lights » (with « All Off ») and « Magic Home Effects » (three effect buttons of your choice).

Scene examples:

  • when someone rings the doorbell → make the living room lamp flash red for 5 seconds;
  • when the garden light stops responding → send me a message (turned off at the switch);
  • at sunset → kitchen strip at 40%, then an orange-pink fade on the living room strip.

Magic Home Lights and Effects Widgets (generated illustration, not a screenshot)

[Screenshot to come: the Discovery tab with a bulb, a strip, and a plug]

Installation

  • From the store: search for « Magic Home ». Available later today, pending indexing.
  • Or from the repository URL: https://github.com/William-De71/gladys-magic-home.

Minimum Gladys version: 5.1.1.

  1. Install the integration by accepting network discovery (UDP 48899).
  2. Configuration: « Search and test devices ».
  3. Discovery tab: add devices, then widgets and scenes.

Known limitations

  • Protocol not documented by the manufacturer: I wrote it based on flux_led, which Home Assistant uses. Not yet tested on real devices, only against simulated devices with frames captured from real hardware: your feedback is precious (with the MAGICHOME_MODEL parameter).
  • Not supported: addressable strip and garland animations, music mode, timers, strip settings.
  • 2 or 4 output switches are seen as a single switch; devices only reachable via the cloud are not supported.
Technical details
  • One device per module, identified by its MAC address: it is found after an IP address change (automatic search every hour, and as soon as a device stops responding). A static IP is still recommended.
  • The protocol is chosen based on the model number and firmware version: original protocol without checksum, 8 and 9 byte protocols, 25 byte HSV firmware of recent bulbs, encapsulated frames of addressable strips.
  • One TCP connection per device created (they accept few, the app keeps one); discovered but not added devices are not kept connected.
  • Color temperature is in mired, like Hue and Tasmota in Gladys.
  • Scene actions never trigger a trigger (no loop); a cut of less than 30 seconds triggers nothing.

Provide feedback

Via a GitHub issue or in response to this thread, with the Gladys version, the integration version, and the logs