ZHZN Android: factory installation, operator handover and shopper use

Open the illustrated installation atlas and cabinet checklist.

Instructional illustration; screens and device details vary. Follow the exact steps and approved release record below.

This runbook is for ai.intelliverse.zhzn.kioskx on the Android head unit. The APK implements CSM spring and Y-lift protocols directly through its bundled serial JNI; the vendor CSM AAR is reference material, not embedded software. The Reyeah vending APK (com.ruiye.jd) and the Python Linux agent have separate installation procedures. Do not run two vending controllers on the same port.

Choose your instructions

Follow the complete sequence: install → provision identity/accessories → physical acceptance → Android certificate → final Partner FAT and factory signature → warehouse receipt → operator setup → shopper verification → operator acceptance. A milestone's saved record does not imply that the next milestone is complete.

1. Prepare one cabinet

Use the approved signed ZHZN release and its published SHA-256. Record the APK versionCode, signing certificate, physical cabinet serial and Android head-unit identity in the build record. The source version is in android-app/app/build.gradle.kts; a versioned APK left in a checkout is not proof of the currently approved release. Do not clone an already provisioned app-data image onto another cabinet.

The APK persists hwSerial, initially from ro.serialno, falling back to an AID- identifier. Match that value to the plate and the gateway machine mapping before enrolment. It separately sends deviceId (persisted Android ID, or a random fallback) on enrolment, registration and heartbeat. A cloud enrolment arm bound to a device must use this head unit's ID, not the plate or machine code. For the Android ID on the default user, the bench can read adb shell settings get secure android_id; confirm against the device contact record because Android IDs can differ by app signing key and Android user.

The gateway must have its ZHZN bootstrap credential configured; provision the approved APK's bootstrap credential through the established release process. Manufacturer credentials belong to the bench. The APK can read factory.api-key from its app files for the Partner API FAT upload; do not bake that key into a public APK. Factory device diagnostics, Partner API acceptance tests and the signed shipping certificate are separate records: one successful upload does not prove all three succeeded.

2. Install and lock

Use a factory-fresh Android user with no accounts or existing device owner. Keep the established signing key for every update.

adb install -r zhzn-kioskx.apk
adb shell dpm set-device-owner ai.intelliverse.zhzn.kioskx/ai.intelliverse.zhzn.admin.KioskDeviceAdmin
adb shell cmd package set-home-activity ai.intelliverse.zhzn.kioskx/ai.intelliverse.zhzn.ui.KioskActivity
adb shell am start -n ai.intelliverse.zhzn.kioskx/ai.intelliverse.zhzn.ui.KioskActivity

The package name and class namespace differ: the short component ai.intelliverse.zhzn.kioskx/.admin.KioskDeviceAdmin is incorrect. If the ROM does not support the HOME command, select ZHZN KioskX in Android's default Home app settings. Verify the owner assignment actually succeeded before proceeding. Screen pinning is an Android user-exitable fallback, not factory acceptance for a locked public kiosk. Preinstallation alone does not grant silent-update rights.

Power-cycle and verify automatic launch, Home/Recents and notification-shade blocking. Tap the top-left corner seven times within five seconds for the PIN service menu. Use the configured cabinet PIN; the build fallback is only for a cabinet that has never received its cloud PIN. Verify Android Settings exit and return to the kiosk. Never leave the cabinet on a documented factory PIN.

3. Enrol and test at the factory

Create the manufacturer's build record for the unclaimed serial. An authorized manufacturer may arm its own unclaimed build using POST /api/v1/machines/{no}/device-credential/arm, with a reason and the actual deviceId. A claimed cabinet needs its operator or an admin. Then let the APK exchange its bootstrap credential at /zhzn/enrol and persist the returned key; do not also issue a competing credential manually from the bench.

Retries back off as far as hourly. A 30-minute arm can expire before a backed-off retry: after the cabinet is online, restart the app to retry promptly or use an appropriately bounded arm window. Never interpret a successful arm as completed enrolment. Do not claim the cabinet into a customer fleet at the factory.

