Developer reference

Last verified 2026-10-16

This is the interoperability spec for the BRX tagger and headset: transport, framing, every known command and event with its field map, the $WEAP / $GSET / $PSET / $SIR tables, the optical IR word, the USB console, and the headset link. Every command, token, field name and wire value on this page is literal.

Credit, first. The BRX serial protocol was discovered and proven by LaserTagMods (the JEDGE / JBOX / NRFL-Bases projects, github.com/LaserTagMods). Everything on this page is an independent, clean-room restatement. We verified it on our own taggers, decoded it from public app metadata, or captured it off the air. It contains no Battle Company code or assets. If you build on this, credit them too.

Ground rule. Stock BRX firmware is never modified. Every capability below is reached over the tagger's own serial protocol, and power-cycling always restores a tagger to normal operation.

Transport, framing and safety

One text protocol, three ways in. The BRX speaks a plain ASCII, comma-delimited command language on a hardware UART. Gen1 exposes it over Bluetooth Classic, Gen2/3 over BLE, and the community drives it from a wire. The frames are identical on all three.

Who found this. Protocol discovery for the BRX platform is the work of LaserTagMods (JEDGE / JBOX). This page restates their findings independently, with our own bench verification.

Transport by generation

BLE: Nordic UART Service UUIDs

Generation detection heuristic. Power on the tagger and run a BLE scan. If it advertises the UART service it is Gen2/3. If nothing appears on BLE but the device pairs over Bluetooth Classic it is Gen1.

Frame anatomy

$ + COMMAND + (, + token)* + ,*

• ASCII, comma-delimited tokens. Starts with $COMMAND, ends with ,*.
• Empty tokens are legal and meaningful: consecutive commas mean "leave unchanged / not applicable". $SPAWN,,* (one empty token) is a different command from $SPAWN,*.
• Example: $PING,* replies $PONG,*.
• Tokens may not contain a comma, * or a line break (that is the validator in protocol.py: ^\$[A-Z0-9!]+(,[^,*\r\n]*)*,\*$).
• Notifications can arrive merged ($ALCD,…$BUT,0,1,*); split on the next $ as well as on *.

Waking a gun and holding the link

1. Connect and subscribe to the TX notify characteristic. Establishing a link is intermittent (the official app behaves the same) and the link holds once it is up. Retry. That is the fix.
2. On a fresh power-up, send $STOP,* then $PHONE,* (after a power-cycle $PHONE,* alone wakes it). A just-booted gun ignores a bare $VERSION,* until then.
3. $PHONE,* opens the event tap: the gun says "phone connected", answers $BUT,3,0,*, streams button events and $VOLTS telemetry, and locks its on-gun menu until a game is configured or it is power-cycled.
4. Idle taggers are silent: outside app mode no unsolicited messages are sent, so no button, trigger or hit traffic.
5. The official app's connect ritual (captured, fw v4.32) is $STOP,*, $PLAYX,0,*, $VOL,69,0,*, $PLAY,VA20,3,6,,,,,* ("connection established"), then once per session $NAME,<name>,* plus $VERSION,*. It never sends $PHONE,*.
6. The headset must be linked or the gun will connect, answer a quick $PING, then drop within seconds and echo nothing to config. After a gun-initiated $DISCONNECT,*, back off at least 5 s before reconnecting.

The safety model. Three layers, in order of what they protect:

1. Firmware is never written, so a power-cycle always restores a tagger.
2. A host refuses malformed frames and requires an explicit confirm for any command outside the known-safe list (below).
3. The panic sequence $CLEAR,* then $SP,99,* silences and stops a gun.

The panic sequence leaves the gun with no $SIR table, so it cannot be hit until it is re-armed or power cycled. That is intended for a panic stop and must not be mistaken for a playable state. Battle Company's official USB updater is the factory-restore path.

mcp/brx_mcp/protocol.py enforces four buckets with three outcomes, not one flat known-safe list:

1. KNOWN_COMMANDS. The instrument sends these with no confirm. Each row records the agreed token count when available, whether the effect is bench-proven on v4.32, and an evidence note. Examples include $STUN,<ms>, $BUMP in its 5-field shape, $TMP, $DIE, $TEAM, $PID, $IRTX and $RADSK.
2. CONFIRM_REQUIRED_COMMANDS. Recognised names with version-conflicted evidence: $PRES, $INVU, $BHIT and $FIREX. They remain unsupported until the named bench checks settle their shape and effect.
3. DENIED_COMMANDS. Refused even with confirm=true, each with a reason: factory restore ($FACTORY); DFU ($CDFU, $HEADDFU, $DDFU); pairing ($PAIR, $PIN, $CLEARDEVICE, $INQ, $GPAIR, $GPAIRX); the gun's own radio-module control frames ($!…, $^…, $&…); the IR word-format switch ($IRT); factory and hardware tests ($FTST, $BURN, $DUTY the laser duty cycle, $SOL, $MUZ); provisioning writes ($DTYPE, $DEV, $SITE, $TSTRNAME); $VIBTOGGLE; $ASKSN (prints the headset PIN); $RESET; the zombie headset family ($ZOM, $ZTOG, $ZON, $ZOFF, $BOOM, $ZombieKeyActive); and the USB console word SETUP. HANG_PRONE_COMMANDS is a separate list, today only $DPLAY: the send tool passes it only with confirm=true and allow_hang=true together, one frame at a time, so a supervised bench run can try to make a lock-up on demand. Both lists reach the phone app as NODE_DENIED_COMMANDS, and the phone refuses to write any of them.
4. Anything else needs confirm=true.

