diff --git a/README.md b/README.md new file mode 100644 index 0000000..0f3985b --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# 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. + +If you enabled `DEBUG`, log messages will be sent to `MQTT_TOPIC/log`. diff --git a/include/README b/include/README deleted file mode 100644 index 194dcd4..0000000 --- a/include/README +++ /dev/null @@ -1,39 +0,0 @@ - -This directory is intended for project header files. - -A header file is a file containing C declarations and macro definitions -to be shared between several project source files. You request the use of a -header file in your project source file (C, C++, etc) located in `src` folder -by including it, with the C preprocessing directive `#include'. - -```src/main.c - -#include "header.h" - -int main (void) -{ - ... -} -``` - -Including a header file produces the same results as copying the header file -into each source file that needs it. Such copying would be time-consuming -and error-prone. With a header file, the related declarations appear -in only one place. If they need to be changed, they can be changed in one -place, and programs that include the header file will automatically use the -new version when next recompiled. The header file eliminates the labor of -finding and changing all the copies as well as the risk that a failure to -find one copy will result in inconsistencies within a program. - -In C, the usual convention is to give header files names that end with `.h'. -It is most portable to use only letters, digits, dashes, and underscores in -header file names, and at most one dot. - -Read more about using header files in official GCC documentation: - -* Include Syntax -* Include Operation -* Once-Only Headers -* Computed Includes - -https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html diff --git a/include/config.sample.h b/include/config.sample.h index fbbe31d..fb53d01 100644 --- a/include/config.sample.h +++ b/include/config.sample.h @@ -4,36 +4,36 @@ #define FASTLED_INTERNAL #include -//#define DEBUG +//#define DEBUG // Uncomment this to enable Debug messages via Serial and, if enabled, MQTT. //#define CONFIG_USABLE // Uncomment this by removing the // at the beginning! -#define WIFI_SSID "..." -#define WIFI_PASS "..." +#define WIFI_SSID "..." // SSID of the wifi to connect to +#define WIFI_PASS "..." // Password of the wifi -#define LED_WIDTH 16 -#define LED_HEIGHT 16 -#define LED_COUNT 256 -#define LED_TYPE WS2812B -#define DATA_PIN 14 -#define COLOR_ORDER GRB -#define BRIGHTNESS 20 // Can be overwritten via MQTT_TOPIC_BRIGHTNESS -#define TEMPORAL_DITHERING 0 +#define LED_WIDTH 16 // Number of LEDs in horizontal direction +#define LED_HEIGHT 16 // Number of LEDs in vertical direction +#define LED_COUNT 256 // Total number of LEDs. WIDTH*HEIGHT. +#define LED_TYPE WS2812B // Type of LEDs +#define DATA_PIN 14 // PIN the LEDs are connected to on the microcontroller +#define COLOR_ORDER GRB // Order of the colors of the LEDs. If you get unexpected colors, you should change this. +#define BRIGHTNESS 20 // Default brightness of the LEDs. 1 (lowest)-255 (brightest) +#define TEMPORAL_DITHERING 0 // Use temporal dithering. Can lead to flickering. -#define NTP_SERVER "pool.ntp.org" -#define NTP_INTERVAL 300000 -#define NTP_OFFSET 7200 +#define NTP_SERVER "pool.ntp.org" // NTP server to use to fetch the current time +#define NTP_INTERVAL 300000 // Interval in ms to update the time from the NTP server. 300000 ms = 5 minutes +#define NTP_OFFSET 7200 // Offset of your local time from UTC in seconds. Germany, daylight savings time = 2 hours = 7200 seconds -#define MQTT_ENABLE -#define MQTT_SERVER "..." +#define MQTT_ENABLE // Use MQTT. Add slashes to the start of the line to disable MQTT completely. +#define MQTT_SERVER "..." // Data for connecting to the MQTT server #define MQTT_PORT 1883 #define MQTT_USER "..." #define MQTT_PASS "..." -#define MQTT_TOPIC "pitrix/" // MQTT-Topic to listen to. Must not start with a slash, but must end with one." -#define MQTT_REPORT_METRICS +#define MQTT_TOPIC "pitrix/" // MQTT topic to listen to. Must not start with a slash, but must end with one. +#define MQTT_REPORT_METRICS // Whether to report metrics via MQTT. Disable if unwanted. #define MQTT_TOPIC_WEATHER "accuweather/pitrix/" // MQTT topic to listen for weather data. Must not start with a slash, but must end with one. -#define HOSTNAME "pitrix-%08X" -#define OTA_STARTUP_DELAY 10 // How many seconds to wait at startup. Set to 0 to disable. +#define HOSTNAME "pitrix-%08X" // Hostname of the ESP to use for OTA and MQTT client id. %08X will be replaced by the chip id. +#define OTA_STARTUP_DELAY 10 // How many seconds to wait at startup. This is useful to prevent being unable to flash OTA by a bug in the code. Set to 0 to disable. #define FPS 50 #define SHOW_TEXT_DELAY 100