Open Factory test from the PIN service menu. Confirm actual board protocol, module, port and geometry, and grant USB permission when an adapter is fitted. An LTE modem's serial ports are not VMC ports. Confirm USB permission and board recovery again after a cold boot and adapter reseat. Exercise a known lane and verify the physical drop and row/column mapping, including the last lane.

Complete the displayed camera, microphone, speaker, touch, screen and vend-board checks with real evidence. Record absent optional hardware honestly. Have the authorized bench tooling bind fitted accessories; the current APK has no accessory-scan controls. Retain the Nayax Device Number's leading zeros. Follow the detailed sign-off guide for the native certificate and the separate Partner factory signature. The APK submits only the observed vmc board communication result and screen screen/touch result to the Partner FAT. It does not assert a physical dispense, power/network test or that optional hardware is absent. File the remaining physical observations and honest fitted/absent dispositions through the manufacturer bench workflow before Partner sign-off. A queued upload or local pass is not a server certificate.

4. Receive and set up in Operator X

The warehouse administrator records USA warehouse receipt. The operator then uses Setup: claim the exact serial, set venue/location, configure Nayax if fitted, fill trays and complete verification. A serial owned by another operator needs a transfer; do not invent a second serial. Inspect shipment condition and the factory record before recording acceptance.

Confirm the operator account's country and currency before commissioning; aisle prices are denominated in that account currency. Set each aisle's product, price and physical stock, then compare the storefront and reader amount. Verify the configured columns per row against the cabinet. On Android, configure Wi-Fi or LTE through Android Settings/the cabinet modem; the Python agent's SoftAP, /etc/zhzn-agent.env and systemctl instructions do not apply to this APK.

Verify the hosted storefront loads the correct cabinet's catalog. Enable remote screen explicitly when needed, then confirm capture and a harmless input from Operator X. A feature flag being enabled does not prove the cabinet applied it. Check heartbeat age, board readiness, device identity and outstanding reports.

5. Acceptance transaction and recovery

1. Buy one inexpensive stocked item through the configured real payment path. Record the order number, correct price/currency and lane. Confirm one physical drop, a settled vend outcome in Operator X and the corresponding stock change.
2. Check the same order after a refresh/retry: it must not dispense twice. Never retry a payment by creating another order to investigate the first one.
3. Run a controlled failed-vend case on the bench. Confirm the failure and refund or reconciliation state in Operator X; a failed vend is not proof of a refund.
4. Interrupt connectivity after a bench vend; restore it and confirm reports drain and the order resolves without a second motor movement. Do not clear app storage while reports are pending.
5. Power-cycle offline and online. Verify cached configuration, the PIN gate, identity, board recovery and storefront recovery. Offline card selling also requires the configured MDB reader and a cached valid planogram; QR checkout requires connectivity.
6. Test a higher-versionCode, same-signer APK update on a bench unit. Confirm installation outcome and the running version after relaunch. Android OTA uses APK digest/signature checks and PackageInstaller, not the Linux tarball, Ed25519 release-key file or systemd rollback path.

Use adb install -r for a same-signer update. Uninstalling or clearing app data loses device credentials, vend deduplication history, pending reports and cached configuration. A replaced head unit needs an attributed cloud identity reset and correct serial mapping; do not copy a different cabinet's app data as recovery.

6. Use Operator X for first setup

Use your operator account on your own phone or the operator web console. Check that the account and cabinet serial are correct before modifying inventory or accepting delivery. The Android PIN unlocks the vending machine's service menu; it is not your Operator X login.

