docs: design record for the Trigger Oscilloscope on Mazduino boards

Notes on what rusEFI's Trigger Oscilloscope actually does, how it differs from
the Primary Tooth and Composite loggers, what it costs in flash/RAM/CPU, and
what a board revision would have to provide (an ADC-capable trigger input).

Nothing is implemented - this records the findings so the next board revision
can be decided with the numbers in hand. References are to ext/rusefi/firmware
at the submodule revision in this tree.

Author: amrikarisma

docs/trigger-scope.md

@@ -0,0 +1,272 @@
+# Trigger Oscilloscope on Mazduino boards
+
+Implementation notes for bringing rusEFI's Trigger Oscilloscope up on Mazduino
+hardware. Nothing here is implemented yet — this is a design record of what the
+upstream feature does, what it costs, and what a board revision would have to
+provide.
+
+Everything below was read out of `ext/rusefi/firmware` at the submodule revision
+in this tree. File and line references are to that copy.
+
+---
+
+## 1. What it is, and why the existing loggers are not it
+
+rusEFI ships three trigger diagnostics. They are usually confused with each
+other, so the distinction matters when deciding whether this is worth the board
+change:
+
+| Logger | TS name | What it records | Needs |
+|---|---|---|---|
+| Primary tooth | "Primary Tooth Time Logger" | one timestamp per rising edge | nothing extra |
+| Composite | "Composite Logger" | a timestamp per *edge*, plus level/sync/TDC flags | nothing extra |
+| **Trigger scope** | "Trigger Oscilloscope" | the **raw analog voltage** on the trigger line, sampled continuously | an ADC-capable input |
+
+The first two are digital: they tell you *when* the ECU's own comparator decided
+an edge happened. If the comparator is misbehaving, they tell you nothing about
+why — a VR signal that is too weak to cross the threshold at cranking, ringing
+on a long unshielded run, or a Hall sensor with a slow rise time all look the
+same from a digital logger: a missing or spurious tooth.
+
+The trigger scope samples the conditioned analog waveform, so you see amplitude,
+shape and noise. That is what makes it worth the hardware, and also why it
+cannot be retrofitted in firmware alone.
+
+---
+
+## 2. Why it does not work on Mazduino today
+
+`trigger_scope.cpp` is wrapped entirely in `#ifdef TRIGGER_SCOPE`
+(`firmware/console/binary/trigger_scope.cpp:7`). The define comes from the
+board's own makefile — on AlphaX 4chan, `board.mk:24`:
+
+```make
+DDEFS += -DTRIGGER_SCOPE
+```
+
+No Mazduino board defines it, and none has a `trigger_scope_config.h`. So
+`initTriggerScope()` is never compiled in, and the `TS_TRIGGER_SCOPE_ENABLE`
+case inside `TS_SET_LOGGER_SWITCH` is compiled out too — the firmware answers
+the start command with a NAK.
+
+**The generated INI is misleading here.** `tunerstudio.template.ini` emits the
+`loggerDef = triggerScope, "Trigger Oscilloscope", csv` block unconditionally,
+so every Mazduino INI advertises a logger the firmware cannot run. TunerStudio
+will list it and fail. Consider suppressing that block for boards without the
+define when this is picked up.
+
+---
+
+## 3. Protocol, for whoever writes the app side
+
+The scope rides the same `TS_SET_LOGGER_SWITCH` ('l', `0x6C`) command as the
+tooth and composite loggers, with a different sub-command byte:
+
+| Action | Bytes | Constant |
+|---|---|---|
+| Start | `6C 04` | `TS_TRIGGER_SCOPE_ENABLE` |
+| Stop | `6C 05` | `TS_TRIGGER_SCOPE_DISABLE` |
+| Read | `6C 06` | `TS_TRIGGER_SCOPE_READ` |
+
+Wrapped in the usual TS CRC frame. `dataReadyCondition` is the
+`triggerScopeReady` output channel; reading before it is set answers
+`TS_RESPONSE_OUT_OF_RANGE` (`0x84`).
+
+The response payload is a flat array of 2-byte records, no header or footer:
+
+```
+recordDef   = 0, 0, 2
+recordField = channel1, <name>, bit 0, 8 bits, scale 6.6/255, "v"
+recordField = channel2, <name>, bit 8, 8 bits, scale 6.6/255, "v"
+```
+
+So byte 0 is channel 1, byte 1 is channel 2, interleaved for the whole buffer.
+Samples are **8-bit** (the ADC runs in 8-bit mode, `ADC_CR1_RES_1`), and the
+buffer is `BIG_BUFFER_SIZE` = 8192 bytes → 4096 sample pairs per read.
+
+The channel names come from the board's `prepend.txt`, e.g. AlphaX 4chan:
+
+```c
+#define TS_TRIGGER_SCOPE_CHANNEL_1_NAME "C2/C3 Crank VR"
+#define TS_TRIGGER_SCOPE_CHANNEL_2_NAME "E5/E6 Cam VR"
+```
+
+---
+
+## 4. The hardware requirement
+
+### 4.1 The scale factor tells you the divider
+
+The INI scales a sample by `6.6 / 255`. An 8-bit full-scale reading is 255,
+which the ECU reports as 6.6 V, while the pin itself can only see VREF = 3.3 V.
+That is a **2:1 divider in front of the ADC pin**: 6.6 V at the input becomes
+3.3 V at the pin.
+
+If a Mazduino revision uses a different divider, the `6.6` in the INI has to
+change to match, or every reading is wrong by that ratio. It is a per-board
+constant baked into the generated INI, so it belongs with the board's other
+scaling values.
+
+### 4.2 What has to reach the pin
+
+The scope taps the signal **after** protection and conditioning but **before**
+(or in parallel with) the digital comparator. Wanted:
+
+- Divider to put the working range inside 0–3.3 V at the pin (2:1 for the 6.6 V
+  scale above).
+- Clamp diodes to 3.3 V and GND. A VR sensor at high RPM swings far beyond this
+  and will otherwise destroy the pin.
+- Series resistor between the clamp and the pin to limit clamp current.
+- Keep the existing conditioning path intact — the scope is a passive observer,
+  the decoder still runs off the comparator output.
+
+A VR sensor is bipolar and swings negative. The AlphaX inputs are named
+`IN_RES*`, which on Hellen boards are biased analog inputs, so the negative half
+of the swing is lifted into range by the bias network. A Mazduino tap would need
+the same treatment: bias the signal to roughly mid-rail so both halves of the VR
+waveform are visible, otherwise the negative half clips to 0 V and the trace is
+useless for judging symmetry.
+
+### 4.3 The pin must be on the ADC
+
+On `mazduino-core` the trigger input is `Gpio::C6`
+(`boards/mazduino-core/board_configuration.cpp:89`). **PC6 has no ADC channel on
+STM32F4** — it is a digital-only pin. So this cannot be done by re-declaring an
+existing pin; the conditioned signal has to be routed to a spare ADC-capable pin
+as a second net. That is a board respin, not a firmware change.
+
+ADC-capable pins on the STM32F4 in use: PA0–PA7, PB0–PB1, PC0–PC5, and PF3–PF10
+on the 144-pin parts.
+
+---
+
+## 5. The blocker: ADC3 is already spoken for
+
+This is the part that decides the design, and it is specific to Mazduino.
+
+Upstream puts the scope on ADC3:
+
+```c
+#define TRIGGER_SCOPE_ADC ADCD3     // trigger_scope_config.h
+```
+
+Mazduino puts **software knock** on ADC3 (`boards/mazduino-core/knock_config.h`):
+
+```c
+#define KNOCK_ADC ADCD3
+#define KNOCK_PIN_CH1 Gpio::F4      // ADC_CHANNEL_IN14
+#define KNOCK_PIN_CH2 Gpio::F5      // ADC_CHANNEL_IN15
+```
+
+Upstream already treats these as mutually exclusive — `startSampling()` and
+`initTriggerScope()` both bail out when `enableSoftwareKnock` is set, with the
+comment *"Trigger scope and knock currently mutually exclusive"*. They also
+compete for the same 8 KB scratch area: `BigBufferUser` has separate
+`TriggerScope` and `KnockSpectrogram` entries, and only one holder at a time.
+
+Three ways out, in increasing order of effort:
+
+1. **Accept the exclusivity.** Scope works only with software knock disabled.
+   Cheapest, and matches upstream. Knock is not something you need while
+   diagnosing a trigger that will not sync, so in practice the conflict is
+   mild — but it must be surfaced in the UI, or the feature will read as broken
+   to anyone with knock enabled.
+2. **Put the scope on a different ADC unit** (ADC1/ADC2), if the chosen pin's
+   channel is reachable from it and the DMA stream is free. Needs care: ADC1 is
+   busy with the normal sensor scan. Check `STM32_ADC_USE_ADC*` in `mcuconf.h`
+   and the DMA stream map before committing.
+3. **Share ADC3 by time-slicing.** Not worth it — both features want continuous
+   DMA into a large buffer.
+
+Recommendation: option 1 for a first cut, and pick the scope pin on ADC3
+(PF3–PF10 range, next to the existing knock pins) so no ADC rework is needed.
+
+---
+
+## 6. Sample rate and capture window
+
+From `trigger_scope_config.h`, `TRIGGER_SCOPE_SAMPLE_TIME = ADC_SAMPLE_144`, in
+8-bit mode, with two channels in the scan group.
+
+On STM32F4, one conversion takes `SMP + resolution` ADC clocks, where the
+8-bit resolution costs 8 cycles. So per channel pair:
+
+```
+cycles_per_scan = 2 * (144 + 8) = 304
+f_scan          = f_adc / 304
+```
+
+`f_adc` is `PCLK2 / STM32_ADC_ADCPRE`. With PCLK2 = 84 MHz and a /4 prescaler
+that is 21 MHz, giving roughly:
+
+```
+f_scan ≈ 21e6 / 304 ≈ 69 kSa/s per channel
+window  = 4096 scans / 69 kSa/s ≈ 59 ms
+```
+
+**Verify `STM32_ADC_ADCPRE` for the target board before quoting these numbers** —
+they move directly with the prescaler. The knock config in this repo derives its
+rate the same way and is a good template:
+
+```c
+#define KNOCK_SAMPLE_RATE (STM32_PCLK2 / (4 * (84 + 12)))
+```
+
+~59 ms is about 3 crank revolutions at 3000 rpm, or half a revolution at
+cranking speed. Enough to see the gap and judge waveform shape; not enough for a
+long-term noise hunt. `triggerScopeGetBuffer()` re-arms the next capture 10 ms
+after each read, so a continuous read loop gives a repeating snapshot, not a
+gapless recording.
+
+---
+
+## 7. Firmware checklist
+
+Once the hardware exists:
+
+1. `boards/<board>/trigger_scope_config.h`:
+   ```c
+   #define TRIGGER_SCOPE_ADC          ADCD3
+   #define TRIGGER_SCOPE_SAMPLE_TIME  ADC_SAMPLE_144
+   #define TRIGGER_SCOPE_PIN_CH1      Gpio::Fx
+   #define TRIGGER_SCOPE_ADC_CH1      ADC_CHANNEL_INxx
+   #define TRIGGER_SCOPE_HAS_CH2      true      // cam channel, optional
+   #define TRIGGER_SCOPE_PIN_CH2      Gpio::Fy
+   #define TRIGGER_SCOPE_ADC_CH2      ADC_CHANNEL_INyy
+   ```
+2. `boards/<board>/board.mk`: `DDEFS += -DTRIGGER_SCOPE`
+3. `boards/<board>/prepend.txt`: set `TS_TRIGGER_SCOPE_CHANNEL_1_NAME` and
+   `..._2_NAME` to the real connector pin labels — these are what the user sees
+   as the trace legend.
+4. If the divider is not 2:1, change the `6.6` scale in the INI template for
+   this board.
+5. Decide and document the knock interaction. `enableSoftwareKnock` silently
+   disables the scope today; if that stays, the INI should gate the logger on
+   it so TunerStudio does not offer a dead button.
+
+Note `adcConvGroupCh1` hardcodes two channels in `ADC_SQR3`. A single-channel
+board still works but wastes half the buffer on a dead channel — worth a small
+patch upstream-side if only one channel is fitted.
+
+---
+
+## 8. App side (MTuneX)
+
+Not implemented, and deliberately so: adding a button that NAKs on every board
+currently shipped would only confuse people. When a board gains the hardware:
+
+- The commands are three fixed 2-byte payloads (section 3), so `TsProtocol`
+  needs one more builder alongside the tooth/composite ones.
+- Gate the menu entry on the ECU actually supporting it. The INI's `loggerDef`
+  is not a reliable signal today (section 2); until that is fixed, gate on the
+  board name or on a probe that tolerates a NAK.
+- The existing Tooth Logger screen already has a mode selector and a raw-data
+  table; a scope trace is a third mode rather than a new screen.
+
+---
+
+## 9. Speeduino
+
+No equivalent. Speeduino has the tooth logger and three composite variants, all
+digital edge logging off the same interrupt. There is no ADC path on the trigger
+input and no scope command in its serial protocol.