diff --git a/App_Resources/Android/src/main/AndroidManifest.xml b/App_Resources/Android/src/main/AndroidManifest.xml index 98e2715e..efec7b97 100644 --- a/App_Resources/Android/src/main/AndroidManifest.xml +++ b/App_Resources/Android/src/main/AndroidManifest.xml @@ -131,5 +131,14 @@ android:name="com.faceclaw.app.FaceclawTimerReceiver" android:enabled="true" android:exported="false" /> + + diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.java b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.java new file mode 100644 index 00000000..90becbef --- /dev/null +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.java @@ -0,0 +1,141 @@ +package com.faceclaw.app; + +import android.content.BroadcastReceiver; +import android.content.Context; +import android.content.Intent; +import android.os.Handler; +import android.os.Looper; +import android.util.Log; +import android.util.Xml; + +import org.xmlpull.v1.XmlPullParser; + +import java.io.File; +import java.io.FileInputStream; +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; + +/** + * adb-triggered export/import of the faceclaw_settings SharedPreferences + * file, so configuration (API keys, device addresses, ...) can be moved off a + * release build, where run-as is unavailable. See scripts/pull_config.sh and + * scripts/push_config.sh, which use run-as on debuggable builds and fall back + * to this receiver otherwise. + * + * adb shell am broadcast -n com.faceclaw.app/.FaceclawSettingsPortReceiver \ + * -a com.faceclaw.app.SETTINGS_EXPORT + * adb pull /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-export.xml + * + * adb push settings.xml /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-import.xml + * adb shell am broadcast -n com.faceclaw.app/.FaceclawSettingsPortReceiver \ + * -a com.faceclaw.app.SETTINGS_IMPORT + * + * Security: the settings file contains API tokens, so the manifest guards + * this receiver with android.permission.DUMP — a development permission the + * adb shell holds but ordinary apps cannot obtain without adb's help, keeping + * the trigger reachable from adb only. The transfer file lives in + * getExternalFilesDir(), which other apps cannot read on Android 11+ (and + * which the scripts delete as soon as the transfer completes); on the + * Android 7-10 devices minSdk still admits, apps holding READ_EXTERNAL_STORAGE + * could read it during that window. + */ +public class FaceclawSettingsPortReceiver extends BroadcastReceiver { + private static final String TAG = "FaceclawSettingsPort"; + public static final String ACTION_EXPORT = "com.faceclaw.app.SETTINGS_EXPORT"; + public static final String ACTION_IMPORT = "com.faceclaw.app.SETTINGS_IMPORT"; + private static final String PREFS_FILE = "faceclaw_settings.xml"; + private static final String EXPORT_NAME = "faceclaw-settings-export.xml"; + private static final String IMPORT_NAME = "faceclaw-settings-import.xml"; + + @Override + public void onReceive(Context context, Intent intent) { + String action = intent == null ? null : intent.getAction(); + try { + if (ACTION_EXPORT.equals(action)) { + setResultData(exportSettings(context)); + } else if (ACTION_IMPORT.equals(action)) { + setResultData(importSettings(context)); + // Exit once the broadcast result has been delivered: this + // process may hold stale in-memory SharedPreferences that a + // later apply() would flush over the imported file, and the + // next launch must re-read from disk. + new Handler(Looper.getMainLooper()).postDelayed(() -> { + Log.i(TAG, "Exiting after settings import"); + System.exit(0); + }, 500); + } + } catch (Exception e) { + Log.e(TAG, "Settings " + action + " failed", e); + setResultData("error: " + e); + } + } + + private File prefsFile(Context context) { + return new File(context.getApplicationInfo().dataDir, "shared_prefs/" + PREFS_FILE); + } + + private File externalFile(Context context, String name) throws IOException { + File dir = context.getExternalFilesDir(null); + if (dir == null) { + throw new IOException("external files dir unavailable"); + } + return new File(dir, name); + } + + private String exportSettings(Context context) throws IOException { + File prefs = prefsFile(context); + if (!prefs.exists()) { + return "error: no settings file yet (" + prefs + ")"; + } + File out = externalFile(context, EXPORT_NAME); + copy(prefs, out); + return "exported: " + out; + } + + private String importSettings(Context context) throws Exception { + File staged = externalFile(context, IMPORT_NAME); + if (!staged.exists()) { + return "error: nothing staged at " + staged; + } + validatePrefsXml(staged); + File prefs = prefsFile(context); + prefs.getParentFile().mkdirs(); + if (prefs.exists()) { + copy(prefs, new File(prefs.getPath() + ".bak")); + } + copy(staged, prefs); + staged.delete(); + return "imported: " + prefs + " (previous settings in " + PREFS_FILE + ".bak)"; + } + + /** Reject files that are not a SharedPreferences document. */ + private void validatePrefsXml(File file) throws Exception { + try (InputStream in = new FileInputStream(file)) { + XmlPullParser parser = Xml.newPullParser(); + parser.setInput(in, null); + int event = parser.next(); + while (event != XmlPullParser.START_TAG && event != XmlPullParser.END_DOCUMENT) { + event = parser.next(); + } + if (event != XmlPullParser.START_TAG || !"map".equals(parser.getName())) { + throw new IOException("not a SharedPreferences document"); + } + // Walk the rest so malformed XML is caught before it replaces + // the live settings file. + while (parser.next() != XmlPullParser.END_DOCUMENT) { } + } + } + + private void copy(File from, File to) throws IOException { + try (InputStream in = new FileInputStream(from); + OutputStream out = new FileOutputStream(to)) { + byte[] buffer = new byte[8192]; + int n; + while ((n = in.read(buffer)) > 0) { + out.write(buffer, 0, n); + } + } + } +} diff --git a/CHANGELOG b/CHANGELOG index 541b04e0..e0b81293 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,6 +1,7 @@ # Chagelog ## 0.6.1 - Future +* Settings import/export scripts work on release builds ## 0.6 - 2026-08-29 - Start keeping a changelog and making signed binaries via GitHub Releases diff --git a/README.md b/README.md index d83b2e48..75dd4dcd 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,19 @@ User-facing documentation lives at https://faceclaw.org/. ![Assistant settings](website/screenshots/settings-assistant.png) ![Display settings](website/screenshots/settings-display.png) + ## Installation +Download faceclaw-.apk from the GitHub releases section on the phone +that will be paired with the glasses and install it. On first run, the app will +walk you through pairing with the glasses and installing custom firmware. + + +## Compiling + +If you want to customize faceclaw, the best way to do it is to download the +source code and using a coding agent such as Codex or Claude Code. + To compile, you will need an Android SDK environment with SDK version 35 installed and licenses accepted, and the ANDROID_HOME pointing to the install. You will need Nativescript installed, and a JDK environment (v21), with the @@ -34,6 +45,12 @@ phone and tap the "Build number" field seven times. Then plug the phone's USB-C port into your computer, authorize access on the phone, and run `./build_and_run.sh` to install. +Note that if you have installed a signed release build, you will have to +uninstall it before installing a customized version. Use scripts/pull_config.sh +to export a copy of your configuration first, and scripts/push_config.sh to +import it into the new version. + + ## Features diff --git a/scripts/adbutil.sh b/scripts/adbutil.sh new file mode 100644 index 00000000..5295fb4b --- /dev/null +++ b/scripts/adbutil.sh @@ -0,0 +1,46 @@ +# Sourceable adb helper functions shared by the scripts/ utilities. +# Not a standalone script; use: source "$(dirname "$0")/adbutil.sh" + +# adb_preflight +# +# Checks that adb exists, exactly one device is reachable, and is +# installed, then prints the install mode on stdout: +# debug - debuggable build; run-as works +# release - installed but not debuggable; run-as is refused +# Any other condition prints a diagnosis to stderr and returns nonzero (which +# aborts callers running under `set -e`). +adb_preflight() { + local package="$1" + local state + + if ! command -v adb >/dev/null 2>&1; then + echo "Error: adb not found on PATH" >&2 + return 1 + fi + + # get-state fails outright when there is no device or more than one, and + # reports states like "offline" / "unauthorized" for unusable ones. + if ! state="$(adb get-state 2>&1)"; then + echo "Error: no usable adb device ($state)." >&2 + echo " Connected devices:" >&2 + adb devices -l | sed '1d;/^$/d' >&2 + return 1 + fi + if [ "$state" != "device" ]; then + echo "Error: adb device is in state '$state' (offline/unauthorized?)" >&2 + return 1 + fi + + # grep rather than pm's exit code: exit-code propagation over `adb shell` + # needs shell protocol v2, which very old adb binaries lack. + if ! adb shell pm path "$package" 2>/dev/null | grep -q "^package:"; then + echo "Error: $package is not installed on this device" >&2 + return 1 + fi + + if adb shell run-as "$package" true >/dev/null 2>&1; then + echo debug + else + echo release + fi +} diff --git a/scripts/pull_config.sh b/scripts/pull_config.sh index 61e6fdcc..2bba7b0a 100755 --- a/scripts/pull_config.sh +++ b/scripts/pull_config.sh @@ -1,11 +1,36 @@ #!/bin/bash # Pull faceclaw's shared preferences off the attached device. # Usage: pull_config.sh [output-file] (default: faceclaw_settings.xml) +# +# Uses run-as on debuggable (dev) builds. On release builds, where run-as is +# refused, falls back to the FaceclawSettingsPortReceiver broadcast, which +# copies the settings file into the app's external files dir for adb to pull +# (and which only the adb shell can trigger; see the receiver's javadoc). set -euo pipefail +source "$(cd "$(dirname "$0")" && pwd)/adbutil.sh" + PACKAGE=com.faceclaw.app PREFS=shared_prefs/faceclaw_settings.xml OUT="${1:-faceclaw_settings.xml}" +EXPORT_REMOTE=/sdcard/Android/data/$PACKAGE/files/faceclaw-settings-export.xml -adb exec-out run-as "$PACKAGE" cat "$PREFS" > "$OUT" -echo "Pulled $PREFS to $OUT" +MODE="$(adb_preflight "$PACKAGE")" + +if [ "$MODE" = debug ]; then + adb exec-out run-as "$PACKAGE" cat "$PREFS" > "$OUT" + echo "Pulled $PREFS to $OUT" +else + echo "Release build installed; using settings-port broadcast..." + RESULT="$(adb shell am broadcast -n "$PACKAGE/.FaceclawSettingsPortReceiver" \ + -a com.faceclaw.app.SETTINGS_EXPORT)" + if ! printf '%s' "$RESULT" | grep -q 'data="exported:'; then + printf '%s\n' "$RESULT" >&2 + echo "Error: export broadcast did not report success (old app version?)" >&2 + exit 1 + fi + adb pull "$EXPORT_REMOTE" "$OUT" >/dev/null + # The export contains API tokens; don't leave it sitting on shared storage. + adb shell rm "$EXPORT_REMOTE" + echo "Pulled $PREFS to $OUT (via settings-port export)" +fi diff --git a/scripts/push_config.sh b/scripts/push_config.sh index f5bbf526..1ad627ff 100755 --- a/scripts/push_config.sh +++ b/scripts/push_config.sh @@ -3,12 +3,21 @@ # Usage: push_config.sh [input-file] (default: faceclaw_settings.xml) # Validates the XML, force-stops the app (so a running instance doesn't # overwrite the pushed file from its in-memory prefs), then installs it. +# +# Uses run-as on debuggable (dev) builds. On release builds, where run-as is +# refused, falls back to the FaceclawSettingsPortReceiver broadcast: the file +# is staged in the app's external files dir and the receiver (adb-only; see +# its javadoc) validates and installs it, then exits so the next launch +# re-reads settings from disk. set -euo pipefail +source "$(cd "$(dirname "$0")" && pwd)/adbutil.sh" + PACKAGE=com.faceclaw.app PREFS=shared_prefs/faceclaw_settings.xml IN="${1:-faceclaw_settings.xml}" STAGE=/data/local/tmp/faceclaw_settings_push.xml +IMPORT_REMOTE=/sdcard/Android/data/$PACKAGE/files/faceclaw-settings-import.xml if [ ! -f "$IN" ]; then echo "Error: $IN not found" >&2 @@ -24,8 +33,25 @@ else exit 1 fi +MODE="$(adb_preflight "$PACKAGE")" + adb shell am force-stop "$PACKAGE" -adb push "$IN" "$STAGE" -adb shell run-as "$PACKAGE" cp "$STAGE" "$PREFS" -adb shell rm "$STAGE" -echo "Pushed $IN to $PREFS (app was force-stopped; relaunch it to pick up the new settings)" + +if [ "$MODE" = debug ]; then + adb push "$IN" "$STAGE" + adb shell run-as "$PACKAGE" cp "$STAGE" "$PREFS" + adb shell rm "$STAGE" + echo "Pushed $IN to $PREFS (app was force-stopped; relaunch it to pick up the new settings)" +else + echo "Release build installed; using settings-port broadcast..." + adb push "$IN" "$IMPORT_REMOTE" >/dev/null + RESULT="$(adb shell am broadcast -n "$PACKAGE/.FaceclawSettingsPortReceiver" \ + -a com.faceclaw.app.SETTINGS_IMPORT)" + if ! printf '%s' "$RESULT" | grep -q 'data="imported:'; then + printf '%s\n' "$RESULT" >&2 + adb shell rm -f "$IMPORT_REMOTE" + echo "Error: import broadcast did not report success (old app version?)" >&2 + exit 1 + fi + echo "Pushed $IN to $PREFS via settings-port import (previous settings kept as $PREFS.bak)" +fi