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(whileDEVICE_APP_CONNECTEDis true).
Reading vs. writing in practice
invalidValue on a mismatch.Device
| Key | Type | Description |
|---|---|---|
FSM_STATE | string | The state the tagger is in, to read. Its changes come as fsm/state events, not as deviceState ones. |
DEVICE_ROLE | number | Host, client, moderator, etc. |
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_IP | string | The tagger's address on the WiFi network once it has one; empty when not connected (cleared on disconnect, never left stale). |
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 | Whether an app is connected, which turns the live event stream on: true while a Bluetooth connection that has written to the app API is open (a phone, the Device Manager, a watch), or once the USB console has spoken it. Worked out from the connections: a headset's or another device's connection going leaves it alone, and it goes false when the last app connection closes (firmware 1.0.1069). An app may still set it. |
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. |
HEADSET_COLOUR | number | The colour the headset's headband rests on in place of the team colour, 0xRRGGBB (r*65536 + g*256 + b); 0 for none. Set by the game script (rgb.setHeadsetColour: the Juggernaut wears its colour), pushed to the headset once on a change, cleared at the end of the game. |
DEVICE_HEAP_FREE | number | Free internal RAM in bytes, polled every couple of seconds. Internal RAM is the scarce one. Event rate-limited (~1s). |
DEVICE_HEAP_LARGEST | number | The largest free block of internal RAM in bytes: what an allocation actually needs. It falls before DEVICE_HEAP_FREE does when the heap fragments. Event rate-limited (~1s). |
DEVICE_STACK_FREE | number | The main loop task's stack low-water mark in bytes. Event rate-limited (~1s). |
DEVICE_PSRAM_FREE | number | Free PSRAM in bytes. Event rate-limited (~1s). |
DEVICE_ESP_BRIDGE | boolean | Relay ESP-NOW mesh traffic over the event channel. |
Audio board
| Key | Type | Description |
|---|---|---|
AUDIO_VERSION | string | The audio board's firmware version; empty until it answers. |
AUDIO_WIFI_STATUS | number | The audio board's WiFi: 0 nothing stored, 1 stored but not connected, 2 connected. |
AUDIO_WIFI_SSID | string | The network the audio board has stored; empty when none. |
AUDIO_UPDATE_STATE | number | The audio board's update: 0 idle, 1 checking, 2 a newer version is available, 3 downloading, 4 installing, 5 installed and waiting for the tagger to confirm it, 6 failed, 7 up to date, 8 about to restart into its update. |
AUDIO_UPDATE_PERCENT | number | Download progress, 0–100. Event rate-limited (~1s). |
AUDIO_UPDATE_VERSION | string | The version the audio board is updating to, or found on the server. |
AUDIO_UPDATE_ERROR | string | Why the audio board's last update failed; empty otherwise. |
AUDIO_HEAP_FREE | number | The audio board's free internal RAM in bytes, as it reports it every two seconds. Event rate-limited (~1s). |
AUDIO_HEAP_LARGEST | number | The audio board's largest free block of internal RAM in bytes. Event rate-limited (~1s). |
AUDIO_PSRAM_FREE | number | The audio board's free PSRAM in bytes. Event rate-limited (~1s). |
AUDIO_PSRAM_LARGEST | number | The audio board's largest free block of PSRAM in bytes. Event rate-limited (~1s). |
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). |
GPS_EXTERNAL_LAT | number | A latitude supplied by a connected phone, for when the tagger's own module can't get a lock (indoors, among buildings). Kept apart from GPS_LATITUDE, so a borrowed position is never mistaken for the module's own fix. |
GPS_EXTERNAL_LON | number | The phone-supplied longitude, as GPS_EXTERNAL_LAT. |
Game
| Key | Type | Description |
|---|---|---|
GAME_CONNECTED | boolean | Whether the device is in a game. |
GAME_ID | number | Current game id. |
GAME_TOKEN | number | A random number the host makes for each game and hands to joiners: what tells this game from a later one that reuses the one-byte 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_MIN_PLAYERS | number | Players needed, the host included, before the host can start. 1 lets the host play alone. |
GAME_HOST_MAC | string | The host's MAC address (when this device is a client). |
GAME_DISPLAY_NAME | string | Human-readable game name. |
GAME_TITLE | string | The title the host gave the game in the app's lobby ("Timmy's birthday"): the game config's title, which every tagger gets with the settings. At most 32 bytes of UTF-8; empty for none, when the game's name is shown. It heads the lobby on a tagger, the scoreboard and the after-action report (firmware 1.0.1071). |
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_PICKUP | boolean | Whether scanning a weapon tag may change a player's weapon in this game. Advisory: the tagger still reads tags and raises the event either way, so a script can react to a tag it may not equip. True by default. |
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_WIN_CONDITION | number | How the game is won: 0 score (reach GAME_WIN_TARGET), 1 elimination (be the only side left). The same setting decides a game the clock stops: a score game goes to the highest total, an elimination game to whoever has most players still in. |
GAME_WIN_TARGET | number | Reach this and the round ends; 0 for no target, so the game runs until a side is eliminated or the clock stops it. A team's total in a team game, one player's in a free-for-all, in whatever GAME_SCORE_BASED says the game is decided on. |
GAME_START_COUNTDOWN_SECS | number | Seconds counted down between the game being ready and play beginning; 0 starts as soon as everything is loaded. 10 when the config leaves it out. |
GAME_ASSIST_WINDOW_SECS | number | How long after damaging someone a player still earns an assist for their death, in seconds; 0 for the whole life. 10 by default. |
GAME_SHOW_LIVES | boolean | Whether lives are shown: the tagger's lives row and the app's lives column. A game with unlimited lives turns it off (showLives: false in its config). |
GAME_TEAM_DISPLAY_TYPE | number | What the in-game team band counts: 0 each side's score (points when the game scores, kills when it does not), 1 how many players each side still has in, as Infection shows survivors. |
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. |
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_HITS_LANDED | number | Hits this player landed in the game, each confirmed by the victim's tagger. Counted for the after-action report. |
PLAYER_HITS_TAKEN | number | Hits this player took in the game. |
PLAYER_DAMAGE_TAKEN | number | Damage this player took in the game. |
PLAYER_KILLED_BY_ID | number | The player id of whoever last eliminated this player, set as they go down. |
PLAYER_KILLED_BY_NAME | string | That player's name when the roster has it; empty otherwise (fall back to the id). |
PLAYER_KILLED_BY_CAUSE | number | What eliminated this player, set with PLAYER_KILLED_BY_ID: 0 a shot, 1 real gear's explosion, 2 a drone strike, 3 the game's own rule. |
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_NAME | string | The equipped weapon's display name, from its definition. |
WEAPON_AMMO | number | Current ammo. |
WEAPON_AMMO_MAX | number | Maximum ammo. |
WEAPON_FINITE_AMMO | boolean | Whether the equipped weapon draws from a limited supply. |
WEAPON_TOTAL_AMMO | number | Rounds the equipped weapon has left in all, the magazine included. Only meaningful when WEAPON_FINITE_AMMO is true. |
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_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. |
WEAPON_SLOTS | number | How many weapons this player can carry now. A player's, not the game's: an upgrade may grant more and a penalty take some away. A weapon's starting slot is set on its definition (weaponSlot), not by game-level keys. |
WEAPON_SLOTS_INITIAL | number | The slots the config granted, which a reset returns to. 2 by default. |
WEAPON_SLOTS_MAX | number | The most slots any upgrade may grant. 4 by default. |
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. |