DocsBluetooth LE Open APIDevice State Reference

Device State Reference

The device's live state, exposed as named values you can read, write, and subscribe to.

Device state is a flat set of named values. Each one is:

Readable — { method: "get", ns: "deviceState", prop: "<KEY>" }
Writable — { method: "set", ns: "deviceState", prop: "<KEY>", value: … }
Streamable — whenever a value changes, an event is pushed on EVENTS_OUT (while DEVICE_APP_CONNECTED is true).

Reading vs. writing in practice

Many values are populated by the device itself (GPS, battery, kill counts, ammo during play) — you'll usually read and subscribeto those rather than write them. The API allows writing any value; it's coerced to the value's type and rejected with invalidValue on a mismatch.

Device

Key	Type	Description
`FSM_STATE`	string	Current state-machine state (also on the fsm namespace).
`DEVICE_ROLE`	number	Host, client, moderator, etc.
`DEVICE_ENV`	number	Indoor / outdoor environment.
`DEVICE_VOLUME`	number	Device audio volume.
`DEVICE_BATTERY_LEVEL`	number	Battery percent, 0–100, on the Li-ion discharge curve (0% at 3.2 V a cell); 255 before the first reading. Event rate-limited (~5s).
`DEVICE_BATTERY_MV`	number	The pack's voltage in millivolts, smoothed: the one the percentage comes from. Event rate-limited (~5s).
`DEVICE_BATTERY_MINUTES`	number	Estimated minutes of play left, from the percentage and the minutes table (@battlecore/api/battery); 65535 with no pack or before the first reading. Event rate-limited (~5s).
`DEVICE_BATTERY_WARN`	boolean	The battery warning: the minutes left under device/batteryWarnMinutes (30 by default), or the low flag. What turns the tagger's battery red.
`DEVICE_BATTERY_LOW`	boolean	Under 3.2 V a cell (clears above 3.35 V): the hard floor.
`DEVICE_BATTERY_FAULT`	boolean	Under 2.8 V a cell: a dead cell or no working protection. Do not charge it.
`DEVICE_BATTERY_PACK_PRESENT`	boolean	Whether a pack is fitted; false on USB power.
`DEVICE_WIFI_NAME`	string	Provisioned WiFi network name.
`DEVICE_WIFI_STATUS`	number	0 = disconnected, 1 = connecting, 2 = connected.
`DEVICE_BLE_MAC`	string	The device's Bluetooth MAC address.
`DEVICE_BLE_COUNT`	number	Number of connected BLE devices.
`DEVICE_APP_CONNECTED`	boolean	Set true to enable the live event stream. Set on connect.
`DEVICE_HEADSET_CONNECTED`	boolean	Whether a headset is paired.
`HEADSET_BATTERY_LEVEL`	number	The linked headset's battery percent, 0–100, as it reports it; 255 while none is linked or it has not reported. Event rate-limited (~5s).
`HEADSET_BATTERY_MV`	number	The linked headset's pack voltage in millivolts; 0 while none is linked.
`HEADSET_BATTERY_MINUTES`	number	The linked headset's estimated minutes left (the headset's table); 65535 when unknown.
`HEADSET_BATTERY_LOW`	boolean	The linked headset is under 3.2 V a cell.
`HEADSET_BATTERY_FAULT`	boolean	The linked headset is under 2.8 V a cell: do not charge it.
`HEADSET_BATTERY_WARN`	boolean	The linked headset's minutes left are under this tagger's device/batteryWarnMinutes, or it is low.
`HEADSET_BATTERY_PACK_PRESENT`	boolean	The linked headset has a pack fitted.
`HEADSET_LOOK`	number	How the headset's lights look for this player: 0 as usual, 1 down between lives (a red pulse), 2 out (dark). Always 0 when the game's headsetDownFlash is off.
`DEVICE_ESP_BRIDGE`	boolean	Relay ESP-NOW mesh traffic over the event channel.
`IR_RECEIVER_ENABLED`	boolean	Whether the IR receiver is enabled.
`DEVICE_DEBUG_ENABLED`	boolean	Whether BLE debug output is enabled.

NFC

Key	Type	Description
`NFC_TAG`	string	UID (hex) of the currently-present NFC tag; empty when no tag is present. Treat a change to a non-empty value as "a tag appeared", and to empty as "removed".
`NFC_DATA`	string	The first NDEF text/URI record payload of the last tag read. Set (and streamed) just before NFC_TAG when a tag appears, so it is available when NFC_TAG changes. NOT cleared on removal.

Location

