Configure the kiosk, resources, and readers
Set the operating flow and physical wiring, with a field reference for what configuration actually controls.
Before you begin
- Use the native kiosk application for serial discovery and physical controller tests.
- Prepare the kiosk account, intended project and device, bookable resources, and their capability links.
- Attend the installation during door tests and confirm which compartments can be opened.
Verified against integrate-nekospaze-app at 5d1abe32660e on 8 September 2026. This reference describes source fields and their consumers, including stored options that do not yet enforce behavior.
Step by step
Prepare the shared device and resources
In the shared database model, create or verify the device and its Serial open capability, then link each resource to the correct capability, board, and channel. Confirm the kiosk is bound to the intended device. Its device-to-resource links determine which booking access rows the PIN flow can match.
Connect the kiosk account
Run Setup and enter the installation's Client ID and Client Secret on Connect. The current button labelled Simulate paired device performs authentication and saves tokens. Continue offline only saves a preference; it does not remove existing tokens or stop an existing database connection.
Discover and verify hardware
Choose the serial port and baud rate, then inspect the responsive controller boards. Select installed reader hardware and the HID byte-order option when appropriate. Discovery generates channel rows for a responding board; verify their mapping against the actual compartments before any open test.
Choose the operating flow
Select Retail Locker for vending or Parcel drop-off for food/parcel bookings. Hybrid is disabled. Receiver, Depositor, and Staff rows store Open Access, PIN, NFC, or Face preferences, but they do not enforce those authentication methods in the current routes.
Apply and inspect the result
Verify the port and baud in Discover and the device binding in Settings. Then check Review's connection label, locker count, flow, and selected hardware summary. Apply configures local serial, starts supported reader listeners, and marks setup complete. It does not provision cloud devices, resource links, or access rules, despite the online success screen's wording.
Commission one complete journey
Test a known booking on its mapped compartment, record the physical door result, and confirm the occupancy and completion updates reach the server. Test the reader capture separately. Use the office, delivery, or charger-borrowing acceptance scenarios if those policies are required; selecting auth preferences cannot enable them.
You’re ready when
The local kiosk configuration and shared hardware mapping are documented and ready for attended validation.
Troubleshooting
- No serial devices are available in the browser
- Serial discovery and reader testing require the native application. Check the installed adapter, controller, port, and baud there.
- Setup says synced to cloud but resources are missing
- Apply does not create the shared database records. Check the kiosk account's visible devices/resources, device binding, operating flow, and resource capability links.
- A selected face or USB reader produces no scans
- The runtime profile builder currently starts only the board-connected HID and DQ-CUBE profiles. HIK-VISION and detected USB entries do not create working listener profiles in this kiosk.
- A shared booking code is shown but rejected as already used
- The backend supports Shared rows with no action list, and the app can display them. The current kiosk treats an empty action list as unusable. Use a verified PerAction service configuration for this PIN flow; Shared support requires an application change.
- Changing authentication or offline preferences changes only the summary
- That matches the current implementation. Role preferences are not authorization gates, and connectionMode does not control the token-driven database connection.
Technical details
- KioskConfig storage
- One localStorage-backed row in kiosk-config. id is always kiosk. Optional fields below are absent by default; setup is local to this kiosk.
- setupComplete
- Boolean; default false. Controls setup redirects and reader autostart. Apply sets true; this flag is not a cloud-provisioning or security certificate.
- lockerFlow
- retail or parcel; default retail. Selects routes and resource kinds. Parcel mode includes food and parcel resources; retail uses retail resources. Hybrid is not enabled.
- connectionMode / pairingCode
- connectionMode is online or offline, default offline; it is a saved setup preference, not a network switch. Optional pairingCode is declared but unused by the current credentials-based Connect screen.
- deviceId
- Optional binding to a shared device ID, also selected and saved during synchronization. Verify it names the intended kiosk and that its capabilities link only to intended resources.
- setupSerialPort / setupBaudRate
- Optional discovery drafts. Apply configures the selected native port and writes runtime serial settings; baud falls back to 9600 when absent.
- setupAuthHardwareIds / setupAuthHardware
- Optional selected IDs and display snapshots. Each snapshot contains id, name, detail, kind, transport, and detected. Selection or detection does not prove a working authentication integration.
- authReaders
- Optional runtime profiles. Each has id, name, readerType (DQCUBE or HID), dataPort, parseMode, and optional powerDevice, wiegandType, swapBytes. Supported parse modes are dqcube-brackets, wiegand-hex, and raw.
- receiverAuth / depositorAuth / staffAuth
- Each accepts open, pin, nfc, or face. Defaults are nfc, open, and pin respectively. These are persisted setup preferences only; they do not gate receiver, depositor, or staff routes.
- Runtime serial-config
- Separate local row with id serial, portName, and baudRate. Settings offers baud rates 4800, 9600, 19200, 38400, 57600, and 115200. The native app restores the saved connection at startup.
- HID board profile
- readerType HID; dataPort 0x92; powerDevice 0x41; parseMode wiegand-hex; wiegandType 0x03; swapBytes false by default. Validate the identifier format with the installed reader.
- DQ-CUBE board profile
- readerType DQCUBE; dataPort 0xD0; powerDevice 0x43; parseMode dqcube-brackets. The profile is for the board connection; a detected USB entry is not a USB runtime implementation.
- Reader polling
- auth-reader-listener-enabled is a separate localStorage preference; absent means enabled. The current scan consumer is the diagnostic panel, not a personal or staff access decision.
- Device and resource capabilities
- A device capability supplies deviceId, capability, and a Serial command with hex. A resource capability links resourceId to deviceCapabilityId and can supply channel, board, and label. Open lookup prefers open/open_extend. Hex can be literal or use {channel} or {extend_open}.
- BookingAccessCodeMode
- Backend values are None, Shared, and PerAction; default PerAction. None creates no codes; Shared creates actionless rows the current kiosk rejects; PerAction creates DropOff/PickUp rows. Numeric code uniqueness is scoped by project, service, and overlapping action sets.
- Credentials and language
- Device credentials/tokens are stored separately from KioskConfig. They identify the installation, not a human staff member. kiosk-language stores en or th; default is English.
- Timeout and branding
- The idle window is a 100-second source constant, disabled on home/setup and paused by selected operations. It is not setup-editable. Kiosk shell branding is bundled assets and CSS, not a KioskConfig option.
Common questions
- Where should an installer create the current device capabilities?
- Console's Database → Devices surface edits the shared device model and Serial capabilities. Project Settings → Devices is a separate HTTP-based device surface; confirm which integration your installation uses.
- Does an active resource mean a compartment is physically empty?
- No. The shared resource status is Active or Maintenance. Booking timestamps and physical contents are separate; verify the assignment and actual compartment.
- Can I customize the logo and theme in setup?
- The reviewed kiosk uses bundled branding assets and source CSS. KioskConfig has no logo-upload or theme field. English and Thai language selection is available.
- Does re-running setup erase credentials and all settings?
- No. Re-entry snapshots the current setup and resets selected setup drafts. It does not clear credentials, the bound device, flow, role preferences, or the separate runtime serial collection. Cancel can restore the saved setup snapshot.
Still stuck? Tell support what happened and which step you reached.
Email support