Skip to content

BLE TRANSFER Packet🔗

The KTag TRANSFER packet (hex 0x08) implements a type of two-phase commit protocol to transfer items from device to device.

First Use Case: K-Point Collection🔗

The Transfer packet was first implemented to enable a game feature called K-Point Collection. The feature works like this: there are one or more K-Point Fountains, usually implemented as phones running the Android KTag Apps, which periodically offer K-Points by means of the Offer Unlimited subtype of the Transfer packet. Each KTag device which receives such a packet addressed to it (or broadcast) will add the quantity of each item in the packet to it's own inventory. The Transaction Number is used to limit the number of actual transmissions at the application level, since the BLE advertisement gets repeated by the Fountain for robustness.

Once a player has obtained a K-Point (or K-Points) on his device, he can return to his Collection Point (again, usually a (different) phone running the Android KTag Apps), where the Collection Point will initiate a Transfer automatically by means of the Request Involuntary Friendly subtype of the Transfer packet. The player's device then responds by initiating a two-phase commit transfer of the K-Points in its inventory (see the example below).

Before the Transfer: Querying and Reporting Inventory🔗

It is sometimes useful for one KTag device to ask another KTag device about what items it is carrying. This is accomplished with the Request Inventory subtype of the Transfer packet. Devices, upon receiving a new Request Inventory addressed to them or broadcast, should respond with an Inventory subtype of the Transfer packet. Note that neither of these results in the transfer of any items; these packets are informational only.

Initiating a Transfer🔗

Request Voluntary (Ask)🔗

This subtype attempts to initiate a TPC transfer by requesting it of a device. The receiving device prompts its operator for permission; if agreed to, the transfer can proceed.

Request Involuntary Friendly (Unload)🔗

This subtype initiates a TPC transfer by requesting it of a device on the same team. The receiving device confirms the same team, and then proceeds automatically.

Request Involuntary Unfriendly (Steal)🔗

This subtype initiates a TPC transfer by requesting it of a device on a different team. The receiving device confirms the team is not the same as its own, and then proceeds automatically. Other features of the game control when and if stealing items is allowed.

Example TPC Transfer initiated by Request Involuntary Friendly (Unload)🔗

It the example below, Device A wished to send an item to Device B.

sequenceDiagram
    participant A as Device A (Sender)
    participant L as BLE
    participant B as Device B (Receiver)

    Note over A,B: Item transfer begins

    A->>L: 1. Offer with transaction number = 1 (request to send item)
    L-->>B: 1. Offer (tn=1, delivered)
    B->>L: 2. Offer Acknowledged (tn=1, ready to receive)
    L-->>A: 2. Offer Acknowledged (tn=1, delivered)

    Note over A: Send item

    A->>L: 3. Commit (tn=1, payload)
    Note over A: A deducts the item from its inventory.
    L-xB: 3. Commit lost in transit ❌

    Note over B: Timeout — no token received, so resend acknowledgement

    B->>L: 4. Offer Acknowledged (tn=1, ready to receive)
    L-->>A: 4. Offer Acknowledged (tn=1, delivered)

    Note over A: Duplicate acknowledgement — Retransmit commit

    A->>L: 5. Commit (tn=1, payload)
    Note over A: A DOES NOT deduct the item again, since the tn is the same.
    L-->>B: 5. Commit (tn=1, delivered) ✓

    Note over B: B credits the item to its inventory, and sends acknowledgment

    B->>L: 6. Commit Acknowledged (tn=1 confirmed)
    L-xA: 6. Acknowledgement lost in transit ❌

    Note over A: No Acknowledgement — retransmit commit

    A->>L: 7. Commit (tn=1, payload)
    L-->>B: 7. Commit (duplicate, tn=1)

    Note over B: Duplicate detected — discard & re-ACK

    B->>L: 8. Commit Acknowledged (tn=1, re-sent)
    L-->>A: 8. Commit Acknowledged (delivered) ✓

    Note over A,B: Item successfully transferred