Key	Type	Description
`GPS_SATELLITES`	number	Satellites locked. Event rate-limited (~2s).
`MOTION_SPEED`	number	The player's speed from the tagger's accelerometer: 0 still, 1 walking, 2 running. Changes at most every couple of seconds (a new speed has to hold 2 s). Always 0 on a tagger with no accelerometer.
`GPS_LATITUDE`	number	Latitude. Event rate-limited (~2s).
`GPS_LONGITUDE`	number	Longitude. Event rate-limited (~2s).

Game

Key	Type	Description
`GAME_CONNECTED`	boolean	Whether the device is in a game.
`GAME_ID`	number	Current game id.
`GAME_UID`	string	The game's uid for telemetry: 32 hex characters the host made as it started the game, the same on every tagger in it. Empty outside a game, and before the start.
`GAME_STARTED_AT`	number	When the host started the game, in seconds since 1970 (UTC); 0 when the host's clock had not been set (device/time).
`GAME_PLAYER_COUNT`	number	Players in the game / lobby.
`GAME_HOST_MAC`	string	The host's MAC address (when this device is a client).
`GAME_DISPLAY_NAME`	string	Human-readable game name.
`GAME_TIME`	number	Live game clock. GET returns the running clock.
`GAME_TIME_MAX_MINS`	number	Game length in minutes (0 = unlimited).
`GAME_SCRIPT_ID`	string	BattleScript file id for the game.
`GAME_SCRIPT_LABEL`	string	BattleScript label.
`GAME_IS_TEAM_BASED`	boolean	Whether the game is team-based.
`GAME_ENVIRONMENT`	number	Where the game is played: 0 indoor, 1 mixed, 2 outdoor. The host's choice, sent to every tagger in its game.
`GAME_SHOT_RANGE_MAX`	number	The environment's maximum shot range, 1-100% of full reach, from the host's device/environmentRanges.
`GAME_RESPAWN_MODE`	number	How the game respawns a player, from its config (respawnMode). The game script gives it meaning, not the firmware: the shipped games use 0 for "pull the trigger" and anything else for "something else respawns you" (a base, a medic).
`GAME_RESPAWN_TIME_SECS`	number	How long a respawn takes, in seconds, from the config (respawnTimeSecs, 5 when absent) or the script. The respawn screen counts it down.
`GAME_LAST_STANDING_ENDS`	boolean	Whether the game ends by itself when only one side, or one player, is still in. True unless the config (lastStandingEnds) or the script turns it off, as a game that ends itself does.
`GAME_WEAPON_SLOT_1`	number	Weapon id the first slot starts holding — a reference into the game's weapons list, not a definition. 0 means the slot starts empty, which is how a game makes players find a weapon before they can shoot.
`GAME_WEAPON_SLOT_2`	number	As above for the second slot. Published but not yet equipped from: there is no weapon switching, so a second slot has nowhere to go.
`GAME_IR_PROTOCOL`	string	The game's IR protocol (irProtocol in its config): every tagger in the game shoots and hears with it. Empty outside a game, where the default (battlecore2) is used.
`GAME_IR_CARRIER_HZ`	number	The game's IR carrier in place of its protocol's own (irCarrierHz in its config): 36000, 38000, 40000 or 56000; 0 for the protocol's. The host's, sent to every tagger in its game and kept for a rejoin.
`GAME_RADAR_TYPE`	number	Motion tracker mode: 0 = off, 1 = players shown only while walking or running (MOTION_SPEED above 0, by the thresholds in motion/config), 2 = players always shown.
`GAME_TRACKER_RANGE_M`	number	Radius the motion tracker covers, in metres.
`GAME_GPS_TRANSMIT`	boolean	Whether the device broadcasts its position even with the radar off, so positions can be logged for replay. Any GAME_RADAR_TYPE above 0 turns this on regardless.
`GAME_GPS_MIN_MOVE_M`	number	Metres the player must move before their position is broadcast again. Keeps GPS drift off the air while a player stands still.
`GAME_MAP_TYPE`	number	0 = unlimited, 1 = limited.
`GAME_SCORE_BASED`	boolean	Whether this game scores points. When false the leaderboard ranks on kills alone and every player's points stay at zero. Absent means false.
`AUDIO_PACK`	string	Audio pack in use.
`TEAM_POINTS`	number	The team's total score (signed).

Player & vitals

