# Android and Linux device integration architecture

Implementation checkpoint: 26 September 2026. This chapter is the common integration contract for UIC Home on Android and xTMSAgent on UIC A10-T Linux terminals. Operator procedures are in the [Android integration manual](manuals/android-integration-en.html) and [Linux integration manual](manuals/linux-integration-en.html), with [Spanish Android](manuals/android-integration-es.html) and [Spanish Linux](manuals/linux-integration-es.html) editions.

## Common lifecycle

```text
SuperAdmin onboards serial + customer + portal model
        |
        v
Device receives or claims its unique Device Secret
        |
        v
Device creates a private key and obtains an IoT certificate
        |
        v
Certificate possession is confirmed
        |
        v
First authenticated MQTT connection marks IoT Provisioned
        |
        v
Telemetry, commands, parameters and application tasks
```

A terminal never creates its own fleet record. The SuperAdmin must first register the exact manufacturer serial under the correct customer and model. Enrollment fails closed when the serial, customer, assignment epoch, model family, device state or bootstrap proof does not match.

The Device Secret and IoT certificate are independent factors. MQTT admission requires the current device ID, assignment epoch, Device Secret and the exact non-revoked client-certificate fingerprint. Topic authorization limits a terminal to its own namespace. The first successful MQTT session closes enrollment downloads and marks the terminal IoT Provisioned; this avoids permanently disabling a terminal when certificate issuance succeeds but network admission temporarily fails.

## Runtime paths

| Path | Purpose | Required security |
| --- | --- | --- |
| MQTTS 5883 | Telemetry, commands, results, parameter request/response | TLS server validation, per-device client certificate, Device Secret and exact topic scope |
| HTTPS 5102 | Enrollment, certificate issuance/confirmation, application and parameter downloads | TLS server validation plus bootstrap or provisioned device identity appropriate to the endpoint |
| WSS 5102 | Android remote screen and input | Short-lived portal-authorized session, local capture approval and Android accessibility for control |
| gRPC 15101 | Portal/broker to DataService | Loopback-only service authentication; never expose publicly |

MQTT carries bounded JSON envelopes, not APKs, Linux packages, screen frames or payment data. Large artifacts use authenticated HTTPS. Every important terminal result is retained locally until the matching SQL commit receipt is received. MQTT PUBACK means broker receipt only.

## Enrollment differences

### Android UIC Home

The current Android production-bootstrap workflow is not yet packaged as a general field installer. An authorized provisioning station installs the correct brand/customer APK and transfers an enrollment record into app-private storage for the debug/test workflow. UIC Home encrypts the record with AndroidKeyStore, deletes plaintext input, generates its IoT private key inside AndroidKeyStore and provisions the certificate. An ordinary APK install alone does not enroll the terminal.

Updates must use the same package ID and compatible signing certificate with replace/install-in-place semantics so private enrollment, command history and keys remain. Uninstalling UIC Home or clearing its data removes those items and requires authorized enrollment recovery plus IoT certificate rotation.

### Linux A10-T xTMSAgent

The xTMSAgent customer package contains server/customer bootstrap data, never a terminal Device Secret. It starts the A10 communication service before enrollment so Ethernet, Wi-Fi or cellular can be configured on a new device. It reads the hardware serial and full reported model from the SDK, then calls `/device-iot/enroll` to claim the already-onboarded record. The returned unique enrollment is written atomically to `/home/user1/.xtms/enrollment.json` with mode `0600`; the bootstrap file is removed.

If the serial is not onboarded, the device shows **Enrollment pending** and retries every 60 seconds or when the operator requests Retry. It must remain usable for communications configuration while pending. The development `updateTMS.sh` only installs a package on the lab terminal; it is not part of identity enrollment and is not a production dependency.

## Reported state

Both agents report a current snapshot containing identity, portal-model-compatible family, full reported model, OS/version, agent version, uptime, capabilities, network interfaces, local IP/MAC addresses, public IP observed by TMS, free/total storage, available/total memory and user-application inventory.

Android inventory excludes system apps and system-app updates. Linux A10 inventory reads the installed `userappl` application. `cfg/appname.txt` supplies the display name and `cfg/version.txt` supplies the version; the configured application ID defaults to `PAYMENT_APP`.

Location is optional. Valid reported telemetry always takes precedence over a manual portal position. History adds a point only after a change of at least 100 metres; smaller changes update the current point without creating precision-noise history. Devices without a valid reported coordinate can be assigned a manual location by an authorized operator. See chapter 34.

## Commands and evidence

The broker delivers commands at least once. Agents validate protocol version, device ID, assignment epoch and expiry, persist command identity before an external effect, and return the previous result on redelivery.

| Capability | Android UIC Home | Linux xTMSAgent |
| --- | --- | --- |
| Current telemetry / request status | Yes | Yes |
| Display message | Yes, wake-capable activity | Yes, agent display or payment-app bridge |
| Reboot | Brand SDK with boot evidence | Payment-app coordination then device reboot |
| Application install | Model-specific APK through brand SDK | Signed native A10 `prodapp.tarball.tar.gz` through `os_update_application` |
| Application uninstall | Brand SDK; UIC Home protected | Removes configured `userappl` payload |
| Parameters | Read-only provider to payment app | File bridge and parameter response file |
| Remote desktop | WSS screen + accessibility input | Not implemented |

Android installation verifies package ID, version, signer and exact artifact hash. A10 installation verifies portal hash before the vendor update API performs platform signature/install checks. Successful A10 install or uninstall queues the terminal result before reboot; the restarted agent then reports fresh inventory. A task is rejected while the payment application reports an unsafe state such as an open batch.

## Restrictions and operating rules

- Do not put terminal secrets, private keys, full PAN, track data, CVV, PIN material or payment keys in telemetry, audit, logs or command results.
- Keep terminal clocks synchronized. Enrollment and certificate proofs have short validity windows.
- Do not disable TLS hostname or certificate validation to solve connectivity failures.
- The online badge is an MQTT-presence lease, not proof that a requested operation completed.
- Queued or dispatched application work is not installation success. Use the terminal result and refreshed inventory.
- USB reverse mappings are Android laboratory transport only and disappear on disconnect/reboot.
- Android battery-optimization exemption and vendor power policies must be qualified for unattended screen-off connectivity.
- A10-T installation media and official field-install steps remain to be documented after the production installer is finalized.
- Remote control is Android-only in the current release and still requires local capture approval.
- Automatic IoT certificate renewal/CA rollover, malware scanning and production fleet-scale qualification remain outstanding.

## Failure recovery

| Symptom | Recovery path |
| --- | --- |
| Serial not found / enrollment pending | Verify exact manufacturer serial, customer, enabled state and model onboarding; then retry |
| Certificate issued but MQTT unavailable | Correct network/TLS/clock and retry; enrollment stays open until the first valid MQTT connection |
| Revoked or lost IoT key | SuperAdmin rotates the IoT certificate, then the agent provisions a new key/certificate |
| Device Secret lost or rotated | Use the approved enrollment recovery path; the old secret cannot be recovered from SQL |
| Android app data cleared | Re-enroll and rotate IoT credentials; reinstalling alone is insufficient |
| Linux package task fails | Check portal model mapping, package hash, A10 signature, disk space, payment-app state and command detail |
| Operation remains dispatched | Confirm terminal online state, task expiry, local agent log and durable result/outbox; do not assume success |