Merge branch 'main' of https://github.com/MrMatt57/pitclaw

Author: MrMatt57

.gitignore

@@ -5,6 +5,9 @@
 .vscode/launch.json
 .vscode/ipch
 
+# Node.js
+node_modules/
+
 # OS
 .DS_Store
 Thumbs.db

.specs/012-readme-docs-restructure.md

@@ -0,0 +1,89 @@
+# 012: Restructure README and Documentation
+
+**Branch**: `feature/readme-docs-restructure`
+**Created**: 2026-02-18
+
+## Summary
+
+Restructure the README to focus on what new visitors need (what it is, hardware, quick start) and move developer-focused content into dedicated docs. The goal is a concise onboarding experience for people who want to build this project, with an index linking to deeper development guides.
+
+## Requirements
+
+- README should prominently show: what the project is, hardware requirements/BOM, and a quick getting started guide
+- Move wiring diagram out of README into `docs/wiring.md`, linked from the hardware section
+- Create `docs/firmware-development.md` covering firmware building, testing, architecture, and source layout
+- Create `docs/web-development.md` covering simulator usage, cook profiles, web UI development, and WebSocket protocol
+- README should have a "Development" section that serves as an index linking to the doc files
+- Keep the README hardware section (BOM, probes, 3D printed parts) intact — builders need it
+- Preserve all existing content; nothing should be lost, just reorganized
+- All internal links should work correctly
+
+## Design
+
+### README.md (streamlined)
+
+Keep these sections in README:
+1. **Header** — logo, badge, one-paragraph description, screenshot
+2. **Features** — bullet list (as-is)
+3. **Hardware** — BOM table, probes, 3D printed parts. Add a link to `docs/wiring.md` for wiring details
+4. **Quick Start** — condensed: clone, setup script, build & flash, first boot steps, accessing web UI, factory reset, OTA mention
+5. **Development** — brief index paragraph linking to:
+   - `docs/firmware-development.md` — building, testing, architecture
+   - `docs/web-development.md` — web UI, simulator, WebSocket protocol
+   - `docs/wiring.md` — wiring diagram and pin assignments
+   - `enclosure/README.md` — 3D printing and assembly
+6. **License** — TBD
+
+Remove from README (moved to docs):
+- Wiring diagram → `docs/wiring.md`
+- Simulator section → `docs/web-development.md`
+- Running Tests section → `docs/firmware-development.md`
+- Web UI detailed description → `docs/web-development.md`
+
+### docs/wiring.md
+
+- Carrier board wiring diagram (the ASCII art from current README)
+- Pin assignment table
+- Probe voltage divider schematic
+
+### docs/firmware-development.md
+
+- Prerequisites (manual install list — the non-Windows path)
+- Quick setup script mention
+- Build & flash commands (firmware targets)
+- Running tests (native + embedded)
+- OTA update details
+- Architecture overview: source layout tree, key modules described
+- Configuration persistence (config.json structure)
+- Error detection table
+- Key technical constants (Steinhart-Hart, PID defaults, fan control)
+
+### docs/web-development.md
+
+- Simulator setup and usage (build, run, options)
+- Cook profiles table
+- Web UI features overview
+- PWA details (manifest, service worker)
+- WebSocket protocol documentation (all message types)
+- Key constraint: web UI must work identically on simulator and ESP32
+- Editing workflow (edit files in firmware/data/, refresh browser)
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `README.md` | Restructure: keep intro/features/hardware/quick-start, add dev index, remove moved sections |
+| `docs/wiring.md` | **New**: wiring diagram, pin assignments from README |
+| `docs/firmware-development.md` | **New**: firmware dev guide with build/test/architecture content |
+| `docs/web-development.md` | **New**: web UI + simulator dev guide |
+
+## Test Plan
+
+- [x] All links in README resolve correctly (relative paths to docs/)
+- [x] No content lost — all information from old README exists somewhere in new structure
+- [x] README is concise and focuses on builder onboarding
+- [x] docs/wiring.md contains the full wiring diagram
+- [x] docs/firmware-development.md covers building, testing, and architecture
+- [x] docs/web-development.md covers simulator, web UI, and WebSocket protocol
+- [ ] Firmware builds (`pio run -e wt32_sc01_plus`) — docs-only change, no source code modified
+- [ ] Simulator builds (`pio run -e simulator`) — docs-only change, no source code modified

