Install and operate Android on a ZHZN vending machine

Open the illustrated installation atlas and cabinet checklist.

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

For the manufacturer or authorized installer standing at the cabinet. This covers the Android computer in the vending machine. Operator X is the separate app or website used on the operator's phone/computer to manage the machine; installing Operator X on the cabinet does not install the vending app.

Use the ZHZN vending package ai.intelliverse.zhzn.kioskx. The Reyeah package com.ruiye.jd belongs to a different installation. The ZHZN package includes its vending controller and customer WebView; it does not need the Python agent or a separate vendor SDK installation.

Before you start

Have these ready:

• The approved, signed ZHZN release APK and its published SHA-256, supplied by the release owner. Do not use a debug build or an old APK found in a checkout.
• The cabinet/plate serial, model, board type and intended tray layout; a build record for this cabinet; the contact authorized to arm its device identity.
• An Android head unit compatible with the approved release. The current source targets Android 7.0/API 24 or newer and builds for ARM 32-bit/64-bit. Confirm the manufacturer's actual ROM and hardware in acceptance testing.
• Stable cabinet power, working touchscreen, network access and the authorized cabinet PIN. On a new unit that has never contacted the cloud, get the factory access procedure from the release owner; do not assume an old published PIN.
• For the recommended bench install: a laptop with Android Platform Tools, a data-capable USB cable and access to the tablet's Android debug connection. This is not the USB/MDB reader or a VMC board serial cable.

Record existing version, ownership and pending transactions before servicing a working cabinet. Wait for any shopper/payment/dispense to finish. A same-signer update preserves app data; uninstalling or clearing storage does not.

Android controls in plain language

Android menu names vary by manufacturer ROM. The expected result matters more than the spelling: the correct network is connected, the correct app is Home, and device-owner provisioning is confirmed.

Install with a bench laptop — recommended

1. Check the downloaded file

Match the full SHA-256 against the release owner's value:

# macOS
shasum -a 256 zhzn-kioskx.apk
# Linux
sha256sum zhzn-kioskx.apk

For a technician with Android build tools, apksigner verify --print-certs zhzn-kioskx.apk displays the signing certificate and verifies the APK signature. Compare the certificate to the approved signing identity. A matching file digest alone is not permission to replace a cabinet's established signing key.

2. Connect the intended head unit

On a factory-fresh tablet, open Android Settings. If developer options are not already available, use the ROM's About device/Build number procedure to enable them, then enable USB debugging. Connect the laptop and approve its debugging prompt on the cabinet. Use the displayed device list to confirm the target:

adb devices -l

• device: the debug connection is ready.
• unauthorized: unlock the tablet and approve this laptop's debugging prompt.
• offline or no entry: check the data cable, debug port and USB debugging; reconnect before retrying installation.

If multiple tablets are attached, address each command to the intended serial. The examples below use a shell variable on macOS/Linux; replace its value with one serial from adb devices -l, not the cabinet's printed machine code:

export KIOSK_ADB_SERIAL='REPLACE_WITH_ADB_DEVICE_SERIAL'
adb -s "$KIOSK_ADB_SERIAL" install -r zhzn-kioskx.apk

Wait for Success. If installation fails, use the troubleshooting table below; do not make uninstalling the existing app the default repair.

3. Provision the kiosk lock and Home app

For production, use a factory-fresh Android user with no accounts or existing device owner. Installing the APK and setting Home are separate from assigning it as device owner:

adb -s "$KIOSK_ADB_SERIAL" shell dpm set-device-owner ai.intelliverse.zhzn.kioskx/ai.intelliverse.zhzn.admin.KioskDeviceAdmin
adb -s "$KIOSK_ADB_SERIAL" shell cmd package set-home-activity ai.intelliverse.zhzn.kioskx/ai.intelliverse.zhzn.ui.KioskActivity
adb -s "$KIOSK_ADB_SERIAL" shell am start -n ai.intelliverse.zhzn.kioskx/ai.intelliverse.zhzn.ui.KioskActivity

Use the complete component names as written: the application ID contains .kioskx, but the class namespace does not. If the ROM lacks the Home command, use Settings → Apps → Default apps → Home app → ZHZN KioskX, and choose it permanently if Android asks. Confirm provisioning:

adb -s "$KIOSK_ADB_SERIAL" shell dumpsys device_policy
adb -s "$KIOSK_ADB_SERIAL" shell dumpsys package ai.intelliverse.zhzn.kioskx

The first output must identify this package/component as device owner. The second identifies the installed package/version. A successful install message alone does not prove that the owner or Home settings succeeded.

Device owner lets the app enter managed lock task. Ordinary screen pinning is exitable through Android and is not sufficient factory sign-off for a locked public kiosk. A preinstalled app also needs the relevant Android privilege or device-owner status for silent updates; copying an APK into a factory image is not by itself proof of that privilege.

4. Connect the venue or bench network

Use Android Settings → Wi-Fi/Network & Internet to choose the intended network and enter its password. Complete any captive-portal sign-in while servicing, then verify the kiosk itself reaches its cloud and loads the correct catalog. Wi-Fi bars alone do not establish internet or gateway access.

For Ethernet or the cabinet's LTE modem, use the manufacturer's connection and SIM/APN procedure. Do not unplug the card reader or VMC cable to diagnose an internet problem. The Python agent's service-code/SoftAP setup is not built into this Android APK.

5. Complete first contact

The app registers its hardware serial, receives machine configuration and attempts device enrolment. The cloud must be provisioned and the cabinet armed as described in Factory and operator handover. Match the resulting machine code and device ID to this physical cabinet.

