Divoom Proxy for ESP32

Allows you to send commands to your Divoom device through various protocols. It works as a companion for my Home Assistant integration, but you can also use it as standalone communicator for your Divoom devices. Currently the following input protocols are implemented. You can find more information in the documentation below.

• Serial
• TCP
• MQTT

• Requirements
• Installation
  • Easy Installation
  • Manual Installation
• Configuration
  • Easy Configuration
  • Manual Configuration
• Usage
  • Serial
  • TCP
  • MQTT
  • MODE Commands
    • MODE alarm
    • MODE brightness
    • MODE clock
    • MODE countdown
    • MODE datetime
    • MODE design
    • MODE effects
    • MODE game
    • MODE gamecontrol
    • MODE keyboard
    • MODE light
    • MODE lyrics
    • MODE memorial
    • MODE noise
    • MODE playstate
    • MODE radio
    • MODE scoreboard
    • MODE timer
    • MODE visualization
    • MODE volume
    • MODE weather
• Troubleshooting
  • Cannot connect
  • GIF does not work

This firmware obviously needs an ESP32. Other then that, not much is needed, as the ESP32 already brings WiFi and Bluetooth with it.

In the future I might use ESP Web Tools for an easier installation process. For now, you have to go for the manual installation.

This firmware is a PlatformIO project. Until I can find and prepare a more easy way for you to get started, you have to just download the source code and build and upload it to an ESP32 via VS Code yourself.

• Download the repository. If you know git, a clone is fine. If not, just download https://github.com/d03n3rfr1tz3/esp32-divoom/archive/main.zip to get the most recent code in a ZIP file.
• Copy the corresponding content of the ZIP file into a directory of your choice
• Open the directory with PlatformIO via VS Code
• Connect your ESP32 with a working USB Data Cable
• Press Upload in the PlatformIO Project Tasks
• ...
• Profit

Well again, currently there is no easy way, but that might change in the future.

Currently you need to configure the firmware directly in your own config_local.h before flashing. This might change in the future.

The default configuration config.h has a lot of empty values you very likely want to fill. To not run into problems with later updates, I recommend you to create a config_local.h with your own values. Here is an example:

#ifndef _CONFIG_LOCAL_H
    #define _CONFIG_LOCAL_H
    
    #undef WIFISSID1
    #undef WIFIPASS1
    #define WIFISSID1        "My WiFi 1"
    #define WIFIPASS1        "MySuperSecretPassword1"

    #undef WIFISSID2
    #undef WIFIPASS2
    #define WIFISSID2        "My WiFi 2"
    #define WIFIPASS2        "MySuperSecretPassword2"

    #undef MQTT_HOST
    #undef MQTT_USER
    #undef MQTT_PASS
    #define MQTT_HOST        "192.168.0.2"
    #define MQTT_USER        "mqtt"
    #define MQTT_PASS        "MySecretPassword"
#endif

Notice the undefining of each value before defining it with my own value. That way you don't get ugly warnings from the compiler later. 😉

You can control your Divoom devices via Serial. Obviously this is more for debugging purposes, but might also be helpful for a quick test. If you press Monitor in the PlatformIO Project Tasks, you can send some commands directly to your ESP32. Just prepare them in Notepad and then copy them into the Terminal (you will not see what you typed/copied) and press Enter. Depending on the actual command, the ESP32 will then send commands to your Divoom device and also give you some information or received packets back. Here are some examples:

This command connects to your Divoom device with the MAC address 01:12:23:45:56:67 and on port 1.

CONNECT 01:12:23:45:56:67 1

This command sends raw bytes to your connected Divoom device. The raw bytes represent the brightness command. The first one sets the brightness to 50% and the second one to 100%.

SEND 01 04 00 74 32 AA 00 02
SEND 01 04 00 74 64 DC 00 02

This command disconnect from your Divoom device.

DISCONNECT 01:12:23:45:56:67

This command sets the brightness to 100% of your connected Divoom device. As you can see, this is a more human readable format. You can find a full list of MODE commands here: MODE commands

MODE brightness 100

You can also control your Divoom devices via TCP. Obviously that is not really meant for user interaction, but for actual communication one a lower level. The most used case for TCP is my own Home Assistant integration, which uses this ESP32 firmware as a Bluetooth Proxy. But maybe you want to develop your own application based on this, so here are some examples:

