Box Commands — Advanced

Overview

A Box Command payload is a 16-byte binary structure passed as customCommandData to the Tapkey SDK’s TriggerLock method. The box decodes these bytes and executes the requested actions.

App (Base64 string)
  → Tapkey SDK: TriggerLock(lockId, customCommandData)
    → BLE connection to box
      → Box decodes 16 bytes and executes
        → Box sends feedback response

The payload is transmitted opaquely by the Tapkey SDK — it does not interpret the content.

Command structure (16 bytes)

Byte	Field	Description
0	Reserved	Always `0x00`
1	DBC	Data byte count, always `0x10` (16)
2–3	DVER	Protocol version (little-endian), always `0x01 0x00`
4	DP	Delay for planned commands (see encoding)
5	EPR / EPRP	Extra presses: bits 0–1 = EPR, bits 4–5 = EPRP
6	PRD	Press duration for generic commands (see encoding)
7	PAD	Pause between presses for generic commands
8	PRDP	Press duration for planned generic commands
9	PADP	Pause for planned generic commands
10	LLA	Lock angle override — always use 0
11	ULA	Unlock angle override — always use 0
12	Flags A	Immediate command bits
13	Flags B	Immediate command bits (continued)
14	Flags C	Planned command bits
15	Flags D	Planned generic command bits

Byte 12 — Immediate command flags

Bit	Flag	Action
0	LB	Lock Box (lock drawer)
1	UB	Unlock Box (unlock drawer)
2	LC	Lock Car (press lock button)
3	UC	Unlock Car (press unlock button)
4	ST	Get Status (request feedback)
5	RN	Read NFC tags
6	FR	Factory Reset (deep sleep)
7	DB	Disable Box

Byte 13 — Immediate command flags (continued)

Bit	Flag	Action
0	EB	Enable Box
1	BP	Beep
2	BK	Blink (reserved, do not use)
3	LG	Lock Generic (configurable press)
4	UG	Unlock Generic (configurable press)
5–7	—	Reserved

Byte 14 — Planned command flags

Bit	Flag	Action
0	LBP	Lock Box (planned, delayed by DP)
1	UBP	Unlock Box (planned)
2	LCP	Lock Car (planned)
3	UCP	Unlock Car (planned)
4–7	—	Reserved

Byte 15 — Planned generic command flags

Bit	Flag	Action
0–2	—	Reserved
3	LGP	Lock Generic (planned)
4	UGP	Unlock Generic (planned)
5–7	—	Reserved

Encoding formulas

DP — Planned delay (seconds)

Planned commands (LBP, UBP, LCP, UCP, LGP, UGP) execute after a delay controlled by DP.

Encode: DP = floor(√(2·t_s − 1))
Decode: t_s = (DP² + 1) / 2

DP value	Delay
1	1 s
2	2.5 s
3	5 s
4	8.5 s
6	18.5 s
7	25 s
11	61 s (~1 min)
19	181 s (~3 min)
60	~30 min
85	~1 hour
255	~9 hours

PRD / PAD — Duration (milliseconds)

Used by generic commands (LG, UG) to control press duration and pause between presses.

Encode: value = floor(√(2·t_ms − 1))
Decode: t_ms = (value² + 1) / 2

Value	Duration
14	~98 ms
22	~242 ms
32	~512 ms
45	~1013 ms (~1 s)
63	~1985 ms (~2 s)
77	~2965 ms (~3 s)
100	~5000 ms (~5 s)

EPR / EPRP — Extra presses

Total keyfob button presses = 1 + EPR. Range: 0–3.

EPR	Total presses
0	1 (single)
1	2 (double)
2	3 (triple)
3	4 (quadruple)

Command reference

Standard commands (LC, UC, LB, UB)

Simple keyfob button press (lock or unlock) and box drawer control. Single press with default duration — no additional parameters needed.

Generic commands (LG, UG)

Configurable keyfob button press with control over:

Number of presses (EPR)
Press duration (PRD)
Pause between presses (PAD)

Use for double-press unlock, long-press lock, or rapid multi-press sequences.

Planned commands (LCP, UCP, LBP, UBP, LGP, UGP)

Execute autonomously after the delay specified by DP. The box performs planned commands independently — even after the BLE connection is closed. There is no way to cancel a planned command once sent.

Status command (ST)

Requests Group 1 feedback (battery, drawer state). Can be combined with any other command.

Execution rules

The box enforces specific rules when processing a command payload:

Contradicting commands abort execution

If a command contains contradicting flags — for example LB (Lock Box) and UB (Unlock Box) simultaneously — the box responds with error code 4: “Invalid command combination” and the entire command is aborted. No part of the payload will be executed.

The same applies to:

LC + UC (Lock Car + Unlock Car)
LBP + UBP (Lock Box Planned + Unlock Box Planned)
LCP + UCP (Lock Car Planned + Unlock Car Planned)
DB + EB (Disable Box + Enable Box)

Command execution order

Regardless of bit position in the payload, the box always executes commands in a fixed priority order:

EB (Enable Box) — always executed first if present
All other immediate commands (LB, UB, LC, UC, ST, LG, UG, RN, BP, etc.)
DB (Disable Box) — always executed last if present
Planned commands are scheduled (not executed immediately)

This guarantees that:

An EB + other commands combination will re-enable the box before attempting further actions
A DB at the end ensures the box is disabled after all other actions complete

Disable Box / Enable Box — access control

The DB (Disable Box) and EB (Enable Box) commands provide a remote access control mechanism. A disabled box rejects all incoming commands from any BLE connection until explicitly re-enabled with EB.

