Skip to content

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 TriggerLockCommand 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.

mBleLockCommunicator.executeCommandAsync(
    bluetoothAddress,
    physicalLockId,
    tlcpConnection ->
    {
        byte[] boxCommandData = ...
        TriggerLockCommand boxCommand = new DefaultTriggerLockCommandBuilder()
            .setCustomCommandData(boxCommandData)
            .build();

        return mCommandExecutionFacade.executeStandardCommandAsync(tlcpConnection, boxCommand, timeout);
    }, 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 BoxCommandBuilder 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. 

byte[] boxCommandData = BoxCommandBuilder.buildUnlockCarUnlockBox();

TriggerLockCommand boxCommand = new DefaultTriggerLockCommandBuilder()
    .setCustomCommandData(boxCommandData)
    .build();

1.2 Unlock car, lock box

This function creates box command data to unlock the car while locking the box. 

byte[] boxCommandData = BoxCommandBuilder.buildUnlockCarLockBox();

TriggerLockCommand boxCommand = new DefaultTriggerLockCommandBuilder()
    .setCustomCommandData(boxCommandData)
    .build();

1.3 Lock car, lock box

This function creates box command data to lock both the car and the box. 

byte[] boxCommandData = BoxCommandBuilder.buildLockCarLockBox();

TriggerLockCommand boxCommand = new DefaultTriggerLockCommandBuilder()
    .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. 

byte[] boxCommandData = BoxCommandBuilder.buildStatus();

TriggerLockCommand boxCommand = new DefaultTriggerLockCommandBuilder()
    .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 BoxFeedbackV3 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:

  • getBatteryStateOfCharge(): Returns the battery's state of charge as a percentage.
  • isBatteryIsCharging(): Checks if the battery is currently charging.
  • isBatteryChargerIsConnected(): Determines if the charger is connected.
  • isDrawerState(): Checks the current state of the drawer.
  • isDrawerAccessibility(): Checks if the drawer is unlocked and accessible.

BoxFeedbackV3Parser 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. 

mBleLockCommunicator.executeCommandAsync(
    bluetoothAddress, 
    physicalLockId, 
    tlcpConnection -> {
        // ...
    }, timeout)
    .continueOnUi(commandResult -> {
        CommandResult.CommandResultCode commandResultCode = commandResult.getCommandResultCode();
        switch (commandResultCode) {
            case Ok: {
                Object object = commandResult.getResponseData();
                if (object instanceof byte[]) {
                    byte[] responseData = (byte[]) object;

                    // Evaluate box feedback
                    BoxFeedbackV3 boxFeedbackV3 = BoxFeedbackV3Parser.parse(responseData);
                }
                break;
            }
            // ...
        }
        // ...
    })