Troubleshooting

Device not found

1. Use a known USB cable that supports data.
2. Connect directly to the Mac.
3. Unplug and reconnect tinyTouch in normal mode, without holding BOOT.
4. Close Arduino, ESP-IDF monitor, screen, and other serial tools.
5. Look for /dev/cu.usbmodem*:

ls /dev/cu.usbmodem*

To select a device:

tinytouch status --port /dev/cu.usbmodem101

sensor reports offline

Check both 3.3 V connections, ground, and UART direction. Connect sensor TX to RX and sensor RX to TX.

Reconnect the device, then run tinytouch status.

Serial port busy

Close serial monitors and other tinyTouch commands. If the port remains busy, inspect the HID helper:

launchctl print "gui/$UID/com.tinytouch.helper"
tail -n 100 "$HOME/Library/Logs/tinyTouch/helper.err"

Rerun HID setup to repair the LaunchAgent:

tinytouch setup --mode hid --skip-enroll

PIV not found

Reconnect the device, wait several seconds, then inspect the smart card state:

system_profiler SPSmartCardsDataType
sc_auth identities

For an unpaired identity, run tinytouch pair. If no identity appears, run tinytouch keys, reconnect, and retry. For a PIN prompt, enter 111111.

HID doesn't type

Check that the helper is loaded and inspect both logs:

launchctl print "gui/$UID/com.tinytouch.helper"
tail -n 100 "$HOME/Library/Logs/tinyTouch/helper.log"
tail -n 100 "$HOME/Library/Logs/tinyTouch/helper.err"
tinytouch logs

If the logs report a Keychain access error after an upgrade, run:

tinytouch repair

Repair also works while tinyTouch is disconnected. Enter your login Keychain password in the terminal if requested, and approve the macOS Keychain dialogs. Repair preserves saved credentials, verifies unattended access, and reinstalls the current helper. For an older CLI without repair, follow Upgrade an older CLI.

If credentials are missing, run tinytouch setup --mode hid --skip-enroll. If the saved password is wrong, run tinytouch password and enter the correct password twice. For a password assigned to one finger, use tinytouch password --finger NUMBER. These commands preserve pairing and fingerprints.

If HID types the wrong characters, select your intended layout in macOS, run tinytouch keyboard-layout auto, then save the actual password with tinytouch password. Use tinytouch keyboard-layout us only when you need US key positions or an existing manual character mapping.

HID supports passwords up to 160 UTF-8 bytes and 160 typed keys in the active ASCII-capable layout. One accent key followed by a letter or space is supported; characters requiring Option or more than one accent key are unsupported.

Flashing fails

In Chrome or Edge, close other serial tools and retry. For a connection timeout, disconnect USB, hold BOOT while plugging it in, then release BOOT.

Report a problem

Include the board, mode, and this output:

tinytouch --version
sw_vers
tinytouch --verbose status
tinytouch logs