Key	Type	Description
`PLAYER_READY`	boolean	Whether the player is marked ready.
`PLAYER_NAME`	string	Player name.
`PLAYER_ID`	number	Player / tagger id.
`PLAYER_TEAM_ID`	number	Team the player is on: 0–15 (0 red, 1 blue, 2 yellow, 3 green; 4–15 have no colour yet), or 255 for none, as in a free-for-all.
`PLAYER_SHIELD`	number	Current shield.
`PLAYER_SHIELD_INITIAL`	number	Shield the player starts with.
`PLAYER_SHIELD_MAX`	number	Maximum shield.
`PLAYER_SHIELD_FULL_RECHARGE_TIME`	number	ms to recharge shield 0→100%. 0 = not recharging.
`PLAYER_ARMOUR`	number	Current armour.
`PLAYER_ARMOUR_INITIAL`	number	Armour the player starts with.
`PLAYER_ARMOUR_MAX`	number	Maximum armour.
`PLAYER_LIVES`	number	Current lives.
`PLAYER_LIVES_INITIAL`	number	Lives the player starts with.
`PLAYER_LIVES_MAX`	number	Maximum lives.
`PLAYER_POINTS`	number	The player's total score (signed).
`PLAYER_KILL_COUNT`	number	Kills achieved.
`PLAYER_DEATH_COUNT`	number	Deaths.
`PLAYER_IS_INVULNERABLE`	boolean	Whether the player cannot take damage.
`PLAYER_IS_RESPAWNING`	boolean	Whether a respawn countdown is running.
`COUNTDOWN_SECS`	number	Live on-screen countdown in seconds (e.g. respawn). Read alongside FSM_STATE.

Weapon

Key	Type	Description
`WEAPON_ID`	number	Currently enabled weapon.
`WEAPON_AMMO`	number	Current ammo.
`WEAPON_AMMO_MAX`	number	Maximum ammo.
`WEAPON_SHOTS_FIRED`	number	Total shots fired.
`WEAPON_SHOT_POWER`	number	Current shot power (damage or healing).
`WEAPON_SHOT_RANGE`	number	How far the current weapon's shots carry, 1-100% of the emitter's full reach (50 reaches about half as far). Set from the weapon when it is equipped; each shot carries it times GAME_SHOT_RANGE_MAX.
`WEAPON_SHOT_TYPE`	number	Current shot type.
`WEAPON_SHOT_INTERVAL_MS`	number	Minimum time between shots (fire rate).
`WEAPON_SHOT_CHARGE_MIN_MS`	number	Minimum charge-up time.
`WEAPON_SHOT_CHARGE_MAX_MS`	number	Maximum charge-up time.
`WEAPON_SHOT_DELAY_MS`	number	Delay between trigger pull and firing.
`WEAPON_IS_CHARGE_BASED`	boolean	Whether the weapon must be charged before firing.
`WEAPON_IS_CHARGING`	boolean	Whether the weapon is currently charging.
`WEAPON_SHOT_CHARGE_AUTO_FIRE`	boolean	Fire on full charge vs. on trigger release.
`WEAPON_CAN_RELOAD`	boolean	Whether the current weapon can reload.
`WEAPON_RELOAD_DELAY_MS`	number	Reload time in ms.
`WEAPON_BUSY_COUNT`	number	Count of actions making the weapon busy (reloading, jammed, …). A count, not a flag — values above 1 are normal when actions overlap.
`LED_MUZZLE_FLASH`	boolean	Whether the muzzle-flash LED is on.

Reading NFC tags

Subscribe to NFC_TAG to react to tags: it holds the UID (hex) of the tag currently on the reader, and is set back to an empty string the moment the tag is removed. So a change to a non-empty value means "a tag appeared" and a change to empty means "removed".

NFC_DATA is set before NFC_TAG

When a tag appears, the device reads its first NDEF text or URI record and puts the payload in NFC_DATA — and it does so before updating NFC_TAG. Because events are delivered in order, by the time you receive the NFC_TAG change the matching NFC_DATA has already arrived. Read them together: trigger off NFC_TAG, then use the latest NFC_DATA.

NFC_DATA is not cleared on removal (it reflects the last tag read), and is empty if the tag had no readable NDEF text/URI record. Both NTAG/Ultralight and MIFARE Classic tags are supported.

Game states

The device's state machine drives what's happening in a game. Subscribe to the fsm event ({ ns: "fsm", prop: "state", value }) to follow transitions, or read the current value with { method: "get", ns: "fsm", prop: "state" }. The common gameplay states:

State	Meaning
`HOME`	Lobby / idle — looking for and counting nearby players.
`GAME_LOBBY`	Joined a game lobby, waiting for the game to start.
`IN_GAME`	Actively playing.
`DEAD`	Eliminated, awaiting respawn (trigger-pull or respawn box).
`RESPAWNING`	Respawn countdown running — see COUNTDOWN_SECS.
`GAME_OVER`	This player is out of lives (player-specific).
`GAME_END`	The game has ended for everyone.