Linux A10-T terminal integration manual

xTMSAgent integration checkpoint, 26 September 2026. This guide documents how the UIC A10-T Linux terminal connects and interacts with UIC Connect TMS. The official production A10-T installation procedure will be added after its installer and field process are finalized.

1. Components and responsibility

xTMSAgent is the resident management agent. It starts and monitors the bank payment application, controls the A10 communications service, maintains the authenticated MQTT connection, reports telemetry/application inventory, processes TMS commands and exchanges parameter files with the payment application through a local bridge.

The portal model is the generic UIC / A10-T / Linux compatibility family. The device also reports its complete hardware model, for example A10-TKR42NDBKT0NU1; both values appear in device details. Compatibility and package targeting use the portal model.

2. Enrollment sequence

1. A SuperAdmin creates or selects the UIC A10-T model and onboards the exact hardware serial under the correct customer.
2. A protected customer-specific xTMSAgent package supplies customer/server/bootstrap configuration, but no terminal Device Secret.
3. On first start, xTMSAgent starts CommServer before TMS enrollment. The operator can press F2 Config to select/configure Ethernet, Wi-Fi or cellular.
4. The agent reads the SDK serial and complete reported model and claims only the existing portal record through /device-iot/enroll.
5. TMS returns the unique device ID, Device Secret, assignment epoch and topic prefix. The agent atomically writes /home/user1/.xtms/enrollment.json with mode 0600 and removes the bootstrap file.
6. The agent generates/provisions the IoT certificate, confirms private-key possession and connects to MQTT.
7. The first authenticated MQTT connection marks the certificate Provisioned and closes further enrollment downloads.

The terminal cannot create or assign its own portal record. A missing/incorrect serial displays Enrollment pending and retries every 60 seconds or when Retry/Enter is used. Communications configuration remains available while pending.

3. Installation status

Production A10-T installation instructions are intentionally reserved for a later revision. Do not treat the development updateTMS.sh, a serial-console copy or a manually copied credential file as the field enrollment design. In the development lab, updateTMS.sh only downloads/installs the already-built signed package; xTMSAgent itself performs enrollment and certificate provisioning after boot.

Until the field installer is approved, preserve these requirements:

• package the correct customer bootstrap securely;
• sign with the approved A10 application key;
• install under /home/user1 using the vendor-approved update path;
• never include a returned terminal Device Secret in a reusable package;
• preserve /home/user1/.xtms across normal agent updates;
• restrict enrollment, IoT key and configuration files to the agent user.

4. Communications configuration

CommServer supports Ethernet, Wi-Fi and cellular according to firmware/hardware. It starts before enrollment to avoid a bootstrap deadlock. Saving is explicit: leaving Config with Cancel must not report CONFIG UPDATED or alter stored values. Only the menu's Save action commits changes. Status notices must dismiss on a key press.

Verify IP/DNS routing, correct UTC time, HTTPS/MQTT server-name trust and access to production ports 5102/5883. Public IP shown by the portal is the address observed by TMS, which can differ from local interface addresses through NAT/proxy.

5. Telemetry and inventory

The current report includes:

• manufacturer serial, UIC brand, A10-T portal family and complete reported model;
• Linux/firmware version, xTMSAgent version and uptime;
• Ethernet/Wi-Fi/cellular state, interface IP and MAC addresses, and public IP observed by TMS;
• free and total storage plus available and total memory;
• capabilities and current user-application inventory.

The payment application normally resides in ./userappl. Inventory uses cfg/appname.txt for its display name, cfg/version.txt for the version and the configured ID (normally PAYMENT_APP) for package identity. Missing files produce an absent/unknown inventory entry rather than fabricated metadata.

A10-T currently does not report geolocation. An operator with Device Write access can assign a manual portal location by address, map pin or coordinates. If a future agent reports valid coordinates, reported telemetry becomes authoritative.

6. MQTT, results and local bridge

xTMSAgent uses the same per-device MQTTS topics and authenticated HTTPS download endpoint as Android. It validates device ID, assignment epoch and expiry and journals work before device effects. Telemetry/results remain in a local outbox until TMS returns a storage receipt.

The payment application writes status/config requests and reports through bridge files. Parameter responses are written to the configured parameter payload file and bridge/parameters_response.json. The agent checks bridge/payment_status.json; application/parameter work can be rejected while open transactions or a batch make the update unsafe.

Supported portal operations include Request Status, Send Message, Reboot, signed A10 payment-application install and uninstall. Remote desktop is not implemented for A10-T.

7. Application package lifecycle

The portal accepts the native signed prodapp.tarball.tar.gz. Its outer archive contains app.tar.gz and app.tar.gz.sign; the application archive contains appl.out and cfg/version.txt, with cfg/appname.txt recommended. The portal validates structure and SHA-256 and keeps the exact uploaded bytes. The terminal vendor update API performs A10 signature/install validation.

For install, xTMSAgent downloads through authenticated HTTPS, verifies the command hash, ensures the payment app is not running/open-batch unsafe, and calls os_update_application for ./userappl. It queues the verified result and reboots so the normal boot path activates the application and reports fresh inventory.

For uninstall, the agent coordinates payment-app shutdown, removes/recreates userappl, reports evidence that the configured application is absent and reboots. UIC Connect shows task completion only after terminal evidence; dispatch alone is not success.

8. Acceptance checklist

• Exact serial pre-onboarded and generic portal model UIC A10-T selected.
• F2 Config available before enrollment; Cancel does not save.
• Enrollment file exists with mode 0600; bootstrap source removed.
• IoT certificate becomes Provisioned and device is Online.
• Portal shows complete reported model, OS/version, agent version and uptime.
• Storage and memory show both available/free and total values.
• Interface IP/MAC and observed public IP are present when available.
• userappl inventory uses appname/version files.
• Request Status and Send Message complete with stored results.
• A disposable signed application install/uninstall completes, reboots and refreshes inventory.

9. Troubleshooting