Pixoo REST

A RESTful API to easily interact with the Wi-Fi enabled Divoom Pixoo devices.

---

ℹ️ INFORMATION

This project was created back in February 2022; aiming to provide a REST-like interface for the pixoo library.
With an update from August 2024, the library's creator decided to implement/integrate a dedicated REST-interface himself.

However, pixoo-rest still offers unique features like ...

• built-in Swagger UI
• "pass through" endpoints (with example payloads and detailed descriptions)
• (pre-built) container image
• Helm chart
• etc.

So... I'll keep maintaining the project as long as there's enough interest.

---

Table of Contents

• Introduction
• Disclaimer
• Changelog
• Getting started
  • Clone
  • Init
  • Configure
• Running
  • Direct
  • Containerized
• Usage
  • Examples
• License

Introduction

The main purpose of this app is to provide an easy-to-use Swagger UI to interact with your Pixoo device.

Making it easier to ...

• ✏️ draw pixels, lines, rectangles, and text
• 🖼️ quickly upload images
• 🎞️ play animations using GIFs
• ⚙️ set the device's channel, brightness, etc.
• ⬇️ automatically download and display resources from a URL

... from your own applications or home-automation tasks.

Pixoo REST makes use of the great Pixoo Python library by SomethingWithComputers; which offers various helpful features like automatic image conversion. 👍

However, it is also possible to simply pass through raw JSON-data to the Pixoo's built-in HTTP-API via this Swagger UI.
(The Swagger UI will provide handy example payloads (for easy editing) in this case.)

Disclaimer

This REST API is by no means a by-the-books reference on how proper REST APIs should be implemented; but simply a "convenience wrapper" for the aforementioned Pixoo library.

The actual HTTP API of the Pixoo device leaves a lot to be desired.
First and foremost proper/official documentation. 😉
Most of the pass-through payload objects got discovered via reverse engineering, try-and-error, or this website: doc.divoom-gz.com.

⚠️ Use at your own risk.

Changelog

A (more or less) detailed changelog can be found here: 📖

Getting started

Clone

Clone this repo ...

git clone https://github.com/4ch1m/pixoo-rest.git

... and change directory:

cd pixoo-rest

Init

Update/initialize the pixoo submodule:

git submodule update --init

Configure

Create an .env-file (in the project's root) and put your individual settings in it; like so:

# MANDATORY: the hostname of your Pixoo device; defaults to "Pixoo64" if omitted
PIXOO_HOST=192.168.178.11

# OPTIONAL: enable debug mode for the Pixoo-library; defaults to "false" if omitted
PIXOO_DEBUG=true

# OPTIONAL: the screen size of your Pixoo device (which gets passed to the Pixoo-library); defaults to "64" if omitted
PIXOO_SCREEN_SIZE=64

# OPTIONAL: enable (Flask) debug mode for the REST-app; defaults to "false" if omitted
PIXOO_REST_DEBUG=true

# OPTIONAL: the hostname to listen on; defaults to "127.0.0.1" if omitted
PIXOO_REST_HOST=0.0.0.0

# OPTIONAL: the port being used; defaults to "5000" if omitted
PIXOO_REST_PORT=5000

# OPTIONAL: the amount of retries that should be performed to connect to the Pixoo-device when starting the app; defaults to "infinity" when omitted
PIXOO_TEST_CONNECTION_RETRIES=10

# OPTIONAL: WSGI-conform way to configure a base-path/prefix-url (which may be needed when running behind a reverse proxy); NOTE -> this string must start with a slash!
# (CAUTION! Only set this if you really need it.)
SCRIPT_NAME=/pixoo-rest

Running

The app can now be run ...

• 🐍 directly; using your existing (venv-)Python installation

or

• 📦 fully packaged inside a dedicated (Docker-)container

Direct

Create a virtual environment and activate it (optional; but recommended):

python3 -m venv .venv
source .venv/bin/activate

Install all dependencies:

pip install -r requirements.txt

Finally, run the app:

python -m pixoo_rest.main

Containerized

Simply execute ...

docker compose up

... to automatically build the container and run it.

NEW ⭐

If you don't want to build the container image yourself, you now can use the pre-built image from hub.docker.com.

Simply uncomment the image-attribute in docker-compose.yml, and comment out the build-attribute:

  app:
    image: 4ch1m/pixoo-rest:latest
    #build: .

There's also a Helm chart you can use for deployments to K8s.

Usage

Open http://localhost:5000 in a web browser and make some requests using the Swagger UI:

NOTE:
For every executed request you'll get a handy curl command-line (ideal for reuse in home-automation scripts).

Examples

A few example (shell-)scripts can be found here: 🧰

Credits

Example animation file (duck.gif) by kotnaszynce / OpenGameArt.

License

Please read the LICENSE file.