PANIC_SEQUENCE = ["$CLEAR,*", "$SP,99,*"]

Is the baud rate real over BLE?

No. BLE has no baud. 115200 is the UART behind the radio bridge. That is why BLE and a wire speak identical frames.

Why does my client drop at ~6.6 s?

The link holds fine once up (80 s+ sessions with the official app, multi-minute sessions with ours). Establishment is intermittent; retry in a loop. If it dies within seconds and echoes nothing to config, the headset is not linked.

Can a command brick the gun?

Nothing in the protocol writes firmware. Every state written over BLE is wiped by a power-cycle (except $NAME, which persists).

Command reference

Every known command, with args and meaning: host to tagger, tagger to host, and headset. Copy the frames exactly as written.

These tables are a summary for readers. The full row for each command, with its evidence and every retraction, is in the protocol reference. Where the two disagree, the protocol reference is right, and a repo test fails until this page agrees with it. The protocol was first discovered and proven by LaserTagMods (JEDGE / JBOX).

How to read the tables. "Direction" is host to gun (>>) or gun to host (<<). Some commands were sent and received on hardware; others carry field names taken from the Callsign app's IL2CPP metadata (names certain, wire position = declaration order) or come from LaserTagMods sources and community captures, unreproduced on hardware. Each row says which. Commands the app knows that are untested on hardware sit in their own table at the end of this section. Where a command's field map has its own section ($WEAP, $GSET/$PSET, $SIR), the row says so.

Host to tagger: lifecycle and configuration

Host to tagger: in-game effects, feedback and pools

Headset commands (host to gun to headset)

Tagger to host: events and echoes

Seen in the app's vocabulary, not exercised by us. These are facts about the Callsign app's request namespace only. On-tagger behaviour has not been observed.

Complete vocabulary from the app's own request namespace. AMMO ASKDLC ASSIST BHIT BMAP BUMP CLEAR DLC FSET GLED GREN GSET HFIRE IRTX LIFE MELEE NAME PLAY PLAYX PSET SIR SPAWN START STOP STUN VERSION VIB VOL WEAP ZOOM · headset BLINK CHASE HLED HLOOP LED · notifications ALCD BUT GOTDLC HIR HP LCD SFLASH TIME VERSION VOLTS. $PING, $TID, $SP, and the $RV/$RP/$UR/$KK/$DD family are not in it. They come from LaserTagMods and our bench. Absence from the app does not mean non-existent.

The arm sequence: from $CLEAR to a live gun

The exact frame order that takes a tagger live, respawns it, and ends the game. Send these frames in this order. We captured the order from the official app and reproduced it with our own host.

The headset is a second device and it needs time. A command that the tagger must relay to the headset is received, processed and executed there, not instantly. Send $SPAWN within about 2 seconds of a death and the headset never executes it: it stays stuck flashing the green out-blink while the gun is alive and registering hits normally, so the player looks dead while playing normally. Measured 2026-09-02: gaps of 1.0 s and 2.0 s stick, and 2.5 s, 3.0 s and 6.0 s are clean. Leave at least 3 seconds. The same applies to anything else with a headset side effect, such as $HLOOP and $HLED. Note the gun queues commands and drains them one at a time, so a frame echoing back proves the gun received it, not that the headset executed it.

$CLEAR wipes the $SIR table and the gun then ignores every hit. This is the most confusing failure mode the gun has: the gun arms, spawns, reports full pools, answers $QUERY normally and looks perfectly healthy, while every shot that reaches it is discarded. There is no $HIR, the headset stays dark, and the pools never move, so it presents as a broken headset or a dead sensor. It is neither. The $SIR matrix decides what an incoming IR word does to this gun, unmatched cells are silently ignored, and after $CLEAR there are no cells at all. Re-sending the $SIR rows alone restores it immediately. Bench-proven 2026-09-02: deterministic 5/5, and independent of how long you wait between $CLEAR and $SPAWN (tested 0.05 s to 1.0 s). Note the table SIZE does not matter, only its absence: a one-row table and the full ten-row table both registered 24/24 in an interleaved A/B.

This sequence is the official iOS app driving a live game on firmware v4.32, reproduced byte-for-byte on real taggers. Three pieces are easy to leave out, and the gun spawns wrong without them: $AMMO after spawn, $BMAP before and after spawn, and the empty token in $SPAWN,,*.