1. Claim: in Set up machine, scan/type the exact serial and choose Claim machine. A previously claimed machine can resume at Locate. If it belongs to another operator, arrange a transfer rather than changing its ID.
2. Locate: use Check machine address, enter the structured address and Check address. Review the returned address/map point, choose the matching candidate and explicitly confirm it. At the actual cabinet, enter its exact machine number and placement, then record the separate physical-presence declaration through Confirm installation (web: Confirm installation as operator). A legacy pin or geocoder match does not prove installation or postal deliverability. Verify venue time zone and the separate commercial host arrangement. See the address walkthrough.
3. Nayax: for a fitted reader, use Bind reader with its actual Device Number, preserving leading zeros. Test the reader/cabinet pairing; a saved number or “online” reader does not prove it can accept the vend amount or that takings reach your Core account. A reader still settling to a previous owner's Core actor does not satisfy card-payment readiness. A cabinet with no reader can proceed using a correctly configured live Scan & Pay path; do not bind a fictitious reader to complete setup.
4. First fill: physically load the assigned products before confirming stock. The wizard tops up non-faulted low aisles to capacity. For a partial fill, use the machine's per-aisle count controls instead of claiming full.
5. Go-live checks: require the confirmed address and separate on-site installation record for this serial; inspect claimed, online, payments ready, stocked planogram and board readiness. paymentsReady accepts either nayaxBound or scanpayReady. The QR check requires a live Stripe key, a configured webhook and an enabled currency; a simulated or test-mode QR does not pass production commissioning. These are configuration checks: correct failures, then perform the real acceptance purchase and verify settlement.
6. Done: confirm the actual status is Machine is live. Setup saved — not live yet means configuration was saved but commissioning is incomplete.

Production refuses forced go-live, including an administrator's request. If a legacy client still exposes Force go-live (checks incomplete), it cannot bypass production checks. Correct the failed check and repeat verification; saving setup is not permission to open an unready cabinet.

Destination country, currency and payment limits

Commission the actual destination profile. Confirm the operator's currency, reader's configured currency/decimal places, processor account eligibility, settlement owner and approved product/age rules. Matching currency labels and a saved binding alone do not prove authorization, delivery, capture or a refund.

• Native MDB card accepts one product line and one unit per purchase, online or offline. Card and offline reports preserve the sale's currency and decimal places. Verify that the fitted reader accepts that exact amount and that a delayed report retains the original sale amount after an inventory reprice.
• The current Nayax Spark integration permits USD only. Other currencies are refused before a remote payment request.
• The current Stripe QR integration refuses three- or four-decimal currencies and UYI. It encodes whole-unit ISK and UGX using Stripe's required representation. Other currencies remain subject to Stripe's country, account and payment-method availability and amount limits.
• Hyperswitch, PayPal and Checkout.com adapters currently use USD. New non-USD QR payments use only a supported Stripe route. Older non-USD authorizations on the USD-only adapters require reconciliation directly with the processor; automatic capture/refund is held to avoid a wrong-currency charge.
• With capture after delivery enabled, buy one product and one unit at a time by QR. Multi-product or multi-unit QR baskets are refused before payment. Existing shared authorizations requiring manual settlement must be reconciled together at the processor; do not refund one line as though it had a separate hold.

A currency or amount mismatch is a payment exception: verify the original charge and follow the refund/reconciliation process before another attempt. Factory acceptance and automated checks do not certify every country or payment provider. Retain destination-specific transaction evidence and any unresolved release restriction in the handover pack.

Sales summaries retain each order's recorded currency and show separate currency groups instead of adding unlike currencies into one total. An unavailable total must not be treated as zero. Tax and cost accounting is currently validated for USD; non-USD order summaries mark those fields unavailable. Arrange verified accounting/reconciliation for the destination before approving that market.

7. Accept delivery in the operator web console

Inspect the cabinet and its factory records before accepting it. On the web machine detail, review Build & factory QA and the Android certificate/read view. The Flutter factory card currently displays records; it does not provide all web acceptance controls.

In the host card (for example, No host linked), link the actual CRM venue and terms, or use This machine has no host, enter the real reason and Save when that is the true arrangement. A location pin by itself does not establish who receives host payments. Resolve the host-arrangement gate before delivery acceptance.

Only after the shipment is inspected and verified, choose Accept this machine in Build & factory QA. The current button records the condition as good; do not use it merely to acknowledge arrival of a damaged cabinet. Use the approved service/exception process and document the condition first. The separate Partner factory sign-off must already exist. Acceptance is a recorded commitment and is not a substitute for repair or for go-live testing.

8. Operate the machine day to day

Keep a service record with the cabinet serial, time, actual action, order/evidence references and result. Do not store admin/device credentials in customer-facing notes. Return the vending head unit from Android Settings to its locked shopper screen before leaving.