payfrit-beacon-ios/CLAUDE.md

Payfrit Beacon iOS

Native Swift iOS app for provisioning iBeacon hardware at restaurant tables. Repo: payfrit-beacon-ios on Forgejo.

Purpose

Utility app for restaurant setup staff to:

1. Scan for nearby BLE iBeacons
2. Check UUID against known bulk manufacturer defaults (ban list)
3. Assign table names to beacons (smart-incremented)
4. Save beacon + auto-create service point records via API

Environment

• Server: dev.payfrit.com (always dev — this is a setup tool)
• API Base: https://dev.payfrit.com/api
• IS_DEV: Driven by DEV compiler flag (orange DEV banner on all screens)
• OTP: Dev server uses magic OTP (no Twilio)

Database (dev schema — migrated Jan 2026)

Connected via API, not direct SQL. Dev DB uses clean, unprefixed names. PKs are always ID. FKs reference their parent table.

Table	PK	Key Columns
Beacons	ID	UUID, Name, BusinessID, IsActive
ServicePoints	ID	BusinessID, Name, TypeID, Code, SortOrder, IsActive, BeaconID
Businesses	ID	Name, ParentBusinessID

Note: POST /api/beacons/save.php auto-creates a ServicePoint when saving a beacon.

API Endpoints Used

Method	Endpoint	Auth	Purpose
POST	/auth/loginOTP.php	No	Send OTP to phone
POST	/auth/verifyLoginOTP.php	No	Verify OTP, get token
POST	/businesses/list.php	Yes	List user's businesses
POST	/businesses/get.php	Yes	Get single business
POST	/servicepoints/list.php	Yes	List service points for business
POST	/servicepoints/save.php	Yes	Create/update service point
POST	/beacon-sharding/allocate_business_namespace.php	Yes	Allocate UUID+Major shard
POST	/beacon-sharding/get_beacon_config.php	Yes	Get complete beacon config
POST	/beacon-sharding/register_beacon_hardware.php	Yes	Register provisioned device
POST	/beacon-sharding/verify_beacon_broadcast.php	Yes	Verify beacon is broadcasting
POST	/beacon-sharding/resolve_business.php	Yes	Resolve business by UUID+Major
POST	/beacon-sharding/allocate_servicepoint_minor.php	Yes	Auto-assign minor value
GET	/beacons/list_all.php	No	All active beacons (UUID→ID map)
POST	/beacons/lookup.php	No	Lookup beacon assignments by UUID
POST	/beacons/lookupByMac.php	No	Lookup beacon by MAC address
POST	/beacons/list.php	Yes	List beacons for a business
POST	/beacons/save.php	Yes	Create/update beacon + auto-create service point
POST	/beacons/wipe.php	Yes	Wipe/deactivate a beacon

Build & Deploy

Build in Xcode targeting iOS 17+. No local testing — deploy to device for BLE testing.

Project Structure

PayfritBeacon/
├── Api.swift                   REST client, all API calls, auth token mgmt
├── BeaconBanList.swift         Known bad UUID prefixes (factory defaults)
├── BeaconProvisioner.swift     DX-Smart CP28 GATT provisioner (24-step write sequence)
├── BeaconScanner.swift         iBeacon CLLocationManager scanner
├── BeaconShardPool.swift       64 Payfrit shard UUIDs (matches Android + migration.sql)
├── BLEBeaconScanner.swift      CoreBluetooth BLE scanner + BeaconType enum
├── BusinessListView.swift      Business selection screen
├── DebugLog.swift              Shared logging singleton
├── DevBanner.swift             Orange "DEV" banner overlay
├── LoginView.swift             OTP login screen
├── PayfritBeaconApp.swift      App entry point
├── RootView.swift              Root navigation
├── ScanView.swift              Main provisioning hub
├── ServicePointListView.swift  Service point list + beacon assignment
└── UUIDFormatting.swift        UUID string formatting extensions

DX-Smart CP28 Provisioning Protocol

BLE Service & Characteristics

• Service: 0000FFE0-0000-1000-8000-00805F9B34FB
• FFE1 (Notify): Response notifications (RX)
• FFE2 (Write): Command TX
• FFE3 (Write): Password authentication

Packet Format

[4E][4F][CMD][LEN][DATA...][XOR_CHECKSUM]

Header: 4E 4F (fixed). Checksum: XOR of CMD ⊕ LEN ⊕ DATA bytes.

Command Codes

Code	Purpose
0x11-0x16	Select frame 1-6
0x60	Save config to flash
0x61	Set frame as device info
0x62	Set frame as iBeacon
0x71	Write device name (max 20 ASCII)
0x74	Write UUID (16 bytes BE)
0x75	Write Major (2 bytes BE)
0x76	Write Minor (2 bytes BE)
0x77	Write RSSI@1m (1 byte signed)
0x78	Write adv interval (1 byte, x100ms)
0x79	Write TX power (1 byte, 0-7 index)
0xA0	Trigger off
0xFF	Disable frame (no data)

24-Step Write Sequence

1. DeviceName (0x71) → Frame1 select (0x11) → Frame1 type (0x61) → Frame1 RSSI/AdvInt/TxPow
2. Frame2 select (0x12) → Frame2 iBeacon (0x62) → UUID/Major/Minor/RSSI/AdvInt/TxPow
3. TriggerOff (0xA0)
4. Disable frames 3-6 (select 0x13-0x16 + 0xFF for each)
5. SaveConfig (0x60)

Authentication

Passwords tried in order: 555555, dx1234, 000000. Written to FFE3 with .withResponse.

Ban List UUIDs

Hardcoded in BeaconBanList.swift. Known factory-default prefixes:

• E2C56DB5 — Apple AirLocate sample
• B9407F30 — Estimote default
• FDA50693 — Generic Chinese bulk default
• F7826DA6 — Kontakt.io default
• 74278BDA — Generic bulk default
• 00000000 / FFFFFFFF — Unconfigured hardware

Dependencies

• SwiftUI + Combine
• CoreBluetooth (BLE GATT operations)
• CoreLocation (CLBeaconRegion for iBeacon ranging)
• Security (Keychain for auth token storage)

App Flow

1. Login → OTP (Keychain-saved token for re-auth)
2. Select Business → Auto-select if one, list if multiple
3. Select Service Point → Table assignment target
4. Scan → BLE scan → show results with status badges
5. Provision → Connect → Auth → Write 24-step config → Save
6. Register → API call to register hardware
7. Repeat or Done