JapyScope Remote — Codes Reference

Living document — extend freely as new codes/diagnostics are introduced. Covers every “enter a code” flow on the device plus a maintainer-facing error/status code list for support and troubleshooting.

Key map (physical 3×4 keypad + KY-040 encoder + optional external joystick)

External joystick (optional — docs/WIRING.md)

A KY-023-style dual-axis joystick module, if connected (shared.db’s joystick_enabled), is a second, independent source of the very same events above — see firmware/hal/input/joystick.py and keys.py:

It’s a drop-in alternative to the encoder for navigation, and the more natural way to do the 4-directional jog above (keypad 2/4/6/8 double as digit-entry T9 keys everywhere else; the joystick’s axes never do).

No diagonal jog: a push deflected on both axes at once (e.g. up-and-right) is deliberately treated as no input rather than snapped to one axis — the mount only jogs one cardinal direction (N/S/E/W) at a time. Push the stick cleanly toward one direction (see firmware/hal/input/joystick.py’s _direction_from_axes()).

SmartSearch T9 exception

Everywhere else in the system, “9” always means “back, never an action” — this is a deliberate, load-bearing rule (state machine code in firmware/ui/ relies on it). Inside the SmartSearch/TYPE screen only, this is flipped: “9” is a normal T9 letter key (classic-phone layout — w/x/y/z/9), and FN2 becomes “cancel out of SmartSearch” instead. This was a deliberate v0 decision (16.9) to match old-phone muscle memory, overriding the original mockup’s design. Do not “fix” this back without re-confirming with Ján — it looks inconsistent but is intentional.

Full T9 map (firmware/hal/input/keys.py order, letters per digit):

Dev Tools codes

4-digit code entered via rotate-per-digit (Home → Dev Tools). The real implementation lives in firmware/ui/controller.py (ControllerUI._devtools_code()) — that’s what runs on the device. docs/mockup.html’s handleDevtools() is a browser-only prototype of the same behavior, kept in sync for prototyping/demo purposes, but it is not a substitute for the firmware implementation and a code must not be marked functional in this table until it actually works in firmware/ui/. Add new Dev Tools codes here as they’re introduced, and wire them into both firmware/ui/controller.py and the mockup — don’t scatter magic numbers in firmware/ui/ without a matching entry in this table.

None of the above currently require the sudo password — add the requirement here (and enforce it in firmware/ui/) the day a Dev Tools code becomes genuinely destructive (e.g. a future factory-reset code). 9955 runs arbitrary local .sh files, but only ones the device owner already placed in {homepath}/custom themselves — same trust level as having a shell on the device, not a remote-execution surface.

Sudo password

• Default: 1234 (factory default, stored as a salted PBKDF2 hash in shared.db settings.sudo_password).
• Set via Menu → Sudo Password (same rotary-dial 4-digit entry as Dev Tools codes).
• Intended to guard destructive Dev Tools actions — none of the current codes need it (see table above), since none are destructive yet.
• Not a real security boundary — same spirit as the Web UI access code below: a deterrent, not encryption-grade auth. Don’t build anything safety-critical behind it without upgrading the mechanism first.

Web UI access code

• Dynamic, generated from the controller’s Menu → Wi-Fi / Web Access screen, shown on the e-ink display with a countdown.
• Entered on the Web UI’s login page (/) to gain access.
• 5 wrong attempts → 30s lockout (see mockup login-msg flow, to be ported to webui/app.py).
• Deliberately not high-security — same LAN-only, deterrent-level design as the sudo password.

Maintainer-facing status / error codes (new, beyond the mockup)

These don’t exist in the HTML mockup — added here for docs/TROUBLESHOOTING.md and systemd journal greps once the firmware app has real logging. Extend as new failure modes are found during bring-up.