This commit is contained in:
James Babcock committed 2026-08-24 00:19:07 -07:00
commit fa241161e4
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);
}