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	255 = full, 0 = empty. Event rate-limited (~5s).
`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.
`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).
`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_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_RESPAWN_MODE`	number	Trigger respawn, base respawn, etc.
`GAME_RESPAWN_TIME_SECS`	number	Respawn delay in seconds.
`GAME_WEAPON_1`	number	Starting weapon 1 (0 = none).
`GAME_WEAPON_2`	number	Starting weapon 2 (0 = none).
`GAME_RADAR_TYPE`	number	0 = off, 1 = movement-based, 2 = permanent.
`GAME_MAP_TYPE`	number	0 = unlimited, 1 = limited.
`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.
`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_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_IS_BUSY`	number	Count of actions making the weapon busy (reloading, jammed, …).
`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.