Device maintenance commands
These commands are public so an independent implementation can support the hardware. Public syntax is not authorization to operate a production cabinet. Server-to-device maintenance commands require authenticated roles, cabinet scope checks, audit logs and an explicit rollback or recovery plan.
FA: maintenance eject
Downlink: {FA,messageId,slotNumber,crc}
Uplink: {FA,sameMessageId,result,crc}
| Field | Meaning |
|---|---|
slotNumber=0 | Eject all slots |
slotNumber>0 | Force-eject the specified slot |
result=1 | Device accepted the operation |
result=0 | Device rejected the operation |
FA is a maintenance action and the ejected power bank is not enabled for discharge. Do not use it as a rental substitute.
FL: slot enable or disable
Downlink: {FL,messageId,slotNumber,operation,crc}
Uplink: {FL,sameMessageId,disabledMaskHex,crc}
| Field | Meaning |
|---|---|
slotNumber=0 | Apply to all slots |
slotNumber>0 | Apply to one slot |
operation=0 | Enable |
operation=1 | Disable |
disabledMaskHex | Hex bitmask; bit 0 is slot 1, bit 1 is slot 2, and so on |
Examples of mask semantics: 00000000 means no disabled slots; 0000000F means slots 1-4 are disabled.
OT: firmware upgrade control
Upgrade downlink: {OT,operation,host,port,path,md5,fileSize,crc}
Control/query downlink: {OT,operation,crc}
Uplink: {OT,result,resultInfo,crc}
operation | Meaning |
|---|---|
1 | Upgrade main-board MCU |
10 | Upgrade all stacked sub-board MCUs; already-upgraded boards may be skipped |
20 | Upgrade 8-port expansion-board MCU |
0 | Query upgrade progress; no host/path parameters |
11 | Query all sub-board firmware versions; no host/path parameters |
111 | Stop upgrade; no host/path parameters |
| Response | Meaning |
|---|---|
result=1 or 10 | Progress or accepted/success response; interpret resultInfo by operation/profile |
result>=200 | Operation-specific failure code |
fileSize>0 | Expected firmware size in bytes |
fileSize=0 | Resume mode on supporting firmware |
md5 is supplied with the firmware path and must match the downloaded file. Production implementations should additionally require TLS where supported, an allowlisted host, signed artifacts, model/version compatibility checks, staged rollout, power-state checks and a tested recovery path. Never accept an arbitrary URL from an end-user client.
SQ: stacked sub-board query
Downlink: {SQ,messageId,operation,0,crc}
Uplink: {SQ,sameMessageId,boardCount,board1,...,boardN,crc}
Each board record is index:boardId:firmwareVersion. Validate boardCount against the number of records; do not silently drop an extra board.
NI: power bank ID write
Downlink: {NI,messageId,slotId,newPowerBankId,crc}
Uplink: {NI,sameMessageId,result,currentPowerBankId,crc}
| Field | Meaning |
|---|---|
slotId | Source profile documents 1..12; use the selected cabinet topology |
newPowerBankId | Up to 16 characters on this command/profile; use 15 for cross-firmware compatibility |
result=1 | Write accepted |
result=0 | Write failed or was not applied |
This command changes asset identity. Require a second confirmation in operator UI, verify the post-write ID, and retain old/new values in the audit record.
KU: key event report
Uplink: {KU,lastMessageId,deviceId,keyOperation,crc}
There is no protocol acknowledgement.
keyOperation | Meaning |
|---|---|
1 | Short press |
2 | Long press, at least three seconds |
3 | Double press |
Treat KU as an event, not a rental, return or maintenance success. Any server-side action triggered by a key event must still pass its own authorization and state checks.