Pixoo REST

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

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 alongside the app.py-file / docker-compose.yml-file 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

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
. venv/bin/activate

Install all dependencies:

pip install -r requirements.txt

Finally, run the app:

python app.py

Containerized

Simply execute ...

docker compose up

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

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: 🧰

License

Please read the LICENSE file.