$CLEAR,*
$START,*
$GSET,1,0,1,0,1,0,50,1,*
$PSET,0,0,45,70,70,50,,H44,JAD,V33,V3I,V3C,V3G,V3E,V37,H06,H55,H13,H21,H02,U15,W71,A10,*
$WEAP,0,...                (primary)
$WEAP,1,...                (secondary)
$WEAP,4,...                (melee, always sent)
$SIR,... x10               (incoming-IR effects table)
$BMAP,0,0,,,,,*   $BMAP,1,100,0,1,99,99,*   $BMAP,2,97,,,,,*
$BMAP,3,98,,,,,*  $BMAP,4,98,,,,,*          $BMAP,5,98,,,,,*
$BMAP,8,4,,,,,*
$TID,<team>,*              (ours; the app relies on defaults)
$PLAYX,0,*
$PLAY,VA81,4,6,,,,,*       (go-live voice cue)
$SPAWN,,*                  <-- go-live (note the empty token)
$AMMO,0,36,108,1,*         <-- load magazines
$AMMO,1,6,12,1,*
$BMAP,0,0,,,,,*            <-- trigger re-mapped AFTER spawn

$BMAP,1,100 only works with two weapons loaded. The sequence above sends $WEAP,0 and $WEAP,1, so ALT cycles between them. Send one $WEAP slot and function 100 has nothing to cycle to: the gun reloads instead (bench 2026-09-17). A single-weapon loadout maps ALT to 98, the inert function, so the button does nothing.

What the gun echoes back

The config head is silent and safe. Writing $CLEAR through $TID without $SPAWN plays nothing, and a configured-but-unspawned gun ignores IR: no $HIR, no $HP. "Get some" and the cocking sound belong to $SPAWN. A head held unspawned for about 2 minutes then spawned went live with config intact.

Death and respawn are host-driven

1. Victim reports $HP,0,0,0,* then $LCD,0,0,0,<slot>,<mag>,<reserve>,*. The gun does not revive itself, and a dead gun's trigger produces $BUT events but no $ALCD decrement (it cannot fire).
2. The app sends $HLOOP,0,0,* about 1.7 s after death.
3. After the game's respawn delay (the app's own timer, about 10 s in the capture; community reports a per-death ramp capping at 45/90 s) the host sends $SPAWN,,*.
4. Gun echoes $LCD,45,70,0,0,36,216,*: HP, armor and ammo restored with no $AMMO needed.
5. A dead gun in a hosted game ignores incoming IR: 448 distinct words, including every grenade-beacon shape, failed to revive one. Only the host can. The one exception is fn 34, which registers a $HIR on a dead gun and moves nothing (bench 2026-09-18). The 2018 BC app's revive beam is fn 34 on protocol 14, counted by the phone. Our 448-word test had no fn 34 or fn 35 row in the table.

After a BLE drop, re-send the whole head. Re-sending the full sequence ($CLEAR, $START, …, $SPAWN,,*, $AMMO) on a fresh link brought a gun back in every bench case.

# Clean end-of-game, as the official app does it (note the ~3.9 s settle before the last $PLAY):
$VOL,69,0,*
$HLED,,6,,,,,*
$STOP,*
$CLEAR,*
$PLAY,VSF,4,6,JAY,,,,*     # victory sting (slot 1) + "victory" announcer (slot 4); solo game: $PLAY,VS6,4,6,,,,,*

Do I need the reload-handle pull?

No. The manual's reload-handle pull is the local start; $SPAWN,,* is the remote one. Both exist.

Where do respawn time, game time, lives and score-to-win go?

Nowhere on the gun. Three captures at respawn 5/15/30 s gave byte-identical $GSET/$PSET. Your host keeps the clock.

Is the second $BMAP,0,0 (after $SPAWN) needed?

Yes. Omit it and the trigger is dead.

$WEAP: the weapon definition

Forty-odd comma-separated tokens make a weapon out of data: damage, cadence, fire mode, ammo, sounds, IR type. This section maps every token.

A weapon is data, not firmware. The gun has no weapons baked in; the host sends a full $WEAP frame into one of six slots (0-5) by Callsign convention, not a firmware limit: the 2018 BC app loaded weapons into slots 0-7, with melee in slot 7 ($BMAP,8,7). The field names come from the Callsign app's metadata (declaration order = wire order); the positions and meanings below were then pinned by capturing the 19 stock weapons (20 frames) with the operator naming each one, and by flipping single tokens on a live gun.

# Two known-good frames (slot 0 Assault Rifle, slot 1 Charge Rifle):
$WEAP,0,,100,0,0,24,0,,,,,,,,100,850,32,32768,1400,0,0,100,100,,0,,,R01,,,,D04,D03,D02,D18,,,,,32,9999999,75,,*
$WEAP,1,,100,8,0,150,0,,,,,,,,1250,850,100,32768,2500,0,14,100,100,,14,,,E03,C15,C17,,D30,D29,D37,A73,C19,C04,20,150,100,9999999,75,,*
# A captured Shotgun (slot 1): the only stock weapon with the extra-headset block populated:
$WEAP,1,2,100,0,0,45,0,,,,,,70,80,900,850,6,24,400,2,7,100,100,,0,,,T01,,,,D01,D28,D27,D18,,,,,6,12,75,30,*

