feat(hardware): PCB design for MaraTUI controller board

.gitignore

@@ -1,3 +1,13 @@
 /target
 /.embuild
 .env
+
+# KiCad
+hardware/**/*.bak
+hardware/**/_autosave-*
+hardware/**/*.lck
+hardware/**/~*.lck
+hardware/**/~*
+hardware/**/fp-info-cache
+hardware/.history/
+hardware/**/*:Zone.Identifier

README.md

@@ -134,7 +134,7 @@ Target board: **ESP32 Type-C** with an external **ILI9341** 240×320 TFT display
 | Short (on loading)| Toggle display backlight        |
 | Long              | Enter / exit Debug overlay      |
 
-See [docs/hardware.md](docs/hardware.md) for the full pinout and wiring diagram.
+See [docs/hardware.md](docs/hardware.md) for ESP32 pinout and display wiring. KiCad project, Gerbers, and renders are in [`hardware/`](hardware/).
 
 ## Security Considerations
 
@@ -146,3 +146,24 @@ See [docs/hardware.md](docs/hardware.md) for the full pinout and wiring diagram.
 ## Roadmap
 
 - Offline mode using NVS storage
+
+### Home Assistant integration
+
+See [docs/home-assistant.md](docs/home-assistant.md) for the Node-RED bridge that maps MaraTUI MQTT topics to HA entities via MQTT Discovery.
+
+### ESP32 (flash)
+
+```
+cargo run --release
+```
+
+On device startup the app:
+
+1. Reads config from `MARATUI_*` env values (embedded at build time)
+2. Connects to Wi‑Fi
+3. Starts MQTT client
+4. Publishes telemetry frames to `<MARATUI_MQTT_TOPIC_PREFIX>/telemetry`
+5. Publishes telemetry events (shot start/end, water refill, mode change) to `<MARATUI_MQTT_TOPIC_PREFIX>/events`
+6. Publishes device status (IP, RSSI, uptime, heap) to `<MARATUI_MQTT_TOPIC_PREFIX>/status`
+
+> Note: current `esp-idf-svc` MQTT API in this project exposes MQTT 3.1 / 3.1.1 protocol selection; the implementation uses 3.1.1.

docs/hardware.md

@@ -13,10 +13,10 @@ Target board: **ESP32 Type-C** (generic) with external **ILI9341** 240x320 TFT d
 | Display Pin | ESP32 GPIO | Notes |
 |-------------|------------|-------|
 | SCK / CLK   | GPIO18     | VSPI CLK |
-| SDA / MOSI  | GPIO23     | VSPI MOSI |
-| DC / RS     | GPIO27     | Data/Command select |
-| CS          | GPIO25     | Chip Select |
-| RST / RESET | GPIO33     | Hardware reset |
+| SDA / MOSI  | GPIO21     | VSPI MOSI |
+| DC / RS     | GPIO23     | Data/Command select |
+| CS          | GPIO19     | Chip Select |
+| RST / RESET | GPIO22     | Hardware reset |
 | LED / BLK   | GPIO14     | Backlight (driven HIGH = on) |
 | VCC         | 3.3V       | |
 | GND         | GND        | |
@@ -26,13 +26,13 @@ Target board: **ESP32 Type-C** (generic) with external **ILI9341** 240x320 TFT d
 | Function | ESP32 GPIO | Notes |
 |----------|------------|-------|
 | TX       | GPIO17     | UART1 TX |
-| RX       | GPIO16     | UART1 RX, 9600 baud 8N1 |
+| RX       | GPIO16     | UART1 RX |
 
 ### Button
 
 | Button   | ESP32 GPIO | Notes |
 |----------|------------|-------|
-| Button 1 | GPIO32     | Internal pull-up enabled |
+| Button 1 | GPIO12     | Internal pull-up enabled |
 
 Button connects GPIO to **GND** through a tactile switch (active LOW, NegEdge detection).
 Short press (< 500 ms): toggle Dashboard ↔ Graphs. Long press (≥ 500 ms): toggle Debug screen.

hardware/README.md

@@ -0,0 +1,31 @@
+# MaraTUI PCB
+
+Custom ESP32 controller board for the Lelit Mara espresso machine.
+
+## Components
+
+| Ref | Part | Link |
+|-----|------|------|
+| U1 | ILI9341 2.8" SPI TFT with touch | [Amazon TR](https://www.amazon.com.tr/2-8in%C3%A7-SPI-Dokunmatik-Ekran-Mod%C3%BCl%C3%BC/dp/B0GWFFJBZN) |
+| U2 | ESP32-WROOM-32 | [Amazon TR](https://www.amazon.com.tr/ESP32-Wroom-32-Wifi-Bluetooth-Geli%C5%9Ftirme-Kart%C4%B1/dp/B0BT7SW1LF) |
+| SW1 | Tactile switch | |
+| J1 | Barrel jack (power) | |
+| J2 | 3-pin connector (GND + UART) | |
+
+## Custom Libraries
+
+Non-standard components are bundled in `lib/` so the project opens without missing library errors on any machine.
+
+| File | Description |
+|------|-------------|
+| `lib/symbols/esp32_30pin.kicad_sym` | ESP32-WROOM-32 symbol |
+| `lib/symbols/tft_320x240.kicad_sym` | ILI9341 320×240 symbol |
+| `lib/footprints/maratui.pretty/ESP32_30pin.kicad_mod` | ESP32 footprint |
+| `lib/footprints/maratui.pretty/TFT-320x240.kicad_mod` | TFT display footprint |
+
+
+## Manufacturing
+
+Gerber files for fabrication: `gerbers/maratui-v1.0.zip`
+
+Tested with JLCPCB default 2-layer settings.

hardware/fp-lib-table

@@ -0,0 +1,4 @@
+(fp_lib_table
+	(version 7)
+	(lib (name "Maratui Footprints") (type "KiCad") (uri "${KIPRJMOD}/lib/footprints/maratui.pretty") (options "") (descr ""))
+)