Code Monkey home page Code Monkey logo

pixoo-rest's Introduction

Pixoo REST

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

Table of Contents

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

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

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:

Screenshot

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.

pixoo-rest's People

Contributors

4ch1m avatar dueyfinster avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

pixoo-rest's Issues

How to change listener from localhost to interface

Hi,
first, I really like what you built and it works well in my tests.
But I would like to know what parameter to change in which file to have the service no longer only accepting requests on 127.0.0.1.
In your screenshot you use the interface IP and I would need that as well to access the REST from external.
Thanks

Integration offizieller API

Achim klingt deutsch, daher bin ich mal so frei: Ich bin jetzt durch Zufall auf deine Swagger-Integration gestoßen... Super Sache - danke dafür! Nun zum Thema:

Unter http://doc.divoom-gz.com/web/#/12?page_id=89 steht eine offizielle API-Beschreibung zur Verfügung. Vielleicht sind da noch unentdeckte Funktionen vorhanden.
Spannend dürfte hier insbesondere der Find device command sein. Vielleicht könnte man sich damit die Angabe des PIXOO_HOST sparen und automatisiert im Netzwerk nach dem Gerät suchen?

uploaded gif 1st frame glitched

this is a great utility, thank you. i'm using it to upload gifs to the pixoo 64 and it's working great except for the 1st frame of each gif gets glitched - meaning colors are slightly off, sharpness too. super noticeable with looped gifs.

i wonder if there's some fine tuning to that process that needs to take place?

Feature Request: Multiple Pixoo 64's

I have Pixoo 64's in multiple rooms of my house; I would like the ability to have either multiple devices in your add on, or the ability to add additional instances of your addon. Thank you!

Love this by the way, I'm having a blast in Home Assistant with this.

Feature Request: POST GIF per URL

It would be nice to be able to upload a GIF via a URL.
That means: I enter a URL, the API downloads the image and forwards it to the Pixoo.

Docker option no longer works with latest SomethingWithComputers / pixoo library, simulator component seems to be problem

Hello,

Thanks for your work on this!

I am trying to build and run the docker container option in your documentation on Ubuntu 20.04 LTS. However SomethingWithComputers latest pixoo library includes a Python TK simulator. This causes the docker container to fail to run. I don't want to use the simulator, just your rest API web functions.

I add :

RUN apt-get update && apt-get install --yes --no-install-recommends python-tk

to the DockerFile and the image builds. However it fails to start with the following:

[2022-10-02 15:21:08 -0700] [7] [ERROR] Exception in worker process
Traceback (most recent call last):
  File "/usr/local/lib/python3.10/site-packages/gunicorn/arbiter.py", line 589, in spawn_worker
    worker.init_process()
  File "/usr/local/lib/python3.10/site-packages/gunicorn/workers/base.py", line 134, in init_process
    self.load_wsgi()
  File "/usr/local/lib/python3.10/site-packages/gunicorn/workers/base.py", line 146, in load_wsgi
    self.wsgi = self.app.wsgi()
  File "/usr/local/lib/python3.10/site-packages/gunicorn/app/base.py", line 67, in wsgi
    self.callable = self.load()
  File "/usr/local/lib/python3.10/site-packages/gunicorn/app/wsgiapp.py", line 58, in load
    return self.load_wsgiapp()
  File "/usr/local/lib/python3.10/site-packages/gunicorn/app/wsgiapp.py", line 48, in load_wsgiapp
    return util.import_app(self.app_uri)
  File "/usr/local/lib/python3.10/site-packages/gunicorn/util.py", line 359, in import_app
    mod = importlib.import_module(module)
  File "/usr/local/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/usr/app/app.py", line 11, in <module>
    from pixoo.pixoo import Channel, Pixoo
  File "/usr/app/pixoo/pixoo/__init__.py", line 10, in <module>
    from .simulator import Simulator, SimulatorConfig
  File "/usr/app/pixoo/pixoo/simulator.py", line 5, in <module>
    from pixoo import Palette
ImportError: cannot import name 'Palette' from 'pixoo' (unknown location)

Thanks for your work and help!

/apispec_1.json invalid when creating client library

I want to create a python client based on the swagger spec:


swagger_to_py_client.py \                                                                                         
                                                    --swagger_path ./apispec_1.json \
                                                    --outpath ./pixoo-rest-client
Traceback (most recent call last):
  File "/Users/Phlogi/Downloads/docker_playground/pixoo/pixoo-venv/bin/swagger_to_py_client.py", line 33, in <module>
    sys.exit(load_entry_point('swagger-to==5.0.0', 'console_scripts', 'swagger_to_py_client.py')())
  File "/Users/Phlogi/Downloads/docker_playground/pixoo/pixoo-venv/lib/python3.10/site-packages/swagger_to/bin/swagger_to_py_client.py", line 34, in main
    raise AssertionError("Errors in {}:\n{}".format(swagger_path, "\n".join(errs)))
AssertionError: Errors in apispec_1.json:
"paths"/"/brightness/{percentage}"/"put"/"parameters"/0:RawDict([('default', 85), ('description', 'Percentage value of display brightness.'), ('in', 'path'), ('maximum', 100), ('minimum', '0'), ('name', 'percentage'), ('required', True), ('type', 'integer')]) is not valid under any of the given schemas

Failed validating 'oneOf' in schema['properties']['paths']['patternProperties']['^/']['properties']['put']['properties']['parameters']['items']:
    {'oneOf': [{'$ref': '#/definitions/parameter'},
               {'$ref': '#/definitions/jsonReference'}]}

On instance['paths']['/brightness/{percentage}']['put']['parameters'][0]:
    RawDict([('default', 85),
             ('description', 'Percentage value of display brightness.'),
             ('in', 'path'),
             ('maximum', 100),
             ('minimum', '0'),
             ('name', 'percentage'),
             ('required', True),
             ('type', 'integer')])

We used the JSON schema of OpenAPI 2 from: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/88cd94419e117b154b67b834fa8e471bb98bd346/schemas/v2.0/schema.json

Defaults to server's IP

Fresh install of Ubuntu 20
Followed instructions
Set .env variables
Ran docker-compose up

Site is accessible but when I try to run a command, the IP it uses is the server's IP, not PIXOO_HOST

Copy python .env file in Dockerfile for docker container build

Hello and thank you for your work on this project!

After creating the .env file as specified in the documentation to the same directory as the app.py file, I need to add to the Dockerfile the following line after the 'COPY app.py .' line

COPY .env .

Sending Images / GIFS from FileSystem

Hello,
I install your Docker on my Synology NAS and with the Interface i can select, upload and send images / gifs to my pixoo 64. As I want to use the REST calls via CURL (Twitch Chat integration) and tried to execute the CURL commands via Shell but I can't figure out how I can send a local (file is on the Synology NAS) to the pixoo. No matter what syntax, folder will all permission I use, I always get a curl: (26) Failed to open/read local data from file/application error.

e.g. with this one:
curl -X POST "http://192.168.178.32:8085/sendGif" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "gif=@/volume1/web/HEADICORN.gif;type=image/gif" -F "speed=100" -F "skip_first_frame=false" curl: (26) Failed to open/read local data from file/application

I hope you can help me out. Thanks in Advance!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.