Protocol Documentation#
Configuration data structures for HayBox firmware.
AnalogModifier#
Analog axis modifier definition.
Creates a mapping that a specified analog axis should have a specified multiplier applied to it when a specified set of button inputs are held down.
| Field | Type | Label | Description |
|---|---|---|---|
| buttons | Button | repeated | A list of buttons that must all be pressed simultaneously to activate this modifier. |
| axis | AnalogAxis | The analog axis to modify. | |
| multiplier | float | The multiplier to apply to axis. | |
| combination_mode | ModifierCombinationMode | The resolution behaviour to use when multiple modifiers are applied to the same axis. |
AnalogTriggerMapping#
Analog trigger mapping.
Maps a button input to set a specified analog trigger with a predetermined value.
| Field | Type | Label | Description |
|---|---|---|---|
| button | Button | The button input that should activate the trigger. | |
| trigger | AnalogTrigger | The analog trigger to activate. | |
| value | uint32 | The value to set the trigger to when button is pressed. |
ButtonComboMapping#
Mapping of multiple button inputs to a single digital output.
| Field | Type | Label | Description |
|---|---|---|---|
| buttons | Button | repeated | A list of buttons that must all be pressed simultaneously to activate this mapping. |
| digital_output | DigitalOutput | The digital button output to activate when the button combo is pressed. |
ButtonRemap#
Button remapping descriptor.
Specifies a remapping from one button to another. You can map multiple physical buttons to activate the same button, but one physical button cannot activate multiple inputs.
| Field | Type | Label | Description |
|---|---|---|---|
| physical_button | Button | The physical button input to remap. | |
| activates | Button | The button input to activate instead when the above physical button is pressed. |
ButtonToColorMapping#
Button to RGB color code mapping.
Used by RgbConfig to specify per-key lighting colors.
| Field | Type | Label | Description |
|---|---|---|---|
| button | Button | The button to apply the LED color to. | |
| color | uint32 | The RGB color value to apply. |
ButtonToKeycodeMapping#
Button to HID keyboard keycode mapping.
Used by KeyboardModeConfig to map button inputs to keyboard inputs.
| Field | Type | Label | Description |
|---|---|---|---|
| button | Button | The button input that should output this keycode. | |
| keycode | uint32 | The HID keycode to output. |
CommunicationBackendConfig#
A communication backend config.
Defines a comms backend profile.
| Field | Type | Label | Description |
|---|---|---|---|
| backend_id | CommunicationBackendId | The ID of the underlying CommunicationBackend implementation to use. |
|
| default_mode_config | uint32 | The default gamemode profile to activate after initialization. | |
| activation_binding | Button | repeated | The combination of buttons to hold on plugin to activate this comms backend config. |
| secondary_backends | CommunicationBackendId | repeated | Currently unused. |
Config#
The global container for all device configuration data.
| Field | Type | Label | Description |
|---|---|---|---|
| game_mode_configs | GameModeConfig | repeated | Array containing all defined gamemode profiles. |
| communication_backend_configs | CommunicationBackendConfig | repeated | Array containing all defined communication backend configs. |
| custom_modes | CustomModeConfig | repeated | Array containing custom controller mode definitions. |
| keyboard_modes | KeyboardModeConfig | repeated | Array containing custom keyboard mode definitions. |
| rgb_configs | RgbConfig | repeated | Array containing per-key RGB lighting profiles. |
| default_backend_config | uint32 | Index into the communication_backend_configs array specifying which CommunicationBackendConfig to fall back to if none is selected by button holds, console detection, or other methods. This array index starts at 1, because Protobuf 3 does not transmit zeroes and has no other way to check field presence. | |
| default_usb_backend_config | uint32 | Index into the communication_backend_configs array specifying which CommunicationBackendConfig to default to if the console detection step detects that USB is connected, and no button hold or other method is used to manually select a specific USB backend. This array index starts at 1, because Protobuf 3 does not transmit zeroes and has no other way to check field presence. | |
| rgb_brightness | uint32 | Overall RGB brightness modifier, which applies to all RgbConfigs. | |
| melee_options | MeleeOptions | Melee mode specific options. | |
| project_m_options | ProjectMOptions | Project M mode specific options. |
Coords#
Analog stick coordinates.
Used by various customisation options to describe analog stick positions with unsigned X and Y values.
| Field | Type | Label | Description |
|---|---|---|---|
| x | uint32 | The X coordinate of the stick. | |
| y | uint32 | The Y coordinate of the stick. |
CustomModeConfig#
Custom gamemode definition.
Used to implement a fully custom gamemode from scratch, mapping button inputs to digital buttons, stick directions, analog trigger values, and analog axis modifiers.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | Currently unused. | |
| digital_button_mappings | Button | repeated | An ordered list of button inputs to map to gamepad buttons, following the same order of the output buttons in DigitalOutput (i.e. first input in this list is mapped to the A button, second input is mapped to B, and so on). |
| stick_direction_mappings | Button | repeated | An ordered list of button inputs to map to analog stick directions, following the order of the specifiers in StickDirectionButton (i.e. first input in this list is mapped to Left Stick Up, second input is mapped to Left Stick Down, and so on). |
| analog_trigger_mappings | AnalogTriggerMapping | repeated | Maps button inputs to specific analog trigger values values. |
| modifiers | AnalogModifier | repeated | Applies specified multipliers to analog axes when specified buttons are pressed. |
| stick_range | uint32 | The base stick range to apply based when stick direction buttons are pressed, which may then have modifiers applied to it. | |
| button_combo_mappings | ButtonComboMapping | repeated | Applies mappings of multiple button inputs to single digital output. |
DeviceInfo#
Device info message.
Sent to host in response to a GET_DEVICE_INFO command.
| Field | Type | Label | Description |
|---|---|---|---|
| firmware_name | string | The name of the firmware running on the device - HayBox by default, but can be changed in PlatformIO config. | |
| firmware_version | string | The running firmware build version. | |
| device_name | string | The name of the device - currently this is pulled straight from the PlatformIO build environment name. |
GameModeConfig#
A general config profile.
Defines a gamemode profile.
| Field | Type | Label | Description |
|---|---|---|---|
| mode_id | GameModeId | The ID of the underlying InputMode implementing class to use. |
|
| name | string | The name of the profile (optional). | |
| socd_pairs | SocdPair | repeated | Pairs of button inputs to apply SOCD handling to, and the SOCD cleaning algorithms to use. |
| button_remapping | ButtonRemap | repeated | Button remappings to apply. |
| activation_binding | Button | repeated | The combination of buttons to press simultaneously to activate this profile. |
| custom_mode_config | uint32 | Index into the Config.custom_modes array of CustomModeConfigs. Only valid when mode_id = CUSTOM_MODE. This array index starts at 1, because Protobuf 3 does not transmit zeroes and has no other way to check field presence. | |
| keyboard_mode_config | uint32 | Index into the Config.keyboard_modes array of KeyboardModeConfigs. Only valid when mode_id = KEYBOARD_MODE. This array index starts at 1, because Protobuf 3 does not transmit zeroes and has no other way to check field presence. | |
| rgb_config | uint32 | An RgbConfig to apply when this mode is activated. This is an index into the Config.rgb_configs array of RgbConfigs (optional). This array index starts at 1, because Protobuf 3 does not transmit zeroes and has no other way to check field presence. |
KeyboardModeConfig#
A config profile for a custom HID keyboard mode.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | Currently unused. | |
| buttons_to_keycodes | ButtonToKeycodeMapping | repeated | A map of button inputs to HID keycodes. |
MeleeOptions#
Melee mode specific options.
| Field | Type | Label | Description |
|---|---|---|---|
| crouch_walk_os | bool | Set to true to enable downward diagonal coordinate which will cause you to enter walk state if you are hit while crouching. | |
| disable_ledgedash_socd_override | bool | Set to true to disable the horizontal SOCD modifier override intended to assist with ledgedashing. | |
| custom_airdodge | Coords | Custom airdodge X/Y coordinates. Valid X/Y values are 0 to 80. |
ProjectMOptions#
Project M mode specific options.
| Field | Type | Label | Description |
|---|---|---|---|
| true_z_press | bool | Set to true to make a Z input (mapped to RF3 by default) output an actual Z button press rather than the default analog shield + A grab macro. The default macro behaviour allows you to L cancel with Z without being locked out of tech, and true Z is still accessible by pressing Mod X (mapped to LT2 by default) and Z at the same time. | |
| disable_ledgedash_socd_override | bool | Set to true to disable the horizontal SOCD modifier override intended to assist with ledgedashing. | |
| custom_airdodge | Coords | Custom airdodge X/Y coordinates. Valid X/Y values are 0 to 100. |
RgbConfig#
A per-key RGB lighting profile.
| Field | Type | Label | Description |
|---|---|---|---|
| button_colors | ButtonToColorMapping | repeated | Map of buttons to RGB color codes. |
| default_color | uint32 | The default color to apply where specific button color is not mapped. | |
| animation | RgbAnimationId | The animation effect to apply to the LEDs. | |
| speed | uint32 | Speed at which to render the animation. |
SocdPair#
SOCD pair.
Specifies a pair of button inputs to apply SOCD handling to, and the SOCD cleaning algorithm to use.
| Field | Type | Label | Description |
|---|---|---|---|
| button_dir1 | Button | The first direction button. | |
| button_dir2 | Button | The second direction button. | |
| socd_type | SocdType | The SOCD cleaning mode to apply to the above button inputs. |
AnalogAxis#
Analog axis specifier used for binding AnalogModifiers to specific axes.
| Name | Number | Description |
|---|---|---|
| AXIS_UNSPECIFIED | 0 | No axis specified. |
| AXIS_LSTICK_X | 1 | Left stick X-axis. |
| AXIS_LSTICK_Y | 2 | Left stick Y-axis. |
| AXIS_RSTICK_X | 3 | Right stick X-axis. |
| AXIS_RSTICK_Y | 4 | Right stick Y-axis. |
| AXIS_LTRIGGER | 5 | Left trigger axis. |
| AXIS_RTRIGGER | 6 | Right trigger axis. |
AnalogTrigger#
Analog trigger specifier used by AnalogTriggerMapping to bind button inputs to analog trigger values.
| Name | Number | Description |
|---|---|---|
| TRIGGER_UNSPECIFIED | 0 | No trigger specified. |
| TRIGGER_LT | 1 | Left Trigger. |
| TRIGGER_RT | 2 | Right Trigger. |
Button#
Button identifiers for all 60 supported button inputs.
| Name | Number | Description |
|---|---|---|
| BTN_UNSPECIFIED | 0 | Unspecified button. |
| BTN_LF1 | 1 | Left Finger 1 |
| BTN_LF2 | 2 | Left Finger 2 |
| BTN_LF3 | 3 | Left Finger 3 |
| BTN_LF4 | 4 | Left Finger 4 |
| BTN_LF5 | 5 | Left Finger 5 |
| BTN_LF6 | 6 | Left Finger 6 |
| BTN_LF7 | 7 | Left Finger 7 |
| BTN_LF8 | 8 | Left Finger 8 |
| BTN_LF9 | 9 | Left Finger 9 |
| BTN_LF10 | 10 | Left Finger 10 |
| BTN_LF11 | 11 | Left Finger 11 |
| BTN_LF12 | 12 | Left Finger 12 |
| BTN_LF13 | 13 | Left Finger 13 |
| BTN_LF14 | 14 | Left Finger 14 |
| BTN_LF15 | 15 | Left Finger 15 |
| BTN_LF16 | 16 | Left Finger 16 |
| BTN_RF1 | 17 | Right Finger 1 |
| BTN_RF2 | 18 | Right Finger 2 |
| BTN_RF3 | 19 | Right Finger 3 |
| BTN_RF4 | 20 | Right Finger 4 |
| BTN_RF5 | 21 | Right Finger 5 |
| BTN_RF6 | 22 | Right Finger 6 |
| BTN_RF7 | 23 | Right Finger 7 |
| BTN_RF8 | 24 | Right Finger 8 |
| BTN_RF9 | 25 | Right Finger 9 |
| BTN_RF10 | 26 | Right Finger 10 |
| BTN_RF11 | 27 | Right Finger 11 |
| BTN_RF12 | 28 | Right Finger 12 |
| BTN_RF13 | 29 | Right Finger 13 |
| BTN_RF14 | 30 | Right Finger 14 |
| BTN_RF15 | 31 | Right Finger 15 |
| BTN_RF16 | 32 | Right Finger 16 |
| BTN_LT1 | 33 | Left Thumb 1 |
| BTN_LT2 | 34 | Left Thumb 2 |
| BTN_LT3 | 35 | Left Thumb 3 |
| BTN_LT4 | 36 | Left Thumb 4 |
| BTN_LT5 | 37 | Left Thumb 5 |
| BTN_LT6 | 38 | Left Thumb 6 |
| BTN_LT7 | 39 | Left Thumb 7 |
| BTN_LT8 | 40 | Left Thumb 8 |
| BTN_RT1 | 41 | Right Thumb 1 |
| BTN_RT2 | 42 | Right Thumb 2 |
| BTN_RT3 | 43 | Right Thumb 3 |
| BTN_RT4 | 44 | Right Thumb 4 |
| BTN_RT5 | 45 | Right Thumb 5 |
| BTN_RT6 | 46 | Right Thumb 6 |
| BTN_RT7 | 47 | Right Thumb 7 |
| BTN_RT8 | 48 | Right Thumb 8 |
| BTN_MB1 | 49 | Menu Button 1 |
| BTN_MB2 | 50 | Menu Button 2 |
| BTN_MB3 | 51 | Menu Button 3 |
| BTN_MB4 | 52 | Menu Button 4 |
| BTN_MB5 | 53 | Menu Button 5 |
| BTN_MB6 | 54 | Menu Button 6 |
| BTN_MB7 | 55 | Menu Button 7 |
| BTN_MB8 | 56 | Menu Button 8 |
| BTN_MB9 | 57 | Menu Button 9 |
| BTN_MB10 | 58 | Menu Button 10 |
| BTN_MB11 | 59 | Menu Button 11 |
| BTN_MB12 | 60 | Menu Button 12 |
Command#
Message type identifier for use when sending/receiving messages to/from a HayBox device.
| Name | Number | Description |
|---|---|---|
| CMD_UNSPECIFIED | 0 | Invalid command. |
| CMD_GET_DEVICE_INFO | 1 | Request device info from device. |
| CMD_SET_DEVICE_INFO | 2 | Respond with device info to host. |
| CMD_GET_CONFIG | 3 | Request current active configuration from device. |
| CMD_SET_CONFIG | 4 | Respond to host with current active configuration, or send new configuration to apply to device. |
| CMD_ERROR | 5 | Respond to host with error message. |
| CMD_SUCCESS | 6 | Respond to host confirming operation completed successfully. |
| CMD_REBOOT_FIRMWARE | 7 | Request for device to reboot into firmware. |
| CMD_REBOOT_BOOTLOADER | 8 | Request for device to reboot into bootloader. |
CommunicationBackendId#
Gamemode identifier.
Indicates to the firmware which communication backend class to switch to when activating a CommunicationBackendConfig.
| Name | Number | Description |
|---|---|---|
| COMMS_BACKEND_UNSPECIFIED | 0 | No backend specified. |
| COMMS_BACKEND_DINPUT | 1 | HID/DirectInput gamepad backend. |
| COMMS_BACKEND_XINPUT | 2 | XInput gamepad backend. |
| COMMS_BACKEND_GAMECUBE | 3 | GameCube console backend. |
| COMMS_BACKEND_N64 | 4 | N64 console backend. |
| COMMS_BACKEND_NES | 5 | NES console backend. |
| COMMS_BACKEND_SNES | 6 | SNES console backend. |
| COMMS_BACKEND_NINTENDO_SWITCH | 7 | Nintendo Switch USB backend. |
| COMMS_BACKEND_CONFIGURATOR | 8 | Configurator mode - for reading/writing config via this protocol. |
DigitalOutput#
Output state button identifiers, used by CustomModeConfig to bind button inputs to digital gamepad outputs.
| Name | Number | Description |
|---|---|---|
| GP_UNSPECIFIED | 0 | Invalid output. |
| GP_A | 1 | The A button. |
| GP_B | 2 | The B button. |
| GP_X | 3 | The X button. |
| GP_Y | 4 | The Y button. |
| GP_LB | 5 | The left bumper. |
| GP_RB | 6 | The right bumper. |
| GP_LT | 7 | The left trigger. |
| GP_RT | 8 | The right trigger. |
| GP_START | 9 | The Start button. |
| GP_SELECT | 10 | The Select button. |
| GP_HOME | 11 | The Home button. |
| GP_CAPTURE | 12 | The Capture button. |
| GP_DPAD_UP | 13 | The Up direction on the D-Pad. |
| GP_DPAD_DOWN | 14 | The Down direction on the D-Pad. |
| GP_DPAD_LEFT | 15 | The Left direction on the D-Pad. |
| GP_DPAD_RIGHT | 16 | The Right direction on the D-Pad. |
| GP_LSTICK_CLICK | 17 | The click input of the left analog stick. |
| GP_RSTICK_CLICK | 18 | The click input of the right analog stick. |
GameModeId#
Gamemode identifier.
Indicates to the firmware which gamemode class to switch to when activating a GameModeConfig.
| Name | Number | Description |
|---|---|---|
| MODE_UNSPECIFIED | 0 | No mode specified. |
| MODE_MELEE | 1 | Built-in Super Smash Bros Melee mode. |
| MODE_PROJECT_M | 2 | Built in Project M/Project+ mode. |
| MODE_ULTIMATE | 3 | Built-in Super Smash Bros Ultimate mode. |
| MODE_FGC | 4 | Built-in traditional fighting game/hitbox-style mode. |
| MODE_RIVALS_OF_AETHER | 5 | Built-in Rivals of Aether mode. |
| MODE_KEYBOARD | 6 | Keyboard mode - a GameModeConfig using this mode id must set GameModeConfig.keyboard_mode_config to reference a KeyboardModeConfig. |
| MODE_CUSTOM | 7 | Custom gamemode - a GameModeConfig using this mode id must set GameModeConfig.custom_mode_config to reference a CustomModeConfig. |
ModifierCombinationMode#
Modifier combination mode.
Specifies the behaviour when multiple modifiers are applied to the same axis.
| Name | Number | Description |
|---|---|---|
| COMBINATION_MODE_UNSPECIFIED | 0 | No combination mode specified - currently defaults to COMBINATION_MODE_OVERRIDE. |
| COMBINATION_MODE_COMPOUND | 1 | Compound combination mode - modifiers applying to the same axis stack with each other multiplicatively. |
| COMBINATION_MODE_OVERRIDE | 2 | Override combination mode - modifiers applying to the same axis override each other, with the last one applied taking priority over all others. |
RgbAnimationId#
RGB animation identifier.
Indicates to the firmware which animation to use when activation an RgbConfig.
| Name | Number | Description |
|---|---|---|
| RGB_ANIM_UNSPECIFIED | 0 | No animation specified. |
| RGB_ANIM_STATIC | 1 | Static - no animation. |
| RGB_ANIM_BREATHE | 2 | Simple "breathing" (fade in, fade out) animation. |
| RGB_ANIM_REACTIVE_SIMPLE | 3 | Per-key reactive LED (keys light up when pressed). |
SocdType#
SOCD cleaning methods.
| Name | Number | Description |
|---|---|---|
| SOCD_UNSPECIFIED | 0 | No SOCD cleaning |
| SOCD_NEUTRAL | 1 | Neutral SOCD (Left + Right = neutral) |
| SOCD_2IP | 2 | Second input priority: Left -> Left + Right = Right, and vice versa. Releasing the second direction gives the original direction. |
| SOCD_2IP_NO_REAC | 3 | Second input priority without reactivation - same as above, except releasing the second direction results in neutral. The original direction must be physically reactuated. |
| SOCD_DIR1_PRIORITY | 4 | The first button in the SocdPair always takes priority over the second |
| SOCD_DIR2_PRIORITY | 5 | The second button in the SocdPair always takes priority over the first |
StickDirectionButton#
Stick direction specifiers used for mapping analog stick directions to buttons in CustomModeConfig.
| Name | Number | Description |
|---|---|---|
| SD_UNSPECIFIED | 0 | No stick direction specified. |
| SD_LSTICK_UP | 1 | Up on the left analog stick. |
| SD_LSTICK_DOWN | 2 | Down on the left analog stick. |
| SD_LSTICK_LEFT | 3 | Left on the left analog stick. |
| SD_LSTICK_RIGHT | 4 | Right on the left analog stick. |
| SD_RSTICK_UP | 5 | Up on the right analog stick. |
| SD_RSTICK_DOWN | 6 | Down on the right analog stick. |
| SD_RSTICK_LEFT | 7 | Left on the right analog stick. |
| SD_RSTICK_RIGHT | 8 | Right on the right analog stick. |