Skip to content

KTag BLE Advertisement Specification๐Ÿ”—

Version 0.14, November 7, 2026

KTag devices communicate by broadcasting Bluetoothยฎ Low Energy (BLE) advertisements. Each advertisement carries one KTag packet in its Manufacturer Specific Data, and this page describes the format of every type of KTag packet. It replaces the KTag Beacon Specification spreadsheet.

Common Format๐Ÿ”—

Every KTag packet is a single BLE advertising data (AD) structure of type Manufacturer Specific Data, 31 bytes long. The first ten bytes are the same for every packet type:

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent Number      
(varies)0xXX      
0x10        
        
0x18       
       
Offset Size Field Value
0x00 1 Length 0x1E (30 bytes follow)
0x01 1 AD Type 0xFF (Manufacturer Specific Data)
0x02โ€“0x03 2 Company Identifier 0xFFFF (Other)
0x04โ€“0x07 4 KTag Packet Indicator 0x4B 0x54 0x61 0x67 (ASCII KTag)
0x08 1 KTag Packet Type See Packet Types
0x09 1 Event Number See below

Bytes 0x0A to 0x1E (21 bytes) depend on the packet type.

The Event Number tells apart logical instances of a packet. A device repeats the same advertisement many times so that it's heard reliably, and a receiver uses the Event Number to act on each one only once. A device increments the Event Number whenever it sends new data in a packet of that type.

Event Number vs. Event ID

Don't confuse the Event Number with the Event ID of the EVENT packet. Event IDs identify types of system-level events, while Event Numbers distinguish one packet from the next.

Packet Indicator๐Ÿ”—

Indicator Format
KTag (0x4B 0x54 0x61 0x67) Cleartext
KShh (0x4B 0x53 0x68 0x68) Encrypted (reserved for future use)

Packet Types๐Ÿ”—

Type Packet
0x00 Reserved
0x01 Instigate Game
0x02 Event
0x03 Tag
0x04 Console
0x05 Status
0x06 Parameters
0x07 Hello
0x08 Transfer

