https://github.com/kirillsimin/zengge-lightbulbs
Utility for installing and controlling Zengge (Magic Home, Magic Hue, Surplife) smart light bulbs. Supports turning lights on/off, adjusting brightness, changing colors, setting dynamic effects, and scheduling automation. Designed for seamless integration and enhanced smart home experiences with an intuitive interface and flexible API.
https://github.com/kirillsimin/zengge-lightbulbs
flux-led lightbulb magichome magichue rgb smart-home smart-light smart-lights smarthome surplife zengge
Last synced: 2 months ago
JSON representation
Utility for installing and controlling Zengge (Magic Home, Magic Hue, Surplife) smart light bulbs. Supports turning lights on/off, adjusting brightness, changing colors, setting dynamic effects, and scheduling automation. Designed for seamless integration and enhanced smart home experiences with an intuitive interface and flexible API.
- Host: GitHub
- URL: https://github.com/kirillsimin/zengge-lightbulbs
- Owner: kirillsimin
- Created: 2020-03-15T15:42:36.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-07T21:22:28.000Z (3 months ago)
- Last Synced: 2025-04-12T22:16:07.473Z (2 months ago)
- Topics: flux-led, lightbulb, magichome, magichue, rgb, smart-home, smart-light, smart-lights, smarthome, surplife, zengge
- Language: Python
- Homepage:
- Size: 30.3 KB
- Stars: 21
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Zengge Lightbulb CLI Utility
*Formerly known as Magic Hue utility*
This repository includes two scripts:
The `setup.py` script allows the user to connect the "Zengge" lightbulb to their Wi-Fi.
The `control.py` script provides an easy API for the "Zengge" lightbulbs.
## Installation
1. Plug in your Zengge lightbulb and turn it on. It will start flashing different colors.
2. Connect to its Wi-Fi (something like LEDnetE1234B).
3. Run the `setup.py` script, providing your SSID and your Wi-Fi password:
```
python3 setup.py -ssid MyWifiEndpoint -pswd MyAwesomePassword
```
If the script worked, your lightbulb will turn green within a few seconds.
*Note: Currently, the script is automated for WPA2PSK / AES only. Modify it if your Wi-Fi uses a different mode and encryption.*
## Usage
Once your lightbulb is on your network, you can use the `zengge.py` script with the following arguments:
```
-h, --help show help message and exit
-ip provide the IP for the lightbulb; i.e. -ip 192.168.2.2
-raw accept colon-separated raw hex string; i.e. -raw 71:23:0f
-rgb accept comma-separated RGB values; i.e. -rgb 100,155,75
-white accept value of white temperature and brightness (0-255); i.e. -white 150,255
-warm accept value of warm white (0-255); i.e. -warm 150
-cool accept value of cool white (0-255); i.e. -cool 150
-power accept 'on' or 'off'; i.e. -power on
-status get the bulb's status
-version get the bulb's version
```
The user must provide the lightbulb's IP address and either RGB values, HEX values, or a white setting. An updated list of known combinations and rules for HEX values can be found below.
#### RGB Example:
This will set the lightbulb to red:
```
python3 control.py -ip 192.168.2.2 -rgb 200,0,0
```
#### White Example:
This will set the lightbulb to a specific white temperature and brightness:
```
python3 control.py -ip 192.168.2.2 -white 150,255
```
#### Warm White Example:
This will set the lightbulb to half power of warm white:
```
python3 control.py -ip 192.168.2.2 -warm 123
```
#### Raw Hex Example:
This will turn the lightbulb on with its last setting:
```
python3 control.py -ip 192.168.2.2 -raw 71:23:0f
```
## Understanding the Bulb's HEX Codes:
### Versions AK001-ZJ2101 & AK001-ZJ2145
I've been able to sniff a few codes that the app sends to the lightbulb. The structure of the hex list follows a pattern. The first bit defines the type of action. Then follow informational bits that define colors, brightness, etc. The entire list is followed by a checksum bit, masked by 255. For example, this is the broken-down list for turning the bulb on:
| Action Bit | Body Bit List | Finish Bit | Checksum Bit |
| ---------- | ------------- | ---------- | ------------ |
| `71` | `24` | `0f` | `a4` |
And here is how the data looks for magenta/purple color:
| Action Bit | Body Bit List | Finish Bit | Checksum Bit |
| ---------- | ---------------- | ---------- | ------------ |
| `31` | `ff:2f:ff:00:f0` | `0f` | `5d` |
**It's important to note that this script will calculate the checksum bit. You MUST NOT include it in the -raw argument.**
There are several different types of commands (Action Bits) that the bulb accepts:
- `31` - Color options
- `61` - Pulse/gradual options
- `71` - Power options
- `81` - Status options
The `31` and `61` action bit commands follow this structure in the body bit list:
```
31:RR:GG:BB:?BRIGHTNESS?:?COLORTYPE?:0f
61:COLOR(S):BRIGHTNESS:0f
```
The following examples can help you further understand the structure of the body bit list:
### HEX Examples
*Note that the final checksum bit is not included here. The script will add it automatically.*
| Action Type | Values |
| ------------------------- | ---------------------- |
| On | `71:23:0f` |
| Off | `71:24:0f` |
| | |
| RGB (255,47,255) | `31:ff:2f:ff:00:f0:0f` |
| RGB (255,126,0) | `31:ff:7e:00:00:f0:0f` |
| RGB (0,79,255) | `31:00:4f:ff:00:f0:0f` |
| | |
| Warm White 100% | `31:00:00:00:ff:0f:0f` |
| Warm White 50% | `31:00:00:00:80:0f:0f` |
| Warm White 1% | `31:00:00:00:02:0f:0f` |
| | |
| 7 Color range, 100% speed | `61:25:1f:0f` |
| 7 Color range, 50% speed | `61:25:10:0f` |
| 7 Color range, 1% speed | `61:25:01:0f` |
| Red gradual, 100% speed | `61:26:1f:0f` |
| Red gradual, 50% speed | `61:26:10:0f` |
| Green gradual, 100% speed | `61:27:1f:0f` |
| Blue gradual, 100% speed | `61:28:01:0f` |
### Special Signature for AK001-ZJ21411
Firmware 11 has a very different signature and uses 23 bytes instead of 8 (or 9). Here are some parts I've been able to decipher:
**b0b1b2b3000102** -- header, always the same
**34** -- counter, keeps ticking up
**000ee00100** -- filler ??
**b1** - white / **a1** - color
**000000** - white, HEX values for Hue / 2, Saturation , Value if color (ie **006464**)
**00** -- warm / **64** cool
**64** -- brightness for white
**0000140000** -- filler?
**24** -- checksum
| Header | Counter | Filler | Type | White/Color HEX | Warm/Cool | Brightness | Filler | Checksum |
| -------------- | -------- | ----------- | ----- | ---------------- | --------- | ---------- | ---------- | -------- |
| `b0b1b2b3000102` | `34` | `000ee00100` | `b1/a1` | `000000` / `006464` | `00/64` | `64` | `0000140000` | `24` |