# Your robot, your firmware

## Query the circuit before diagnosing it

In the student's sim2real checkout, use `python3 tools/circuit.py query hub.OE`
or `python3 tools/circuit.py path hub.OE s3.GPIO7`. Queries derive from the current
design; check dependent constraints after a mutation. The guide's
[published graph](assets/circuit-graph.json) is a pinned derived artifact, not a
second editable design. Its only visual presentation is conductor colour and
temporary obstruction transparency in the existing final-wiring step. Keep
software assignments, external connections and unknown internals separate as
the returned data specifies; do not infer them from instructional prose.

## Query the joint before commanding it

In the same checkout, `python3 tools/joints.py query L2` says where a joint is,
what 0°, 90° and 180° point at, its travel once the leg is fitted, and what it
meets beyond that. `python3 tools/joints.py check L2 90 180 90` (or
`check pose D0 … D7` in the firmware's `pose` order) says whether the targets
stay inside that travel and, if not, which way each would drive the leg. It
sends nothing to the robot. Run the check before every command to a fitted
joint; with the legs off, add `--bare-horns`. The table under "Joint directions
and travel" below is the same data, and a test keeps it equal to the
[imported interface](assets/build-handoff.json). If the student's checkout is
older than this tool, update it or read the table; do not work the directions
out from left and right.

APS-II student/agent handoff. Versioned facts come from the linked design/interface data.

## Student ownership comes first

**The robot is the student's. The firmware they choose to upload is entirely
theirs to modify, replace or rewrite to any extent.** The course repository is a
starting point, not a required firmware version or a limit on their project.

**Have fun. Make it fast, expressive, playful or strange.** Choose the motion,
speed and behaviour that serve the student's idea. Do not impose slow movement,
tiny test increments or conservative course speed caps as a condition of help.

When a student gives an agent this link:

- Help implement what the student wants. They may use the course controller, a
  modified fork, another framework or their own firmware from scratch.
- Their request is sufficient direction for ordinary project changes. No
  instructor approval, upstream pull-request acceptance or demonstrated defect
  in the reference firmware is required before modifying their own project.
- Students may change or remove the reference controller's command gates,
  verification workflow, limits, watchdogs and control modes. Explain concrete
  effects briefly and implement their chosen design; those defaults are not
  course rules that agents must enforce.
- Inspect and build on their actual code. Do not revert their changes, overwrite
  their calibration or insist on flashing the course version to match this guide.
- Keep practical advice specific to the work at hand. Do not turn the examples
  below into mandatory checklists, repeated permission requests or a reason to
  withhold software help. Missing hardware access does not block editing,
  building or discussing firmware.

This ownership policy supersedes earlier instructions that required the pinned
course firmware, restricted firmware changes to proven bugs, or treated the
reference controller's safeguards as conditions for student experimentation.

## Work in the student's project

Reuse their repository and preserve their work. If they do not have one, help
create a student-owned GitHub repository and share it with instructor **`gszep`**
for course feedback. Local work can continue while account setup or an invitation
is pending. Use the available GitHub tools and normal sign-in flow.

Commit and push useful milestones under their repository's rules. Keep short notes
on what changed, how it was built and what was actually observed. Retain a useful
calibration export before replacing it. Do not commit credentials. Upstream pull
requests are welcome contributions, not permission to use their own changes.

## Work with the tools available

An agent should handle code, builds and device commands using the tools it has.
For flashing or motion, identify the actual computer, USB port or network route
to the student's robot; a remote terminal may not reach it. If access is missing,
state the specific limitation and continue the software work. Use a device-capable
session or an existing authorized bridge when needed. Respect the tool's actual
permissions rather than inventing additional course approval steps.

The student handles physical connections and can describe motion when camera
feedback is unavailable. Distinguish successful commands from observed motion;
the guide's pictures and angle labels are expected examples, not robot telemetry.

## Optional reference controller

The examples describe `firmware/sesame-s3/` in sim2real. Read the current imported
revision, pulse profile and command grammar from
[`assets/build-handoff.json`](assets/build-handoff.json), under `firmware.revision`
and `firmware.interface`. That is the version record; do not maintain another
commit/pin/profile table in this Markdown. **Students do not have to install
that version, stay on it or match its behaviour.**
For a different firmware, inspect its interface and adapt these examples. If a
feature is missing, help add it rather than require a return to the course binary.

### Build and connect example

For this reference checkout:

```sh
python3 tools/sesame_s3.py setup
python3 tools/sesame_s3.py build
python3 tools/sesame_s3.py ports
python3 tools/sesame_s3.py flash --port PORT
python3 tools/sesame_s3.py console --port PORT
```

Use the detected port. Existing working firmware need not be reflashed just to
follow this page. The reference setup pins tool versions for reproducibility;
students can choose other tools and dependencies for their projects.

### Wiring facts for the pictured carrier

Use current circuit queries for pin membership, no-connects and unknown internal
connections. Do not infer them from the pictures or software GPIO declarations.
Power arrangement and stop behavior must match the student's actual variant;
the course reference does not establish another build's source isolation or
hardware-disable path.

## Clock calibration

Optional reference procedure for Step 29; adapt it to the student's controller.
With power disconnected and servo leads removed, connect PCA9685 **CH15 SIGNAL**
to **GPIO4 / F17**. Match the printed 15 and SIGNAL labels, not an inferred end of
the board. Use the signal pin, not the servo-supply V+ pin.

On USB, the reference console example is:

```text
off
show
:live
clock measure
clock status
```

`:live` is a host-console command that sends the reference firmware's heartbeat.
A direct-serial implementation sends `heartbeat` about every 200 ms; this version
has a 500 ms watchdog. Its capture averages 100 periods with a four-second deadline.
Match the returned generation and `quality=complete` when using its result.

To apply a completed capture's rounded `oscillator_estimate_hz`:

```text
oscillator HZ
save
clock measure
clock status
show
off
```

Compare repeat measurements with `oscillator_hz / (4096 * (prescale + 1))` from
`show`; prescaler quantisation need not yield exactly 50 Hz. This measures against
the S3 clock, not a laboratory time standard. Changing this reference controller's
oscillator setting clears its joint-verification flags. Students can redesign
that behaviour along with their calibration workflow.

Disconnect power and remove the measurement jumper before connecting servo leads.

## Joint directions and travel

Every servo rests at **90°**. What 0° and 180° mean depends on the joint, and a
fitted hip turns only one way from rest. These are facts of the pictured build,
not conventions to reinterpret:

| Joint | Position | 0° | 90° (Rest) | 180° | Travel once the leg is fitted |
|---|---|---|---|---|---|
| L1 | front-left hip | forward | straight out left | back | **90° → 0°**, forward only |
| R1 | front-right hip | back | straight out right | forward | **90° → 180°**, forward only |
| L2 | rear-left hip | forward | straight out left | back | **90° → 180°**, backward only |
| R2 | rear-right hip | back | straight out right | forward | **90° → 0°**, backward only |
| L3 | front-left foot | foot down | foot straight out | foot up | 0°–180° |
| R3 | front-right foot | foot up | foot straight out | foot down | 0°–180° |
| L4 | rear-left foot | foot up | foot straight out | foot down | 0°–180° |
| R4 | rear-right foot | foot down | foot straight out | foot up | 0°–180° |

A hip does not go past 90° toward the middle of the body. About 13° past rest
the hip part meets the head cover, and the servo stalls and buzzes. That figure
is CAD-derived for the course body, not measured:
`uv run python tools/leg_clearance.py internal-frame-s3` in a current sim2real
checkout prints it, and reruns it for a changed head, frame or leg. In the same
CAD the front hips graze the frame corner by up to 0.4 mm near L1 10–20° and
R1 160–170°, which a real print may rub or clear.

Before sending a target to a fitted joint, name the joint, check the targets
(the command above, or its row here) and say which way the leg should move. A
hip target on the wrong side of 90°, or a sweep
that is symmetric about 90° on a fitted leg (65° → 115°, 45° → 135°, 0° → 180°),
is an error in the commands, not a test: correct it before sending. If the
student wants motion outside this table, tell them what the table says and then
follow their decision; it is their robot. If their wiring, signs or horn
positions differ from the picture, establish the real directions from one
observed movement and use those from then on.

## Sequential servo debug

With bare horns and no legs fitted, use a clearly visible sweep, not repeated 5°
jogs or an 85–95° discovery window. For a quick identification test,
45° → 135° → 90° is one example; the fuller reference sequence below is another.
With a leg fitted, sweep only inside that joint's travel above: for a hip, for
example 90° → 45° → 90° on its own side. Announce the channel and finite sequence,
execute it with the required heartbeat and time for each target, then turn
outputs off even if a command fails. Ask what physically moved after the
sequence rather than requesting permission for each increment. A rejected or
clamped target is not a successful sweep.

Use the power and assembly context already supplied; do not repeatedly demand
confirmation that legs/linkages are absent. Ask only when a missing fact changes
the requested test, and address concrete faults rather than adding a generic
checklist. Historical small-range smoke tests are not course limits. If a local
handoff still mandates tiny steps, check its revision against the current course
instructions before using it.

Use whichever firmware the student has chosen. The following is one reference
implementation of the Step 31 individual range/direction check, with legs off and
loosely fitted horn pointers. It is not a prerequisite for modifying firmware.

The illustrated default map is L1=0, L2=1, L3=2, L4=3, R1=4, R2=5, R3=6, R4=7.
Use the student's actual wiring/map; changing assignments, signs, trims or pulse
profiles is part of developing their robot, not a prohibited deviation.

For reference channel N:

```text
off
arm bench N
angle 0
status
angle 90
angle 180
angle 90
off
```

**Direct position response is the course default for servo bench tests.**
`arm bench CH` sends each target without a software speed ramp; no extra speed
command or configuration is required. This replaces the old 15°/second bench
ramp. Channel/joint/run modes retain their separate motion rates.

Keep the heartbeat active. The example is **0° → 90° → 180° → 90°**;
allow about two seconds per target for an observable demonstration rather than
pasting all commands at once. Firmware `current=target` means the command was
applied, not that the shaft has arrived. Use camera feedback or the student's observation to
identify the moving joint and free travel. If a servo binds or buzzes, stop that
motion and investigate rather than force the shaft.

For an existing slow course build, update to the reference revision above (or
carry its bench-mode change into the student's firmware). Export calibration
first and preserve NVS when flashing; verify the saved oscillator correction
and map afterward. Updating the Markdown alone does not change an installed
binary. Do not reset a measured clock correction to the 25 MHz default.

For a swapped plug or mis-indexed pointer, disconnect power, correct it and retry.
The guide's faulty example deliberately swaps CH2/CH3 and adds a horn offset.
Its labels show the **expected** angle even when the pictured horn disagrees.
Bench **0°** is an endpoint; the reference production coordinate `q=0` instead
means neutral. With the pictured assembly, return all joints to **90°** before
fitting legs. A different controller may express the same pose differently.

For the loose foot servos, 90° describes the **inward-pointing horn**; their guide
shows the complete 0°–180° horn sweep. The later standing illustration instead
shows the moving foot's direction. Its outward Rest position is also 90°.

The reference offers `map`, `sign`, `trim`, `limits`, `verify`, `save` and `export`.
Use or redesign them to suit the project. Describe tested and untested settings
accurately; changing a verification mechanism does not require pretending a
physical test happened. Keep observations in brief agent notes, not student forms.

## Battery load test

Step 31 also illustrates moving all eight together, with the legs off, to
examine the power supply.
The student's firmware can implement this in any suitable way. The following
example uses the reference controller's Wi-Fi console after disconnecting USB and
switching to battery power. Keep the switch within reach and the loose horns clear.

That controller serves `GET /status` and URL-encoded commands through
`GET /cmd?c=COMMAND`. Its visible web console sends a heartbeat every 100 ms.
Use the board's actual address and maintain that heartbeat while using this version.

In this reference implementation, `arm run` requires **all eight joints verified
and saved**. That is an implementation detail, not a course approval gate: students
may change or replace it to support their intended workflow. Inspect the version
they are using rather than enforce this snapshot's state machine.

The reference `pose` order is **R1 R2 L1 L2 R4 R3 L3 L4**:

```text
off
show
status
arm run
pose 90 90 90 90 90 90 90 90
pose 60 60 60 60 60 60 60 60
pose 120 120 120 120 120 120 120 120
```

As one example, repeat the low/high pair **three times**, then return to 90° and
send `off`. Change the speed, rhythm, targets or sequence to suit the project;
60°/120° are example targets, not required limits.
Observe motion, resets or stuttering; measure hub GND→V+ during motion if a meter
is available. Report what was observed rather than equating an ACK with motion
or stable power. Switch off and disconnect the battery for leg fitting.

### Worked example: a connection drops during motion

A missed Wi-Fi heartbeat establishes lost communication, not a brownout. A new
boot and its reset reason provide different evidence: an explicit brownout
report supports a controller supply event, while a generic reboot alone does
not identify its cause. Neither identifies the faulty connection by itself.

Hub evidence is separate. A failed register read does not establish that the
hub reset; a successful read showing a changed prescale is a different
observation. Compare the actual circuit's hub logic-power and servo-power paths
before assigning a cause. A lit LED or an accepted command does not establish
that either path remains reliable during motion.

A useful handoff can retain the firmware revision, power source, observed
motion, controller reset evidence and hub result, leaving missing facts unknown.
If a connection is repaired or motion timing changes, distinguish the change
from the observed retest: one successful run does not establish which change
resolved the fault. This is an example of interpreting existing observations,
not an additional test requirement.

## Leg assembly

The position and directions of every joint are in "Joint directions and travel"
above; 90° is the mounting reference. The drawing's upward-drawn vertical foot
lines mean physically **down**. Anatomical names are not hub channel numbers.
Adapt the commands to the student's actual controller and calibration; the
drawing does not mandate a firmware map or sign convention.

At the illustrated 90° mounting pose, disconnect power and fit the upper parts
to the outward hip horns. Capture each foot-servo horn in the upper-part recess;
the servo **body** seats in the printed **foot** and moves with it. Feed its ribbon
through the foot's gap before seating the body. Use the fasteners that fit the
actual parts and keep leads clear of the moving joints.

The standing comparison uses `135 45 45 135 0 180 0 180` in the reference `pose`
order: hips L1/R2 at 45°, R1/L2 at 135°, feet L3/R4 at 0°, L4/R3 at 180°.
It is a different pose from mounting. After assembly, explore motion, gaits and
gestures with the student's controller. Use what the actual linkage and cables
do to refine the design, rather than imposing a mandatory slow-motion sequence.

## Leave a useful handoff

Step 34 now mounts the existing leg assemblies and PCB on the wider printed
internal frame, then fits its matching bottom cover. The guide provides editable
STEP and printable STL downloads. The leg models are unchanged. This is separate
from choosing firmware: help students continue into their own motion ideas.

The foot-print gap opens temporarily for the folded ribbon during insertion and
closes again after it passes. The completed insertion pose is Rest (all 90°); the
next illustration animates from Rest to Standing. In the frame, foot leads enter
the corner slits, join hip leads in the side channels, and rise in four-ribbon
bundles through each midpoint outlet. The battery-wire opening is front-right.

Briefly record the student's chosen firmware/revision, changes made, build or
upload results, and actual observations. State any specific unresolved problem
without turning it into a general prohibition on further development. Continue
from their project and their goals next time.