This connects to your Divoom device with the MAC address 01:12:23:45:56:67 and on port 1. The packet starts with a single byte 0x69 hinting this is a connect packet, followed by the MAC address also in raw bytes as well as the optional port number.

690112233445566701

This sends raw bytes to your connected Divoom device. The raw bytes represent the brightness command. Typical for the Divoom protocol, the packet starts with 0x01 and ends with 0x02. The first packet sets the brightness to 50% and the second one to 100%.

0104007432AA0002
0104007464DC0002

This disconnect from your Divoom device. The packet starts with a single byte 0x96 hinting this is a disconnect packet, followed by the MAC address also in raw bytes.

960112233445566701

You can also control your Divoom devices via MQTT as well as getting a few states. This is variant you probably will use, when you are going for the standalone mode. The actual commands are similar to the Serial input. Additionally the general state will be published to MQTT_TOPIC/proxy, the bluetooth connection state to MQTT_TOPIC/bluetooth and advertise bluetooth devices to MQTT_TOPIC/advertise/[MAC] while [MAC] stands for the actual MAC address like 01:12:23:45:56:67.

Commands should be sent to the topic MQTT_TOPIC/command. For the MQTT_TOPIC part, you have to look into your config_local.h. Default is divoom/, which makes the command topic divoom/command.

This command connects to your Divoom device with the MAC address 01:12:23:45:56:67 and on port 1.

CONNECT 01:12:23:45:56:67 1

This command sends raw bytes to your connected Divoom device. The raw bytes represent the brightness command. The first one sets the brightness to 50% and the second one to 100%.

SEND 01 04 00 74 32 AA 00 02
SEND 01 04 00 74 64 DC 00 02

This command disconnect from your Divoom device.

DISCONNECT 01:12:23:45:56:67

This command sets the brightness to 100% of your connected Divoom device. As you can see, this is a more human readable format. You can find a full list of MODE commands here: MODE commands

MODE brightness 100

Here you can find a full list of MODE commands that are supported as well as some descriptions and examples. If you are coming from my Home Assistant integration, you probably will notice a few similarities.

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.

MODE alarm [number] [time] [weekdays] [alarmmode] [triggermode] [frequency] [volume]

MODE alarm 1 07:30 0111110 0 0 85.1 100

Sets the brightness.

MODE brightness [value]

MODE brightness 100

Shows the clock channel.

MODE clock [clock] [twentyfour] [weather] [temp] [calendar] [color] [hot]

MODE clock 1 1 1 1 1 FF0000 1

Shows the countdown tool.

MODE countdown [value] [countdown]

MODE countdown 1 02:30

Sets the datetime.

MODE datetime [date] [time]

MODE datetime 2020-12-24 20:15:00

Shows the design channel.

MODE design [value]

MODE design 0

Shows the effects channel.

MODE effects [value]

MODE effects 1

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.

MODE game [value]

MODE game 1

Sends controlling commands to the currently open game.

MODE gamecontrol [value]

MODE gamecontrol 0

Controls the keyboard LEDs specifically on the Ditoo.

MODE keyboard [value]

MODE keyboard 0

Shows the light channel.

MODE light [brightness] [color] [power]

MODE light 100 FF0000 1

Shows the lyrics channel. Might not be supported by every Divoom device.

MODE lyrics

MODE lyrics

Sets a memorial (reminder).

MODE memorial [number] [date] [time] [text]

MODE memorial 1 2020-12-31 59:59:59 Happy New Year!

Shows the noise meter.

MODE noise [value]

MODE noise 1

Sets the playstate for the currently played music. Only supported by Divoom devices with audio features.

MODE playstate [value]

MODE playstate 0

Shows and plays the radio channel. Only supported by Divoom devices with the radio feature.

MODE radio [value] [frequency]

MODE radio 1 85.1

Shows the scoreboard channel or tool.

MODE scoreboard [version] [player1] [player2]

MODE scoreboard 0 1 2

Shows the timer tool.

MODE timer [value]

MODE timer 1

Shows the visualization channel.

MODE visualization [value]

MODE visualization 1

Sets the volume. Only supported by Divoom devices with audio features.

MODE volume [value]

MODE volume 100

Sets the weather.

MODE weather [temperature] [weather]

MODE weather 25°C 1

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: d03n3rfr1tz3/hass-divoom#19 (comment)