Box Commands

The simplest way to interact with a flinkey Box is to trigger it. This involves sending a command to the box that causes the box to change its state. This means that if the box was locked, it and the vehicle are unlocked or vice versa.

In either case, the box will acknowledge the command with the so-called box feedback. The box feedback contains information such as whether the box has been locked or unlocked and if the box drawer is open.

In contrast to simply triggering the box, so-called box commands allow more control over what the box should do or how it should behave. Technically speaking, box commands are an extension of the simple trigger process with data that follows a specific protocol to provide additional parameters to the box.

1. Building Box Commands

There are 3 different box commands available that allow independent control over the box and car lock states. This way it is possible to keep the box locked while unlocking the vehicle. A fourth box command queries the box's status information without changing the lock state of the box or the vehicle.

In the Tapkey nomenclature, a Box Command is a TKMDefaultTriggerLockCommand instance that has also been provided with a byte array as Custom Command Data. In the example below, this byte array is represented by the variable boxCommandData.

tapkeyBleLockCommunicator!.executeCommandAsync(
    peripheralId: bluetoothAddress!,
    physicalLockId: physicalLockId,
    commandFunc: { tlcpConnection -> TKMPromise<TKMCommandResult> in
        let boxCommandData: Data = ...
        let triggerLockCommand = TKMDefaultTriggerLockCommandBuilder()
            .setCustomCommandData(boxCommandData)
            .build()

        return commandExecutionFacade.executeStandardCommandAsync(
            tlcpConnection, 
            command: triggerLockCommand, 
            cancellationToken: timeout)
    }, cancellationToken: timeout
)

There are corresponding functionalities available in the WITTE Mobile Library for creating this byte array or let's call it box command data. The class WDBoxCommandBuilder provides 4 methods to build the box command data for each of the 4 supported box commands.

1.1 Unlock car, unlock box

This function creates box command data to simultaneously unlock the car and the box. It includes an optional readNfc parameter that allows to read the UIDs of up to three NFC tags during the command execution process.

let readNfc: Bool = true // Set to true if NFC reading is required, false otherwise
let boxCommandData: Data = WDBoxCommandBuilder.buildUnlockCarUnlockBox(readNfc: readNfc)

let triggerLockCommand = TKMDefaultTriggerLockCommandBuilder()
    .setCustomCommandData(boxCommandData)
    .build()

1.2 Unlock car, lock box

This function creates box command data to unlock the car while locking the box. It includes an optional readNfc parameter that allows to read the UIDs of up to three NFC tags during the command execution process.

let readNfc: Bool = true // Set to true if NFC reading is required, false otherwise
let boxCommandData: Data = WDBoxCommandBuilder.buildUnlockCarLockBox(readNfc: readNfc)

let triggerLockCommand = TKMDefaultTriggerLockCommandBuilder()
    .setCustomCommandData(boxCommandData)
    .build()

1.3 Lock car, lock box

This function creates box command data to lock both the car and the box. It includes an optional readNfc parameter that allows to read the UIDs of up to three NFC tags during the command execution process.

let readNfc: Bool = true // Set to true if NFC reading is required, false otherwise
let boxCommandData: Data = WDBoxCommandBuilder.buildLockCarLockBox(readNfc: readNfc)

let triggerLockCommand = TKMDefaultTriggerLockCommandBuilder()
    .setCustomCommandData(boxCommandData)
    .build()

1.4 Status

This method constructs box command data to retrieve the status, which does not change the state of the car or the box but requests information about current box status. It includes an optional readNfc parameter that allows to read the UIDs of up to three NFC tags during the command execution process.

let readNfc: Bool = true // Set to true if NFC reading is required, false otherwise
let boxCommandData: Data = WDBoxCommandBuilder.buildStatus(readNfc: readNfc)

let triggerLockCommand = TKMDefaultTriggerLockCommandBuilder()
    .setCustomCommandData(boxCommandData)
    .build()

1.5 NFC Tag UIDs

This method constructs box command data to read the UIDs of up to three NFC tags.

let boxCommandData: Data = WDBoxCommandBuilder.buildNfcRead()

let triggerLockCommand = TKMDefaultTriggerLockCommandBuilder()
    .setCustomCommandData(boxCommandData)
    .build()

2. Box Feedback Evaluation

The return value of the execution of a command comprises a byte array, which we refer to as box feedback.

Box feedback provides comprehensive information about the state and status of the box's battery and drawer mechanisms. This includes the battery's state of charge, which is represented as a percentage. Furthermore, the box feedback contains details about the drawer's physical state, specifically whether it is open or closed. Lastly, the feedback includes information on drawer accessibility, denoting whether the drawer is locked or unlocked, thus indicating whether access to the key within the drawer is currently permissible.

The WITTE Mobile Library provides functionalities to parse the Box Feedback Byte Array and thus make it easily accessible for further programmatic processing.

The WDBoxFeedbackV3 class encapsulates the feedback data from a device, specifically relating to battery and drawer states. It provides detailed insights into battery charge level, charging status, charger connection, and the state and accessibility of the drawer:

batteryStateOfCharge: Returns the battery's state of charge as a percentage.
batteryIsCharging: Checks if the battery is currently charging.
batteryChargerIsConnected: Determines if the charger is connected.
drawerState: Checks the current state of the drawer.
drawerAccessibility: Checks if the drawer is unlocked and accessible.

Up to three NFC tag UIDs can be read by the box. The UIDs are also made accessible via the WDBoxFeedbackV3, provided the corresponding command has been issued:

nfcTag1Uid: The UID of the first NFC tag.
nfcTag2Uid: The UID of the second NFC tag.
nfcTag3Uid: The UID of the third NFC tag.

WDBoxFeedbackV3Parser is a utility class responsible for parsing feedback data from a byte array into a BoxFeedbackV3 object. It interprets the given data to provide structured information regarding the battery and drawer status of the device.

tapkeyBleLockCommunicator!.executeCommandAsync(
    peripheralId: bluetoothAddress!,
    physicalLockId: physicalLockId,
    commandFunc: { tlcpConnection -> TKMPromise<TKMCommandResult> in
        // ...
    }, cancellationToken: timeout)
    .continueOnUi { (commandResult: TKMCommandResult?) -> Bool? in
        let commandResultCode: TKMCommandResult.TKMCommandResultCode =
            commandResult?.code ?? TKMCommandResult.TKMCommandResultCode.technicalError

        switch commandResultCode {
            case TKMCommandResult.TKMCommandResultCode.ok:
            let responseData = commandResult?.responseData

            if nil != responseData {
                let bytes = responseData! as! IOSByteArray
                let data = bytes.toNSData()

                // Evaluate box feedback
                var bf: WDBoxFeedbackV3? = WDBoxFeedbackV3()
                let success = WDBoxFeedbackV3Parser.parseData(data, boxFeedback: &bf)
            }
        }
    }