Release: Throttle Setup Wizard 0.1.0

.claude/skills/jeti-voice/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: jeti-voice
+description: Generate spoken voice callouts (WAV files) for a JETI Lua app in this repo with Piper's "Amy" voice, so every app sounds the same. Use this whenever an app needs new speech or audio files: callouts, announcements, warnings, alarms, "say X when Y", voice prompts for a switch, or regenerating/changing an existing app's voice. Also use it when wiring those files into an app (playFile, file checks, fallbacks) or into the transmitter's Sounds on event, and for the license credits the voice requires.
+---
+
+# JETI voice callouts
+
+Every app in this repo speaks with one voice: Piper text-to-speech with the
+US English **"Amy"** model (`en_US-amy-medium`). Speed Gauge (`AG-SpdGa`),
+Flameout Alarm (`AG-FlmOt`) and Throttle Setup Wizard (`AG-TrbSt`) all use
+it. New callouts should too, so a pilot hears one consistent system.
+
+The generators live in `tools/voice/`. They share `make_voice.py`'s helpers;
+each app has its own small script. Read `tools/voice/README.md` for the
+history and options of the existing ones.
+
+## 1. Decide the phrases
+
+For each callout, settle:
+
+- **The words**, short and unambiguous over engine noise. Two to four words
+  is typical ("Turbine off", "Engine relit").
+- **The file name**: 8.3, e.g. `TurbOff.wav`. JETI names are short, and if
+  the pilot will pick the file in a transmitter menu, the name should say
+  what it is.
+- **The delivery**:
+  - *Calm* (announcements, confirmations): no effects. Speed 1.5 suits
+    timed callouts that must be short (Speed Gauge's numbers, Flameout's
+    announcements); for single switch callouts Aaron preferred **1.15**
+    (`make_turbine.py`). When in doubt, generate a few speeds into a
+    scratch folder and let the user pick by ear.
+  - *Urgent* (alarms): pitch-up, presence boost and compression, optionally
+    with a lock tone and fixed-length cycles. Example: `make_flameout.py`.
+- **A length limit** for the self-check, from how the app uses it (e.g. a
+  switch callout should end before the next flick: about 1.5 s; Speed
+  Gauge's numbers must fit 1.3 s).
+- **Where it plays**: from the app (`system.playFile`), or by the
+  transmitter's *Sounds on event* (the app only copies the files to
+  `/Audio`, see section 5).
+
+Agree these with the user before generating; they'll listen to the result.
+
+## 2. Write the generator
+
+Create `tools/voice/make_<app>.py` by copying the closest existing script:
+
+- `make_turbine.py`: the minimal template (a list of phrases, calm pace,
+  `CREDITS.txt`, a length self-check). Start here for most apps.
+- `make_flameout.py`: urgent delivery (filters, compressor), a synthesized
+  tone, and assembling exact-length cycles.
+
+Keep these conventions, which the existing scripts share:
+
+- MIT header (`Copyright (c) 2026 Aaron George`, `SPDX-License-Identifier:
+  MIT`) and a docstring naming the files it writes and the spec/FR they
+  serve.
+- Import the helpers from `make_voice.py` (`synthesize`, `trim`,
+  `normalize`, `resample`, `write_wav`, `write_text`, `PEAK`) by adding
+  `tools/voice` to `sys.path`. **Don't modify `make_voice.py`**: Speed
+  Gauge's 512 files depend on it.
+- Arguments: `--model` (required), `--out` (default
+  `src/Apps/AG-xxxxx`), `--rate` (default 22050), and `--speed` if the
+  pace may need tuning.
+- Output: mono, 16-bit, 22.05 kHz WAV, trimmed of silence (20 ms kept),
+  peak-normalized to −1 dBFS. The DS-24 II plays this format (verified
+  with Speed Gauge, 2026-10-03).
+- Write `CREDITS.txt` into the output folder (copy the text from an
+  existing script and change the app name and the list of processing).
+- Self-check at the end: every file exists and fits its length limit.
+  Exit 1 on failure.
+- Files go in the app's own asset folder, `src/Apps/AG-xxxxx/`
+  (constitution V). Code refers to them as `/Apps/AG-xxxxx/<file>`.
+
+Check it compiles: `python -m py_compile tools/voice/make_<app>.py`.
+
+## 3. Generate
+
+Piper is installed from `tools/voice/requirements.txt`
+(`python -m pip install -r tools/voice/requirements.txt`). The voice model
+is **not** in the repo: `en_US-amy-medium.onnx` and its `.onnx.json` live
+in a folder outside it (download from Hugging Face,
+`rhasspy/piper-voices`, `en/en_US/amy/medium/`). Ask the user for the path
+if you don't know it, then run:
+
+```powershell
+python tools/voice/make_<app>.py --model C:\path\to\en_US-amy-medium.onnx
+```
+
+Piper varies slightly between runs. If a length check fails, raise
+`--speed` a little (e.g. 1.55) rather than loosening the limit.
+
+## 4. Review and commit
+
+- **The user listens on the PC first.** Same voice and pace as the other
+  apps? Only they can approve it; leave that task unticked until they do.
+- **Commit the generated files** with the app (they're part of the
+  install). They are licensed **CC BY-SA 4.0**, not MIT.
+- **Credit the voice everywhere constitution VIII requires**: the asset
+  folder's `CREDITS.txt`, `CREDITS.md` (add a section for the app), the
+  README's app section, and the app's own settings or info screen (a
+  `FONT_MINI` line such as "Voice: Piper, Amy (CC BY-SA 4.0).").
+- Add a section for the new script to `tools/voice/README.md`.
+
+## 5. Use the files in the app
+
+**Played by the app** (Speed Gauge, Flameout Alarm):
+
+- `system.playFile("/Apps/AG-xxxxx/file.wav", AUDIO_QUEUE)` or
+  `AUDIO_IMMEDIATE` for alarms (it cuts in over other speech). Foreground
+  playback is WAV only.
+- **Check the files exist in `init()`**, not per play: `io.open` the
+  absolute path, then the same path without its leading "/" (the JETI
+  Studio emulator needs relative paths; the transmitter takes absolute
+  ones). Close what you open.
+- **If files are missing, degrade quietly**: skip the callout or fall back
+  (Flameout uses beeps), and say so on the settings screen. Never error.
+
+**Played by the transmitter's Sounds on event** (Throttle Setup Wizard):
+
+- The app never plays them. It copies them from its asset folder to
+  `/Audio` on the pilot's request (JETI's audio picker lists `/Audio` and
+  `/Audio/<lang>`), never overwriting an existing file, in small chunks
+  across `loop()` calls, verifying the size and deleting a bad copy. Then
+  it opens the menu with `system.openExternal(":soundEvent")` and says what
+  to assign. See `src/Apps/AG-TrbSt.lua` (Voice callouts) and research R15
+  in `specs/002-turbine-throttle-setup/research.md`.
+- This keeps callouts working after the app is removed from the model, and
+  existing assignments stay visible in JETI's own menu.
+
+## 6. Test where sound actually plays
+
+The JETI Studio emulator plays **no** Lua audio (`playFile` is silent; the
+Emulated Telemetry app just prints a line). So:
+
+- In the emulator, check only the logic: file found / missing messages,
+  which file would play.
+- On the transmitter, check that each file plays, sounds right, and isn't
+  cut off, and (for Sounds on event) that the picker lists the files.
+  These are MANUAL tasks for the user.
+
+Record anything new about playback or file handling in
+`docs/jeti-api-notes.md`.

