# Cardboy Time Sync Companion

This SwiftUI app connects to the Cardboy device over Bluetooth Low Energy and updates its wall clock using the custom time sync service exposed by the firmware. The sources live inside the existing `cardboy-companion/cardboy-companion.xcodeproj` so you can open and run them directly in Xcode.

## Requirements

- Xcode 15 or newer
- iOS 16 or newer deployment target (can be lowered to 15 with minor API tweaks)
- A Cardboy running firmware that includes the BLE time sync service

## How it works

1. The app scans for peripherals exposing service UUID `00000001-CA7B-4EFD-B5A6-10C3F4D3F230`.
2. Once connected it discovers characteristic `00000002-CA7B-4EFD-B5A6-10C3F4D3F231`.
3. Tapping **Sync Now** writes a 12‑byte payload containing:
   - 8 bytes Unix epoch seconds (little endian)
   - 2 bytes time zone offset in minutes from UTC (little endian)
   - 1 byte DST flag (`1` if daylight saving is active)
   - 1 reserved byte (`0`)
4. The firmware applies the timestamp with `settimeofday()` and updates the TZ environment variable so the clock app renders local time.

## Usage

1. Open `cardboy-companion/cardboy-companion.xcodeproj` in Xcode.
2. Enable the `CoreBluetooth` capability for the `cardboy-companion` target (Signing & Capabilities tab).
3. Build & run on a real device (BLE is not available in the simulator).
4. Allow Bluetooth permissions when prompted, then tap **Sync Now**.

Optionally bundle this code into your existing app—`TimeSyncManager` is self‑contained and can be reused.