Keycards and Phone Keys

How it works

Use an enrolled NFC card or Android phone at the dashboard reader to unlock and lock the scooter.

• Add any NFC card as a keycard
• No limit on the number of keycards
• Master keycards can teach in new cards without CLI access
• Export and import physical keycard lists for backup
• Android phone keys with NFC host card emulation and signed authentication
• Names for cards and phones stored on the scooter, visible in the app and dashboard

Setting up keycards

Enroll initial cards with the Installer; see Handbook: Getting started. Add more cards with a master card, or use the lsc commands below.

Use an Android phone as a key

The scooter needs a master card or its initial master-card setup before enrolling a phone. On an Android phone with NFC and host card emulation:

1. Open Keycards in the Librescoot app and select Set up / show phone key.
2. Tap the master card on the scooter to enter learning mode.
3. Hold the unlocked phone against the reader.
4. Tap the master card again to save the new key.

For future taps, the phone must be unlocked with its screen on. Duplicate taps are rejected.

Phone keys are bound to the Android device's Keystore. If the app is reinstalled or its key is lost, remove the old phone fingerprint from the scooter and enroll a new key. NFC phone unlock works independently of BLE; the app uses BLE to list and remove enrolled phones.

Managing keycards and phones

Manage physical keycards on lsd's Keycards page, or use lsc:

lsc keycard list               # List all authorized keycards
lsc keycard add <uid>          # Add a keycard
lsc keycard remove <uid>       # Remove a keycard
lsc keycard add-master <uid>   # Add a master keycard
lsc keycard export cards.json  # Export for backup
lsc keycard import cards.json  # Import from backup

The commands above manage and export physical keycards. You can also teach in new keycards directly with a master card at the dashboard, without SSH access: tap the master to start, tap each new card, then tap the master again to save. Duplicate taps during learning mode are rejected.

On a scooter with keycard protocol v2, the app can list and remove enrolled phones and name unlock cards, master cards and phones. Names live on the scooter as display labels; scooter names take precedence over locally stored app names. The dashboard also groups enrolled credentials and shows the last-used physical unlock card. Phone and name management require a scooter and app supporting keycard=2. Removing the last unlock credential requires an explicit force operation rather than an ordinary removal.