JakubandClaude Opus 5.5
e822242660
Short pages by feature (getting started, messages, contacts, navigation,
tools, settings, lock, hardware) instead of one page per OLED screen, with
Wio Tracker L2 differences as notes; facts checked against the code
(keyboard scripts vs. hold-for-accents, {batt}/{dist}, L2 limits and
settings layout). Developer guides and build flags under docs/solo/developer.
Old docs/solo_features and its ~50 screenshots removed; a hero banner and
three simulator screenshots added; links updated.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.0 KiB
Hardware
External keyboard and joystick
Two optional add-ons, detected at boot; a build with them enabled works the same with nothing plugged in.
| Device | CardKB | Wired joystick |
|---|---|---|
| Wio Tracker L1 (OLED / e-ink) | Grove connector | built in |
| GAT562 30S Mesh Kit | — | built in |
| Heltec V3 / V4 | soldered (below) | soldered (below) |
| ProMicro | on the main I2C bus (required: it has no buttons) | — |
| Cardputer ADV, T-Echo Lite + KeyShield | built-in keyboard instead | — |
CardKB
An M5Stack CardKB types straight into any text field. It sends plain characters, so the keyboard alphabet settings don't apply to it.
| Key | Does |
|---|---|
| Arrows, Enter, Esc | Same as the joystick, Enter and Back |
| Backspace | Deletes before the cursor |
| Fn+Enter | Submits the field |
| Fn+letter | Accents for that letter (Fn+A → á à ä…) |
| Tab | Hold Enter (options menus) |
| Fn+Esc | Locks / unlocks the screen |
Settings › Keyboard › Ext. KB: Full keeps the on-screen grid, so the CardKB and the joystick can be mixed; Compact hides it, the arrows move the text cursor and Enter submits. Compact needs no joystick at all.
Wired joystick
Four direction contacts and a press contact (Enter), each shorted to ground when pressed; the firmware enables the pull-ups, so no resistors are needed. The board's own button becomes Back. Settings › Display › Joystick rotation turns the directions for a stick mounted sideways.
Wiring on the Heltec V3 / V4
Neither board has a joystick or a keyboard connector, so both are soldered to free pins. V3 and V4 use the same pins (confirmed on a V4).
| Function | GPIO |
|---|---|
| CardKB SDA / SCL | 3 / 4 (second I2C bus, not the display's) |
| Joystick up / down / left / right | 23 / 6 / 47 / 48 |
| Joystick press (Enter) | 33 |
| Back | 0 (the PRG button, nothing to wire) |
The pins are set in solo/heltec_v3/platformio.ini
and solo/heltec_v4/platformio.ini.
For a CardKB-only build, comment out the joystick block there and use
Ext. KB = Compact.
Built-in keyboards
The Cardputer ADV has a QWERTY keyboard, the T-Echo Lite a T9 keypad on its
KeyShield add-on (without it the board has no usable input). Their keymaps
are in each board's driver under variants/; they don't follow the CardKB's
Fn shortcuts.
E-ink
The e-ink Wio Tracker L1 (250 × 122) has a few settings of its own in Settings › Display:
- Rotation: landscape or portrait, applied at once; every screen reflows.
- Joystick rotation, independent of the display's.
- Full refresh: how many partial updates between full ones, against ghosting.
Clock seconds are hidden by default, and live timers refresh coarsely, to spare the panel.
Wio Tracker L2
- Buttons: the top one turns the screen off and on; the side one goes home, and held and let go mutes the sound. Side + top takes a screenshot. Holding the side button in the first seconds after power-on starts the CLI rescue on USB serial.
- SD card: holds the message history, maps, GPX trails and live map tiles. Settings › Storage shows what takes the space, how many messages each conversation keeps, and deletes the history.
- USB drive: plugged into a computer, the device asks whether to only charge or to lend the computer the SD card. While lent, the device can't use the card; eject it on the computer and the device restarts. With a screen PIN set, it doesn't ask until the screen is unlocked.
- WiFi: used only for map downloads, live tiles and updates, and off the rest of the time. Settings › WiFi saves several networks and joins the strongest; the WiFi switch in Settings forbids it entirely.
Build flags
Extra hardware (a buzzer, a vibration motor, a Hall sensor for a magnetic
cover, GPIO, an external PA) is enabled with build flags in your own
solo/<board>/platformio.ini; see Build flags.