librescoot-keycard (keycard-service)¶

Description¶

Handles NFC-based authentication for the scooter. Detects keycards via the PN7150 controller, checks UIDs against authorized and master lists, controls LED feedback, and publishes authentication events to Redis. Supports master learning mode on first boot, learn mode for replacing the authorized card set, and a Redis command interface for UID management.

Command-Line Options¶

  --device string       NFC device path (default: /dev/pn5xx_i2c2)
  --data-dir string     Directory for UID storage (default: /data/keycard)
  --redis string        Redis server address (default: localhost:6379)
  --log int             Log level 0-3 (0=error, 3=debug) (default: 2)
  --led-device string   I2C device for LP5562 LED (empty = script-based control)
  --led-address string  I2C address for LP5562 LED (default: 0x30)
  --debug               Enable debug logging

Redis Operations¶

Hash: keycard (written)¶

Fields written on authentication:

• authentication - passed when authorized UID detected
• type - scooter
• uid - UID of the card that authenticated (expires after 10 seconds)

Fields written on command response:

• command-result - Result of last management command (e.g. ok, count:3, card:<uid>, error:<reason>)

Published channel: keycard

• authentication - Published when authorized keycard detected

List: scooter:keycard (consumed)¶

Management commands via LPUSH:

Responses are written to keycard command-result.

Channel: keycard:events (published)¶

Transient per-tap progress events during teach-in flows, for real-time subscribers (installer, BLE bridge). Format <event> or <event>:<uid>:

• Master teach-in: mode-entered:master, mode-exited:master, master-learned:<uid>, rejected:already-authorized:<uid>, error:save-failed:<uid>
• Learn mode: card-learned:<uid> (queued for commit on learn:stop), card-duplicate:<uid>
• Reset: reset

Hardware¶

NFC Reader¶

• Chip: PN7150, I2C interface at /dev/pn5xx_i2c2
• Library: github.com/librescoot/pn7150
• UID format: uppercase hex string (e.g. 04A1B2C3D4E5F6)

LED Controllers¶

I2C LED (LP5562 tri-color):

• I2C bus 2, address 0x30
• Enabled with --led-device /dev/i2c-2
• Green: authorized card; Red: unauthorized; Amber: lookup in progress; Blinking: master learning mode

PWM LEDs (learn mode):

• /dev/pwm_led3, /dev/pwm_led7 — on during learn mode
• Controlled via /usr/bin/ledcontrol.sh

Script-based fallback (when --led-device not set):

• /usr/bin/greenled.sh — color/on/off
• /usr/bin/ledcontrol.sh — PWM pattern control

Operational Modes¶

Master Learning Mode (first boot)¶

Activated when master_uids.txt does not exist:

1. RGB LED blinks (500ms) — waiting for master card
2. First card presented becomes master UID, saved to master_uids.txt
3. Authorized list cleared; RGB LED flashes once to confirm
4. Switches to normal operation

Normal Operation¶

Learn Mode¶

Activated by presenting master UID or via learn:start:

1. PWM LEDs 3 + 7 turn on
2. Each new card presented: added to session queue, Green LED flash
3. Present master UID again or learn:stop to exit
4. Learned cards are appended to the authorized list in authorized_uids.txt (additive)
5. If no cards learned: existing list unchanged
6. PWM LEDs 3 + 7 turn off

File Locations¶

Files are written atomically (write to .tmp, sync, rename).

Systemd Unit¶

• Unit: librescoot-keycard.service
• Binary: /usr/bin/keycard-service
• Requires: valkey.service (redis.service before Librescoot 1.2)
• After: valkey.service, librescoot-vehicle.service

Building¶

make build        # ARM
make build-local  # Host

Related Documentation¶

• Electronic Components — PN7150 and LP5562 hardware
• Redis Operations — Keycard hash details
• Librescoot Services