mirror of
https://github.com/openglow-org/forgefirm.git
synced 2026-09-27 08:41:13 -07:00
ScottW514
00ded74189
The first campaign with the bench actuator wired failed motion.button-hold-resume on the tool, not the machine: the second press was asked while the first 200 ms pulse was still on, the fixture answered 409, the runner handed the step to an operator who was not in the room, and the post pass could not jog a controller left in Hold. - fixture.py: a press waits for the last pulse to end (the fixture's pulse_ms) plus a 300 ms release, so the controller sees the edge; a 409 for a pulse in progress is waited out against button_pulsing and retried once. - runner.py: in an unattended run a fixture refusal ends the test at once as ERROR naming the refusal; the operator fallback stays for attended runs. - baseline.py: a controller in Hold or Door gets a soft reset before the return jog, position kept. - tests: the fake fixture refuses a press while one is in progress and reports button_pulsing; FakeGrbl records ^X and can land a reset in a chosen state; five new tests. - docs: ACCEPTANCE.md fixture rules, fixture/README.md tool's side. No catalog consequence: tool-side change, no covers map moves. Bench: campaign c-20260824174545-0bdc 25/25 with every action by the fixture; the hold reset proven by a dry drill.
123 lines
6.1 KiB
Markdown
123 lines
6.1 KiB
Markdown
# forgefixture: the bench actuator
|
||
|
||
The acceptance campaign asks a person for about eighty small things,
|
||
and most of them are the same three: open the lid, pull the interlock,
|
||
press the button. This is the box that does those on request, so the
|
||
tool can run an operator test with nobody in the room. An ESP32-S3
|
||
DevKitC-1 on the bench network drives three relays wired into the
|
||
machine's own connectors; the acceptance tool (`forgetest`, on the
|
||
machine) asks it over HTTP and then watches the machine for the result,
|
||
the way it watches an operator's hand today.
|
||
|
||
Nothing here touches the laser's safety chain. Two of the contacts are
|
||
normally closed and sit in series with loops the chain already reads;
|
||
the third is normally open across the button input and is only ever
|
||
pulsed. With the fixture unpowered, unplugged, rebooting or crashed, the
|
||
machine is a stock machine.
|
||
|
||
## Hardware
|
||
|
||
| Part | What |
|
||
|---|---|
|
||
| ESP32-S3-DevKitC-1 | any flash size; powered from its USB port by a **USB wall adapter** (see grounds) |
|
||
| 3 × 1-channel 3.3 V optocoupler relay modules, high-level trigger | VCC, GND, IN; coil ~100 mA each |
|
||
| a 2-pin header and jumper | the button channel's enable |
|
||
| the interposer harness at the machine | bench-local; described in the project's hardware facts bank, not here |
|
||
|
||
Pins on the DevKit (all plain GPIOs, no strapping, USB, flash or PSRAM
|
||
role):
|
||
|
||
| Signal | GPIO | Relay contact | Where in the machine |
|
||
|---|---|---|---|
|
||
| lid | 4 | **NC**, in series with the lid-switch loop | energized = the loop opens = lid open |
|
||
| interlock | 5 | **NC**, in series with the interlock loop | energized = the loop opens = interlock pulled |
|
||
| button | 6 | **NO**, across the button input | energized = pressed; pulsed only, 20 to 500 ms |
|
||
| button enable | 7 | input, internal pull-up | a jumper to GND enables the button channel; no jumper, no presses |
|
||
|
||
Relay coils from the machine's 3.3 V (the modules' VCC and GND), the
|
||
three IN pins from the GPIOs above, the DevKit's GND to the modules'
|
||
GND. The modules' opto inputs share GND with their coils, so the ESP32
|
||
and the machine share a ground: power the DevKit from a wall adapter,
|
||
not from a PC, unless you want that PC's ground on the machine.
|
||
|
||
## Build and flash
|
||
|
||
The only input is `fixture.env`: the wifi network, the API key, the
|
||
hostname. Everything else is pinned (ESP-IDF v5.5, the mDNS component in
|
||
`dependencies.lock`).
|
||
|
||
./fixture.sh env # fixture.env from the example, with a fresh key; fill in the wifi
|
||
./fixture.sh build # idf.py if installed, else the espressif/idf container (docker or podman)
|
||
./fixture.sh flash COM5 # or /dev/ttyUSB0; esptool from pip talks to the board directly
|
||
./fixture.sh monitor COM5 # the log
|
||
|
||
Either USB port of the DevKit flashes; the one marked UART shows the log
|
||
too. `fixture.env` is git-ignored and never leaves the bench. A build in
|
||
the container works anywhere docker or podman runs (Git Bash on Windows
|
||
included); `pip install esptool pyserial` is the whole host-side
|
||
requirement for flashing and watching.
|
||
|
||
## What it does on the network
|
||
|
||
It joins the wifi as `forgefixture` (the `HOSTNAME` in `fixture.env`),
|
||
sends that name in its DHCP request, and announces `forgefixture.local`
|
||
over mDNS with a `_forgefixture._tcp` service. It reconnects forever and
|
||
never sleeps the radio. The API is HTTP on port 80, JSON, LAN only, no
|
||
OTA (the flash happens over USB and nowhere else).
|
||
|
||
Every request carries the key in `X-Fixture-Key`; without it, or with
|
||
a wrong one, every path answers 401 and the attempt is logged with the
|
||
caller's address.
|
||
|
||
| Request | Does |
|
||
|---|---|
|
||
| `GET /` or `/state` | identity, firmware version, uptime, the three channels' states, whether the button is enabled, the wifi link |
|
||
| `POST /lid {"state":"open"}` | energizes the lid channel (the loop opens); `"close"` releases it |
|
||
| `POST /interlock {"state":"open"}` | the same for the interlock loop |
|
||
| `POST /button {"ms":200}` | one press, `ms` clamped into 20 to 500 (200 when absent); 409 while the enable jumper is out or a press is still in progress |
|
||
| `POST /release` | every channel released |
|
||
|
||
An action answers with the state as `GET /` shows it. The fixture does
|
||
not read the machine's switches; the tool verifies every action through
|
||
the machine's own readings, which is the point.
|
||
|
||
curl -s -H "X-Fixture-Key: $KEY" http://forgefixture.local/
|
||
curl -s -H "X-Fixture-Key: $KEY" -d '{"state":"open"}' http://forgefixture.local/lid
|
||
|
||
## The tool's side
|
||
|
||
`forgetest` looks for `/data/forgetest/fixture.json` on the machine:
|
||
|
||
{"hostname": "forgefixture", "key": "<the API_KEY>", "ip": null,
|
||
"channels": ["lid", "interlock", "button"], "arm_press": false}
|
||
|
||
`ip` overrides the mDNS lookup (the tool resolves `<hostname>.local`
|
||
itself; the image has no mDNS resolver). `channels` names what is
|
||
wired. `arm_press` stays false unless the fixture may press the button
|
||
to arm the laser for a live test; by default that press is a person's.
|
||
The file is mode 0600 and bench-local. With the fixture up, an
|
||
`operator` test whose actions it covers runs in the unattended queue;
|
||
`live` tests keep their kind and their acknowledgment, and every action
|
||
records who performed it. Presses are spaced by the tool: the next one
|
||
waits for the last pulse to end plus a 300 ms release, so the machine
|
||
sees two presses and not one long one.
|
||
|
||
## What keeps it safe
|
||
|
||
- Every line is driven low first thing at boot, before the radio or the
|
||
server exist, and after any reset.
|
||
- The button is a pulse whose end is armed before the line rises; a hung
|
||
task trips the task watchdog, which panics and reboots to all-low.
|
||
- The button channel needs the jumper; a LAN key leak cannot press the
|
||
button on a fixture whose jumper is out.
|
||
- NC contacts in the loops: a fixture fault can only add an open, never
|
||
mask a real lid open or a pulled interlock.
|
||
- No OTA, no configuration over the network, nothing persisted beyond
|
||
the wifi driver's own calibration.
|
||
|
||
## Layout
|
||
|
||
main/ the firmware: main.c, wifi.c, api.c, relays.c, policy.c (the pure decisions)
|
||
test/ the host test of policy.c (./fixture.sh test)
|
||
fixture.env.example, sdkconfig.defaults, dependencies.lock
|