1- # ESP LED Matrix Display
2- ![ GitHub] ( https://img.shields.io/github/license/TheLogicMaster/ESP-LED-Matrix -Display )
1+ # ESP Smart Display
2+ ![ GitHub] ( https://img.shields.io/github/license/TheLogicMaster/ESP-Smart -Display )
33## About
4- This project is intended to provide an graphically customizeable and functional firmware to drive LED Matrix panels using
5- ESP8266 based microcontrollers. It's powered by the [ PxMatrix] ( https://github.com/2dom/PxMatrix ) driver and is
6- inspired by the concept of [ MorphingClockRemix] ( https://github.com/lmirel/MorphingClockRemix ) and intends to greatly
7- expand upon it, providing an easily customizable system using a JSON based configuration system and a Vue based web
4+ This project is intended to provide an graphically customizeable and functional firmware to drive PX LED Matrix panels and
5+ other common displays using ESP8266 based microcontrollers. It's powered by the [ PxMatrix] ( https://github.com/2dom/PxMatrix )
6+ and Adafruit display drivers. The project gained inspiration from [ MorphingClockRemix] (https://github.com/lmirel/
7+ MorphingClockRemix) and is intended to greatly expand upon it's functionality, providing an easily end-user customizable
8+ system using a JSON based configuration system and a Vue based web
89interface. This is one of my first substantial C++/HTML projcts, so some aspects are still a bit rough. The name itself
910is a placeholder until something clever comes along.
1011
@@ -21,20 +22,32 @@ is a placeholder until something clever comes along.
2122* Tetris Animation font
2223
2324## Demo
24- ![ GitHub Workflow Status] ( https://img.shields.io/github/workflow/status/TheLogicMaster/ESP-LED-Matrix -Display/Build%20Demo )
25+ ![ GitHub Workflow Status] ( https://img.shields.io/github/workflow/status/TheLogicMaster/ESP-Smart -Display/Build%20Demo )
2526
26- A demo of the web dashboard is available [ Here] ( https://thelogicmaster.github.io/ESP-LED-Matrix -Display/ ) . Example data
27+ A demo of the web dashboard is available [ Here] ( https://thelogicmaster.github.io/ESP-Smart -Display/ ) . Example data
2728is provided in place of the normal display API calls. Aside from configuration and image saving, the dashboard should
2829be fully functional.
2930
3031## Hardware
3132ESP32 and ESP8266 are now fully supported. 4MB of RAM is required to use both the web dashboard
32- and OTA updates. This was developed primarily on a P3 32x64 panel, but other sizes should be supported. Wiring is required to
33- be like [ this] ( https://github.com/2dom/PxMatrix#set-up-and-cabling ) . A photoresistor/resistor is supported on pin
34- A0 in [ this] ( https://www.instructables.com/id/NodeMCU-With-LDR/ ) configuration to control the display brightness. There
35- are pre-configured Platformio environments for Wemos D1 Mini, NodeMCU V2, NodeMCU 32S, and the Wemos D1 Mini Lite. Pre-built update
36- binaries are availible for D1 Mini, NodeMCU 32S, and NodeMCU V2. The D1 Mini Lite has 1MB of flash memory, so OTA updates are not
37- supported and features like HTTPS and built-in images are disabled.
33+ and OTA updates.
34+
35+ ### PX LED Matrix Panels
36+ Any panel configuration supported by [ PxMatrix] ( https://github.com/2dom/PxMatrix ) should be supported, but pre-built
37+ binaries are only availible for a few display sizes such as 32x64. Most of development was on P3 and P4 32x64 panels,
38+ so that size is best supported. Wire the display based on [ this] ( https://github.com/2dom/PxMatrix#set-up-and-cabling ) .
39+ The PxMatrix alternate SPI mode is used by default for ESP32 to account for displays that don't have the normal SPI
40+ pins broken out.
41+
42+ ### SSD1306 OLED Displays
43+ Any SSD1306 displays compatible with the [ Adafruit SSD1306] ( https://github.com/adafruit/Adafruit_SSD1306 ) driver should
44+ be fully compatible, though pre-built binaries are again only availible for certain display resolutions, such as 128x64.
45+ For compatibility reasons, images aren't stored in a monochrome format. In SSD1306 display mode, colors are treated as
46+ black or not black when rendering, but still use 16bit colors.
47+
48+ ### Brightness Sensor
49+ A photoresistor/resistor is supported on pin A0 in [ this] ( https://www.instructables.com/id/NodeMCU-With-LDR/ )
50+ configuration to control the display brightness. The sensor value can be viewed in the * Dashboard* page of the web dashboard.
3851
3952## Installation
4053The full release binaries can be flashed using [ esptool] ( https://github.com/espressif/esptool ) or a
@@ -47,13 +60,13 @@ esptool --port /dev/ttyUSB0 write_flash -fm dio 0x00000 nodemcuv2-32x64-v1.bin
4760esptool --port /dev/ttyUSB0 write_flash -fm dio 0x10000 nodemcu-32s-32x64-v1.bin
4861```
4962Alternatively, you can use Platformio or Arduino
50- IDE after downloading the latest [ release] ( https://github.com/TheLogicMaster/ESP-LED-Matrix -Display/releases/latest )
63+ IDE after downloading the latest [ release] ( https://github.com/TheLogicMaster/ESP-Smart -Display/releases/latest )
5164source code.
52- The flash memory split for the program and filesystem is 1 to 1 to 2 for a 4MB board, where 1MB is for the program, 1MB is for
53- firmware OTA updates, and 2MB is for the LittleFS filesystem. For ESP8266 with platformio, this means the ` eagle.flash.4m2m.ld ` ld
54- script. For Arduino IDE, use the ` 4MB (FS: 2MB) ` flashing option. For 1MB boards, Platformio is probably required, as it
55- doesn't look like Arduino IDE has an option to not use flash for OTA . For ESP32, a custom partition file is needed if your
56- board's default flash layout doesn't suit your needs.
65+ The flash memory split for the program and filesystem is 1 to 1 to 2 for a 4MB board, where 1MB is for the program, 1MB is
66+ for firmware OTA updates, and 2MB is for the LittleFS filesystem. For ESP8266 with platformio, this means the
67+ ` eagle.flash.4m2m.ld ` ld
68+ script. For Arduino IDE, use the ` 4MB (FS: 2MB) ` flashing option . For ESP32, a custom partition file is needed if the
69+ default flash layout doesn't suit your needs.
5770
5871### Building the Web Dashboard
5972Manually compiling the firmware and building the dashboard is only required if not flashing one of the pre-built full
@@ -70,37 +83,47 @@ must be done before uploading the filesystem image to the ESP8266.
7083
7184### Arduino IDE
7285To use Arduino IDE, the following libraries must be installed through the library manager:
73- * PxMatrix
86+ * PxMatrix (If using a PX panel)
87+ * Adafruit SSD1306 (If using an SSD1306 OLED display)
7488* Adafruit GFX Library
7589* ESP_DoubleResetDetector
7690* [ ESPAsyncWiFiManager] ( https://github.com/alanswx/ESPAsyncWiFiManager ) (Manually install)
7791* [ ESPAsyncTCP] ( https://github.com/me-no-dev/ESPAsyncTCP ) (If using ESP8266, manually install)
78- * [ AsyncTCP] ( https://github.com/me-no-dev/AsyncTCP ) (If using ESP8266, manually install)
92+ * [ AsyncTCP] ( https://github.com/me-no-dev/AsyncTCP ) (If using ESP32, manually install)
93+ * [ ESPAsyncTCP] ( https://github.com/me-no-dev/ESPAsyncTCP ) (If using ESP8266, manually install)
7994* [ ESPAsyncWebServer] ( https://github.com/me-no-dev/ESPAsyncWebServer ) (Manually install)
8095* ArduinoJson
8196* ezTime
8297* RunningAverage (If using brightness sensor "rolling" average)
8398* TetrisAnimation (If using Tetris font)
8499
100+ Due to Platformio compilation issues when using .INO files directly, the * main.cpp* must be renamed to * display.ino*
101+ before opening the project in Arduino IDE. All board specific definitions in * platformio.ini* must be changed in the new
102+ .INO file if your board isn't a 4MB ESP8266 board.
103+
85104The ESP8266 board support must be installed from
86105[ here] ( https://github.com/esp8266/Arduino#installing-with-boards-manager ) .
87106The [ ESP8266 FS plugin] ( https://github.com/earlephilhower/arduino-esp8266littlefs-plugin )
88107is also needed to upload the web interface. Select the correct board and flash split for your board. First upload the
89- code to the board, then select * FS Data Upload* under * Tools* .
108+ code to the board, then select * FS Data Upload* under * Tools* . The 4MB (1MB FS) flash option must be selected.
90109
91110If using ESP32, add boards using [ this] ( https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md )
92- and use the FS plugin from [ here] ( https://github.com/me-no-dev/arduino-esp32fs-plugin ) .
93-
94- Due to Platformio compilation issue when using .INO files directly, the * main.cpp* must be renamed to * led-matrix-display.ino*
95- before opening the project in Arduino IDE. All board specific definitions in * platformio.ini* must be changed in the new .INO file
96- if your board isn't a NodeMCU V2.
111+ and use the FS plugin from [ here] ( https://github.com/me-no-dev/arduino-esp32fs-plugin ) . A custom partition layout is
112+ used for the project, so the included * partitions.csv* file needs to be copied to
113+ * ~ /.arduino15/packages/esp32/hardware/esp32/1.0.4/tools/partitions/* for Linux, for example. The * boards.txt* file at
114+ * ~ /.arduino15/packages/esp32/hardware/esp32/1.0.4/boards.txt* needs to have the following added:
115+ ``` text
116+ esp32.menu.PartitionScheme.display=Display Layout
117+ esp32.menu.PartitionScheme.display.build.partitions=partitions
118+ ```
119+ The * ESP32 Dev Module* board must be used to select the * Display Layout* partition scheme. Then, run * ESP32 Sketch Data Upload*
120+ under * Tools* .
97121
98122### Platformio
99123To use [ Platformio] ( https://docs.platformio.org/ ) , install it and configure platformio.ini to suit the display size and
100124ESP flash layout. If you are using one of the boards with a pre-configured environment, just use that one, especially
101125since that will enable easy OTA updates using release binaries rather than manually compiling and flashing new ones.
102- Build and upload to the board. There seems to be an issue using .ino files with platformio which necessitates running
103- the upload task twice. Then run the * Upload Filesystem Image* task.
126+ Build and upload to the board. Then run the * Upload Filesystem Image* task.
104127
105128### Initial Setup
106129This project uses [ ESPAsyncWiFiManager] ( https://github.com/alanswx/ESPAsyncWiFiManager ) to handle WiFi configuration. After successfully
@@ -140,7 +163,7 @@ be restored.
140163## Filesystem Corruption Recovery
141164If the dashboard website finishes loading but has a blank screen or the display unexpectedly needs configuration, the
142165flash filesystem could have been corrupted. To re-install the dashboard, visit * http://{display-address}/recovery* to
143- upload a filesystem binary from the [ Releases Page] ( https://github.com/TheLogicMaster/ESP-LED-Matrix -Display/releases/latest ) .
166+ upload a filesystem binary from the [ Releases Page] ( https://github.com/TheLogicMaster/ESP-Smart -Display/releases/latest ) .
144167Flashing the display in this manner will erase all custom images and configuration settings, just like a normal OTA update.
145168The display will not turn off when flashing from the recovery page, so you may want to cover the display to prevent strobing.
146169Custom images can manually be recovered if only the dashboard was corrupted. Visit * http://{display-address}/images*
@@ -179,7 +202,8 @@ non-tetris fonts.
179202### Image Widgets
180203There are two types of images to display: custom images provided by the user and build-in images. The built-in images
181204are read-only at runtime, but more can be easily added by customizing the source code. The dimensions of image widgets
182- are fixed to the size of the image content.
205+ are fixed to the size of the image content. A few animations are availible that scroll the image across the screen in
206+ each direction.
183207
184208### Weather Icon Widgets
185209These components show a simple animation based on the current weather state from OpenWeatherMaps. The API key and
@@ -202,7 +226,7 @@ Availible shapes:
202226This project is intended to handle everything in a more asynchronous way to ensure consistent rendering. Previously, I
203227attempted to branch MorphingClockRemix with a few more features, but it was fundamentally designed differently, where
204228animations would steal the main thread until they were done, which isn't really compatible with my idea for a widget
205- based rendering system. Thus, I started from an empty project setup for PxMatrix .
229+ based rendering system. Thus, I started from scratch .
206230
207231### Rendering
208232Depending on your configuration, up to three display buffers could be used. One or two buffers will be used by PxMatrix
@@ -241,7 +265,7 @@ is enabled by default.
241265* ** Arduino OTA:** This is really only useful for LAN based development, since it doesn't want to flash the FS binary
242266directly over the existing filesystem, presumably, since it complains of not having enough space.
243267* ** Web Server Caching:** Files are cached based on dashboard version, so if you are modifying and testing the dashboard,
244- you may want to disable this. This is disabled by default.
268+ you may want to disable this.
245269* ** Double Buffering:** The PxMatrix library supports using two buffers, with one being the actively rendered buffer
246270and the other being the one being drawn to. This prevents partial renderings of content until the entire screen is done
247271drawing. The downside is that twice as much memory is used for display buffers. This is enabled by default.
@@ -252,7 +276,7 @@ entire library isn't really an option. The library also leaks the drawn characte
252276ideal, either. It's a very cool looking animation, though.
253277
254278### Firmware Embedded Images
255- Addition images can easily be added to the firmware by including the source header for either images stored as a
279+ Additional images can easily be added to the firmware by including the source header for either images stored as a
256280uint8_t, uint16_t, or char(Gimp) array. To make the display aware of the images, simply add a new entry to the * progmemImages*
257281map with the correct type, dimensions, and a name. 565 color and Gimp header files are supported. Both of which can be
258282exported from the dashboard. The 565 format uses half the space that the Gimp format uses, so it is preferable. Unwanted
0 commit comments