Keycards and Phone Keys

How it works

Librescoot uses NFC credentials to unlock and lock the scooter. Hold a compatible card to the reader on the dashboard to unlock. Physical cards are authorized by their stable UID; an enrolled Android phone authenticates with a signed challenge.

Librescoot supports:

• 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

On a fresh installation with the recommended Installer, you teach in your cards before leaving the Installer – see Handbook: Getting started. On the scooter itself, a master card can teach in additional user cards without any tools. The lsc commands below are the fallback for setups without a master card or the Installer.

Use an Android phone as a key

On an Android phone with NFC and host card emulation, open the Librescoot app's Keycards screen and select Set up / show phone key. Then tap an existing master card on the scooter to enter learning mode, hold the unlocked phone against the reader, and tap the master card again to save the new key. The phone screen must be on and the phone unlocked for future taps. Duplicate taps are rejected. The scooter needs a master card (or its initial master-card setup) before a phone can be enrolled.

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

Use the lsc CLI to manage your keycards:

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

These lsc commands manage and export physical-card UIDs. You can teach in new unlock cards with a master card at the dashboard: 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.