Android terminal integration manual

UIC Home 3.9.14-dev (version code 27) integration checkpoint, 26 September 2026. This guide covers NEWPOS NEW9810 and NEXGO N82 builds. Production signing, enrollment distribution and each firmware must be qualified separately.

1. What UIC Home provides

UIC Home is the managed Android launcher and TMS agent. It maintains the authenticated MQTT connection, reports telemetry and application inventory, receives durable operations, downloads applications and parameters through HTTPS, and hosts Android remote assistance. The payment application remains separate.

Use the APK matching both customer flavor and hardware brand. NEWPOS and NEXGO APKs may share one logical application/version in the portal, but they are different model-specific artifacts. Package IDs also differ by customer, brand and debug/release flavor.

2. Prerequisites and restrictions

• A SuperAdmin has registered the exact manufacturer serial under the correct customer and Android model.
• The terminal has reliable network access, correct date/time and trust for the TMS HTTPS/MQTT certificate.
• The APK comes from an approved build and its signer matches the installed version for an in-place update.
• Installation alone does not enroll the terminal. The current test/debug enrollment record must be transferred through an authorized provisioning station.
• Do not uninstall UIC Home or clear its data during an update. This removes the Device Secret, AndroidKeyStore IoT key, command journal and settings.
• Do not use Gradle connected-test cleanup on an enrolled device; it may uninstall the target package.
• Debug APKs and development signing keys are not production credentials.

3. Install from a provisioning computer with ADB

1. Enable the terminal's approved USB debugging/service mode and authorize the provisioning computer.
2. Connect only the target terminal and identify it:

text adb devices -l

1. Install or update without removing app data:

text adb -s <adb-serial> install -r <absolute-path-to-UIC-Home.apk>

1. If Android reports a signer or downgrade conflict, stop. Confirm the selected customer/brand APK and signing certificate. Do not uninstall as a workaround on an enrolled terminal. A deliberate development downgrade needs a documented recovery plan.
2. Launch UIC Home once. The brand SDK initialization registers it as Home; if firmware refuses, use the displayed Set UIC Home as the home app action and Android's standard chooser.

-r preserves data only when package ID and signature are compatible. It does not protect data if the package is removed first.

4. Copy an APK to device memory and install locally

This method is useful when ADB installation is not permitted but an authorized technician can use the device UI.

1. Copy the approved APK to internal storage, normally Download. With an authorized computer this can be done by USB file transfer or:

text adb -s <adb-serial> push <absolute-path-to-UIC-Home.apk> /sdcard/Download/UIC-Home.apk

1. On the terminal, open the vendor file manager or Files > Downloads and select the APK.
2. If Android requests Install unknown apps, allow only the file-manager source for this installation. Managed firmware may require a service password or vendor approval.
3. Select Install/Update. Verify the package name, version and signer shown by the approved release process.
4. Open UIC Home once, confirm it becomes the Home application, then remove the copied APK and disable the temporary unknown-app permission.

Copying the file does not bypass Android/vendor signing policy. Some managed NEWPOS/NEXGO firmware disables USB file transfer or local package installation; use the vendor-approved provisioning path in that case.

5. Install from a USB flash drive or OTG media

1. Place only the approved APK and a release note/checksum on clean removable media.
2. Connect the media through the supported USB/OTG adapter.
3. Open the vendor file manager, browse the USB volume and select the APK.
4. Follow the same unknown-source, signer and first-launch checks as device-memory installation.
5. Eject the media, remove the local installer copy and restore the terminal's normal USB/security policy.

The exact USB mount workflow varies by firmware. UIC Home can restrict the notification shade/USB-mode selector on supported NEXGO firmware, so perform this before kiosk restrictions are enabled or use the service menu.

6. Test/debug enrollment

The enrollment record contains device ID, Device Secret, customer ID, manufacturer serial, assignment epoch, topic prefix, MQTT host/port, HTTPS package URL, trusted server certificate and IoT bootstrap key. Treat it as a credential.

Transfer it directly to app-private storage with the debug package's run-as support. Feed JSON on standard input rather than placing secrets in command arguments or shared storage:

adb -s <adb-serial> shell run-as <installed-package> sh -c 'cat > files/tms-enrollment.json'

Restart UIC Home. It encrypts the enrollment with AndroidKeyStore and removes the plaintext import. The terminal then generates an IoT private key in AndroidKeyStore, obtains and confirms its certificate, and connects to MQTT. The first valid MQTT connection marks the device IoT Provisioned and blocks further credential/certificate download.

For the local USB laboratory only, restore both reverse mappings after a reboot:

adb -s <adb-serial> reverse tcp:18883 tcp:18883
adb -s <adb-serial> reverse tcp:15102 tcp:15102

These mappings are not a production design and disappear when USB disconnects.

7. Required Android settings

1. Select UIC Home as the Home application.
2. In UIC Home select Allow connection with screen off and approve Android's battery-optimization exemption.
3. Enable UIC remote input in Accessibility for remote touch/key control. Screen capture still requires local approval for each remote session.
4. Grant location permission only when customer policy requires reported location. GPS capability does not guarantee an indoor fix.
5. Change the six-digit Android-settings passcode from its development default before deployment. It is unrelated to the Device Secret.

Wi-Fi and Cellular are available under the UIC Home Config screen without the Android-settings passcode. Android Settings remains passcode-protected and should return to the remote-control/settings page rather than expose unrelated system pages on supported firmware.

8. Portal interaction

After connection, verify the portal reports the manufacturer serial, brand/model, Android and API versions, UIC Home version, uptime, free/total storage, available/total memory, network interfaces, observed public IP, battery, capabilities and user-installed applications.

Supported tasks include request status, display message, reboot, model-specific application install, application uninstall except UIC Home, parameter retrieval and remote assistance. Commands are at least-once; UIC Home persists command IDs before effects and retries its result until TMS confirms SQL storage. Queued or Dispatched is not completion.

Application packages are downloaded through authenticated HTTPS and checked for size, SHA-256, package ID, version and signer before the brand SDK is called. The portal refreshes inventory after successful install/uninstall. System applications and system updates are excluded from the inventory.

Location history records changes of at least 100 metres. When Android has no valid fix, an authorized portal operator may set a manual location. A later valid device fix becomes authoritative.

9. Acceptance checklist

• Correct serial/customer/model and Online with recent report.
• IoT certificate state Provisioned; no plaintext enrollment remains.
• Correct UIC Home package, version and default Home resolution.
• Screen-off connection remains online without USB.
• Request Status creates a new report.
• Test message wakes the display and reports success only after it is shown.
• Reboot returns with a new boot/uptime report.
• Application inventory matches the device.
• Remote view and input work after local approval.
• English/Spanish UI follows the device language.

10. Troubleshooting and recovery