Token map (0-indexed: $WEAP,<t0>,<t1>,…,*; the slot is t0)

Two positions to get right.

1. The metadata's field order has rateOfFire before weaponSwapDelay, but the wire has the rate at t14 and the constant 850 at t15. A compiler that trusts the field order ships every weapon at 10 shots/s.
2. Keying weapons by their fire sound (t27) silently merges distinct weapons. The Rocket Launcher and the Rail Gun both fire C03.

Stock weapon signatures (fire sound to weapon to behaviour, as named by the operator at capture)

Overheat is a balance lever on any weapon. Set t38 to switch the mechanism on, t24 for the heat per shot and t35 for the overheat sound, and the live heat gauge streams in $ALCD token 5. Measured on 2026-09-17: an Energy Rifle at t38 = 150 climbed about 3 per shot, locked the trigger out at heat 99 after about 30 rounds and read 102 while locked. Cooling is per weapon, so measure it. The Charge Rifle cooled about 30 per second by itself and restarted from 0 after a 4.8 s lockout. The Energy Rifle did not cool at all while locked: only the reload lever vented it, about 35 per pull, and the same held pull recharged the cell. A HUD heat bar needs no new protocol.

Accuracy is a live per-shot value, not a static stat. $ALCD token 2 is a hit probability, not a threshold: a shot fired below the ceiling can still emit IR at magnitude 0, which is the miss the manual describes elsewhere. It starts each life at t21 and drops under sustained fire in five steps of one fifth of the t21-to-t22 range, until it reaches t22 and holds. The steps do not land one per shot: the two walks below reached their floor on shot 8 and shot 11. It resets to t21 on reload. A native time-based recovery races the drop, so the fire interval decides how hard the model bites: single shots about 2 s apart at t22=0 held a flat 80 and never went lower, while a held trigger reached 0 in eight rounds. The recovery rate itself is not yet measured. Two full-magazine walks on the Assault Rifle (t14=100 ms, trigger held, t21=100):

• t22=100 (stock): token 2 held at 100 for all 32 rounds. No drift at all.
• t22=0: 80, 60, 40, 40, 40, 20, 20, 0, then 0 for the rest of the magazine.
• t22=50: 90, 90, 90, 90, 90, 80, 70, 70, 70, 60, 50, then 50 for the remaining 22 rounds.

Each run fell in five steps, and each step is one fifth of that weapon's ceiling-to-floor range: steps of 20 when the floor is 0, steps of 10 when it is 50. The number of shots differed (8 and 11), so how many rounds it takes to reach the floor is not characterised from two runs. Stock ships t21 = t22 = 100 on every weapon, which is why every capture ever taken of this model showed it inert. The exact hit probability at a given accuracy value is not calibrated; do not treat it as a percentage.

Can I build a semi-auto rifle?

Yes. Set $WEAP t20 to 7: one shot per trigger pull. The Shotgun and the Rocket Launcher both ship that way.

What bounds a custom weapon?

The firmware's behaviour vocabulary: the DamageType and PowerType enums, ReloadType, six slots, and the 2,477 on-gun sound ids. Any combination with arbitrary numbers is buildable; a brand-new damage behaviour is not.

Does a $WEAP re-push mid-game keep the ammo count?

No. It resets mag/reserve to the frame's values. Re-send $AMMO.

$GSET and $PSET: game and player settings

These two frames set the on-gun rules and the player's pools, identity and voice pack.

$GSET,<t1>,…,<t8>,*, validated against the captured $GSET,0,0,1,0,1,0,50,1,*

There is no respawn, time, lives or score token. Three captures at respawn 5/15/30 s and different clocks produced byte-identical $GSET and $PSET, and the 8-field map from the app metadata contains none of them. Those live in the host. Stop looking.

$PSET,<t1>,…,*, sample $PSET,6,0,45,70,70,50,,H44,JAD,V33,V3I,V3C,V3G,V3E,V37,H06,H55,H13,H21,H02,U15,W71,A10,*

The voice pack, slot by slot. The alignment was confirmed on the bench on 2026-09-07: a voice line placed in the hitShield position was heard on a shield hit, and an intermediate "the slots are swapped" reading was retracted after a control showed the sound had not moved. That bench result was measured on the token positions below, which is why the table still holds: the ids on the wire are unchanged, only the field name bound to each token is corrected here, from Battle Company's own sheet, which names seventeen fields for seventeen wire slots (t7-t23), not sixteen from t8.

Our own frame builder (gameconfig._PSET_HEAD) has always sent ids in these positions, and two of them are ear-confirmed against this corrected map: H06 at t16 is the near-miss (bench 2026-09-09), and the hitCrit slot at t20 (bench 2026-09-11).

Three more things about this tail, all measured the same day:

