Provisioning Guide

Step-by-step guide for setting up a new Telpo T10 kiosk device.

Last updated: April 27, 2026

Overview

Provisioning binds a physical device to a school and a unit (bus or gate). After provisioning, the device is locked into kiosk mode and can only be unlocked by a technician with an NFC unlock card or the fallback PIN.

NFC Tag Hardware

Tag	Storage	Use
NTAG215	504 bytes	Unlock cards (payload fits easily)
NTAG216	888 bytes	Provisioning tags (larger payload with URLs + checksum)
NTAG213	144 bytes	Too small. Do NOT use.

Both NTAG215 and NTAG216 are rewritable (~100,000 write cycles). A single physical tag can be rewritten for different schools or different expiry periods. Buy NTAG216 stickers for provisioning and NTAG215 stickers for unlock cards.

Step 1: Install the Kiosk APK

Option A: NFC Provisioning (Device Owner setup)

Factory reset the Telpo T10
On the Android welcome screen, tap 6 times on the welcome text
Android enters NFC provisioning mode
Tap the provisioning NFC tag (prepared by a technician)
Device downloads and installs the kiosk APK as Device Owner
App launches automatically

Option B: Manual Install (Development/Testing)

ADB

bash

adb install -r familypocket-kiosk.apk
adb shell dpm set-device-owner io.familypocket.kiosk/.admin.KioskDeviceAdmin

Provisioning Tag Payload

The NFC provisioning tag contains a single NDEF record with MIME type application/com.android.managedprovisioning. Key fields:

Tag Properties

text

PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME=io.familypocket.kiosk/.admin.KioskDeviceAdmin
PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION=https://cdn.familypocket.io/provision/apk?token=<TOKEN>
PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM=<base64 SHA-256 of APK signing cert>
PROVISIONING_WIFI_SSID=<school WiFi SSID>
PROVISIONING_WIFI_PASSWORD=<school WiFi password>

WiFi credentials are on the tag so the factory-reset device can connect to download the APK. If your school uses open WiFi or the device has cellular, omit the WiFi fields.

The SIGNATURE_CHECKSUM is critical: Android verifies the downloaded APK against this hash before granting Device Owner. Without it, Android refuses to install.

Step 2: School Resolution

The app shows the Provisioning Screen
Enter the school's short code (e.g., ACAD)
Tap "Resolve School"
The app calls POST /auth/kiosk/resolve-school
On success:
- Tenant info is stored (ID, name, logo, DB connection)
- Service URLs are stored (auth, API, WebSocket)
- Device clock is calibrated against server time
- A device token is issued for future API calls

Step 3: Device Registration

Enter the device code (e.g., BUS-KAA-001)
Tap "Register Device"
The app calls POST /api/kiosk/register-device
On success:
- Device is bound to a unit (bus or gate)
- Active role is set (BUS, GATE, HALL, or TRIPS)
- Device hardware metadata is announced to the backend

Step 4: Kiosk Lock

After provisioning completes:

The app automatically enters Lock Task mode (if Device Owner)
The status bar is hidden
The home button is disabled
The device becomes a single-purpose kiosk

Why Device Owner Is Required

Without Device Owner privileges, kiosk mode is escapable:

Users can exit via Back + Recents buttons
The app cannot suppress the status bar or navigation bar
Silent updates are impossible (requires user confirmation)
The app cannot persist across reboots as the default launcher

Device Owner must be granted during the Android setup wizard (via NFC provisioning or ADB). It cannot be added after the device is already set up. If Device Owner setup fails, factory reset and retry.

Device Owner enables: setLockTaskPackages() (kiosk lock), addPersistentPreferredActivity() (default launcher), and installPackage() (silent updates).

Token Lifecycle

Provisioning tokens have strict lifecycle rules:

Property	Value
Expiry	8 hours from generation
Usage	Single-use (marked used_at on first registration)
Revocation	Technician can revoke unused tokens from Token History screen
Fallback PIN	Generated server-side, shown to technician exactly once, then only stored as BCrypt hash

The fallback PIN is displayed once at token generation time. The technician must record it. It cannot be retrieved from the server after that (only the BCrypt hash is stored).

Device Roles

Code	Role	What it does
bus	BUS	Trip management, NFC student scanning, GPS tracking
gate	GATE	Student check-in/out, staff NFC authentication
hall	HALL	Class teacher roll call, NFC attendance
trips	TRIPS	Trip leader venue roll calls

Unlocking a Provisioned Device

To unlock for maintenance:

Hidden gesture: Long-press bottom-left corner (600ms) + 6 rapid taps (3s window)
NFC unlock card: Tap a signed technician card (ECDSA P-256)
PIN fallback: Enter the 6-digit fallback PIN

Anti-brute-force: 5 failed attempts within 10 minutes triggers a 30-minute lockout.

Generating Provisioning Codes

Device codes are created in the tenant admin dashboard:

Go to td.familypocket.io > Devices
Click "Add Device"
Select the unit (bus or gate)
A code like BUS-KAA-001 is generated
Give this code to the technician doing the provisioning

Troubleshooting

Problem	Solution
"School not found"	Verify the short code in td.familypocket.io
"Device code not found"	Verify the code was generated and hasn't expired (24h)
"Device already registered"	Device was provisioned before. Factory reset or contact admin.
App not locking	Ensure Device Owner is set: adb shell dpm list-owners
NFC not working	Check NFC is enabled in Android Settings (before lock)

Re-provisioning

To re-provision a device (change school or unit):

Unlock the device (NFC card or PIN)
In the app, go to Settings > Reset Provisioning
This clears all stored data
The provisioning screen appears again
Follow Steps 2-3 above