# divoom-gateway
A REST API gateway with swagger UI provided that wraps divoom HTTP APIs for controlling divoom devices, like pixoo (and from how divoom's api/doc organizes, maybe more http supported devices in the future).
[](LICENSE-APACHE)
[](https://riff.visualstudio.com/divoom/_build/latest?definitionId=7&branchName=main)
| Release | Status |
|:---:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Crates.io | [](https://crates.io/crates/divoom-gateway) | |
| Install | [](https://github.com/microsoft/winget-pkgs/tree/master/manifests/r/r12f/DivoomGateway) [](https://snapcraft.io/divoom-gateway) |
| Nuget
packages | [](https://www.nuget.org/packages/divoom-gateway.windows.x86/) [](https://www.nuget.org/packages/divoom-gateway.windows.x64/) [](https://www.nuget.org/packages/divoom-gateway.windows.arm64/)
[](https://www.nuget.org/packages/divoom-gateway.linux.x86/) [](https://www.nuget.org/packages/divoom-gateway.linux.x64/) [](https://www.nuget.org/packages/divoom-gateway.linux.arm/) [](https://www.nuget.org/packages/divoom-gateway.linux.arm64/)
[](https://www.nuget.org/packages/divoom-gateway.macos.x64/) |
```bash
> divoom-gateway 192.168.0.123
Starting divoom gateway on: http://127.0.0.1:20821 for device 192.168.0.123.
Please open your browser with URL: http://127.0.0.1:20821 and happy divooming!
# Now, we can open http://127.0.0.1:20821 in browser! Happy Divooming!
```
## How to install
### via Cargo
```bash
cargo install divoom-gateway
```
### via winget
```powershell
winget install DivoomGateway
```
### via scoop
Since we haven't reached the [criteria for Scoop Main bucket](https://github.com/ScoopInstaller/Scoop/wiki/Criteria-for-including-apps-in-the-main-bucket), we need to use our own bucket at this moment.
```powershell
# Add our scoop bucket for the first time.
scoop bucket add r12f https://github.com/r12f/scoop-bucket
# Install
scoop install divoom-gateway
```
## How to use
To start the gateway, we need 3 steps:
### 1. Find the IP address of your device.
There are multiple ways to discover the address:
1. Get the address in divoom app.
2. Or, try our [divoom-cli command line](https://github.com/r12f/divoom/tree/main/divoom_cli) tool and discover all devices.
```bash
> .\divoom-cli.exe discover
- device-name: Pixoo
device-id: 300000001
device-private-ip: 192.168.0.123
```
### 2. Start the gateway with device address assigned
```bash
> divoom-gateway 192.168.0.123
Starting divoom gateway on: http://127.0.0.1:20821 for device 192.168.0.123.
Please open your browser with URL: http://127.0.0.1:20821 and happy divooming!
```
If we are seeing the following error when launching the gateway, it means the default port is taken and we need to use another port:
```bash
Error: Os { code: 10048, kind: AddrInUse, message: "Only one usage of each socket address (protocol/network address/port) is normally permitted." }
```
We can use the below options to specify IP and port when needed:
```bash
# divoom-gateway -s -p
# In this case our machine IP is 192.168.0.234, and we are opening 20822 to connect to device 192.168.0.123:
> divoom-gateway 192.168.0.123 -s 192.168.0.234 -p 20822
Starting divoom gateway on: http://192.168.0.151:20822 for device 192.168.0.164.
Please open your browser with URL: http://192.168.0.151:20822 and happy divooming!
```
### 3. Open browser with URL, that's it!
## Supported commands and more
Currently, we support all commands that documented in divoom's public API doc. For details, please check it [here](https://github.com/r12f/divoom#pixoo-device-apis).
### Play GIF animation
Pixoo devices provided [an API to play GIF file by providing a file location](http://doc.divoom-gz.com/web/#/12?page_id=195), and we wrapped it up and
provided an API on `/api/animation/play-gif`.
However, this API is very restricted on the image size and not very stable. It could end up with crashing your device. Hence, we added another API
called `/api/animation/render-gif`, which allow us to upload a GIF file and generate an animation to play, which is much more stable.
### Play text animation
Once we have used the `/api/animation/render-gif` command to play any animation, we can start use text animation APIs, otherwise these APIs will be
no-op'ed by the device.
### Animation template
To make building animation easier, Divoom Gateway support using YAML and SVG to create a template, then generate animation by passing the parameters.
For more information, please check it here: .
### Device Schedule
To help better controlling the device automatically, Divoom Gateway supports schedule config to create tasks based on cron expressions.
For more information, please check it here: .
## More help
We can find more info in the command help like below.
```bash
> divoom-gateway --help
divoom-gateway 0.0.1
r12f
A REST API gateway with swagger UI provided that wraps divoom HTTP APIs for controlling divoom
devices, like pixoo.
USAGE:
divoom-gateway.exe [OPTIONS]
ARGS:
Device address.
OPTIONS:
-h, --help Print help information
-p, --port Server port. [default: 20821]
-s, --server Server address. [default: 127.0.0.1]
-V, --version Print version information
```
## Debugging
To debug and see the logs and the raw request that we send, we can use `RUST_LOG` environment variable to change the logging level to `debug` to enable the logs:
On Windows with powershell:
```powershell
$env:RUST_LOG="debug"; divoom-cli 192.168.0.123 channel get
```
On Windows with cmd:
```cmd
set RUST_LOG=debug && divoom-cli 192.168.0.164 channel get
```
And on linux:
```bash
RUST_LOG=debug divoom-cli 192.168.0.123 channel get
```
Then we will see the output log like below:
```bash
Starting divoom gateway on: http://127.0.0.1:20821 for device 192.168.0.123.
Please open your browser with URL: http://127.0.0.1:20821 and happy divooming!
[2022-08-01T02:59:40Z INFO poem::server] listening addr=socket://127.0.0.1:20821
[2022-08-01T02:59:40Z INFO poem::server] server started
[2022-08-01T02:59:42Z DEBUG hyper::proto::h1::io] parsed 17 headers
[2022-08-01T02:59:42Z DEBUG hyper::proto::h1::conn] incoming body is content-length (230 bytes)
[2022-08-01T02:59:42Z DEBUG hyper::proto::h1::conn] incoming body completed
[2022-08-01T02:59:42Z DEBUG divoom::clients::common::divoom_rest_client] Sending request: Url = "http://192.168.0.123/post", Body = "{"Command":"Draw/SendHttpText","TextId":0,"x":0,"y":0,"dir":1,"font":0,"TextWidth":0,"speed":100,"TextString":"The gray fox jumped over the lazy dog","color":"#000000","align":2}", Timeout = 2s
[2022-08-01T02:59:42Z DEBUG reqwest::connect] starting new connection: http://192.168.0.123/
[2022-08-01T02:59:42Z DEBUG hyper::client::connect::http] connecting to 192.168.0.123:80
[2022-08-01T02:59:42Z DEBUG hyper::client::connect::http] connected to 192.168.0.123:80
...
```
To revert it back, we can use the same way to set the `RUST_LOG` to `warn` level:
```powershell
> $env:RUST_LOG="warn"
```
## API && SDK
If you are interested in the APIs that this tool is calling and the rust SDK that it uses, please check it here: .
# Acknowledgements
- Thanks to [@farique1](https://github.com/farique1) for allowing me to bundle the classic 8-bits fonts, that generated via his nice project
[Chartotype](https://github.com/farique1/Chartotype), as part of the [Divoom Gateway](https://github.com/r12f/divoom/tree/main/divoom_gateway), which
helps generate text animations.
## License
Apache-2.0: