@@ -74,14 +74,6 @@ flowchart LR
7474
7575jniservice is a gRPC server that exposes the JNI surface and Android APIs over the network.
7676
77- ### Development (via adb)
78-
79- ``` bash
80- make deploy # build, push, start, forward port
81- make deploy HOST_PORT=50052 # use different host port
82- make stop-server # stop the server
83- ```
84-
8577### Rooted devices (Magisk module)
8678
8779Auto-starts on boot.
@@ -97,12 +89,28 @@ Configuration (optional): create `/data/adb/modules/jniservice/jniservice.env`:
9789
9890``` bash
9991JNISERVICE_PORT=50051
100- JNISERVICE_LISTEN=0.0.0.0
92+ # Use this device's current Wi-Fi address.
93+ JNISERVICE_LISTEN=192.168.1.20
10194```
10295
96+ In Magisk app-process mode, the launcher passes the selected file path to
97+ ` app_process ` as ` JNISERVICE_CONFIG ` ; it is parsed as ` KEY=VALUE ` data, not
98+ sourced as shell code. For APK mode, the selected durable file is staged as
99+ ` jniservice.env ` at the package-private path described below. Nonempty listener
100+ environment overrides are rebuilt separately in ` jniservice.launch.env ` on
101+ every launch; an empty file clears prior transient overrides without changing
102+ the durable file. The APK resolves defaults, durable file, staged launch file,
103+ then nonempty process environment values. ` app_process ` resolves defaults,
104+ selected file, then its nonempty process environment. Only
105+ ` JNISERVICE_LISTEN ` and ` JNISERVICE_PORT ` are read from these files;
106+ ` JNISERVICE_DATA_DIR ` remains environment-only. The default is
107+ ` 127.0.0.1:50051 ` ; unspecified addresses such as ` 0.0.0.0 ` and ` :: ` are
108+ rejected. Bind to the phone's current Wi-Fi IPv4 address for direct-LAN access.
109+ The listener reads its settings when the app process starts.
110+
103111### Non-rooted devices (APK)
104112
105- Auto-starts on boot via foreground service.
113+ Auto-starts after the first unlock following boot via a foreground service.
106114
107115``` bash
108116make apk DIST_GOARCH=arm64 # build APK
@@ -111,21 +119,71 @@ adb install build/jniservice-arm64-v8a.apk
111119
112120Open "jniservice" from the launcher once to start the service and register the boot receiver.
113121
122+ The APK reads ` jniservice.env ` from
123+ ` /data/data/center.dx.jni.jniservice/files/jniservice/jniservice.env ` . A
124+ registered, already-approved ` jnicli ` identity with permission to use the raw
125+ JNI API can write this private file through the existing authenticated API:
126+ use ` java.io.FileWriter ` for the path above and write the ` KEY=VALUE ` lines.
127+ That operation needs permission for the raw JNI ` FindClass ` , ` NewStringUTF ` ,
128+ ` GetMethodID ` , ` NewObject ` , and ` CallMethod ` RPCs.
129+ The raw JNI calls use the normal mTLS identity and service ACL; ` jniserviceadmin `
130+ continues to manage permissions, and no separate listener-settings RPC is
131+ provided. After editing the file, restart the app process so the native
132+ listener reloads it; restarting only the foreground service in an already
133+ running process does not reload the native library. For example:
134+
135+ ``` bash
136+ adb shell am force-stop center.dx.jni.jniservice
137+ adb shell am start -n center.dx.jni.jniservice/.JNIServiceActivity
138+ ```
139+
140+ A missing optional file leaves the defaults in effect, while a malformed or
141+ unreadable file prevents startup rather than silently binding somewhere else.
142+
143+ The optional [ phone-local fixed-performance startup action] ( docs/fixed-performance-startup.md )
144+ can re-enable fixed-performance mode after unlock and connection to trusted Wi-Fi,
145+ using a dedicated paired wireless-ADB identity. It is disabled until configured.
146+
114147### Connecting
115148
116- On the device itself:
149+ ` jnicli ` keeps client credentials in ` ~/.jnicli ` by default. Use ` --profile NAME `
150+ for separate devices; this loads ` ~/.jnicli/NAME/{client.crt,client.key,ca.crt} ` .
151+ The ` localhost:50051 ` examples below require jniservice to listen on loopback
152+ (the default); if ` JNISERVICE_LISTEN ` is set to the phone's Wi-Fi IPv4 address,
153+ phone-local calls must use that address too.
154+ Phone-local invocation example (run ` jnicli ` on the phone); hosts should use the
155+ phone-IP direct-LAN example below:
117156
118157``` bash
119- jnicli --addr localhost:50051 --insecure jni get-version
158+ jnicli --profile pixel8pro --addr localhost:50051 auth list-permissions
159+ ```
160+
161+ ` auth register --profile NAME --insecure --cn NAME ` writes the three files to
162+ that profile when the output flags are omitted. Explicit ` --cert ` , ` --key ` , and
163+ ` --ca ` paths always override the defaults.
164+
165+ For direct-LAN access, dial the phone's current Wi-Fi address and configured
166+ port while verifying the server certificate for ` jniservice ` :
167+
168+ ``` bash
169+ jnicli --profile pixel8pro --addr 192.168.0.242:50051 \
170+ --authority jniservice camera photo --index 0 --output photo.jpg
120171```
121172
122- From another machine (via adb port forwarding):
173+ Replace the address and port with the values configured on the phone. This
174+ uses the profile's mTLS credentials and keeps TLS certificate verification
175+ enabled; do not add ` --insecure ` .
176+
177+ Phone-local invocation example (run this on the device); hosts should use the
178+ phone-IP direct-LAN example above:
123179
124180``` bash
125- adb forward tcp:50051 tcp:50051
126181jnicli --addr localhost:50051 --insecure jni get-version
127182```
128183
184+ For headless JPEG capture, including AE warm-up, flash, ISO, and exposure
185+ controls, see [ camera photo controls] ( docs/camera-photo.md ) .
186+
129187## E2E Test Verification
130188
131189Run ` make test-emulator ` to test against a connected device or emulator. Tests skip when ` JNICTL_E2E_ADDR ` is not set.
@@ -146,9 +204,6 @@ Run `make test-emulator` to test against a connected device or emulator. Tests s
146204# Build the CLI for Linux
147205make dist-jnicli-linux
148206
149- # Build and deploy to a connected Android device
150- make deploy
151-
152207# Run E2E tests
153208make test-emulator
154209```
0 commit comments