.gitignore

@@ -19,3 +19,7 @@ venv/
 
 # Local JETI Studio test source (tools/publish/make_apps_json.py --local)
 Apps.local.json
+
+# Model files copied from the transmitter (contain transmitter and receiver IDs)
+docs/examples/models/
+docs/examples/*.jsn

CLAUDE.md

@@ -17,6 +17,7 @@ other work. Remove an item once he says it's done.
 | App (menu name) | Script | Spec | Based on |
 | --- | --- | --- | --- |
 | Speed Gauge | `src/Apps/AG-SpdGa.lua` | `specs/001-speed-gauge/` | DFM Speed Announcer (Dave McQueeney, MIT) |
+| Throttle Setup Wizard | `src/Apps/AG-TrbSt.lua` | `specs/002-turbine-throttle-setup/` | original |
 | Flameout Alarm | `src/Apps/AG-FlmOt.lua` | `specs/003-flameout-alarm/` | original |
 
 Keep this table current when an app is added.
@@ -52,6 +53,9 @@ or shorten an existing credit or license notice.
   structure.
 - `src/Apps/lib/`: shared modules. Check here before writing a helper another
   app may already have.
+- Voice callouts or other speech files: follow the `jeti-voice` skill
+  (`.claude/skills/jeti-voice/`) so every app uses the same Piper "Amy"
+  voice, file format and credits.
 
 ## Layout and naming (constitution V and VII)
 

CREDITS.md

@@ -103,6 +103,22 @@ from Thomas Ekdahl's Jeti ECU telemetry app
 ([thomasekdahlN/jeti](https://github.com/thomasekdahlN/jeti)), which was
 studied for facts only; none of its code is used.
 
+## Throttle Setup Wizard voice callouts — Piper and the "Amy" voice
+
+Throttle Setup Wizard (`AG-TrbSt`) is original work; no code comes from
+another app. Its optional switch callouts, "Turbine off" and "Turbine on",
+use the same **Piper** engine and **"Amy"** (`en_US-amy-medium`) voice
+model by **Mycroft / Rhasspy** as Speed Gauge's voice, credited above,
+generated by [`tools/voice/make_turbine.py`](tools/voice/README.md) at the
+same calm pace (sped up, trimmed and peak-normalized).
+
+The generated files are in
+[`src/Apps/AG-TrbSt/`](src/Apps/AG-TrbSt/) and are licensed **CC BY-SA 4.0**
+(Amy model), not MIT; that folder's `CREDITS.txt` carries the attribution.
+The app copies them to the transmitter's `/Audio` folder only when the pilot
+asks, for use in the transmitter's Sounds on event. No Piper code is part of
+this repository or of the app.
+
 ## JETI model official demos
 
 [`docs/examples/jeti-demos/`](docs/examples/jeti-demos/) holds unmodified demos

README.md

@@ -9,6 +9,7 @@ spec-driven workflow (GitHub Spec Kit + Claude Code) in VS Code.
 | --- | --- | --- | --- | --- |
 | Speed Gauge | [`AG-SpdGa.lua`](src/Apps/AG-SpdGa.lua) | Released (0.3.0) | [001](specs/001-speed-gauge/spec.md) | DFM Speed Announcer by Dave McQueeney (MIT) |
 | Flameout Alarm | [`AG-FlmOt.lua`](src/Apps/AG-FlmOt.lua) | Released (0.1.0) | [003](specs/003-flameout-alarm/spec.md) | Original |
+| Throttle Setup Wizard | [`AG-TrbSt.lua`](src/Apps/AG-TrbSt.lua) | Released (0.1.0) | [002](specs/002-turbine-throttle-setup/spec.md) | Original |
 
 ### Screenshots
 
@@ -26,6 +27,14 @@ Taken on a DS-24 II transmitter.
 <img src="docs/apps/img/flameout-alarm-flameout.png" width="200" alt="Flameout Alarm showing the red FLAMEOUT alarm at 0 RPM">
 <img src="docs/apps/img/flameout-alarm-disarmed.png" width="200" alt="Flameout Alarm disarmed at 35,000 RPM">
 
+**Throttle Setup Wizard:** a guided step, verify passed,
+the summary. Full guide:
+[Throttle Setup Wizard](docs/apps/throttle-setup-wizard.md).
+
+<img src="docs/apps/img/throttle-setup-wizard-guide-2.png" width="200" alt="Throttle Setup Wizard guided step 2: Throttle-Cut output value -100%">
+<img src="docs/apps/img/throttle-setup-wizard-verify-passed.png" width="200" alt="Throttle Setup Wizard Verify: all four passed">
+<img src="docs/apps/img/throttle-setup-wizard-summary.png" width="200" alt="Throttle Setup Wizard Summary: setup complete with measured values">
+
 ### Speed Gauge
 
 Speaks your model's airspeed, warns of stall and overspeed, and shows a
@@ -187,6 +196,41 @@ The sounds in `src/Apps/AG-FlmOt/` are generated with
 [`tools/voice/make_flameout.py`](tools/voice/README.md) and licensed CC BY-SA
 4.0, not MIT. Install = `AG-FlmOt.lua` plus the `AG-FlmOt/` folder.
 
+### Throttle Setup Wizard
+
+Sets up a turbine's throttle on **one two-position safety switch**: **CUT**
+(Throttle Cut, engine off) or **RUN** (Throttle Idle, the engine may run).
+It's simpler and safer than the old habit of clicking the throttle trim down
+to stop and up to arm; Xicoy's manual warns that digital trims cause an
+unstable idle and a slow emergency shutdown.
+
+The app guides the transmitter's own setup and then **proves it** by
+measuring the throttle signal:
+
+- **One recommended setup:** Max negative/positive −80/80, Throttle-Idle
+  offset 20%, Throttle-Cut output value **−100%** (**−125% for Xicoy**).
+  Tested with KingTech, Swiwin and Xicoy ECUs; should work with most others.
+- **Guided setup:** five steps with the exact values, each with an **Open**
+  button that jumps to the transmitter menu.
+- **Verify:** an output check, then the four switch/stick positions,
+  including CUT with the stick at full. Each failure names the setting to
+  fix.
+- **Failsafe:** the receiver's throttle output on **Out OFF**, confirmed by a
+  hand test before the setup counts as complete.
+- **Optional voice callouts** "Turbine off" / "Turbine on", copied to the
+  transmitter's voice folder for its Sounds on Event.
+
+**It only reads and instructs.** It can't change any setting (constitution
+I): the pilot makes each change. Use it on the bench with the engine unable
+to start, remove it from the model once the setup passes, and **always
+re-learn the ECU** (Teach RC) afterwards. Full guide, including the setup by
+hand: [Throttle Setup Wizard](docs/apps/throttle-setup-wizard.md).
+
+The voice files in `src/Apps/AG-TrbSt/` are generated with
+[`tools/voice/make_turbine.py`](tools/voice/README.md) and licensed CC BY-SA
+4.0, not MIT. Install = `AG-TrbSt.lua` plus the `AG-TrbSt/` folder. Tested on
+the DS-24 II; older DC/DS transmitters should work but are untested.
+
 ## Install with JETI Studio
 
 1. In JETI Studio open **File → Configuration**, and add this line to the
@@ -201,8 +245,8 @@ The sounds in `src/Apps/AG-FlmOt/` are generated with
 
 Each app installs exactly its released version (its files come from the
 release tag). Descriptions: [Speed Gauge](docs/apps/speed-gauge.md),
-[Flameout Alarm](docs/apps/flameout-alarm.md) (in JETI Studio once its
-`Apps.json` entry is published).
+[Flameout Alarm](docs/apps/flameout-alarm.md),
+[Throttle Setup Wizard](docs/apps/throttle-setup-wizard.md).
 
 For maintainers: after tagging a release, run
 `python tools/publish/make_apps_json.py`, commit `Apps.json` and merge it to

docs/apps/throttle-setup-wizard.html

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+        <title>Throttle Setup Wizard</title>
+    </head>
+    <body style="padding:10px;float:left;max-width:500px;">
+        <h1>Throttle Setup Wizard</h1>
+        <p>Set up a turbine's throttle on one <b>safety switch</b>, and
+        <b>prove it works</b> before the engine ever starts. For the
+        DS-24 II / DC-24 II.</p>
+        <img src="img/throttle-setup-wizard-verify-passed.png" alt="Verify: all four passed" width="480">
+        <h3>One switch instead of the trim</h3>
+        <p>Many pilots still stop and arm their turbine by clicking the
+        throttle trim fully down and up. Xicoy's manual warns that digital
+        trims cause an unstable idle and a delay in shutting the engine off.
+        One two-position safety switch is simpler and safer:
+        <b>CUT</b> (Throttle Cut, engine off) or <b>RUN</b> (Throttle Idle,
+        the engine may run). You only have to set it up correctly once, and
+        that's what this app is for.</p>
+        <h3>What the app does for you</h3>
+        <ul>
+            <li><b>Proof, not assumption:</b> measures the real throttle
+            signal with the switch at CUT and RUN and the stick at idle and
+            full, and shows pass or fail.</li>
+            <li><b>Tests the dangerous case:</b> switch at CUT with the stick
+            at full must stay at cut.</li>
+            <li><b>Tells you what to fix:</b> e.g. "Switch RUN gave cut:
+            reverse the switch assignment", "Full off by +40 us: check Max
+            positive".</li>
+            <li><b>The right values for your ECU:</b> Max negative/positive
+            -80/80, Throttle-Idle offset 20%, Throttle-Cut output value -100%
+            (-125% for Xicoy). Tested with KingTech, Swiwin and Xicoy.</li>
+            <li><b>Opens each menu for you</b> from the guided steps.</li>
+            <li><b>Failsafe isn't forgotten:</b> you confirm a hand test
+            before the setup is called complete.</li>
+            <li><b>Optional voice callouts:</b> "Turbine off" and "Turbine
+            on" for the transmitter's Sounds on Event.</li>
+        </ul>
+        <img src="img/throttle-setup-wizard-guide-2.png" alt="Guided setup step 2: Throttle-Cut output value" width="480">
+        <p><b>Read and instruct only.</b> The app can't change any setting:
+        you make each change, it tells you exactly what and proves it worked.
+        Use it on the bench with the engine unable to start (fuel off or ECU
+        unplugged). Once the setup passes, remove the app from the model and
+        <b>always re-learn your ECU</b> (Teach RC).</p>
+        <h3>Using it</h3>
+        <ol>
+            <li>Add <b>AG-TrbSt</b> in <i>Applications - User Applications</i>,
+            then open <b>Throttle Setup Wizard</b>.</li>
+            <li><b>Setup inputs:</b> choose the safety switch and the throttle
+            stick (assign it as proportional, P), put the switch at CUT and
+            the stick at idle and press <b>Learn</b>. Choose the throttle
+            output and your ECU (Xicoy or Other).</li>
+            <li><b>Guided setup:</b> five steps with the exact values and an
+            <b>Open</b> button for each menu.</li>
+            <li><b>Verify</b>, then the <b>failsafe</b> hand test and the
+            summary.</li>
+        </ol>
+        <p>Version: <b>0.1.0</b></p>
+        <p>Compatibility: <b>DC/DS-24II</b>, firmware 6.x. Older DC/DS
+        transmitters should work but are untested.</p>
+        <p>Voice callouts: Piper text-to-speech with the "Amy" voice by
+        Mycroft / Rhasspy; the sound files are licensed CC BY-SA 4.0.
+        Throttle Setup Wizard: MIT license, Copyright (c) 2026 Aaron
+        George.</p>
+        <p>Full guide, source and credits:
+        <a href="https://github.com/Flazzarious/jeti-lua-apps/blob/main/docs/apps/throttle-setup-wizard.md">github.com/Flazzarious/jeti-lua-apps</a></p>
+    </body>
+</html>