SystemK

SystemK is the name for the software that is at the core of KTag devices.

The source code for SystemK is available in the KTag git repos at https://git.ktag.clubk.club/Software/SystemK.

State Machine

SystemK implements this Finite-State Machine in each device.

NeoPixels

KTag devices use NeoPixels for visual effects and as part of the user interface. Early devices had a single channel of NeoPixels. Later devices added more independent channels, to provide more interesting effects and a better user experience.

Configuration

Configuration Option Name	Default Value	Description
CONFIG_KTAG_N_NEOPIXEL_CHANNELS	4	Number of NeoPixel channels supported by this hardware.
CONFIG_KTAG_MAX_NEOPIXELS_PER_CHANNEL	8	Maximum number of NeoPixels on a single channel.
CONFIG_KTAG_ANIMATION_STEP_TIME_IN_ms	10	Time between animation updates, in milliseconds.
CONFIG_KTAG_T_DEFAULT_START_GAME_in_ms	30000	Default time (in milliseconds) after starting a game before the countdown begins.
CONFIG_KTAG_MAX_AUDIO_VOLUME	100	Value of audio volume representing the maximum volume possible for this device.
CONFIG_KTAG_MIN_AUDIO_VOLUME	0	Value of audio volume representing the minimum volume possible for this device.

Hardware Support Functions

In addition to the above configuration options, the hardware abstraction layer for a KTag device is required to implement the following interface functions.

Settings

Setting ID	Datatype	Description
SYSTEMK_SETTING_IS_RIGHT_HANDED	uint8_t	1 if this device is configured for a right-handed player, 0 otherwise.
SYSTEMK_SETTING_AUDIO_VOLUME	uint8_t	Value from CONFIG_KTAG_MIN_AUDIO_VOLUME to CONFIG_KTAG_MAX_AUDIO_VOLUME representing the current volume.
SYSTEMK_SETTING_TEAMID	uint8_t	Selected team.
SYSTEMK_SETTING_PLAYERID	uint8_t	Unique-per-team identification of a player.
SYSTEMK_SETTING_WEAPONID	uint8_t	Selected weapon.
SYSTEMK_SETTING_MAX_HEALTH	uint8_t	Maximum health for the game.
SYSTEMK_SETTING_N_SPECIAL_WEAPONS_ON_REENTRY	uint8_t	Number of special weapons (currently only bombs) obtained when reentering after being tagged out.
SYSTEMK_SETTING_T_START_GAME_in_ms	uint32_t	Time (in milliseconds) after starting a game before the countdown begins.
SYSTEMK_SETTING_T_GAME_LENGTH_in_ms	uint32_t	Duration of a game (in milliseconds). If this is zero or UINT32_MAX, the game is untimed.
SYSTEMK_SETTING_SECONDARY_COLOR	uint32_t	Color in addition to the team color used to identify a player's device. The format is Brightness-Red-Green-Blue, where a brightness of 0xFF indicates a false flag.

• SystemKResult_T SETTINGS_get_uint8_t(SystemKSettingID_T id, uint8_t * value)
  
• SystemKResult_T SETTINGS_set_uint8_t(SystemKSettingID_T id, uint8_t value)
  
• SystemKResult_T SETTINGS_get_uint32_t(SystemKSettingID_T id, uint32_t * value)
  
• SystemKResult_T SETTINGS_set_uint32_t(SystemKSettingID_T id, uint32_t value)
  
• SystemKResult_T SETTINGS_get_device_name(char* name)
  
• SystemKResult_T SETTINGS_set_device_name(char* name)
  
• SystemKResult_T SETTINGS_Save(void)
  Called by the system when the settings should be saved to nonvolatile memory.

Infrared Support

• SystemKResult_T Prepare_Tag(void)
  Packs the shot packet with all the necessary data, based on the current settings.
• SystemKResult_T Send_Tag(void)
  Sends a shot packet out the barrel.

Audio Support

• SystemKResult_T Perform_Audio_Action(AudioAction_T * action)
  Called by the system when it needs to interact with the audio subsystem.

Bluetooth® Low Energy¹ Support

• SystemKResult_T BLE_GetMyAddress(uint8_t * BD_ADDR)
  Gets the BD_ADDR (six-byte unique identifier used by BLE) of this device.
• SystemKResult_T BLE_SetAdvertisingData(BLE_AdvertisingData_T * data)
  Called by by the system when it needs to change the advertising data.
• SystemKResult_T BLE_ScanAndAdvertise(void)
  Called at system startup, after the NVM has been initialized and the configurations have been read, to begin interactions.
• SystemKResult_T BLE_StopAdvertising(void)
  Called when the system needs to stop sending BLE advertisements.
• SystemKResult_T BLE_StopScanning(void)
  Called by the system when it no longer needs to listen for BLE advertisements.
• SystemKResult_T BLE_Quiet(uint32_t duration_ms)
  Called when the system has been instructed to only speak when spoken to. The device should cease BLE advertisements for the duration, or until an “Unquiet” is received. A duration_ms of 0 means an indefinite Quiet.
• SystemKResult_T BLE_Unquiet(void)
  Called by the system to resume sending BLE advertisements, effectively ending a Quiet.

NeoPixel Support

• SystemKResult_T HW_NeoPixels_Init(void)
  Called at system startup, after the NVM has been initialized and the configurations read (so the HAL can know the RGB order, for example), but before the animations begin.
• SystemKResult_T HW_NeoPixels_Set_RGB(NeoPixelsChannel_T channel, uint8_t position, uint8_t red, uint8_t green, uint8_t blue)
  Called by the various animations to change the color of a pixel in the back buffer.
• SystemKResult_T HW_NeoPixels_Publish(void)
  Called at the end of each animation frame, to send the pixel colors out to the NeoPixels.

Logging/Console Support

• SystemKResult_T HW_Execute_Console_Command(const uint8_t * const command)
  Executes a console command programmatically.

References

ESP32PSoC

• LED Strip Driver component in the ESP Component Registry.

• NeoPixel Driver using Direct Memory Access by Alan Hawse of Elkhorn Creek.
• GitHub repo of the above.

---

1. Bluetooth® Low Energy is a registered trademark of Bluetooth SIG, Inc. All trade names, trademarks, and registered trademarks mentioned in this documentation are the property of their respective owners, and are hereby acknowledged. ↩