Maintain lockers and inspect failed handoffs
Use Settings, retail Restock, and Console diagnostics with a clear view of current access limitations.
Before you begin
- Obtain the site's authorization for the exact compartments and maintenance actions involved.
- Record occupied compartments and active bookings before any physical door test or status change.
- Current kiosk operator screens have no separate staff credential challenge; protect physical and operational access through site procedures until a staff gate is implemented.
Verified against integrate-nekospaze-app at 5d1abe32660e on 8 September 2026. Maintenance tools exist, but a human staff credential gate and consistent per-resource maintenance authorization still require implementation.
Step by step
Open the relevant operator tool
The current kiosk's operator entry is ten consecutive logo taps, each less than 1.2 seconds apart. It opens Settings in parcel mode or Restock in retail mode. This gesture is navigation, not staff authentication. Console provides separate mailbox and transaction tools for its IoT integration.
Inspect before issuing a command
In Settings, compare the selected serial port and baud, device/resource capability links, reservations, accesses, and pending events. Keep credentials, tokens, and live access codes out of support screenshots. Confirm the physical compartment and affected booking.
Test one attended compartment
Use the mapped locker test after connecting the serial port, and inspect the returned response or acknowledgement. Manual hex sends are available for installers who have verified the controller protocol. These local tests do not require a customer booking and do not check Maintenance status, so test only the authorized target.
Use retail Restock for its defined task
Choose the vendor and assigned-product locker. Open & Restock sends a local open command and assigns the current product with quantity 1; the sheet has no product or quantity editor. Confirm the door and actual stock before relying on the recorded result.
Reconcile booking and device state
Maintenance/Resume Service in retail Restock changes the shared resource between Maintenance and Active. A door command, resource status change, and booking completion are separate operations. Compare the physical handoff, kiosk event queue, and server record before correcting state.
Verify recovery
When local mirrored data needs refreshing, Settings provides Resync Local Database and preserves pending reservation events. Compare the server booking afterward: synchronization deletes an event after three failed attempts, so an empty queue does not prove success. Re-run Setup only when configuration needs changing, then repeat a known booking and physical door test.
You’re ready when
The operator has a specific command, hardware, data, or booking-state finding and can verify recovery on the affected compartment.
Troubleshooting
- Settings opens without a PIN
- That is the reviewed behavior. staffAuth is not enforced. A real staff session and scoped authorization must be implemented before this screen can provide protected admin access.
- Open & Restock fails to update inventory or Maintenance is refused
- Inspect the server error and the kiosk account's project permissions. Local screen access does not grant cloud mutation rights. Check the assigned product, resource project, and current Maintenance state.
- A booking stays in Pending Events
- Compare the queued operation and error with the server booking and account permissions. Resync retains these events and does not itself reconcile a failed handoff. Escalate with the booking reference, event time, and redacted error.
- Pending Events is empty but the server booking is wrong
- The current synchronizer removes an event after three failed attempts as well as after success. Compare the server timestamps and redacted synchronization logs; an empty queue is not proof that the handoff was saved.
- The command succeeded but the door stayed shut
- Inspect the actual door and controller acknowledgement. The local helper can accept a send without a conclusive open acknowledgement; retail pickup also does not reliably surface returned open failures. Do not infer physical collection from a success screen.
- Scanner test shows no captures
- Confirm native runtime, completed setup, enabled listening, and a board-connected HID or DQ-CUBE runtime profile. A listed face or USB reader does not currently supply that profile.
Technical details
- Settings inspectors
- Commands, Lockers, Locker Configs, Reservations, Accesses, Kiosks, Orders, Order Items, Products, Inventory, Pending Events, Tokens, and Serial. Locker Configs shows resource capability links.
- Stock update authority
- The shared stock assignment path requires project-matching or global projects:update or lockers:update. It also validates product/project, nonzero quantity, and resource Maintenance status.
- Resource maintenance authority
- The shared update_resource path requires project-matching or global lockers:update. Its permission check does not enforce a per-resource list.
- Cloud command authority
- Shared device capability invocations require project-matching or global devices:update or projects:update. These server checks are separate from local Settings tests and the unauthenticated operator entry.
- Reservation synchronization
- Drop-off stamps local occupiedAt; pickup stamps completedAt and removes local booking codes. Events queue for server update and are removed after success or three failed attempts. Resync preserves queued events, but does not restore those already discarded; compare the server booking to confirm reconciliation.
- Two status vocabularies
- Shared resources use Active/Maintenance. Console's older IoT locker workflow has active, inactive, in-used, reserved, and failed states. Do not substitute one vocabulary for the other.
Common questions
- Does Maintenance prevent every way of opening a compartment?
- No. Customer booking checks consider Maintenance, but Settings' local door tests do not. A protected maintenance policy must be enforced in the command path, not assumed from the status label.
- Do per-locker group choices restrict all maintenance actions?
- The reviewed shared backend uses project-level permission checks for resource, stock, and device mutations. Do not promise per-resource staff confinement from the group editor alone; implement and test consistent scope enforcement.
- Is Activate the same as Open?
- No. In Console mailbox, Activate changes availability without sending an open command. Open sends a command and checks the returned command result. Neither automatically proves that a booking has been completed.
- Should support receive the Tokens or Accesses inspector?
- Send a redacted error, booking reference, compartment, and time first. Those inspectors can expose installation tokens or live booking credentials.
Still stuck? Tell support what happened and which step you reached.
Email support