Add a settings import/export receiver

If you install a signed release build and want to switch to an unsigned
debug build, that involves an uninstall and reinstall, which by default
will lose your configuration. Modify scripts/pull_config.sh and
scripts/push_config.sh so it works on release builds, not just debug
builds, and update README.md to tell you to export your config before
doing this kind of upgrade.
This commit is contained in:
James Babcock committed 2026-08-30 12:25:06 -07:00
1 parent f4c43090f5
commit 3e8be93833
7 files changed
+271 -6

No files matched your search

@@ -131,5 +131,14 @@
android:name="com.faceclaw.app.FaceclawTimerReceiver"
android:enabled="true"
android:exported="false" />
<!-- adb-only settings export/import (see FaceclawSettingsPortReceiver).
DUMP is a development permission: the adb shell holds it, other
apps cannot get it granted without adb, so this stays reachable
from the command line but not from apps on the phone. -->
<receiver
android:name="com.faceclaw.app.FaceclawSettingsPortReceiver"
android:enabled="true"
android:exported="true"
android:permission="android.permission.DUMP" />
</application>
</manifest>
@@ -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 <map> 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 <map> 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);
}
}
}
}
+1
View File
@@ -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
+17
View File
@@ -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-<version>.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
<!-- Generated from website/content/features.md by scripts/sync-site.mjs; edit there. -->
+46
View File
@@ -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 <package>
#
# Checks that adb exists, exactly one device is reachable, and <package> 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
}
+27 -2
View File
@@ -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
+30 -4
View File
@@ -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