• An empty effect field is not silence. It falls through outward to the neighbouring pool's clip. An empty hitShield plays the armor clip. hitHp is silent when empty only because it is the innermost pool, with nothing further in to fall to. This is not the same rule as an empty voice field, which really does make the gun say nothing.
• energyShieldLoop is a real loop. It runs for as long as the shield is up and survives a $PSET rewrite. Callsign's stock A10 is a ticking clip, so it plays under every shield-band hit. Refuted 2026-09-25: $PLAYX,0,* does not stop it while the shield is up. Only the shield reaching zero stops it, and it can restart after a delay of 15 seconds or more once the shield is up again. Treat it as blocking the audio queue for the rest of the shield's life, not just until the next $PLAYX. Open BRX ships this field empty, so the gun plays no loop and a queued clip plays at once (F347).
• A non-empty $SIR <soundID> overrides the $PSET sound on the row that fired. The two do not layer, so per-weapon and per-pool audio compete for one hit.

Numbering a fleet is one token. Give every gun a distinct $PSET token 1 at arm time and per-player kill attribution is BLE-native: no cable, no IR receiver. Show operators 1-based ids; write id − 1.

$SIR: the incoming-IR effects matrix

What an IR hit does to a gun is decided by the victim's table, not by the shooter's weapon. This section shows how to write that table.

The key idea. An incoming IR word carries a 4-bit protocol (B) and a 2-bit subtype (U). The victim looks up the $SIR row with that <protocol, subtype> key; the row's function decides what the word's 8-bit magnitude is applied to: damage, heal, armor, shield, or a status. No matching row means the hit is silently ignored. The same is true of a wrongly-teamed shot: damage applies only from an enemy team and support only from your own, and a rejected frame emits no $HIR at all. It never reaches BLE. 16 × 4 = 64 addressable cells, all writable per game over BLE.

Battle Company's own sheet names p5-p8: p5 Modifier, p6 RangeOutdoor, p7 Random, p8 RangeIndoor. Our own five-shape probe found p5-p8 do not scale damage.

# The stock 10-row table the official app sends (Team Arena):
$SIR,0,0,,1,0,0,1,,*        standard weapons (AR, SMG, snipers, shotgun…): plain damage
$SIR,0,1,,36,0,0,1,,*       Force Rifle / Sniper Rifle: fn 36 (floor of magnitude ×1.25)
$SIR,0,3,,37,0,0,1,,*       AMR / Bolt Rifle / Burst Rifle: fn 37 (magnitude ×2)
$SIR,1,0,H29,10,0,0,1,,*    respawn + add HP
$SIR,2,1,VA8C,11,0,0,1,,*   add shields
$SIR,3,0,VA16,13,0,0,1,,*   add armor
$SIR,6,0,H02,1,0,90,1,40,*  Rail Gun
$SIR,8,0,,38,0,0,1,,*       Charge Rifle (fn 38 HALVES the magnitude, F225 -- MC re-keys this cell to fn 1)
$SIR,9,3,,24,10,0,,,*       Energy Launcher (fn 24: a phantom hit generator, see the function map)
$SIR,10,0,X13,1,0,100,2,60,* Rocket Launcher
$SIR,11,0,VA2,28,0,0,1,,*   Tear gas
$SIR,13,0,H50,… / 13,1,H57 / 13,3,H49   Energy Blade / Rifle Bash / War Hammer (melee)

Function map. Measured at magnitude 20, baseline HP 45 / armor 70 / shield 0, at the gun-body sensor ($HIR tok1 = 4) from about 40 cm. Protocol independence is measured for 10 of the 41 functions (fn 1, 3, 8, 23, 24, 25, 26, 27, 28, 35). Those ran on the enemy team at subtype 0 only, across protocols 0, 5, 7, 9 and 10. That is 50 cells, none of which varied. Applying the result to the grant and ally functions is an extrapolation, not a measurement. The two multiplier functions, 36 and 37, were measured again on 2026-09-02 across magnitudes 20, 40, 9 and 7 and across 8 different $SIR row-tail shapes, 16 trials, each with an fn 1 control that had to read the magnitude exactly. The row tail does not change the multiplier.

The headset-dome question is now answered (bench 2026-09-11). Fn 36 and 37 only scale on the headset dome (sensor 0 measured; sensors 1-3 untested): the gun body applies the raw magnitude for every function, fn 36/37 included. The headset scale is a function of the $GSET critical shot modifier (t7): fn 36 lands floor(magnitude times (1 plus t7/200)), fn 37 lands floor(magnitude times (1 plus 2 times t7/100)). At t7 equal 50, that is the x1.25 and x2 read on 2026-09-02, so both earlier readings were correct at once; the 2026-08-27 run that read x1.0 was pinned to the gun body the whole time. A t7 equal 0 closing control read fn 37 back to a plain x1 on the headset, confirming t7 as the driver.

Support functions are team-gated in firmware. With $GSET friendlyFire = 0, heals/armor/shield grants register only from a same-team source, and damage registers only from another team. Set friendlyFire = 1 and everything lands from anyone. A medic gun enforces "allies only" with zero host logic (one 2026-09-07 bench run registered team hits the other way round and is still unexplained; treat the rule as documented, not proven).

