67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# pitrix
|
|
|
|
## What is pitrix?
|
|
|
|
pitrix is a software to run on an ESP8266 microncontroller connected
|
|
to a LED matrix. It will display the time and a few other nice effects
|
|
and stuff.
|
|
|
|
pitrix fetches the current time via NTP, is controllable via MQTT and
|
|
can be flashed over-the-air, so you don't need to disassemble your
|
|
nice-looking LED matrix everytime you want to update the software.
|
|
|
|
### Effects
|
|
|
|
|
|
| Name | Description | Image |
|
|
| -------- | -------- | -------- |
|
|
| sinematrix3 | <img src="https://git.schle.nz/fabian/pitrix/raw/branch/master/docs/effects/sinematrix3.gif" width="128" /> | Text |
|
|
|
|
|
|
|
|
## How to use
|
|
|
|
Checkout the code, rename `include/config.sample.h` to `include/config.h`
|
|
and edit it to match your preferences / environment.
|
|
|
|
Then compile and flash it, preferably using PlatformIO.
|
|
|
|
## Control it
|
|
|
|
Currently, control is possible via MQTT and / or HTTP REST API.
|
|
To use MQTT, you have to define `MQTT_ENABLE` and configure your MQTT sever's credentials. MQTT_TOPIC` is set in `include/config.h` and defaults to `pitrix`.
|
|
|
|
To use the HTTP REST API, you have to define HTTP_SERVER_ENABLE and set a port number
|
|
to listen on (80 is set by default).
|
|
|
|
Possible commands / topics are:
|
|
|
|
* `MQTT_TOPIC/mode` / `POST /mode` lets you select an effect to show. See `src/effects.cpp`
|
|
for a list. Default effect is `cycle`, which will cycle through some of
|
|
the available effects. Another effect is `off`, which will just display
|
|
black, effectively turning the display off. (pitrix stays running, so you
|
|
can turn it on again by simply selecting another mode.)
|
|
* `MQTT_TOPIC/brightness` / `POST /brightness` sets the brightness of the display. Valid values
|
|
are between 1 (darkest possible setting) and 255 (maximum brightness).
|
|
* `MQTT_TOPIC/reboot` / `POST /reboot` reboots pitrix. Send any value.
|
|
|
|
You can set retained values to have pitrix read them at startup, effectively
|
|
setting a default effect or brightness. (Do NOT set a retained value for
|
|
`MQTT_TOPIC/reboot` unless you want pitrix to reboot all the time.)
|
|
|
|
## Monitor it
|
|
|
|
The current status ("ONLINE" or "OFFLINE") of pitrix will be set at
|
|
`MQTT_TOPIC/status`.
|
|
|
|
If you enabled `MQTT_REPORT_METRICS`, metrics are sent via MQTT every 15
|
|
seconds:
|
|
|
|
* `MQTT_TOPIC/free_heap` contains the free heap memory in Bytes.
|
|
* `MQTT_TOPIC/uptime` contains the uptime of pitrix in seconds.
|
|
* `MQTT_TOPIC/fps` contains the currently reached frames per second.
|
|
|
|
If you enabled HTTP server, you can always make GET requests to `/free_heap`, `/uptime` or `/fps` to get those values.
|
|
|
|
If you enabled `DEBUG`, log messages will be sent to `MQTT_TOPIC/log`.
|