Divoom Integration for Home Assistant
Allows you to send commands to your Divoom device through a Home Assistant notification service. It allows you to control your Divoom device in your automations and scripts however you want. Currently no reading commands or sensors are implemented, because everything works through a Notification Service. Just send controls/animations to your Divoom device through that Notification Service.
- Requirements
- Installation
- Configuration
- Usage
- Basic Modes
- Examples
- MODE alarm
- MODE brightness
- MODE clock
- MODE connect
- MODE countdown
- MODE datetime
- MODE design
- MODE disconnect
- MODE effects
- MODE game
- MODE gamecontrol
- MODE image
- MODE keyboard
- MODE light
- MODE lyrics
- MODE memorial
- MODE noise
- MODE off
- MODE on
- MODE playstate
- MODE radio
- MODE raw
- MODE scoreboard
- MODE sleep
- MODE timer
- MODE visualization
- MODE volume
- MODE weather
- YAML vs UI
- Examples per Device
- Troubleshooting
- Credits
For this component to actually have chance to work, it needs a Bluetooth Classic connection. Unlike Bluetooth Low Energy (BLE), Bluetooth Classic, as the name already indicates, is a bit older. Therefore it brings some difficulties with it, which you might not expect, when you only know BLE devices. One for example is that the Bluetooth Proxies from Home Assistant/ ESPHome do only support BLE and therefore cannot be used with this component. Another one is the support in Python itself. While a Bluetooth Classic connection is supported natively by Python, the pairing process is not. That's why you very likely have to do some manual work, if you somehow did not do it already.
As an alternative for directly connecting your Home Assistant via Bluetooth to your Divoom device, you can use my Bluetooth Proxy for ESP32. With this you don't have to fiddle around with Bluetooth Pairing in your Home Assistant. It's currently still quite new, so there might be some minor issues here and there. If you are using my Bluetooth Proxy for ESP32, you can skip the whole Bluetooth Hardware and Bluetooth Pairing parts of this documentation.
Of course you need Bluetooth hardware for that. It does not matter if you use the integrated Bluetooth controller of a Raspberry Pi 3/4/5 or an additional dongle. As long as it supports a classic Bluetooth connection via RFCOMM, you are good to go. When in doubt, just try it or have a look at the following part of the Home Assistant documentation: https://www.home-assistant.io/integrations/bluetooth/
As described above, you need to pair your Divoom device at least once to your Home Assistant device. After the pairing is done, this component can connect to your Divoom device anytime it's needed, even after restarting your Home Assistant. You have multiple possibilities to pair your Home Assistant to your Divoom device. The following commands can be used to pair your devices. Use them via SSH.
bluetoothctl
and thenpair DIVOOM_DEVICE_MAC
and optionally alsoconnect DIVOOM_DEVICE_MAC
ORrfcomm connect HCI_DEVICE DIVOOM_DEVICE_MAC DIVOOM_DEVICE_PORT
Choose what fits your Home Assistant installation or host system best. bluetoothctl
is the more modern way and should be available even on
very basic HASS.io installations. rfcomm
and maybe even hciconfig hci0 up
beforehand is an older way. Obviously you have to fill in
some placeholders above.
HCI_DEVICE
: The id of your Bluetooth controller. Typically justhci0
, especially if you are using integrated Raspberry Pi Bluetooth.DIVOOM_DEVICE_MAC
: The MAC address of your Divoom device. You can either get it via the Divoom App or by scanning for it.DIVOOM_DEVICE_PORT
: The port of your Divoom device. Typically its just1
, but on some audio-supported devices it might be2
.
First we need to install the component. That can be done in two ways: Easy or Manual
- Use HACS
- ...
- Profit
- Download the repository. If you know git, a clone is fine. If not, just download https://github.com/d03n3rfr1tz3/hass-divoom/archive/main.zip to get the most recent code in a ZIP file.
- Copy the corresponding content of the ZIP file into
custom_components\divoom
in your Home Assistant configuration directory. - Create a directory named
pixelart
in your Home Assistant configuration directory, for images that you may want to display on your device. - Optionally copy the content of the
pixelart
directory from the ZIP file
Second we need to enable/ configure the component. Again that can be done in two ways: Easy or Manual
- Go to Integrations
- If there is an auto-discovered entry, you are lucky and can skip two steps
- Use
Add Integration
and Search forDivoom
- Choose your Divoom device from the list of discovered Bluetooth devices
- Choose a
port
. If you are unsure, first try1
. If that doesn't work, try2
. - Select your device type (e.g.
pixoo
,ditoo
and such) - Click Send and then Finish
Beware that the UI configuration currently does not fully support my Bluetooth Proxy for ESP32.
Currently it is supported through auto-discovery via ZeroConf, as well as through the UI configuration by setting the host
option. It does not
add to the list of discovered Bluetooth devices, which means you have to manually type the MAC address in that case.
This can be done by manually adding the following snippet to your configuration.yaml
and filling in the capitalized placeholders. You can create a notify service for every
Divoom device you have, therefore allowing you to add multiple of these snippets.
notify:
- name: NOTIFIER_NAME
platform: divoom
host: "PROXY_HOST_OR_IP"
mac: "DIVOOM_DEVICE_MAC_ADDRESS"
port: DIVOOM_DEVICE_PORT
device_type: "DIVOOM_DEVICE_TYPE"
media_directory: "pixelart"
escape_payload: false
name
(Recommended): The name for the notify service.host
(Optional): The host or IP of your ESP32 with flashed Bluetooth Proxy. Beware, that an ESPHome BLE Proxy does not work, because Divoom is using Bluetooth Classic and not Bluetooth Low-Energy. Just leave it out, if you want your Home Assistant to directly connect via Bluetooth.mac
(Required): The Bluetooth MAC address for the Divoom device.port
(Optional): The Bluetooth channel for the Divoom device. Typically 1, but might be 2 for some devices with audio features.device_type
: The concrete type of your Divoom device.
Currentlyaurabox
,ditoo
,pixoo
,pixoomax
,timebox
,timeboxmini
,tivoo
are supported.media_directory
(Required): A directory, relative to the configuration dir, containing image files in GIF format. The component will use these to display static or animated images on the device.escape_payload
(Optional): Adds escaping of the payload, which might be important for some older Divoom devices with older firmware (afaik some old Timebox versions). Deactivated by default, because newer versions don't need that.
Here is an example how it could look like.
notify:
- name: Divoom Pixoo
platform: divoom
mac: "12:34:56:78:9A"
port: 1
device_type: "pixoo"
media_directory: "pixelart"
escape_payload: false
notify:
- name: Divoom Ditoo
platform: divoom
host: "192.168.0.123"
mac: "12:34:56:78:9A"
port: 2
device_type: "ditoo"
media_directory: "pixelart"
escape_payload: false
This custom component acts as a notify service. This means that the Service Data requires a message parameter, which basically is the command/mode we are sending to the device. Some commands/modes need additional parameters, which should be provided in the service data payload.
There was also an older style, where the message would be left empty and the mode also passed in through the service data. It is still supported as of today, but because it looks odd and confuses people, it's not the preferred way anymore.
The general structure for all modes are similar, but each mode has different parameter. Below the example of the basic structure, you can find a documentation of each mode.
Modern:
service: notify.NOTIFIER_NAME
data:
message: "MODE"
data:
parameter: value
Classic:
service: notify.NOTIFIER_NAME
data:
message: ""
data:
mode: "MODE"
parameter: value
Sets an alarm. You might have to experiment with the options your Divoom device supports and what it actually changes. Unsupported values will be ignored or if possible directly zeroed by this component, to prevent strange behavior.
Parameter | Description |
---|---|
number |
The concrete slot for the alarm. For the actual amount of slots you might have to look into the phone app. |
value |
The concrete time for when the alarm should happen in the format mm:ss . |
weekday |
The typical list of weekdays for when the alarm should happen. |
alarmmode |
The alarm mode. Look into your phone app for what is supported by your Divoom device. |
triggermode |
The trigger mode. Look into your phone app for what is supported by your Divoom device. |
frequency |
The radio frequency to set. |
volume |
The volume of the alarm. |
message: 'alarm'
data:
number: 0
value: '07:30'
weekday:
- mon
- tue
- wed
- thu
- fri
Sets the brightness.
Parameter | Description |
---|---|
brightness or number or value |
The brightness value between 0 and 100. |
message: 'brightness'
data:
brightness: 100
Shows the clock channel.
Parameter | Description |
---|---|
clock |
The style of the clock. Accepts a number between 0 and 9. 0 = Fullscreen, 1 = Rainbow, 2 = Boxed, 3 = Analog square, 4 = Fullscreen negative, 5 = Analog round, 6 = Widescreen |
twentyfour |
Changes between 12h or 24h format. 0 = 12h, 1 = 24h. Defaults to 24h. Doesn't actually change the current time. |
weather |
Actives or deactivates showing the weather with 0 or 1 . |
temp |
Actives or deactivates showing the temperature with 0 or 1 . |
calendar |
Actives or deactivates showing the calendar date with 0 or 1 . |
color |
The color of the clock. Accepts an array of RGB color values. |
hot |
Actives or deactivates showing the slideshow of the best images with 0 or 1 , which is right next to the other boolean-like buttons in the app, but a completely separate command in the protocol |
message: 'clock'
data:
clock: 1
weather: 0
temp: 0
calendar: 1
color: [250, 0, 0]
Explicitly connects to your configured Divoom device. Might be useful, if you just want to connect without changing anything. Typically the connection is opened automatically when using any mode.
message: 'connect'
data:
Shows the countdown tool.
Parameter | Description |
---|---|
value |
Controls the start/stop state. 0 = stop, 1 = start |
countdown |
The concrete countdown in the format mm:ss . |
message: 'countdown'
data:
countdown: '01:30'
Sets the datetime.
Parameter | Description |
---|---|
value |
The date and time in the typical ISO datetime format. Leave it empty or null to just use the current date and time. |
message: 'datetime'
data:
value: '2024-12-31 18:30:00'
Shows the design channel.
Parameter | Description |
---|---|
number |
The number of the concrete design. Ranging from 0-2 you can specify the design 1-3. |
message: 'design'
data:
number: 2
Explicitly disconnects from your configured Divoom device. Might be useful, if you cannot connect with your Phone or other devices. Typically this component leaves the connection open to your Divoom device.
message: 'disconnect'
data:
Shows the effects channel.
Parameter | Description |
---|---|
number |
The number of the concrete effect. Might differ for some Divoom devices. Look into your phone app and count them. |
message: 'effects'
data:
number: 2
Shows a game. It is theoretically possible to open games, that are not shown in your phone app, but they might not work very well.
Parameter | Description |
---|---|
value |
The number of the concrete game. Depending on your device you may have different amount of games. Look into your phone app and count them. |
message: 'game'
data:
value: 2
Sends controlling commands to the currently open game.
Parameter | Description |
---|---|
value |
0 or go = go, 1 or left = left, 2 or right = right, 3 or up = up, 4 or bottom = bottom, 5 or ok = ok |
message: 'gamecontrol'
data:
value: 'go'
Shows the a static or animated image.
Parameter | Description |
---|---|
file |
Specifes the image file relative to the configured media_directory, that will be displayed. |
message: 'image'
data:
file: 'ha16.gif'
Controls the keyboard LEDs specifically on the Ditoo.
Parameter | Description |
---|---|
value |
Changes the keyboard LED effect. -1 = previous effect, 0 = toggle on/off, 1 = next effect |
message: 'keyboard'
data:
value: 1
Shows the light channel.
Parameter | Description |
---|---|
brightness |
The brightness value between 0 and 100. |
color |
The color of the light. Accepts an array of RGB color values. |
message: 'light'
data:
brightness: 75
color: [250, 0, 0]
Shows the lyrics channel. Might not be supported by every Divoom device.
Parameter | Description |
---|---|
number |
The number of the concrete visualization. Might differ for some Divoom devices. Look into your phone app and count them. |
message: 'lyrics'
data:
Sets a memorial (reminder).
Parameter | Description |
---|---|
number |
The concrete slot for the memorial. For the actual amount of slots you might have to look into the phone app. |
value |
The date and time in the typical ISO datetime format (year will be ignored). |
text |
Specifies the name of your memorial, as it will appear in the phone app (default: Home Assistant). Limited to 16 characters. |
message: 'memorial'
data:
number: 0
value: '2000-12-31 00:00:00'
text: 'Happy New Year!'
Shows the noise meter.
Parameter | Description |
---|---|
value |
Controls the start/stop state. 0 = stop, 1 = start |
message: 'noise'
data:
value: 1
Turn the display off.
message: 'off'
data:
Turn the display on.
message: 'on'
data:
Sets the playstate for the currently played music. Only supported by Divoom devices with audio features.
Parameter | Description |
---|---|
value |
Controls the play/pause state. 0 = pause, 1 = play |
message: 'playstate'
data:
value: 1
Shows and plays the radio channel. Only supported by Divoom devices with the radio feature.
Parameter | Description |
---|---|
value |
Controls the on/off state. 0 = off, 1 = on |
frequency |
The radio frequency to set. |
message: 'radio'
data:
value: 1
frequency: 100.3
Sends raw data to the Divoom device. Might be useful, if there is something wrong or not supported by the other modes.
Parameter | Description |
---|---|
raw |
The bytes to send. |
message: 'raw'
data:
raw: [0x74, 0x64]
Shows the scoreboard channel or tool.
Parameter | Description |
---|---|
player1 |
The score of player one to show. |
player2 |
The score of player two to show. |
message: 'scoreboard'
data:
player1: 2
player2: 1
Shows the sleep mode, which plays soothing sounds, optionally with a timer and light.
Parameter | Description |
---|---|
value |
Controls the start/stop state. 0 = stop, 1 = start |
time |
The time in minutes after which to stop the sleep mode. Defaults to 120 when not provided. |
sleepmode |
The sound effect to play. Check in the app how many options are available. Accepts a number. |
frequency |
The radio frequency to set. |
volume |
The volume value between 0 and 100. |
color |
The color of the display. Accepts an array of RGB color values. |
brightness |
The brightness value between 0 and 100. |
message: 'sleep'
data:
value: 1
time: 30
sleepmode: 4
volume: 10
color: [255, 255, 0]
brightness: 50
Shows the timer tool.
Parameter | Description |
---|---|
value |
Controls the start/stop state. 0 = stop, 1 = start |
message: 'timer'
data:
value: 1
Shows the visualization channel.
Parameter | Description |
---|---|
number |
The number of the concrete visualization. Might differ for some Divoom devices. Look into your phone app and count them. |
message: 'visualization'
data:
number: 2
Sets the volume. Only supported by Divoom devices with audio features.
Parameter | Description |
---|---|
volume or number or value |
The volume value between 0 and 100. |
message: 'volume'
data:
volume: 75
Sets the weather.
Parameter | Description |
---|---|
value |
The temperature in degree including the temperature type for celsius or fahrenheit. |
weather |
The actual type of the weather. 1 = clear, 3 = cloudy sky, 5 = thunderstorm, 6 = rain, 8 = snow, 9 = fog |
message: 'weather'
data:
value: '25°C'
weather: 6
Modern:
service: notify.divoom_pixoo
data:
message: "brightness"
data:
brightness: 75
Classic:
service: notify.divoom_pixoo
data:
message: ""
data:
mode: "brightness"
brightness: 75
You can find more examples for each mode and all supported devices in separate files:
Examples for Aurabox: devices/aurabox.txt
Examples for Ditoo: devices/ditoo.txt
Examples for Pixoo: devices/pixoo.txt
Examples for Pixoo Max: devices/pixoomax.txt
Examples for Timebox: devices/timebox.txt
Examples for Timebox Mini: devices/timeboxmini.txt
Examples for Tivoo: devices/tivoo.txt
Make sure, that you at least paired your Home Assistant device once to your Divoom device. Also make sure, that you have the correct MAC address. Also make sure, that your Phone is not currently connected to your Divoom device, because some don't allow that many connections.
If it seems to connect, but looses connection the moment you use any mode, you might have chosen the wrong port. On Pixoo and other non-audio
devices, it's typically port: 1
. But on audio devices, like the Tivoo or Ditoo, it might be port: 2
.
The most common problem is, that the GIF does not have the correct size or format. The Divoom devices (and to some extend my code) are nitpicky in that case. Strangly enough the Divoom app lets you download GIFs, but these are typically in the size of 320x320 and not fitting your device. Your GIF needs to be exactly the size of your Divoom screen (16x16 in case of a Pixoo or similar sized device), non-interlaced and with a global color palette.
I can recommend resizing and converting your GIFs with GIMP. Of course other software might also work, depending on the export/format options. When resizing a GIF downloaded from the Divoom app with GIMP, you better choose no interpolation to not blur your GIF. When exporting with GIMP, make sure to mark the animation checkbox and don't mark the interlace checkbox. For a few more details and an example look into the following comment: #19 (comment)
A lot of the bluetooth communication with the Divoom device is based on gathering information from multiple sources, that already reverse engineered an older or different Divoom device. Only because of this, I could reverse engineer more commands myself. Therefore credit goes to the following owners and git repos (you are the heroes here):
https://github.com/RomRider/node-divoom-timebox-evo/ (especially for the protocol documentation)
https://github.com/mumpitzstuff/fhem-Divoom
https://github.com/ScR4tCh/timebox/
https://bitbucket.org/pjhardy/homeassistant-timebox/src/master/
Also thanks to whoever made the following (official?) documentation of most of the Divoom protocol. Even while it does not have the latest
commands available in the Ditoo, it still helped a lot in refining and completing stuff.
https://docin.divoom-gz.com/web/#/5/146