{"id":22111070,"url":"https://github.com/4ch1m/pixoo-rest","last_synced_at":"2025-04-06T20:10:46.937Z","repository":{"id":38064015,"uuid":"464579726","full_name":"4ch1m/pixoo-rest","owner":"4ch1m","description":"A RESTful API to easily interact with the Wi-Fi enabled Divoom Pixoo devices.","archived":false,"fork":false,"pushed_at":"2024-08-28T13:36:32.000Z","size":1553,"stargazers_count":287,"open_issues_count":0,"forks_count":19,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-30T17:11:10.920Z","etag":null,"topics":["container","divoom","docker","pixoo","pixoo64","python","rest","swagger"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4ch1m.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-28T17:29:32.000Z","updated_at":"2025-03-25T19:36:02.000Z","dependencies_parsed_at":"2023-02-08T17:31:55.066Z","dependency_job_id":"e09025df-ea45-438a-8227-f90c10471708","html_url":"https://github.com/4ch1m/pixoo-rest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ch1m%2Fpixoo-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ch1m%2Fpixoo-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ch1m%2Fpixoo-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4ch1m%2Fpixoo-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4ch1m","download_url":"https://codeload.github.com/4ch1m/pixoo-rest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247543591,"owners_count":20955865,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","divoom","docker","pixoo","pixoo64","python","rest","swagger"],"created_at":"2024-12-01T10:33:03.131Z","updated_at":"2025-04-06T20:10:46.904Z","avatar_url":"https://github.com/4ch1m.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pixoo REST\n\n\u003e A RESTful API to easily interact with the Wi-Fi enabled [Divoom Pixoo](https://www.divoom.com/de/products/pixoo-64) devices.\n\n---\n\n:information_source: **INFORMATION**  \n\nThis project was created back in February 2022; aiming to provide a REST-like interface for the [pixoo library](https://github.com/SomethingWithComputers/pixoo).  \nWith an [update from August 2024](https://github.com/SomethingWithComputers/pixoo/commit/9984e4dfea1cf60ae0ec2cd05a6d39fb40bd8644), the library's creator decided to implement/integrate a dedicated REST-interface himself.\n\nHowever, `pixoo-rest` still offers unique features like ...\n\n* built-in Swagger UI\n* \"pass through\" endpoints (with example payloads and detailed descriptions)\n* (pre-built) container image\n* Helm chart\n* etc.\n\nSo... I'll keep maintaining the project as long as there's enough interest.\n\n---\n\n## Table of Contents\n\n* [Introduction](#introduction)\n* [Disclaimer](#disclaimer)\n* [Changelog](#changelog)\n* [Getting started](#getting-started)\n   * [Clone](#clone)\n   * [Init](#init)\n   * [Configure](#configure)\n* [Running](#running)\n   * [Direct](#direct)\n   * [Containerized](#containerized)\n* [Usage](#usage)\n   * [Examples](#examples)\n* [License](#license)\n\n## Introduction\n\nThe main purpose of this app is to provide an easy-to-use [Swagger UI](https://swagger.io/tools/swagger-ui/) to interact with your Pixoo device.\n\nMaking it easier to ...\n\n* :pencil2: **draw** pixels, lines, rectangles, and text\n* :framed_picture: quickly **upload** images\n* :film_strip: **play** animations using GIFs \n* :gear: **set** the device's channel, brightness, etc.\n* :arrow_down: automatically **download** and display resources from a URL\n\n... from your own applications or home-automation tasks.\n\n**Pixoo REST** makes use of the great [Pixoo Python library](https://github.com/SomethingWithComputers/pixoo) by [SomethingWithComputers](https://github.com/SomethingWithComputers); which offers various helpful features like automatic image conversion. :thumbsup:\n\nHowever, it is also possible to simply **pass through** raw JSON-data to the Pixoo's built-in HTTP-API via this Swagger UI.  \n(The Swagger UI will provide handy example payloads (for easy editing) in this case.) \n\n## Disclaimer\n\nThis 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.\n\nThe actual HTTP API of the Pixoo device leaves a lot to be desired.  \nFirst and foremost proper/official documentation. :wink:  \nMost of the **pass-through** payload objects got discovered via *reverse engineering*, try-and-error, or this website: [doc.divoom-gz.com](http://doc.divoom-gz.com/web/#/12?page_id=143).\n\n:warning: Use at your own risk.\n\n## Changelog\n\nA (more or less) detailed changelog can be found here: [:open_book:](CHANGELOG.md)\n\n## Getting started\n\n### Clone\n\nClone this repo ...\n```bash\ngit clone https://github.com/4ch1m/pixoo-rest.git\n```\n... and change directory:\n```bash\ncd pixoo-rest\n```\n\n### Configure\n\nCreate an `.env`-file alongside the [app.py](app.py)-file / [docker-compose.yml](docker-compose.yml)-file and put your individual settings in it; like so:\n```properties\n# MANDATORY: the hostname of your Pixoo device; defaults to \"Pixoo64\" if omitted\nPIXOO_HOST=192.168.178.11\n\n# OPTIONAL: enable debug mode for the Pixoo-library; defaults to \"false\" if omitted\nPIXOO_DEBUG=true\n\n# OPTIONAL: the screen size of your Pixoo device (which gets passed to the Pixoo-library); defaults to \"64\" if omitted\nPIXOO_SCREEN_SIZE=64\n\n# OPTIONAL: enable (Flask) debug mode for the REST-app; defaults to \"false\" if omitted\nPIXOO_REST_DEBUG=true\n\n# OPTIONAL: the hostname to listen on; defaults to \"127.0.0.1\" if omitted\nPIXOO_REST_HOST=0.0.0.0\n\n# OPTIONAL: the port being used; defaults to \"5000\" if omitted\nPIXOO_REST_PORT=5000\n\n# OPTIONAL: the amount of retries that should be performed to connect to the Pixoo-device when starting the app; defaults to \"infinity\" when omitted\nPIXOO_TEST_CONNECTION_RETRIES=10\n\n# OPTIONAL: WSGI-conform way to configure a base-path/prefix-url (which may be needed when running behind a reverse proxy); NOTE -\u003e this string must start with a slash!\n# (CAUTION! Only set this if you really need it.)\nSCRIPT_NAME=/pixoo-rest\n```\n\n## Running\n\nThe app can now be run ...\n* :snake: directly; using your existing (venv-)Python installation\n\nor\n\n* :package: fully packaged inside a dedicated (Docker-)container\n\n### Direct\n\nCreate a virtual environment and activate it (optional; but recommended):\n```bash\npython3 -m venv venv\n. venv/bin/activate\n```\n\nInstall all dependencies:\n```bash\npip install -r requirements.txt\n```\n\nFinally, run the app:\n```bash\npython app.py\n```\n\n### Containerized\n\nSimply execute ...\n```bash\ndocker compose up\n```\n... to automatically build the container and run it.\n\n#### NEW :star:\n\nIf you don't want to build the container image yourself, you now can use the pre-built image from [hub.docker.com](https://hub.docker.com/r/4ch1m/pixoo-rest).\n\nSimply uncomment the `image`-attribute in [docker-compose.yml](docker-compose.yml), and comment out the `build`-attribute:\n\n```yaml\n  app:\n    image: 4ch1m/pixoo-rest:latest\n    #build: .\n```\n\nThere's also a [Helm chart](helm) you can use for deployments to [K8s](https://kubernetes.io/).\n\n## Usage\n\nOpen [http://localhost:5000](http://localhost:5000) in a web browser and make some requests using the [Swagger UI](https://swagger.io/):\n\n![Screenshot](screenshot.png)\n\n_NOTE:_  \nFor every executed request you'll get a handy [curl](https://curl.se/) command-line (ideal for reuse in home-automation scripts).\n\n### Examples\n\nA few example (shell-)scripts can be found here: [:toolbox:](examples)\n\n## Credits\n\nExample animation file ([duck.gif](swag/duck.gif)) by `kotnaszynce` / [OpenGameArt](https://opengameart.org/content/cute-duck-animated-set).\n\n## License\n\nPlease read the [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4ch1m%2Fpixoo-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4ch1m%2Fpixoo-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4ch1m%2Fpixoo-rest/lists"}