80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# Read-only digital probe
|
||
|
||
`app.digital_probe` is the first Magnifica S development tool. It measures a
|
||
single already-conditioned digital signal; it does not control the machine and
|
||
never configures the ESP32-C3 pin as an output.
|
||
|
||
## Electrical boundary — required before connection
|
||
|
||
Do **not** attach an unknown wire from the coffee machine directly to an
|
||
ESP32-C3 GPIO. First identify the wire with the machine unplugged, then verify
|
||
its voltage, polarity, ground relationship, and behaviour at power-on with
|
||
appropriate test equipment. Connect it only through an interface that ensures
|
||
the ESP32 input stays between GND and 3.3 V at all times, including transients.
|
||
|
||
Use a board GPIO that is actually broken out and not occupied by the board.
|
||
Avoid GPIO2, GPIO8, and GPIO9 (ESP32-C3 boot strapping), GPIO12–GPIO17
|
||
(normally flash), and GPIO18–GPIO19 when USB-JTAG is needed. GPIO3 is a
|
||
candidate on boards that expose it, but confirm the board schematic first.
|
||
|
||
Keep the probe ground disconnected until it is known to be safe to share a
|
||
ground. If the machine signal is not confirmed low-voltage and ground-referred,
|
||
use a suitably rated isolated/conditioned interface instead of a direct link.
|
||
|
||
## Install and use
|
||
|
||
Deploy the whole `firmware/app/` directory. The probe is included in the OTA
|
||
manifest, but it is not auto-started, so normal launcher behaviour is unchanged.
|
||
|
||
At the MicroPython REPL:
|
||
|
||
```python
|
||
from app.digital_probe import open_probe
|
||
probe = open_probe(3) # Replace 3 after confirming your board pin and wiring.
|
||
|
||
probe.state()
|
||
probe.frequency(seconds=2)
|
||
probe.pulse(timeout_us=1_000_000)
|
||
probe.watch(seconds=5, max_events=200)
|
||
```
|
||
|
||
## Continuous probe mode
|
||
|
||
To collect data without interrupting the application, set the following in the
|
||
device-local `/.env` and reset the board:
|
||
|
||
```env
|
||
PROBE_ENABLED=true
|
||
PROBE_GPIO=3
|
||
PROBE_MODE=frequency
|
||
PROBE_FREQUENCY_SECONDS=2
|
||
PROBE_INTERVAL_SECONDS=3
|
||
PROBE_LOG_ENABLED=true
|
||
PROBE_LOG_PATH=/probe_result.txt
|
||
```
|
||
|
||
`PROBE_MODE` may be `state`, `frequency`, `pulse`, or `watch`. The corresponding
|
||
`PROBE_*` settings in `.env.example` control the measurement window, timeout,
|
||
or event cap. The mode continuously writes its results to the serial console;
|
||
it does not expose any output pin or machine-control capability. Set
|
||
`PROBE_ENABLED=false` and reset to return to normal application operation.
|
||
|
||
With `PROBE_LOG_ENABLED=true`, every line emitted by the probe is also appended
|
||
to `/probe_result.txt`. A `===== POWER CYCLE / PROBE START =====` header is
|
||
written at each probe-mode boot, making separate test sessions easy to find.
|
||
Retrieve the file later with `mpremote connect COM3 fs cp :/probe_result.txt
|
||
probe_result.txt`. Logging opens and closes the file for each line to preserve
|
||
data across unexpected power loss; use it for bounded test sessions because
|
||
frequent flash writes use storage and contribute to flash wear.
|
||
|
||
`frequency()` counts rising edges in its measurement window. It is useful for
|
||
signal discovery and approximate rates, but very fast or noisy signals can
|
||
overflow or exceed MicroPython IRQ handling capacity. `pulse()` reports one
|
||
high and one low width; negative results are timeouts (`-2` means the requested
|
||
level did not arrive, `-1` means its pulse did not finish). `watch()` is a
|
||
short, polling-based transition trace and can miss narrow pulses.
|
||
|
||
For every capture, note the machine state, wire identifier, wiring/interface,
|
||
measurement settings, and output. That context is necessary before mapping a
|
||
panel signal to a machine event.
|