Primary use case: A telematics device (e.g. fleet management hardware installed in the vehicle) sends DB to block app users from operating the box. This is useful when:

The vehicle is in a restricted operational state (e.g. maintenance, charging, out of service)
A central system needs to temporarily revoke physical access without modifying digital key assignments
External hardware wants exclusive control over the lock state

To restore normal operation, the telematics device (or any authorized BLE connection) sends EB. Since EB is always executed first in any command payload, it can be combined with other actions in a single command — for example EB + UC (Enable Box + Unlock Car) in one transmission.

New commands cancel pending planned commands

When the box receives any new direct command from the app, all previously scheduled planned commands are cancelled immediately. This is an inherent firmware behavior — there is no dedicated “clear” flag.

Example: If a previous command scheduled “Lock Car after 20 seconds” (LCP with DP=6), but the user sends a new unlock command before the timer expires, the planned lock is cancelled and will never execute.

Examples

Unlock Car + Lock Box + Status

Standard single-press unlock. Box remains locked.

Field	Value
UC	1
LB	1
ST	1

Hex:    00 10 01 00 00 00 00 00 00 00 00 00 19 00 00 00
Base64: ABABAAAAAAAAAAAAGQAAAA==

Lock Car + Lock Box + Status

Standard single-press lock.

Field	Value
LC	1
LB	1
ST	1

Hex:    00 10 01 00 00 00 00 00 00 00 00 00 15 00 00 00
Base64: ABABAAAAAAAAAAAAFQAAAA==

Double Unlock (2 presses, ~3 s pause)

Presses the unlock button twice with approximately 3 seconds between presses. Useful for vehicles requiring a double-press to unlock all doors.

Field	Value	Meaning
UG	1	Generic unlock
EPR	1	1 extra press → 2 total
PRD	32	~512 ms press duration
PAD	77	~2965 ms pause (~3 s)
LB	1	Keep box locked
ST	1	Request feedback

Hex:    00 10 01 00 00 01 20 4D 00 00 00 00 11 10 00 00
Base64: ABABAAABIE0AAAAAERAAAA==

Double Lock (2 presses, ~3 s pause)

Presses the lock button twice with approximately 3 seconds between presses. Useful for deadlock or mirror-fold activation.

Field	Value	Meaning
LG	1	Generic lock
EPR	1	1 extra press → 2 total
PRD	32	~512 ms press duration
PAD	77	~2965 ms pause (~3 s)
LB	1	Keep box locked
ST	1	Request feedback

Hex:    00 10 01 00 00 01 20 4D 00 00 00 00 11 08 00 00
Base64: ABABAAABIE0AAAAAEQgAAA==

Unlock Car + Auto Lock after ~18.5 s

Unlocks the car immediately, then the box firmware autonomously locks the car after ~18.5 seconds.

Field	Value	Meaning
UC	1	Unlock car (immediate)
LB	1	Lock box (immediate)
ST	1	Request feedback (immediate)
LCP	1	Lock car (planned)
DP	6	Delay: ~18.5 seconds

Hex:    00 10 01 00 06 00 00 00 00 00 00 00 19 00 04 00
Base64: ABABAAYAAAAAAAAAGQAEAA==

Unlock Car + Auto Lock Car & Box after ~61 s

Unlocks the car immediately, then both car and box lock automatically after approximately 1 minute.

Field	Value	Meaning
UC	1	Unlock car (immediate)
LB	1	Lock box (immediate)
ST	1	Request feedback (immediate)
LCP	1	Lock car (planned)
LBP	1	Lock box (planned)
DP	11	Delay: ~61 seconds

Hex:    00 10 01 00 0B 00 00 00 00 00 00 00 19 00 05 00
Base64: ABABAAsAAAAAAAAAGQAFAA==

Unlock All (Car + Box) + Status

Unlocks both car and box drawer. Use when physical access to the keyfob is required.

Field	Value
UC	1
UB	1
ST	1

Hex:    00 10 01 00 00 00 00 00 00 00 00 00 1A 00 00 00
Base64: ABABAAAAAAAAAAAAGgAAAA==

Feedback

The box returns a variable-length byte array as response data. One feedback per command, regardless of how many actions are encoded.

Response structure

Byte	Field	Description
0	RVER	Feedback generator version
1	CMDR	Command response code
2+	Groups	Signal groups

CMDR — Response codes

Code	Meaning
0	Success
1	Missing permissions (certificate does not allow this)
2	Cannot read permissions (certificate missing)
3	Unsupported command
4	Invalid command combination
5	Tray opened during execution
6	Cannot execute — tray is open
7	Temperature protection (too hot/cold)
8	BMS update in progress (retry after 2 minutes)
9	Box disabled (send EB to re-enable)

Group 1 — Battery and drawer status

Each group starts with a 2-byte header: Group ID + Signal Length.

Field	Bits (within group data)	Description
BSOC	byte 0, bits 0–6	Battery state of charge (0–100 %)
BIC	byte 0, bit 7	Battery is charging
BST	byte 1, bits 0–6	Temperature: °C = BST − 40
BICC	byte 1, bit 7	Charger connected
DA	byte 2, bit 6	Drawer accessibility (1 = unlocked)
DS	byte 2, bit 7	Drawer state (1 = open)

Deriving app state from feedback

Condition	App state
`DrawerState = true`	Box drawer open
`DrawerAccessibility = true`	Box unlocked
`DrawerAccessibility = false`	Box locked

Safety notes

Interactive tool

Use the Box Command Configurator to visually build and decode commands without manual byte calculation.