- Kotlin 100%
batsignal #
A Bluetooth+ATproto presence signaller
batsignal is an Android app that advertises an AT Protocol
identity — a handle, at:// URI, or did:plc: / did:web: DID — over
Bluetooth LE beacons, so nearby devices can discover who you are without any
network in the middle.
Current scope (phase 1): a single screen where you type the identity to
broadcast, and Start/Stop controls that drive a foreground service
(BeaconService).
The service owns a real BLE advertiser
(ble/BeaconAdvertiser.kt)
that runs two advertising sets — the extended identity frame and a legacy
companion marker — per the
wire format. The notification
and the on-screen status reflect the actual advertise state (advertising /
marker-only / failed with reason), including degradation and
Bluetooth-off/resume handling. Sign-in and resolution of handles to DIDs come
later; on-hardware verification (e.g. nRF Connect with extended scanning
enabled) is still to do.
The manifest plumbing is already banked: runtime requests for
POST_NOTIFICATIONS (Android 13+) and BLUETOOTH_ADVERTISE (Android 12+) are
asked before the service starts, and the service is declared with the
connectedDevice foreground-service type (the correct type for BLE
advertising — there is no bluetooth FGS type) paired with
FOREGROUND_SERVICE_CONNECTED_DEVICE.
Dev setup #
Toolchain is pinned with mise — JDK (Temurin 21 LTS) and Gradle 8.14.5:
mise install
The Android SDK is system-installed (Debian layout) at
/usr/lib/android-sdk — build-tools 36.0.0, platform android-36 — and wired
up via git-ignored local.properties. If it's missing:
echo "sdk.dir=/usr/lib/android-sdk" > local.properties
Build:
mise exec -- ./gradlew assembleDebug
Prefer mise exec -- over a bare ./gradlew unless your environment already
resolves java to the pinned JDK: the wrapper picks up whatever java is
first on PATH, and a too-new JDK (e.g. 26) breaks AGP 8.13 with a cryptic
version-number-only error.
Install on device #
adb install app/build/outputs/apk/debug/app-debug.apk
Verifying on hardware #
Use a second device with nRF Connect:
- The legacy companion shows up in any scanner: flags + service data under
4040e298-8e40-40e2-988e-4040e2988e40containingbatsignal+0x01. Quick "is it on" check. - The extended identity frame (service data = marker + the identity string as UTF-8) only appears with extended scanning enabled — enable it in nRF Connect's scanner settings. Standard/legacy scanners cannot see non-legacy frames at all.
- Scanning from another Android app requires
ScanSettings.setLegacy(false); see the receiver notes indesign/beacon-format/beacon-format.glm53.md.
Docs #
doc/abl/research.md— AltBeacon library evaluation; verdict is rawAdvertisingSetin an app-owned foreground service.design/beacon-format/beacon-format.glm53.md— the beacon wire format: marker UUID, extended + legacy companion frames, parameters.