Add proximity-based pairing for Even devices

Stream BLE advertisements into a dedicated pairing flow with arm, ring, serial, and hardware variant detection.

Add proximity ranking, device artwork, pairing safeguards, and unit coverage for discovery and candidate grouping.
This commit is contained in:
Kalani Helekunihi committed 2026-08-22 21:50:17 -05:00
1 parent 35e6977c6c
commit aaaa7288ee
35 files changed
+3309 -140

No files matched your search

@@ -6,151 +6,392 @@ import android.bluetooth.BluetoothDevice;
import android.bluetooth.BluetoothManager;
import android.bluetooth.le.BluetoothLeScanner;
import android.bluetooth.le.ScanCallback;
import android.bluetooth.le.ScanRecord;
import android.bluetooth.le.ScanResult;
import android.bluetooth.le.ScanSettings;
import android.content.Context;
import android.os.Build;
import android.os.Handler;
import android.os.Looper;
import android.util.SparseArray;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
import java.util.regex.Pattern;
/**
* Finds Even Realities hardware over BLE and hands every advertisement up to
* TypeScript with the raw fields the pairing screen needs: the LIVE local name
* from the scan record (BluetoothDevice.getName() is a cache that can hold a
* pre-reset value indefinitely), the full manufacturer-specific payload with
* its company identifier restored so the "ER"+serial+MAC layout survives
* intact, RSSI, advertised TX power, and connectability.
*
* Admission is deliberately loose — a name containing G2 or R1, or the Even
* "ER" manufacturer signature — because renamed custom firmware may drop the
* stock name. Side, serial, and pair matching are decided in TypeScript
* (app/g2/even-advertisement.ts, app/g2/pairing-candidates.ts) where they can
* be unit-tested.
*
* Ported from the discovery path of SybilSight's Bluetooth SDK (G2.didDiscover
* and R1's advertisement snapshot), reduced to what Android exposes.
*/
@SuppressLint("MissingPermission")
public class FaceclawDeviceDiscovery {
private static final Pattern RING_NAME = Pattern.compile("^EVEN R1_[0-9A-F]{6}$");
private static final Pattern RIGHT_NAME = Pattern.compile("^Even G2_32_R_[0-9A-F]{6}$");
private static final Pattern LEFT_NAME = Pattern.compile("^Even G2_32_L_[0-9A-F]{6}$");
/** Even Realities' company identifier: the ASCII bytes "ER" read little-endian. */
public static final int EVEN_COMPANY_ID = 0x5245;
private final Context appContext;
private final BluetoothAdapter bluetoothAdapter;
private final Handler mainHandler = new Handler(Looper.getMainLooper());
private final Object lock = new Object();
private ScanCallback activeCallback;
private volatile FaceclawDeviceDiscoveryListener listener;
public FaceclawDeviceDiscovery(Context context) {
this.appContext = context.getApplicationContext();
Context appContext = context.getApplicationContext();
BluetoothManager bluetoothManager =
(BluetoothManager) this.appContext.getSystemService(Context.BLUETOOTH_SERVICE);
(BluetoothManager) appContext.getSystemService(Context.BLUETOOTH_SERVICE);
if (bluetoothManager == null || bluetoothManager.getAdapter() == null) {
throw new IllegalStateException("Bluetooth adapter unavailable");
}
this.bluetoothAdapter = bluetoothManager.getAdapter();
}
public String getBondedCandidatesJson() {
LinkedHashMap<String, CandidateDevice> matches = new LinkedHashMap<>();
Set<BluetoothDevice> bonded = bluetoothAdapter.getBondedDevices();
if (bonded != null) {
for (BluetoothDevice device : bonded) {
maybeAddCandidate(matches, device, "paired");
}
}
return encodeCandidates(matches);
public boolean isBluetoothEnabled() {
return bluetoothAdapter.isEnabled();
}
public String scanCandidatesJson(int timeoutMs) throws InterruptedException {
LinkedHashMap<String, CandidateDevice> matches = new LinkedHashMap<>();
BluetoothLeScanner scanner = bluetoothAdapter.getBluetoothLeScanner();
if (scanner == null) {
return encodeCandidates(matches);
}
final ScanCallback callback = new ScanCallback() {
@Override
public void onScanResult(int callbackType, ScanResult result) {
if (result == null) {
return;
}
maybeAddCandidate(matches, result.getDevice(), "scan");
}
public void setListener(FaceclawDeviceDiscoveryListener newListener) {
this.listener = newListener;
}
@Override
public void onBatchScanResults(java.util.List<ScanResult> results) {
if (results == null) {
return;
}
for (ScanResult result : results) {
// ------------------------------------------------------------------
// Live scan
// ------------------------------------------------------------------
/**
* Start streaming advertisements to the listener. Returns false when the
* radio is off or the scanner is unavailable; a later platform refusal
* arrives through onScanFailed. Calling while a scan is running is a no-op.
*/
public boolean startScan() {
synchronized (lock) {
if (activeCallback != null) {
return true;
}
if (!bluetoothAdapter.isEnabled()) {
emitLog("scan not started: Bluetooth is off");
return false;
}
BluetoothLeScanner scanner = bluetoothAdapter.getBluetoothLeScanner();
if (scanner == null) {
emitLog("scan not started: no BLE scanner");
return false;
}
final ScanCallback callback = new ScanCallback() {
@Override
public void onScanResult(int callbackType, ScanResult result) {
if (result != null) {
maybeAddCandidate(matches, result.getDevice(), "scan");
emitAdvertisement(result);
}
}
@Override
public void onBatchScanResults(List<ScanResult> results) {
if (results == null) {
return;
}
for (ScanResult result : results) {
if (result != null) {
emitAdvertisement(result);
}
}
}
@Override
public void onScanFailed(int errorCode) {
synchronized (lock) {
if (activeCallback == this) {
activeCallback = null;
}
}
final FaceclawDeviceDiscoveryListener l = listener;
if (l != null) {
final String message = describeScanError(errorCode);
mainHandler.post(() -> l.onScanFailed(errorCode, message));
}
}
};
activeCallback = callback;
try {
scanner.startScan(null, buildScanSettings(), callback);
} catch (Throwable t) {
activeCallback = null;
emitLog("scan not started: " + t);
return false;
}
};
scanner.startScan(
null,
new ScanSettings.Builder().setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY).build(),
callback
);
try {
Thread.sleep(Math.max(500, timeoutMs));
} finally {
emitLog("scan started (unfiltered, low latency)");
return true;
}
}
public void stopScan() {
ScanCallback callback;
synchronized (lock) {
callback = activeCallback;
activeCallback = null;
}
if (callback == null) {
return;
}
BluetoothLeScanner scanner = bluetoothAdapter.getBluetoothLeScanner();
if (scanner != null) {
try {
scanner.stopScan(callback);
} catch (Throwable ignored) {
}
}
return encodeCandidates(matches);
emitLog("scan stopped");
}
private void maybeAddCandidate(Map<String, CandidateDevice> matches, BluetoothDevice device, String source) {
if (device == null) {
return;
public boolean isScanning() {
synchronized (lock) {
return activeCallback != null;
}
String name = device.getName();
String role = classifyRole(name);
if (role == null) {
return;
}
String address = device.getAddress();
if (address == null || address.isEmpty()) {
return;
}
matches.put(address, new CandidateDevice(address, name == null ? "" : name, role, source));
}
private String classifyRole(String name) {
if (name == null) {
return null;
/**
* Replay bonded Even devices to the listener. A bonded listing has no
* signal sample and no manufacturer data, so its serial stays unknown until
* the device is also heard advertising.
*/
public void emitBondedDevices() {
final FaceclawDeviceDiscoveryListener l = listener;
if (l == null) {
return;
}
if (RIGHT_NAME.matcher(name).matches()) {
return "right";
for (String json : bondedCandidateJsonList()) {
l.onAdvertisement(json);
}
if (LEFT_NAME.matcher(name).matches()) {
return "left";
}
if (RING_NAME.matcher(name).matches()) {
return "ring";
}
return null;
}
private String encodeCandidates(Map<String, CandidateDevice> matches) {
/** Bonded Even devices as one JSON array, for callers without a listener. */
public String getBondedCandidatesJson() {
JSONArray array = new JSONArray();
for (CandidateDevice candidate : matches.values()) {
JSONObject object = new JSONObject();
for (String json : bondedCandidateJsonList()) {
try {
object.put("address", candidate.address);
object.put("name", candidate.name);
object.put("role", candidate.role);
object.put("source", candidate.source);
array.put(object);
array.put(new JSONObject(json));
} catch (JSONException ignored) {
}
}
return array.toString();
}
private static final class CandidateDevice {
final String address;
final String name;
final String role;
final String source;
// ------------------------------------------------------------------
// Internals
// ------------------------------------------------------------------
CandidateDevice(String address, String name, String role, String source) {
this.address = address;
this.name = name;
this.role = role;
this.source = source;
private static ScanSettings buildScanSettings() {
ScanSettings.Builder builder = new ScanSettings.Builder()
.setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
.setReportDelay(0);
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
builder.setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES);
builder.setMatchMode(ScanSettings.MATCH_MODE_AGGRESSIVE);
builder.setNumOfMatches(ScanSettings.MATCH_NUM_MAX_ADVERTISEMENT);
}
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
// Accept extended advertising too; setLegacy(true) would hide it.
builder.setLegacy(false);
}
return builder.build();
}
private void emitAdvertisement(ScanResult result) {
final JSONObject object = toJson(result);
if (object == null) {
return;
}
final FaceclawDeviceDiscoveryListener l = listener;
if (l == null) {
return;
}
final String json = object.toString();
if (Looper.myLooper() == Looper.getMainLooper()) {
l.onAdvertisement(json);
} else {
mainHandler.post(() -> {
FaceclawDeviceDiscoveryListener current = listener;
if (current != null) {
current.onAdvertisement(json);
}
});
}
}
private List<String> bondedCandidateJsonList() {
List<String> out = new ArrayList<>();
Set<BluetoothDevice> bonded = bluetoothAdapter.getBondedDevices();
if (bonded == null) {
return out;
}
long now = System.currentTimeMillis();
for (BluetoothDevice device : bonded) {
if (device == null) {
continue;
}
String name = device.getName();
if (!isAdmissible(name, null)) {
continue;
}
JSONObject object = buildJson(
device.getAddress(), name, "", null, null, null, true, "paired", now);
if (object != null) {
out.add(object.toString());
}
}
return out;
}
/** Null when the result is not something we pair with. */
private static JSONObject toJson(ScanResult result) {
BluetoothDevice device = result.getDevice();
if (device == null) {
return null;
}
ScanRecord record = result.getScanRecord();
String liveName = record == null ? null : record.getDeviceName();
String name = liveName != null && !liveName.isEmpty() ? liveName : device.getName();
byte[] manufacturerData = extractEvenManufacturerData(record);
if (!isAdmissible(name, manufacturerData)) {
return null;
}
Integer txPower = null;
if (record != null && record.getTxPowerLevel() != Integer.MIN_VALUE) {
txPower = record.getTxPowerLevel();
}
if (txPower == null && Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
&& result.getTxPower() != ScanResult.TX_POWER_NOT_PRESENT) {
txPower = result.getTxPower();
}
Boolean connectable = null;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
connectable = result.isConnectable();
}
int rssi = result.getRssi();
// 127 is the "unavailable" sentinel; 0 dBm never happens for a real sample.
Integer rssiValue = (rssi == 127 || rssi == 0) ? null : rssi;
boolean bonded = device.getBondState() == BluetoothDevice.BOND_BONDED;
return buildJson(
device.getAddress(), name, toHex(manufacturerData), rssiValue, txPower,
connectable, bonded, "scan", System.currentTimeMillis());
}
/**
* Android strips the 2-byte company identifier from each manufacturer
* record and keys the SparseArray by it. Put the bytes back (little-endian)
* so TypeScript sees the same "ER"+… layout the iOS SDK and HCI captures
* document. Prefers Even's own id; otherwise returns the first record so an
* unexpected company id still reaches the diagnostics log.
*/
private static byte[] extractEvenManufacturerData(ScanRecord record) {
if (record == null) {
return new byte[0];
}
SparseArray<byte[]> all = record.getManufacturerSpecificData();
if (all == null || all.size() == 0) {
return new byte[0];
}
byte[] payload = all.get(EVEN_COMPANY_ID);
int companyId = EVEN_COMPANY_ID;
if (payload == null) {
companyId = all.keyAt(0);
payload = all.valueAt(0);
}
if (payload == null) {
return new byte[0];
}
byte[] out = new byte[payload.length + 2];
out[0] = (byte) (companyId & 0xff);
out[1] = (byte) ((companyId >> 8) & 0xff);
System.arraycopy(payload, 0, out, 2, payload.length);
return out;
}
private static boolean isAdmissible(String name, byte[] manufacturerData) {
if (manufacturerData != null && manufacturerData.length >= 2
&& manufacturerData[0] == 0x45 && manufacturerData[1] == 0x52) {
return true;
}
if (name == null) {
return false;
}
String upper = name.toUpperCase();
return upper.contains("G2") || upper.contains("R1");
}
private static JSONObject buildJson(
String address, String name, String manufacturerHex, Integer rssi, Integer txPower,
Boolean connectable, boolean bonded, String source, long seenAtMs) {
if (address == null || address.isEmpty()) {
return null;
}
try {
JSONObject object = new JSONObject();
object.put("address", address);
object.put("name", name == null ? "" : name);
object.put("manufacturerData", manufacturerHex == null ? "" : manufacturerHex);
object.put("rssi", rssi == null ? JSONObject.NULL : rssi);
object.put("txPower", txPower == null ? JSONObject.NULL : txPower);
object.put("connectable", connectable == null ? JSONObject.NULL : connectable);
object.put("bonded", bonded);
object.put("source", source);
object.put("seenAtMs", seenAtMs);
return object;
} catch (JSONException e) {
return null;
}
}
private static String toHex(byte[] bytes) {
if (bytes == null || bytes.length == 0) {
return "";
}
StringBuilder sb = new StringBuilder(bytes.length * 2);
for (byte b : bytes) {
sb.append(String.format("%02X", b & 0xff));
}
return sb.toString();
}
private static String describeScanError(int errorCode) {
switch (errorCode) {
case ScanCallback.SCAN_FAILED_ALREADY_STARTED:
return "a scan is already running";
case ScanCallback.SCAN_FAILED_APPLICATION_REGISTRATION_FAILED:
return "the Bluetooth stack refused to register the scan (try toggling Bluetooth)";
case ScanCallback.SCAN_FAILED_FEATURE_UNSUPPORTED:
return "BLE scanning is not supported on this device";
case ScanCallback.SCAN_FAILED_INTERNAL_ERROR:
return "internal Bluetooth error";
case 5: // SCAN_FAILED_OUT_OF_HARDWARE_RESOURCES (API 31)
return "out of Bluetooth hardware resources";
case 6: // SCAN_FAILED_SCANNING_TOO_FREQUENTLY (API 31)
return "scanning too frequently; wait a moment and try again";
default:
return "scan failed (code " + errorCode + ")";
}
}
private void emitLog(String line) {
FaceclawDeviceDiscoveryListener l = listener;
if (l != null) {
l.onLog(line);
}
}
}
@@ -0,0 +1,18 @@
package com.faceclaw.app;
/** Callbacks from FaceclawDeviceDiscovery's live scan to the TypeScript layer. */
public interface FaceclawDeviceDiscoveryListener {
/**
* One advertisement (or one bonded device) as a JSON object:
* {address, name, manufacturerData (hex, company id included), rssi|null,
* txPower|null, connectable|null, bonded, source, seenAtMs}.
* Protocol decoding happens in TypeScript (see app/g2/even-advertisement.ts).
*/
void onAdvertisement(String json);
/** The platform refused to start or continue the scan. */
void onScanFailed(int errorCode, String message);
/** Diagnostic line for the pairing log. */
void onLog(String line);
}