README.md

@@ -55,7 +55,7 @@ Compatible alternatives: Maverick ET-72/73 replacement probes (different Steinha
 
 ### 3D Printed Parts
 
-All parametric [OpenSCAD](https://openscad.org/) (free) source files in `enclosure/`. Pre-exported STLs in `enclosure/stl/` if you just want to print.
+All parametric [OpenSCAD](https://openscad.org/) (free) source files in `enclosure/`. Pre-exported STLs in `enclosure/stl/` if you just want to print. See the [enclosure README](enclosure/README.md) for print settings and assembly instructions.
 
 **Controller enclosure** (`bbq-case.scad`) — three parts:
 - **Front bezel** — holds display, bezel lip frames the screen
@@ -79,72 +79,29 @@ All parametric [OpenSCAD](https://openscad.org/) (free) source files in `enclosu
 - 2x small hose clamps (fan assembly to pipe, adapter to pipe nipple)
 - High-temp gasket tape (seal adapter to pipe nipple)
 
-## Wiring
+## Getting Started
 
-All components on the carrier perfboard are connected with short soldered traces. External connections use wire runs to panel-mount jacks and the display board.
+### 1. Clone and Set Up
 
-```
-Panel-mount DC barrel jack (12V in)
-  │
-  └─► Carrier Board 12V rail
-       ├─► MP1584EN buck converter IN → OUT (set to 5.0V)
-       │     ├─► WT32-SC01 Plus 5V (via extension cable)
-       │     └─► Servo VCC
-       │
-       ├─► IRLZ44N MOSFET drain
-       │     └─► Fan +12V (fan GND to MOSFET source)
-       │         Gate ◄── GPIO12 (with 10K pulldown to GND)
-       │
-       └─► GND rail (common ground)
-
-WT32-SC01 Plus Extension Connector (8-pin ribbon cable)
-  GPIO10 (SDA) ──► ADS1115 SDA (on carrier board)
-  GPIO11 (SCL) ──► ADS1115 SCL (on carrier board)
-  GPIO12       ──► IRLZ44N gate (on carrier board)
-  GPIO13       ──► Servo signal (wire to servo)
-  GPIO14       ──► Buzzer (on carrier board)
-  3.3V         ──► ADS1115 VDD + voltage divider supply
-  5V           ──► From MP1584EN output
-  GND          ──► Common ground rail
-
-Probe voltage dividers (on carrier board, x3)
-  3.3V ──[10K 1% resistor]──┬──► ADS1115 AINx
-                             │
-                       [0.1uF cap]
-                             │
-    Panel-mount 2.5mm jack ──┴──► GND
-    (tip=signal, sleeve=GND, polarity doesn't matter)
+```bash
+git clone https://github.com/MrMatt57/pitclaw.git
+cd pitclaw
 ```
 
-## Software Setup
-
-### Quick Start (Windows)
-
-One script installs everything you need — Git, Python, Node.js, PlatformIO CLI, and OpenSCAD:
+**Windows** — one script installs everything (Git, Python, PlatformIO CLI, OpenSCAD):
 
 ```powershell
-# Clone the repo
-git clone https://github.com/MrMatt57/pitclaw.git
-cd pitclaw
-
 # Run from an elevated (Admin) PowerShell
 powershell -ExecutionPolicy Bypass -File scripts\setup-dev.ps1
 ```
 
-The script is idempotent — safe to run again anytime to verify your setup or after pulling updates that add new dependencies.
-
-### Manual Prerequisites
+**Other platforms** — install [PlatformIO CLI](https://docs.platformio.org/en/latest/core/installation.html) (`pip install platformio`).
 
-If you prefer to install tools yourself (or you're not on Windows):
+### 2. Wire and Assemble
 
-1. [Git](https://git-scm.com/)
-2. [Python 3.12+](https://www.python.org/)
-3. [Node.js LTS](https://nodejs.org/) (for simulator/web UI development)
-4. [PlatformIO CLI](https://docs.platformio.org/en/latest/core/installation.html) — `pip install platformio`
-5. [VS Code](https://code.visualstudio.com/) + [PlatformIO extension](https://platformio.org/install/ide?install=vscode)
-6. [OpenSCAD](https://openscad.org/) (optional, for editing enclosure designs)
+Solder the carrier board and wire everything up. See the [wiring guide](docs/wiring.md) for the full diagram and pin assignments.
 
-### Build & Flash (one time via USB)
+### 3. Build and Flash
 
 ```bash
 cd firmware
@@ -161,18 +118,17 @@ pio run -e wt32_sc01_plus --target uploadfs
 
 After this initial flash, all future firmware updates can be done over Wi-Fi at `http://bbq.local/update`.
 
-### First Boot
+### 4. First Boot
 
-1. Power on the device — the setup wizard starts on the touchscreen
-2. Select your temperature units (°F or °C)
-3. A QR code appears on screen — scan it with your phone to connect to the setup Wi-Fi
-4. Your phone auto-opens a portal page — enter your home Wi-Fi credentials
-5. The device joins your network and registers as `bbq.local`
-6. Plug in probes — the wizard shows live readings to verify they work
-7. The fan, servo, and buzzer do a quick self-test
-8. Setup complete — dashboard appears
+1. Power on — the setup wizard starts on the touchscreen
+2. Select temperature units (°F or °C)
+3. Scan the QR code on screen with your phone to connect to the setup Wi-Fi
+4. Enter your home Wi-Fi credentials in the portal page
+5. Plug in probes — the wizard verifies live readings
+6. Fan, servo, and buzzer do a quick self-test
+7. Setup complete — dashboard appears
 
-### Accessing the Web UI
+### 5. Use the Web UI
 
 Open `http://bbq.local` in any browser on the same Wi-Fi network.
 
@@ -184,49 +140,14 @@ For the best experience, add it to your phone's home screen (it's a PWA):
 
 Hold your finger on the touchscreen for 10 seconds during the boot splash screen.
 
-### Running the Simulator (no hardware needed)
-
-Develop and test the web UI without any ESP32 hardware. The simulator serves the same web UI files and speaks the same WebSocket protocol.
-
-```bash
-cd simulator
-npm install          # first time only
-npm run dev          # http://localhost:3000 — auto-refreshes on file changes
-```
-
-Edit files in `firmware/data/` (the web UI) and the browser reloads instantly. Use time acceleration to test long cooks quickly:
-
-```bash
-npm run dev -- --speed 50              # 12-hour brisket cook in ~15 minutes
-npm run dev -- --profile stall         # test the brisket stall scenario
-npm run dev -- --speed 10 --profile fire-out  # test fire-out alarm at 10x
-```
-
-Available profiles: `normal`, `stall`, `hot-fast`, `temp-change`, `lid-open`, `fire-out`, `probe-disconnect`.
-
-### Running Tests
-
-```bash
-# Desktop unit tests (PID, prediction, alarms — no hardware needed)
-pio test -e native
-
-# On-device integration tests
-pio test -e wt32_sc01_plus
-```
-
-## Web UI
-
-The web interface shows:
-- **Live temperatures**: Pit and both meat probes with set points
-- **Temperature graph**: uPlot time-series chart with pit temp, meat temps, fan %, and damper %
-- **Predictive curve**: Dashed projection from current meat temp to target, with predicted done time
-- **Controls**: Set pit target temperature, meat target temperatures, alarm thresholds
-- **Cook timer**: Starts when pit reaches set point; tracks total cook time
-- **Session export**: Download cook data as CSV/JSON (device stores only current/last session — download before starting a new cook)
-- **OTA update**: Flash new firmware at Settings → Update
-- **Alarms**: Configure pit deviation band, meat targets, Pushover notifications
+## Development
 
-The graph timeline focuses on the active cook — ramp-up time is shown compressed on the left, with the main view starting from when the pit first reaches set temperature. The chart extends to the right with a dashed predictive curve showing the projected path to the meat target temperature, with the predicted done time displayed at the end. All times shown in your browser's local timezone.
+| Guide | Topics |
+|-------|--------|
+| [Firmware Development](docs/firmware-development.md) | Building, flashing, testing, architecture, configuration |
+| [Web UI Development](docs/web-development.md) | Simulator, web UI editing, cook profiles, WebSocket protocol |
+| [Wiring](docs/wiring.md) | Wiring diagram, pin assignments, carrier board layout |
+| [Enclosure](enclosure/README.md) | 3D printing, assembly instructions, parametric customization |
 
 ## License