A status page while configuration is incomplete is not the shopper's final screen. Wait for registration/configuration, check any identity refusal, and confirm the storefront shows this cabinet's products. An empty catalog needs operator product/stock setup, not another APK install.

Install from a USB drive or download on the tablet

This can install the APK on a ROM with a file manager/browser and package installer. It does not replace device-owner provisioning:

1. Copy the approved APK to a USB drive supported by the tablet, or download it from the release owner's approved location. Confirm the file/digest at the bench before distributing it.
2. While in authorized Android Settings/service mode, open the APK in Files or the download list. If Android asks, allow installation from that specific source, then return to the installer.
3. Choose Install/Update and wait for completion. Open ZHZN KioskX.
4. Complete the Home and managed-device setup through the approved factory provisioning method. Use the laptop method above if it has not been done.
5. Verify the actual installed version and restore the cabinet's normal service configuration before release.

Do not assume a touchscreen-only sideload creates a hard kiosk or enables unattended OTA updates. If the installation policy blocks the package, have the provisioning owner resolve it instead of disabling unrelated device policies.

Open the service menu and operate the cabinet

1. On the kiosk screen, tap the top-left corner seven times within five seconds.
2. In Service access, enter the authorized cabinet PIN and tap Unlock. Five wrong entries trigger a 60-second lockout. Wait for the displayed time; contact the fleet administrator if the PIN is unknown.
3. Choose the required entry:

After servicing, press Home or launch ZHZN KioskX. Verify the storefront returns and re-enters lock task. Reboot during the bench check to verify automatic startup. Do not leave Android Settings, the PIN menu or a technician demo on a customer-facing cabinet.

Permissions, display and sound

• Allow camera/microphone access when running installed features that need them. Retest after granting access. Denial or missing hardware is not a pass.
• For a USB serial adapter, accept the prompt for the actual fitted adapter. Test permission and board recovery after a cold boot and an unplug/replug. Some ROMs require another approval; acceptance must discover that before ship.
• Set appropriate display brightness and speaker volume in authorized Android Settings; test on the actual panel in the intended lighting/noise conditions.
• Verify readable prices/status, touch response at every required target and a visible clock only when the device has valid time information. Complete the app's screen/speaker checks; a display lighting up is not a full test.

Safe routine maintenance and updates

Use a service window with no active shopper. Check pending reports and order outcomes before a planned shutdown. After startup, confirm a recent heartbeat, board readiness, correct catalog and recovery of any queued reports.

For a same-signer manual update, use adb install -r and the approved APK. For OTA, confirm the reported installed version after the update, not just that the download or install request started. A nonprivileged installation may need an Android confirmation at the cabinet. Do not power off while installation is in progress. Follow the release owner's rollout/rollback procedure; Android versionCode and signing checks can reject a lower or differently signed build.

Do not clear app storage, factory-reset the head unit or uninstall to repair a network outage. That can remove credentials, cached config, outstanding reports and the durable vend history. A replaced head unit requires the attributed identity-reset and serial-mapping procedure in the handover guide.

Recover held offline stock after a failed or unresolved vend

Offline card approval reserves one unit before the motor is commanded. That reservation survives a reboot. An accepted successful report and a later fresh inventory download reconcile the reservation against the server's stock. Failed or unresolved attempts stay held and require physical reconciliation. An online or remote motor attempt also closes the offline catalog before the motor runs and follows the same report-and-refresh requirement.

A completed motor cycle without a witnessed drop can be reported with success=true and outcome not_detected or unknown. That report can reconcile cached stock after acknowledgement and a fresh inventory download; it does not prove the shopper received a product. Investigate a missing product or uncertain payment with the original order and reader records. Do not retry automatically.

1. Put the cabinet into an attended service window. Resolve the original payment and check the pickup tray and affected lanes. Do not create another payment or motor command as a way to discover whether the first one succeeded.
2. Restore connectivity and wait for pending sales/dispense reports to upload. Check their order references in the operator console. If the reader remains active or its outcome is unknown, reconcile that transaction with the payment provider before any controlled reader/app restart. A restart is not proof of cancellation.
3. Count or refill the affected lanes and save the matching stock for this exact cabinet in Operator X. Make this correction after the pending reports finish so a delayed stock update cannot undo the physical count.
4. Enter the cabinet PIN and select Reconcile offline stock / 校准离线库存. Read the explanation, then tap Stock counted and saved / 已核对保存.
5. The action refuses while a card session is active/unresolved, the board is dispensing, or reports remain queued. Resolve the stated condition and repeat the count/save check before retrying. Do not clear storage or bypass the gate.
6. On success, verify the freshly downloaded lane counts, price and availability before returning to shoppers. If the download fails, offline sales stay closed until fresh inventory arrives. Storage failure requires service before sale.

This action preserves transaction history and the durable card-attempt ledger; it neither refunds a payment nor retries a dispense. A missing, future-dated or older-than-24-hours catalog also blocks offline checkout. Correct Android time and obtain a new authenticated catalog instead of editing cached data.

Installer troubleshooting

Before handing the cabinet to the next person

Record cabinet serial, app version/build, signer/digest reference, Android version, device-owner result, Home result, network result and any unresolved fault. Finish manufacturer sign-off, then operator handover. The final physical check is one successful shopper transaction and correct recovery, as described in Shopper use and support. Use Fleet operations and release for daily exception queues, crew access, rollout cohorts and destination-market acceptance.