A RESTful API to easily interact with the Wi-Fi enabled Divoom Pixoo devices.
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.)
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.
A (more or less) detailed changelog can be found here: 📖
Clone this repo ...
git clone https://github.com/4ch1m/pixoo-rest.git... and change directory:
cd pixoo-restUpdate/initialize the pixoo submodule:
git submodule update --initCreate 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
# 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-restThe app can now be run ...
- 🐍 directly; using your existing (venv-)Python installation
or
- 📦 fully packaged inside a dedicated (Docker-)container
Create a virtual environment and activate it (optional; but recommended):
python3 -m venv venv
. venv/bin/activateInstall all dependencies:
pip install -r requirements.txtFinally, run the app:
python app.pySimply execute ...
docker compose up... to automatically build the container and run it.
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.
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).
A few example (shell-)scripts can be found here: 🧰
Example animation file (duck.gif) by kotnaszynce / OpenGameArt.
Please read the LICENSE file.