# Device message, status and reboot execution

This chapter records the operation implementation introduced in UIC Home 3.2.0-dev. The same durable behavior remains in UIC Home 3.9.14-dev, and xTMSAgent now supplies the equivalent message/status/reboot capabilities for A10-T where described in chapter 33. NEWPOS and NEXGO builds share the handler; reboot calls remain brand-specific.

## Behavior and completion

| Operation | Device behavior | Success evidence |
| --- | --- | --- |
| Send message | Shows a plain-text dialog when UIC Home is visible, up to 500 characters; English/Spanish title and close button | `message_displayed` after the dialog is shown; this does not prove the user read it |
| Request status | Captures a fresh report and retries its identical envelope until a SQL receipt arrives | `status_stored` plus telemetry message ID; server checks this device/assignment and a report committed after command creation |
| Reboot | Persists the current Android boot counter before invoking NEWPOS `SystemManager.reboot()` or NEXGO `platform.rebootDevice()` | `reboot_verified` plus increasing before/after boot counters, after reconnection |

Message/status requests have a 60-second window. Reboot uses five minutes to allow startup and reconnection. The server still requires an online MQTT connection lease and the advertised capability when accepting a new operation. Reboot also requires explicit portal confirmation; its capability is advertised only after SDK initialization.

## Durable execution

Private atomic JSON records retain the command ID, assignment epoch, deadline and stage. Duplicate delivery cannot replace or re-execute a recorded command. Invalid identifiers, other devices/assignments, unsupported types and expired envelopes do not execute. Reboot is never retried after its pre-execution record is written: an ambiguous crash can result in failure/expiry, not a reboot loop.

Results persist and retry with the same message ID until TMS confirms SQL storage. A status operation waits for the telemetry storage receipt before emitting its successful result. A reboot result is never generated merely because the SDK returned. Records expire with the command and are cleaned up after seven days while the agent runs.

## Boot recovery and limits

An Android BOOT_COMPLETED receiver schedules a bounded recovery job. It initializes the selected SDK, starts the agent and provides a three-minute background execution window for reconnecting and sending durable results. It does not change the user's selected launcher. Android/vendor scheduling, unlock requirements and connectivity can delay recovery; a five-minute expiry is not a guarantee of completion on every device.

The normal agent remains process-scoped. Continuous background execution and background message notifications are separate work. A message waits for UIC Home to be visible; if this does not happen within the deadline, it expires. No screen overlay permission, payment SDK, printing operation or remote-assistance session is introduced.

## Verification

- Both NEWPOS and NEXGO Android variants compile.
- Six on-device instrumentation checks pass, covering scoped command validation, duplicate persistence, reboot reconciliation without a second SDK call, status receipt matching and invalid messages, plus the existing isolated passcode test.
- 109 .NET integration checks pass, including rejection of unchanged reboot counters, uncommitted status telemetry and old telemetry evidence.
- BANPAIS / NEW9810 / H3R000700069081: portal Request Status succeeded with a stored telemetry receipt; the test message was visually confirmed on the terminal; portal Reboot invoked the SDK, advanced boot counter 6 → 7 and automatically returned `reboot_verified` through the boot recovery job.
- In the USB lab, ADB reverse mappings for 18883 and 15102 must be restored after reboot. They are development transport setup, not a production agent dependency. The physical reboot test restored these mappings without manually opening the launcher.

NEXGO is compile-checked; physical reboot qualification remains necessary on a NEXGO test terminal. Remote assistance remains pending.

## Running Android tests without removing enrollment

Use `scripts/Test-AndroidOperations.ps1 -DeviceSerial <adb-serial>`. It installs with replacement, runs instrumentation, and reopens UIC Home without uninstalling it. The test cases use isolated storage. Avoid the Gradle connected-test cleanup workflow on an enrolled lab device because it can uninstall the application and remove its private enrollment.


## Default Home registration (3.2.1-dev)

The previous launcher declared the Android HOME intent but did not select itself as the default. Version code 5 registers its exact flavor package and LauncherActivity after successful SDK initialization, including boot recovery. Registration is idempotent: it first resolves the current Android HOME activity and skips the SDK call when it already matches.

NEWPOS uses the documented `SystemManager.setDefaultLauncher(packageName, className, false)` call; false avoids launching a second Activity. NEXGO waits for SystemServiceHelper initialization before calling `systemManager.setLauncher(packageName, true)`. No device-owner enrollment, root access or ADB default-home override is used.

The foreground launcher verifies Android's actual HOME resolution after registration. If the firmware declines or the SDK is unavailable, an English/Spanish “Set UIC Home as the home app” button opens Android's standard Home selection flow. A newly installed app must first be launched/provisioned; ordinary Android installation alone does not execute application code.

Verified on NEW9810 H3R000700069081: installing 3.2.1-dev with replacement preserved enrollment; after app startup, Android HOME resolved to `com.uic.tms.home.uic.newpos.debug/com.uic.home.LauncherActivity`, and pressing Home resumed that Activity without a chooser. Both brand variants built successfully; NEXGO default-home behavior remains physically unqualified.