• applied (gun body) = magnitude. applied (headset dome; sensor 0 measured, sensors 1-3 untested) = magnitude × fn multiplier, and only fn 36/37 carry one: fn 36 is 1 + $GSET t7/200, fn 37 is 1 + 2 × $GSET t7/100. The $HIR crit bit (token 6) is a separate field that read 0 on every headset hit measured; it is not what drives this. The critical shot modifier (t7) is a per-game tunable: t7=0 disables the fn 36/37 scaling on the headset, t7=100 triples fn 37 (×3) and lifts fn 36 to ×1.5. The Callsign capture carries t7=50, which is why fn 36/37 read as a fixed ×1.25/×2. Open BRX compiles t7=0, so both land ×1 on the headset as well: four of the five hit sensors are on the headset and BRX players aim there.
• Drain order: shields, then armor, then HP. Armor absorbs 1:1 with no per-hit cap; overflow spills into HP (a sniper's 80 split exactly 70/10).
• Heals clamp at the pool max. Magnitude 200 is a fill, not a stack.
• No function is a damage-over-time. fn 24-27 repeat a hit that moves no pool (the row above); no function drains a pool over time.
• Dead guns accept no IR in app mode, with one exception: fn 34 registers a $HIR on a dead gun and moves nothing (bench 2026-09-18). A native game's Respawn station beacon does revive an armed dead gun (see Native emissions captured off the air below).
• A magnitude-0 word is a miss, and it is invisible over Bluetooth. The victim's gun vibrates and plays its $PSET miss sound, but emits no $HIR and no $HP at all (bench 2026-09-09, against a same-aim magnitude-9 control that produced both). A miss reaches the player and reaches the software not at all, so nothing on either phone can react to one.

Is there a stun?

Yes. $STUN,<ms>,* is a native, silent stun on v4.32 (bench 2026-09-18): it blocks the trigger for the given time, then the gun fires normally again. The gun plays no sound of its own, so the host must play the cue. See the $STUN row above. Over IR there is no stun function: $SIR fn 23 is the only function that visibly changes anything without touching a pool, and it leaves the gun firing. The Callsign app's own abilities are a separate matter: it ships stun content of its own, such as the Sentinel's EMP blast and the Concussion Grenade, driven by app-side logic this page does not cover.

Can I read a native game's $SIR table?

No. The gun never reports it. Capturing an ability's IR word tells you its protocol, not what a native victim binds to it.

Which protocols are free?

Stock uses 0, 8, 10, 11, 13 and 15 (grenade beacon); the app's table also ships rows on 1, 2, 3, 6, 9. Jay's sample arm sequence uses protocol 4 too ($SIR,4,0,,1,0,0,1,,*, a "captured flag pole" row), so protocol 4 is not free either. Truly unused: 5, 7, 12. Every cell is still re-definable per game, since you push the table.

Events: what the gun tells you

Hits, health, HUD echoes, buttons and telemetry, plus the proof that the gun keeps no game state.

$HIR,<sensor>,<irProto>,<shooterId>,<shooterTeam>,<magnitude>,<crit>,<subtype>,*

Not every $HIR is damage. Pickups, heals and status effects arrive on the same message type. The protocol/subtype tells you which row fired.

The other events

The gun keeps no game state. Three separate proofs:

1. Three captures at respawn 5, 15 and 30 s produce byte-identical config. Nothing on the wire encodes a respawn time or a clock.
2. The complete end-of-game tail is $VOL, $HLED, $STOP, $CLEAR, $PLAY. The app never asks the gun for a score.
3. Reconnecting after out-of-range play yields zero frames, and a bare $UP,* gets no reply.

The phone tallies $HIR/$HP live, and it is the only place the score ever existed. Anything needing respawn, a clock or scoring needs a host in range for the whole match.

Per-player attribution and native kill feedback over BLE: the recipe

1. At arm time give every gun a distinct $PSET token 1 (0-63) and a $TID.
2. On the victim, store <shooterId, shooterTeam> from each $HIR; when $HP,0,0,0 arrives, the stored shooter gets the kill.
3. Send the shooter's gun $SFLASH,* (green-sight kill confirm) and $PLAY,,4,6,V3A,,,,* ("kill" on the announcer slot). The official app does exactly this, three kills giving three pairs.
4. Score lines go to every gun's announcer slot from its own host: on a lead change, $PLAY,,4,6,VB17,,,,* ("takes the lead"). Nothing propagates gun-to-gun; there is no nRF score channel to discover.
5. Game end: $PLAY,VSF,4,6,JAY,,,,* on the winner's guns (victory sting plus "victory").

Why does a capture show shooter id 0,0?

Every gun on that capture sat on the default id. The field is always present; $PSET token 1 is what makes it vary.

Why is $SFLASH in the victim's capture "never near a hit"?

Because a kill you score is invisible in your own $HIR/$HP stream. Correlate it with $BUT trigger bursts.

Can a dead gun fire?

No: $BUT,0,1/0 with no $ALCD decrement.

The IR word: what a shot carries through the air

A 25-bit pulse-width-encoded word on a 38 kHz carrier, decoded from LaserTagMods' base-station source and verified on our own receiver and emitter. Read this section if you are building your own IR sender or receiver.

Credit. The layout was decoded from LaserTagMods' NRFL-Bases node1.ino (a referee-free domination base that receives BRX shots), then bench-verified: timings, bit count, field offsets and the parity rule were all confirmed by pushing known $WEAP frames over BLE and watching only the expected bits move. A stock tagger then accepted a fully synthetic word from our emitter (invented player 42 / team 2 / damage 33 landed as a real $HIR and killed the player).

Physical layer

Sync gating. A > 1500 µs sync gate is not BRX-unique (a Sony SIRC remote's 2390 µs header passes it). Bound sync to about 1800-2200 µs and require 25 bits plus the parity rule.

Word layout (transmit order after sync; 25 bits)

A genuine captured melee swing decodes as 1101000111010101101000110 = protocol 13, player 7, team 1, magnitude 90, crit 0, subtype 1.

Parity: what genuine frames emit vs what the gun checks. Real BRX frames set Z by parity over bits 0-22: odd number of ones gives 01, even gives 10 (4/4 captured frames). But the gun's acceptance test is only Z0 ≠ Z1: 01 and 10 both land 8/8, 00 and 11 are rejected 0/8. Compute the true parity for fidelity; use the mismatch to tell your own traffic from a real gun's.

def encode_word(proto: int, player: int, team: int, magnitude: int, crit: int, subtype: int) -> str:
    """25-bit BRX IR word as a bit string (MSB of each field first), Z = genuine-frame parity."""
    bits = (f"{proto & 0xF:04b}{player & 0x3F:06b}{team & 0x3:02b}"
            f"{magnitude & 0xFF:08b}{crit & 1:01b}{subtype & 0x3:02b}")
    ones = bits.count("1")
    return bits + ("01" if ones % 2 else "10")

def decode_word(bits: str) -> dict:
    assert len(bits) == 25
    payload, z = bits[:23], bits[23:]
    return {
        "proto": int(payload[0:4], 2), "player": int(payload[4:10], 2),
        "team": int(payload[10:12], 2), "magnitude": int(payload[12:20], 2),
        "crit": int(payload[20]), "subtype": int(payload[21:23], 2),
        "accepted": z[0] != z[1],
        "parity_matches": z == ("01" if payload.count("1") % 2 else "10"),
    }

Native emissions captured off the air

Headset emission cannot be forced over BLE. $IRTX, $HFIRE, $MELEE and $BHIT produced zero IR with a receiver control passing before and after. The headset emits only for a physical melee swing and for the Sentinel death-nova. A physical melee swing works in a compiled, host-driven game too, with the shipped $WEAP,4 melee frame and $SIR,13,* rows (bench-confirmed 2026-09-24, two guns, two hits): it is not native-game-only. An emitter A/B (bench 2026-09-24, small n) confirms the swing itself leaves the shooter's headset, not the barrel: covering the barrel by hand still landed a hit, and covering the headset domes landed none in two swings.

Do I need a victim gun to test an emitter?

No. A VS1838B on an ESP32 decodes the word, and the sync/mark timings above are the acceptance spec.

Can a station revive a dead player by IR?

Not in a hosted game. There a dead gun ignores IR, except that fn 34 registers a $HIR and moves nothing, so the host can see the beam and revive the gun over BLE. The 2018 BC app's revive beam used $SIR fn 34 on protocol 14. In a native game, yes: the Respawn station beacon revives a dead gun that the station armed (see Native emissions captured off the air).

Why do my captured frames come out as prefixes (16/17/20/21 bits)?

Your capture sketch is printing while the next frame lands. Turn the RAW dump off.

The USB serial console: QUERY and SETUP

The micro-USB "Programing Port" is a Teensy serial console with two commands. It is not the $ protocol and not SSH.

The BRX has two ports: charging, and a separate micro-USB "Programing Port". Plugged into a computer it enumerates as a Teensyduino USB Serial CDC device (Windows COMx, macOS /dev/tty.usbmodem*, Linux /dev/ttyACM*, VID 16C0). Baud is ignored. This is what the community means by "PuTTY into the tagger". The command set came from LaserTagMods' headset-pairing note.

What the port does and does not do

QUERY
Gun Info
Gun Version: v4.32
Serial Number/Head PIN: <SERIAL>      <- matches the sticker on the paired headset
Gun Name: Tactix2                     <- the field $NAME writes
Headset Version: hds.59               <- reads '?' briefly after a power-cycle until the headset re-handshakes
Gun: 7.671 VOLTS
PlayerID 0                            <- device-level player id (separate from the per-game $PSET id)
FieldID1
NRFhost 1
NRFslave 1
devHost 1                             <- developer/host image, not retail
Head: 3.837 VOLTS                     <- headset battery
Head Tested:
Head BURN in test: 0
Gun BURN in test: 3hours28minutes
Grenade Pin: <PIN>
Laser: 16.9 mW
PCB-5
BTchip- 4
BT central V: devhost.03

Real-format quirks the parser has to survive: Gun Name is NUL-padded, lines end \r\r\n, Laser can read UNTESTED instead of a number, Grenade Pin is a real non-zero value. brx-mcp ships parse_query() and python -m brx_mcp usb-query [port], which saves a backup to ~/.brx-mcp/device-backups/.

SETUP: the provisioning/re-pair path (identity lives here)

1. Run QUERY on both gun and headset-side records first; SETUP on the gun asks for the headset's serial number. That is the gun to headset pairing mechanism.
2. The "Factory Defaults" banner is a mode header, not an action: entering SETUP and power-cycling out changed nothing (field-by-field diff).
3. The community's "change tagger ID / re-pair the headset" procedure is this console (LaserTagMods' headset-pairing note); the identity fields it concerns are the ones QUERY prints: PlayerID, FieldID, Serial Number/Head PIN, Grenade Pin.
4. Only the first prompt (the headset serial) has been walked on our bench. Do it only on a gun you can afford to re-pair.
5. For per-game identity you do not need this: $PSET token 1 over BLE sets the player id each game.

Firmware backup is impossible; do not reflash. Teensy's HalfKay bootloader is write-only by design, so no image can be read back. Rollback depends entirely on Battle Company supplying the original image. The official app's version gate (supports "until v2.01e") is an upper bound; it warns and still runs a game.

Community fixes, from Jay's JEDGE install document (untested by us):

• For a Bluetooth fault: send QUERY, then BLUETOOTH, then 4, then Disconnect.
• For a PCB fault: send QUERY, then PCB, then 4.

We do not record any code, PIN or unlock value here.

Is $QUERY,* over BLE the same thing?

No. Over BLE it returns a $-framed status array with no serial, PIN or version. The device record is USB-only.

What is the advertised BLE name vs Gun Name?

Two fields: the advertisement is Tactix-XXXX from the MAC tail; Gun Name is what $NAME writes.

Headset, link and what survives

Which state lives where, and what a BLE drop, a headset switch-off, or a power-cycle each wipe. Read this before you write code that reconnects to a gun.

State survival matrix

Headset off means no BLE. Switching a linked headset off makes the gun send $DISCONNECT,* and drop. A headset-less gun "connects", answers a quick $PING, then dies within seconds and echoes nothing to a config head. A power-cycled gun needs its headset re-linked before BLE holds. A held link plus $ALCD echoes is the headset check. There is no dedicated probe. The official app silently drops a headset-less gun within about 1.2 s.

Headset behaviours (native and autonomous: they work under any host's game head)

Other headset facts

Screamers. A tagger left powered all day can stop holding BLE. It still advertises, but the connection drops or hangs. The community calls this the "screamer" state. Power-rest guns between sessions; keep them charged (firmware will not re-pair below a battery threshold).

What a gun answers in each state, and other bench facts (2026-10-16)

All bench-proven on v4.32 (Tactix-9498 and Tactix-E20D, 2026-10-16).

• Three states after a reset. A gun that was just power-cycled answers nothing at all before $START or $PHONE: $LIFE,0,0,0, $QUERY, $AMMO and $VERSION all get no reply, and no $VOLTS arrives for over a minute. $PHONE,* wakes it, but the first read then answers all zeros ($HP,0,0,0, which looks like a death). After $START, $QUERY answers $LCD,0,0,0,0,0,0 and an array with every field 0. After a $CLEAR teardown the gun keeps stock pools ($LIFE,0,0,0 gives $HP,45,70,0) and $QUERY gives $LCD,45,70,0,0,0,0 with every weapon field empty. Treat all-zero weapon fields as "the head is gone".
• An unspawned but configured gun answers $QUERY with $LCD,0,0,0,4,1,0 (slot 4, not a live slot 0). The array body arrives about 8 s late and has no closing *, as on a dead gun. A later $SPAWN still lands normally.
• The death $LCD reports the live slot. A kill while the gun was on slot 1 gave $LCD,0,0,0,1,5,24 (slot 1, magazine 5, reserve 24). The $QUERY reply's $LCD also carries the live shield in token 3.
• $GLED has no blink. Token 6 values 1, 2, 3 and 400 all gave solid LEDs. Blinking is done by the host.
• ALT swaps during a stun disarm, and melee still works. With both slots disarmed ($AMMO zeroed), a press of ALT still swaps the active slot, and a melee swing still emits the melee word (protocol 13). A stun therefore jams firing only.
• The stock gun sometimes ignores the first slot change after a $SPAWN, a re-arm or a pickup equip, and it ignores ALT while a reload runs. A host must confirm a swap from the next $ALCD, not assume it.
• Every energy weapon refills on a tap. The Energy Rifle, Plasma Sniper and Rail Gun refill after a 50 ms lever tap exactly as after a hold, at the weapon's reload time (t19) plus 0.5 to 0.6 s.
• Team mode drops a teammate's word inside the gun. With distinct player ids on one team, 12 shots from a teammate produced no $HIR and no damage. The same shooter on another team produced $HIR and damage.
• $SIR protocol 11 function 24 registers a hit with zero damage, with no damage over time and no native poison sound.

Tooling and captures

The brx-mcp command line and MCP server, which is how this project drives a tagger, is documented in the mcp/ directory of the repository, in its README.md.

How every fact on this page was captured, and how to take the next capture, is the capture runbook.