hass-divoom

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.

Table of Contents

• Requirements
  • Bluetooth Proxy
  • Bluetooth Hardware
  • Bluetooth Pairing
• Installation
  • Easy Installation
  • Manual Installation
• Configuration
  • Easy Configuration
  • Manual 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 signal
  • MODE sleep
  • MODE temperature
  • MODE text
  • MODE timer
  • MODE visualization
  • MODE volume
  • MODE weather
  • YAML vs UI
  • Examples per Device
• Troubleshooting
  • Cannot connect
  • GIF does not work
• Credits

Requirements

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.

Bluetooth Proxy

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.

Bluetooth Hardware

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/

Bluetooth Pairing

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 then pair DIVOOM_DEVICE_MAC and optionally also connect DIVOOM_DEVICE_MAC \ OR
• rfcomm 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 just hci0, 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 just 1, but on some audio-supported devices, like the Timoo, Tivoo or Ditoo it might be 2. Timebox Mini is also a special case with its port: 4.

Installation

First we need to install the component. That can be done in two ways: Easy or Manual

Easy Installation

• Use HACS
• ...
• Profit

Manual Installation

• 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

Configuration

Second we need to enable/ configure the component. Again that can be done in two ways: Easy or Manual

Easy Configuration

• Go to Integrations
• If there is an auto-discovered entry, you are lucky and can skip two steps
• Use Add Integration and Search for Divoom
• Choose your Divoom device from the list of discovered Bluetooth devices
• Choose a port. If you are unsure, first try 1. If that doesn't work, try 2, 4 or all the other digits.
• 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.

Manual Configuration

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. \ Currently aurabox, backpack, ditoo, ditoomic, pixoo, pixoomax, timebox, timeboxmini, timoo and tivoo are supported. If you have a different device, you might try one that's most similar to yours.
• 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

Usage

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.

Basic Modes

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. Not all modes are supported across all devices. If in doubt, look into your mobile app if your device even has the corresponding feature and then look into the example files for your specific device.

Modern:

service: notify.NOTIFIER_NAME
data:
  message: "MODE"
  data:
    parameter: value

Classic:

service: notify.NOTIFIER_NAME
data:
  message: ""
  data:
    mode: "MODE"
    parameter: value

Examples

MODE alarm

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

MODE brightness

Sets the brightness.

Parameter	Description
brightness or number or value	The brightness value between 0 and 100.

message: 'brightness'
data:
  brightness: 100

MODE clock

Shows the clock channel. Be aware, that this mode is very limited on older device like Aurabox or Timebox Mini.

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. | | 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]

MODE connect

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