Initial pushmain

12 files changed, 105 insertions, 0 deletions

diff --git a/docs/POWER.md b/docs/POWER.md
new file mode 100644
index 0000000..9082796
--- /dev/null
+++ b/docs/POWER.md
@@ -0,0 +1,12 @@
+# Power — T-Modem-s1224
+
+| Net / path | Role |
+|------------|------|
+| `VIN_12` | Barrel jack **5.5×2.1** centre-**positive** |
+| `U_REG` | Buck **12 V → 5 V** (Mini560 5 V class / MP1584-class on headers) |
+| `+5V` / `+5V_REG` | Board rail after buck (+ optional series PTC) |
+| `GND` | Common ground |
+| USB `VBUS` | **Isolated** — **DNI** OR diode · **no** feed into 5 V rail |
+| USB D+/D− / GND | Flash + CDC command path to Pico · LCD service via Pico |
+
+Pico **VSYS/VBUS pin on headers** is fed from the **board 5 V rail**, not from the Type-A receptacle VBUS.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..1d0492e
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,33 @@
+# Docs — T-Modem-s1224
+
+| Doc | Role |
+|-----|------|
+| [`USER-GUIDE.md`](USER-GUIDE.md) | Anyone — what it is · assemble · flash · terminals · SAVE |
+| [`../README.md`](../README.md) | Product overview |
+| [`../firmware/s1224/README.md`](../firmware/s1224/README.md) | Pico softmodem FW |
+| [`POWER.md`](POWER.md) | 12 V barrel / no USB power |
+| [`../hardware/kicad/t-modem-s1224/README.md`](../hardware/kicad/t-modem-s1224/README.md) | PCB · DNI modem/socket |
+| [`../hardware/BOM.md`](../hardware/BOM.md) | Planning BOM (tracked) |
+| [`figures/`](figures/) | Board overview + assembly steps 1–8 |
+
+## Operate (standalone)
+
+**No MAX25-Stack required.** Flash `s1224-*.uf2` → USB → `/dev/ttyACM*` → KISS (`0xC0`) or ASCII `HELP`. Fixed boot banner prints once. **All matching terminals work** insofar as applicable.
+
+**INI `SAVE`:** last **4 KiB** of Pico flash as a config **blob** — not a filesystem.
+
+## Figures
+
+| File | Content |
+|------|---------|
+| [`figures/s1224-board-overview.png`](figures/s1224-board-overview.png) | Top-down board · major parts |
+| [`figures/fig-01-pcb-standoffs.png`](figures/fig-01-pcb-standoffs.png) | Step 1 — PCB + standoffs |
+| [`figures/fig-02-power-section.png`](figures/fig-02-power-section.png) | Step 2 — 12 V → buck → 5 V |
+| [`figures/fig-03-modem-dni.png`](figures/fig-03-modem-dni.png) | Step 3 — modem/socket/XTAL **DNI** |
+| [`figures/fig-04-pico.png`](figures/fig-04-pico.png) | Step 4 — Pico H |
+| [`figures/fig-05-display.png`](figures/fig-05-display.png) | Step 5 — I²C display |
+| [`figures/fig-06-leds.png`](figures/fig-06-leds.png) | Step 6 — indicators |
+| [`figures/fig-07-connectors.png`](figures/fig-07-connectors.png) | Step 7 — AF/PTT · USB |
+| [`figures/fig-08-final-check.png`](figures/fig-08-final-check.png) | Step 8 — final check |
+
+**AS-IS** · GPLv3 · non-profit · standard reference only.
diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md
new file mode 100644
index 0000000..567dbcb
--- /dev/null
+++ b/docs/USER-GUIDE.md
@@ -0,0 +1,60 @@
+# T-Modem-s1224 — user guide
+
+**Audience:** anyone · **Version:** v1.0-prototype · **AS-IS** · GPLv3 · non-profit
+
+Softmodem sibling of **c1224**: Pico does AFSK (PWM/ADC) + USB **KISS** half-TNC. **No** TCM3105 / socket. Power **12 V**; USB = flash + KISS + ASCII service only.
+
+## What you need
+
+- Assembled board with modem IC / socket / crystals **DNI**
+- **12 V** centre-positive supply
+- USB host + **any** serial/KISS terminal that speaks the CDC interface below
+- AF wiring: **GP6** → radio TX AF · RX AF → **GP26** · **GP9** PTT
+
+## Assemble · flash (overview)
+
+Figures: [`figures/`](figures/) — steps 1–8 (do not edit PNGs for text-only doc updates).
+
+1. Power path on board · **no** USB VBUS power.  
+2. Leave modem/socket/XTAL area **unstuffed**.  
+3. Flash **`s1224-300.uf2`**, **`s1224-1200.uf2`**, or **`s1224-2400.uf2`**.  
+4. Apply **12 V** · plug USB for CDC.
+
+| UF2 | Mark / Space (Hz) |
+|-----|-------------------|
+| 300 | 1600 / 1800 |
+| 1200 | 1200 / 2200 (Bell 202) |
+| 2400 | ~1775 / 3250 (Y2-class · not Dire Wolf 2400) |
+
+Build: [`../firmware/s1224/README.md`](../firmware/s1224/README.md).
+
+## Terminals (all that match)
+
+USB CDC ACM · raw **8N1**:
+
+| Path | Use |
+|------|-----|
+| **KISS** `0xC0` … `0xC0` | Packet (half-TNC + softmodem) |
+| ASCII lines when not mid-frame | `HELP` · `STATUS` · `PTT` · `ID` · INI |
+
+**All terminals should work insofar as applicable** — serial apps for service ASCII; KISS tools for packet.
+
+Open `/dev/ttyACM*` → fixed boot banner once → KISS or `HELP`.
+
+## CDC commands
+
+`HELP` · `STATUS` · `ID` · `PTT ON`/`OFF` · `QUIET`/`VERBOSE` · `INI`/`GET`/`SET`/`SAVE`/`RELOAD`/`DEFAULTS`
+
+## INI · SAVE
+
+`SET key=value` then **`SAVE`**. Persist storage = **last 4 KiB of Pico flash** as a **config blob** — **not** a filesystem. Example: [`../share/s1224.ini.example`](../share/s1224.ini.example).
+
+## Optional stacks
+
+Standalone is enough. MAX25 / HyBBX are **not required** and are not claimed as shipped integrations here.
+
+## Power
+
+See [`POWER.md`](POWER.md).
+
+**AS-IS** · no warranty · no support · standard reference only · sibling of **c1224**.
diff --git a/docs/figures/fig-01-pcb-standoffs.png b/docs/figures/fig-01-pcb-standoffs.png
new file mode 100644
index 0000000..26e4db4
--- /dev/null
+++ b/docs/figures/fig-01-pcb-standoffs.png
diff --git a/docs/figures/fig-02-power-section.png b/docs/figures/fig-02-power-section.png
new file mode 100644
index 0000000..8fe1ec5
--- /dev/null
+++ b/docs/figures/fig-02-power-section.png
diff --git a/docs/figures/fig-03-modem-dni.png b/docs/figures/fig-03-modem-dni.png
new file mode 100644
index 0000000..8ba724a
--- /dev/null
+++ b/docs/figures/fig-03-modem-dni.png
diff --git a/docs/figures/fig-04-pico.png b/docs/figures/fig-04-pico.png
new file mode 100644
index 0000000..8649c60
--- /dev/null
+++ b/docs/figures/fig-04-pico.png
diff --git a/docs/figures/fig-05-display.png b/docs/figures/fig-05-display.png
new file mode 100644
index 0000000..f670ba9
--- /dev/null
+++ b/docs/figures/fig-05-display.png
diff --git a/docs/figures/fig-06-leds.png b/docs/figures/fig-06-leds.png
new file mode 100644
index 0000000..a8eaa05
--- /dev/null
+++ b/docs/figures/fig-06-leds.png
diff --git a/docs/figures/fig-07-connectors.png b/docs/figures/fig-07-connectors.png
new file mode 100644
index 0000000..efe1090
--- /dev/null
+++ b/docs/figures/fig-07-connectors.png
diff --git a/docs/figures/fig-08-final-check.png b/docs/figures/fig-08-final-check.png
new file mode 100644
index 0000000..5b6e0b0
--- /dev/null
+++ b/docs/figures/fig-08-final-check.png
diff --git a/docs/figures/s1224-board-overview.png b/docs/figures/s1224-board-overview.png
new file mode 100644
index 0000000..55b5a77
--- /dev/null
+++ b/docs/figures/s1224-board-overview.png