pitrix/README.md

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

## 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, preferrably using PlatformIO.

## Control it

Currently, control is only possible via MQTT. `MQTT_TOPIC` is set in
`include/config.h` and defaults to `pitrix`.

Possible commands / topics are:

* `MQTT_TOPIC/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` sets the brightness of the display. Valid values
  are between 1 (darkest possible setting) and 255 (maximum brightness).
* `MQTT_TOPIC/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 `DEBUG`, log messages will be sent to `MQTT_TOPIC/log`.