Data Types๐Ÿ”—

  • Multi-byte values are little-endian (least significant byte first).
  • SInt8, SInt16 and SInt32 are signed (two's complement); UInt8, UInt16 and UInt32 are unsigned.
  • A color is a 32-bit value 0xBBRRGGBB: brightness, red, green, blue. Because it's sent little-endian, the bytes go out in the order BB GG RR BB: blue first and brightness last.
  • A BD_ADDR is a 6-byte Bluetooth device address, sent least significant byte first: the reverse of the order in which it's usually written. For example, the address AA:BB:CC:DD:EE:FF is sent as FF EE DD CC BB AA. A target BD_ADDR of FF:FF:FF:FF:FF:FF targets all devices.
  • Unused bytes are sent as 0xFF. Receivers ignore them, so that a later version of this specification can give them a meaning.
  • 0xXX in the tables means the value varies.

0x01 Instigate Game๐Ÿ”—

Sent to start a game.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberGame Length (ms)Time Remaining until Countdown (ms)
0x010xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x10Time Remaining until Countdown (ms) (cont.)      
0xXX0xXX0xFF0xFF0xFF0xFF0xFF0xFF
0x18       
0xFF0xFF0xFF0xFF0xFF0xFF0xFF
Offset Size Field Type Notes
0x0Aโ€“0x0D 4 Game Length (ms) UInt32 0 means an untimed game.
0x0Eโ€“0x11 4 Time Remaining until Countdown (ms) UInt32
0x12โ€“0x1E 13 Unused

0x02 Event๐Ÿ”—

Signals a system-level event to one device, or to all of them.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberTarget BD_ADDR
0x020xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x10Event IDEvent Data
0xXX0xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x18       
0xFF0xFF0xFF0xFF0xFF0xFF0xFF
Offset Size Field Type Notes
0x0Aโ€“0x0F 6 Target BD_ADDR BD_ADDR FF:FF:FF:FF:FF:FF targets all devices.
0x10โ€“0x13 4 Event ID UInt32 See below.
0x14โ€“0x17 4 Event Data UInt32 Meaning depends on the Event ID.
0x18โ€“0x1E 7 Unused
Event ID Event Event Data Description
0 No Event Unused Reserved. Devices take no action when they receive this event.
1 Configure Unused The target device(s) need configuration.
2 Configured Unused Configuration of the target device(s) is complete.
3 Wrapup Complete Next State Wrapup is complete for the target device(s), which should proceed to the Next State.
4 Game Over Unused The game is over.
5 Quiet Duration (ms) The target device(s) stop BLE advertising for the given duration, or until they receive an Unquiet. A duration of 0 means stay quiet until an Unquiet. A new Quiet during a quiet period restarts the timer with the new duration. A quiet device still listens: when it receives a PARAMETERS Request Parameter Change addressed to it, it advertises its reply (for about 3 seconds in SystemK), then goes quiet again for the rest of the period. SystemK also ends a quiet period when the device leaves the Configuring state or starts playing.
6 Unquiet Unused The target device(s) may resume BLE advertising.
7 Force State Next State The target device(s) proceed immediately to the Next State. This may ruin active games, or cause a device to reprogram itself. Use with care!

The Next State values are the SystemK top-level states.

0x03 Tag๐Ÿ”—

Sent when a device tags (or heals) another device over BLE.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberTx Power LevelProtocolTeam IDPlayer IDDamage
0x030xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x10ColorTarget BD_ADDR
0xXX0xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x18Target BD_ADDR (cont.)Splash Target TeamsSplash Min. RSSIHops RemainingSplash ID
0xXX0xXX0xXX0xXX0xXX0xXX0xXX
Offset Size Field Type Notes
0x0A 1 Tx Power Level (dBm) SInt8
0x0B 1 Protocol UInt8 The tag protocol, as used for IR tags.
0x0C 1 Team ID UInt8
0x0D 1 Player ID UInt8
0x0Eโ€“0x0F 2 Damage SInt16 32767 is a one-shot kill. -32767 restores full health.
0x10โ€“0x13 4 Color Color
0x14โ€“0x19 6 Target BD_ADDR BD_ADDR FF:FF:FF:FF:FF:FF targets all devices.
0x1A 1 Splash Target Teams UInt8 0 = all teams, 1 = the originating team only, 2 = all except the originating team. 0xFF = unspecified (no team filter).
0x1B 1 Splash Minimum RSSI (dBm) SInt8 Receivers ignore the packet unless its RSSI is greater than this value. 0xFF (-1) means use the receiver's default threshold (-75 dBm in SystemK).
0x1C 1 Hops Remaining UInt8 How many more times the packet may be relayed, at most 5. 0 or 0xFF means it isn't relayed.
0x1Dโ€“0x1E 2 Splash ID UInt16 Identifies one tag across all its relays, so that each device acts on it only once. 0xFFFF means no splash ID (the packet is never relayed).

Splash Fields๐Ÿ”—

Bytes 0x1A to 0x1E are the splash fields, used by the BLE Bomb and the Bunker Buster (see Accessory Weapons and Splashes). The splash target teams are relative to the Team ID in the packet, which is the team of the originating device.

The originating device sets the splash fields. A device that relays the packet copies everything unchanged except Hops Remaining, which it decrements. This keeps the team filter relative to the originating device, and lets targeted tags still reach their target. A device in any Playing state relays a tag that has hops remaining, whether or not it was the target, and whether or not the tag affected it.

A device that doesn't support splashes sends 0xFF in all five bytes. Receivers treat such a packet as an ordinary, unrelayed tag.

0x04 Console๐Ÿ”—

Carries a text command or message.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberConsole String
0x040xXX      
0x10Console String (cont.)
        
0x18Console String (cont.)
       
Offset Size Field Type Notes
0x0Aโ€“0x1E 21 Console String ASCIIZ Null-terminated ASCII text, at most 20 characters. Bytes after the terminator are 0x00.

0x05 Status๐Ÿ”—

Reports a device's current state.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberTx Power LevelProtocolTeam IDPlayer IDHealth
0x050xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x10Maximum HealthPrimary ColorSecondary Color
0xXX0xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x18Secondary Color (cont.)SystemK Top-Level StateShots RemainingShot Capacity  
0xXX0xXX0xXX0xXX0xXX0xFF0xFF
Offset Size Field Type Notes
0x0A 1 Tx Power Level (dBm) SInt8
0x0B 1 Protocol UInt8
0x0C 1 Team ID UInt8
0x0D 1 Player ID UInt8
0x0Eโ€“0x0F 2 Health UInt16
0x10โ€“0x11 2 Maximum Health UInt16
0x12โ€“0x15 4 Primary Color Color A brightness of 0xFF indicates a False Flag.
0x16โ€“0x19 4 Secondary Color Color A brightness of 0xFF indicates a False Flag.
0x1A 1 SystemK Top-Level State UInt8 See below.
0x1B 1 Shots Remaining UInt8 0xFF means not reported.
0x1C 1 Shot Capacity UInt8 0xFF means not reported.
0x1Dโ€“0x1E 2 Unused

SystemK Top-Level States๐Ÿ”—

Value State
0 Initializing
1 Reprogramming
2 Configuring
3 Ready
4 Instigating
5 Responding
6 Counting Down
7 Interacting
8 Tagged Out
9 Consenting
10 Wrapping Up

0x06 Parameters๐Ÿ”—

Reads or changes a device's settings. Each packet carries up to two key/value pairs.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberTarget BD_ADDR
0x060xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x10SubtypeParameter Key 1Parameter Value 1Parameter Key 2
0xXX0xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x18Parameter Key 2 (cont.)Parameter Value 2  
0xXX0xXX0xXX0xXX0xXX0xFF0xFF
Offset Size Field Type Notes
0x0Aโ€“0x0F 6 Target BD_ADDR BD_ADDR FF:FF:FF:FF:FF:FF targets all devices.
0x10 1 Subtype UInt8 See below.
0x11โ€“0x12 2 Parameter Key 1 UInt16
0x13โ€“0x16 4 Parameter Value 1 Format depends on the key.
0x17โ€“0x18 2 Parameter Key 2 UInt16
0x19โ€“0x1C 4 Parameter Value 2 Format depends on the key.
0x1Dโ€“0x1E 2 Unused

A key of 65535 (0xFFFF) marks an unused key/value pair.

Subtype Meaning
0x00 Request Current Parameter Information
0x01 Current Parameter Information
0x02 Request Parameter Change
0x03 Acknowledge Parameter Change
0x04 Error Changing Parameters
0x05โ€“0xFE Reserved
0xFF Error Responding to Request

Parameter Keys๐Ÿ”—

Key Meaning Value Format
0 Reserved
1 Team ID UInt32
2 Player ID UInt32
3 Game Length (ms); 0 means untimed UInt32
4 Maximum Health UInt32
5 Secondary Color Color
6 Special Weapons Received on Game Reentry UInt32
7 Shot Capacity UInt32
8 Reload on Game Reentry UInt32 (Boolean)
9 Minimum Time Between Shots UInt32
10 Minimum RSSI to Initiate Transfer (dBm) SInt32
11 Accessory Mode: 0 = off, 1 = BLE Bomb, 2 = Bunker Buster UInt32
12 Bunker Buster Direct Damage (0 to 255) UInt32
13 Splash Damage (0 to 255) UInt32
14 Splash Minimum RSSI (dBm, -100 to 0) SInt32
15 Splash Target Teams: 0 = all, 1 = originating team only, 2 = all except originating team UInt32
16 Special Weapon Cooldown (ms); 0 means no cooldown UInt32
17 Splash Hops (0 to 5) UInt32
18โ€“10000 Reserved
10001 Shots Fired This Game UInt32
10002 Tags Received This Game UInt32
10003 Times Tagged Out This Game UInt32
10004โ€“65534 Reserved
65535 Unused Key/Value Pair

0x07 Hello๐Ÿ”—

Announces a device and what it is.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberSystemK Major VersionSystemK Minor VersionDevice TypeTeam IDDevice Name
0x070xXX0xXX0xXX0xXX0xXX0xXX 
0x10Device Name (cont.)
        
0x18Device Name (cont.)
       
Offset Size Field Type Notes
0x0A 1 SystemK Major Version UInt8
0x0B 1 SystemK Minor Version UInt8
0x0Cโ€“0x0D 2 Device Type UInt16 See below.
0x0E 1 Team ID UInt8
0x0Fโ€“0x1E 16 Device Name ASCII ASCII text, padded with 0x00. A name of exactly 16 characters fills the field and has no terminator.

The mobile apps use the Device Type to show appropriate icons, among other things.

Device Type Device
0x0000 Little Boy BLuE
0x0001 2020TPC
0x0002 Mobile App
0x0003 32ESPecial
0x0004 Test Infrastructure
0x0005โ€“0xFFFE Reserved
0xFFFF Unknown

0x08 Transfer๐Ÿ”—

Moves items, such as K-Points, from one device to another. See the TRANSFER Packet page for how the subtypes work together.

0/81/92/A3/B4/C5/D6/E7/F
0x00LengthManufacturer Specific DataCompany: OtherKTag Packet Indicator
0x1E0xFF0xFF0xFF0x4B โ€˜Kโ€™0x54 โ€˜Tโ€™0x61 โ€˜aโ€™0x67 โ€˜gโ€™
0x08KTag Packet TypeEvent NumberTarget BD_ADDR
0x080xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x10SubtypeTeam IDTransaction NumberItem 1 IDItem 1 QuantityItem 2 ID
0xXX0xXX0xXX0xXX0xXX0xXX0xXX0xXX
0x18Item 2 ID (cont.)Item 2 QuantityItem 3 IDItem 3 Quantity
0xXX0xXX0xXX0xXX0xXX0xXX0xXX
Offset Size Field Type Notes
0x0Aโ€“0x0F 6 Target BD_ADDR BD_ADDR FF:FF:FF:FF:FF:FF targets all devices.
0x10 1 Subtype UInt8 See below.
0x11 1 Team ID UInt8
0x12 1 Transaction Number UInt8 See below.
0x13โ€“0x14 2 Item 1 ID UInt16
0x15โ€“0x16 2 Item 1 Quantity UInt16 65535 means all of the item.
0x17โ€“0x18 2 Item 2 ID UInt16
0x19โ€“0x1A 2 Item 2 Quantity UInt16 65535 means all of the item.
0x1Bโ€“0x1C 2 Item 3 ID UInt16
0x1Dโ€“0x1E 2 Item 3 Quantity UInt16 65535 means all of the item.

The Transaction Number is an arbitrary number that stays the same for the whole transfer. It prevents the same transfer from being made twice.

Subtype Meaning
0x00 Reserved
0x01 Request Inventory
0x02 Inventory (information only; no transfer)
0x03 Request Voluntary (needs the player's acknowledgment)
0x04 Request Involuntary Friendly (unload)
0x05 Request Involuntary Unfriendly (steal)
0x06 Offer Unlimited (no two-phase commit needed)
0x07 Offer Atomic
0x08 Acknowledge Atomic Offer
0x09 Commit Atomic Offer
0x0A Acknowledge Atomic Commit
0x0B Echo BD_ADDR
0x0C Acknowledge Echo BD_ADDR
0x0Dโ€“0xFE Reserved
0xFF Reserved
Item ID Item
0x0000 Reserved
0x0001 K-Point
0x0002โ€“0xFFFD Reserved for future items
0xFFFE Transfer nonce (used by Echo BD_ADDR)
0xFFFF No item (ignore this ID/quantity pair)

The transfer nonce isn't a game item. It's a protocol element, and it's never added to or removed from any inventory.