# Traditional launcher — development implementation

Current update: [chapter 16](16-connectivity-and-geolocation.md) supersedes the earlier Wi-Fi/cellular protection and location-collection status.
## Scope and source layout

The active :app module now points to launcher/ in the existing agents/uicu_home Gradle project. The copied app/ folder is retained unchanged as migration reference for legacy AWS/TMS and NEXGO functionality. Its old entry points, credentials and receivers are not packaged in the new launcher.

One active launcher module has independent client (uic, banpais, banrural) and brand (newpos, nexgo) flavor dimensions. Shared screens contain no vendor imports. Each brand supplies BrandDevice behind DeviceManagement. NEWPOS uses a compile-only SDK stub and the terminal's com.pos.device shared library. NEXGO includes only its own AAR. Payment, EMV, PIN-pad and printing are excluded.

The current flavor interface initializes the SDK and identifies the device. Installation, reboot, kiosk policies and remote control remain separate integration work. A subsequent change added live MQTT telemetry to the new TMS; see chapter 13. The existing server checkpoint continues to run independently.

## Launcher behavior

- Large navy date/time header, respecting the terminal's locale and 12/24-hour preference.
- Compact original app icons and labels in an adaptive grid; installed applications refresh on return and package changes.
- Dedicated Wi-Fi, cellular and Android Settings icons. Cellular opens Network & Internet when no ready SIM is present, because this NEWPOS firmware closes the dedicated mobile screen without one.
- One six-digit passcode for all three shortcuts; Settings is excluded from the ordinary app grid. NEWPOS PosSettings and Device Config entries also require the passcode.
- Change passcode requires the current passcode and matching new entries.
- Initial passcode is the six-digit value explicitly selected by the product owner in this task. It is initialized once per app-data installation; changing it survives app restart/update.
- No auto-start of legacy AWS services and no automatic home-role, device-owner or kiosk changes.

## Passcode boundary

This is a launcher entry-point gate, not a system-wide Android settings lock. Notification shade, other apps, vendor tools and adb can still offer separate settings paths. Device-owner/vendor policy enforcement is needed for managed lockdown and must be tested per brand.

PIN verification uses PBKDF2-HMAC-SHA256 with a random salt and a Keystore HMAC key. Plaintext PINs are not persisted. The requested default remains a known bootstrap value, so change it before deployment. Backup is disabled. Verification runs off the UI thread. Five failed attempts trigger a persisted 60-second delay; further failures increase it up to 15 minutes. Wall-clock changes can affect this local throttle; it is not tamper-resistant device-owner enforcement.

The passcode screen disables screenshots, autofill and saved field state. Returning home abandons the visible attempt. Authentication grants one settings launch; there is no cached unlocked session in the launcher. Once Android Settings is open, navigating inside it is governed by Android, not this launcher.

## Build and test

From agents/uicu_home, using the installed Android SDK and JDK 21:

    gradlew.bat :app:assembleUicNewposDebug :app:assembleUicNexgoDebug
    gradlew.bat :app:testUicNewposDebugUnitTest
    gradlew.bat :app:connectedUicNewposDebugAndroidTest

Debug app IDs are com.uic.tms.home.uic.newpos.debug and com.uic.tms.home.uic.nexgo.debug. Release signing is not configured. This avoids replacing unrelated installed launchers during testing.

Tests cover ASCII six-digit validation (including leading zeros), bounded escalating delays, initial PIN verification, PIN changes, rejection of the former PIN, persistence, throttling and absence of stored plaintext. Hardware verification results are recorded below after testing.

## Architecture supersession

Chapter 11's service APK proposal now applies to the future payment application only. uicu_home uses in-process brand flavors for management, as subsequently selected by the product owner. EMV/printing/PIN services are not part of this launcher.

## Verified on 23 September 2026

Both UIC NEWPOS and UIC NEXGO debug APKs built successfully. Two JVM rules tests passed; one instrumentation test on the connected NEWPOS Android 13 terminal passed, covering initial code, changing code, persistence, rejection of old/wrong code, lockout and no plaintext credential storage. The final NEWPOS debug APK was installed and opened.

Physical UI checks passed: incorrect passcode rejection, successful Android Settings/Wi-Fi launches, cellular fallback to Network & Internet without a ready SIM, and gates on NEWPOS PosSettings and Device Config. Screenshot reviewed at the terminal's actual 480×854 resolution. NEXGO physical validation remains pending. The system default home application was not changed automatically.

![Traditional launcher on NEWPOS](images/uicu-home-newpos.png)