Project Title

ESP32 LED Matrix Controller with SD-Card Configuration

A flexible LED matrix driver for ESP32-based controllers that reads its entire configuration (LED & panel layout, SPI/SD settings, and Wi‑Fi credentials) from a JSON file stored on an SD card. Designed for easy reconfiguration without reflashing firmware.

Features

• LittleFS as Fallback: Just run pio run --target upload, (change fs data at /data and than run) pio run --target buildfs, pio run --target uploadfs
• SD‑Card Configuration: Load hardware and network settings from /config.json on SD card
• LED Matrix Layout: Define multiple panels, their positions, sizes, and orientation parameters (rotate, flip, serpentine)
• Flexible LED Strip Mapping: Support for skipped LEDs, multiple input segments, reversing order, and custom SPI pins
• Wi‑Fi Autoconnect: Automatically connect to Wi‑Fi using credentials in the JSON config
• Lightweight JSON: Powered by ArduinoJson for fast parsing on constrained devices

Hardware Requirements

• ESP32 development board (or equivalent)
• MicroSD card module wired to SPI pins
• SD card (formatted FAT32)
• LED strip (e.g., WS2812b) or matrix panels
• Power supply rated for your LED count

Software Requirements

• PlatformIO

Wiring

ESP32        SD     LED Strip
-----        --     ---------
3V3  (or 5V) VCC    (LED 5V)
GND          GND    (LED GND)
GPIO22 (CS)  CS
GPIO18 (SCK) SCK
GPIO23 (MOSI) MOSI
GPIO19 (MISO) MISO  (optional)
GPIO<order>  WS2812B   (configured pin in JSON)

Adjust pins in the JSON under hw.led.ins[0].pin[0] and hw.led.ins[0].pin[1] as needed. Otherwise you wont se an image

Configuration File (/config.json)

Place a JSON file named config.json at the root of your SD card. The file should define two top‑level objects: hw and wifi.

{
  "hw": {
    "led": {
      "total": 512,
      "ins": [
        {
          "start": 0,
          "len": 512,
          "skip": 0,
          "pin": [5],
          "order": 1,
          "rev": false
        }
      ],
      "matrix": {
        "panels": [
          {
            "b": true,
            "x": 0,
            "y": 0,
            "w": 16,
            "h": 16,
            "r": false,
            "v": false,
            "s": true
          },
          {
            "b": true,
            "x": 16,
            "y": 0,
            "w": 16,
            "h": 16,
            "r": false,
            "v": false,
            "s": true
          }
        ]
      }
    }
  },
  "wifi": {
    "ssid": "YourNetworkSSID",
    "password": "YourNetworkPassword"
  },
  "ap": {
    "ssid": "ESP32_AP_1",
    "password": "test1234"
  }
}

Key	Description
hw.led.total	Total number of LEDs across all panels
hw.led.ins[].start	Starting LED index for this input segment
hw.led.ins[].len	Number of LEDs in this segment
hw.led.ins[].skip	Number of LEDs to skip at the start
hw.led.ins[].pin	SPI / data pin number(s)
hw.led.ins[].order	Color order enum (e.g., GRB = 1)
hw.led.ins[].rev	Reverse LED strand direction
hw.led.matrix.panels	Array of panel layout objects
panels[].b	Panel enabled (boolean)
panels[].x, y	Top‑left corner of panel in the virtual grid
panels[].w, h	Width and height of each panel in LEDs
panels[].r	Flip panel horizontal (right start led)
panels[].v	Flip panel vertically
panels[].s	Override serpentine LED-wiring
wifi.ssid	Wi‑Fi network SSID
wifi.password	Wi‑Fi network password
ap.ssid	Access Point ssid (Optional, defaults to "ESP32_AP")
ap.password	Accesspoint network password (Optional, defaults to "test1234")

Sections of this should be compatible with WLED-Config. Mainly the hw. (only tested for WS2812b-matrices single output)

Usage

Without SDCard or Reader (Fallback Option, not recommended)

• Just run pio run --target upload
• change fs data at /data and than run
• run pio run --target buildfs
• run pio run --target uploadfs

Read infos at Fork_Changes_for_LittleFS.md

With SD Card (much more storage)

1. Ensure your SD-Card is formated and has only one Fat32-Partition. (Otherwise the ESP might not recognise the SD-Card at all)
2. . Copy ./example-sd-card-content/* to the root of your SD card.
   1. Select right config or edit ./example-sd-card-content/config.json
   2. (Optional) add your images at ./example-sd-card-content/images/ put your bitmaps *.bmp inside. convert "./input.png" -strip -colorspace sRGB -type TrueColor "BPP24:output-image.bmp"
   3. (Optional) regenerate python helper_scripts/wifi_qr_bitmap.py --ssid "ESP32_AP_Example" --password "test1234" --auth WPA --matrix 48 48 --out ./example-sd-card-content/images/wifi.bmp
   4. Finally copy everything to root of your SD-Card
3. Insert the SD card into the Esp-Sd-Cardreader.
4. Install the Project with Platform.io to your ESP.
5. The firmware will parse hardware settings and Wi‑Fi credentials at startup.

Troubleshooting

• SD init failed:
  • Check CS pin wiring and SD card formated FAT.
  • Check SD-Card formating
  • SD card might not work at all
• JSON parse error: Verify that config.json is valid JSON (e.g., via JSONLint).
• Wi‑Fi not connecting: Confirm SSID/password are correct and in range.
• If you find something bad about this repo: Check existing Issues or Open a new Issue

License - MIT

The MIT License (MIT)

Copyright © 2025 UwUTastisch

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.