HID-RP

The hid-rp component provides a wrapper around https://github.com/intergatedcircuits/hid-rp and also provides an example implementation of a configurable HID Gamepad using hid-rp.

HID-RP Example
- How to use example
  - Hardware Required
  - Build and Flash
- Example Output

API Reference

Header File

components/hid-rp/include/hid-rp.hpp

Header File

components/hid-rp/include/hid-rp-gamepad.hpp

Classes

template<size_t BUTTON_COUNT = 15, typename JOYSTICK_TYPE = std::uint16_t, typename TRIGGER_TYPE = std::uint16_t, JOYSTICK_TYPE JOYSTICK_MIN = 0, JOYSTICK_TYPE JOYSTICK_MAX = 65534, TRIGGER_TYPE TRIGGER_MIN = 0, TRIGGER_TYPE TRIGGER_MAX = 1023, uint8_t REPORT_ID = 1> class GamepadInputReport : public hid::report::base<hid::report::type::INPUT, 1>

HID Gamepad Input Report This class implements a HID Gamepad with a configurable number of buttons, a hat switch, 4 joystick axes and two trigger axes. It supports setting the buttons, hat switch, joysticks, and triggers, as well as serializing the input report and getting the report descriptor.

HID-RP Example

  static constexpr uint8_t input_report_id = 1;
  static constexpr size_t num_buttons = 15;
  static constexpr int joystick_min = 0;
  static constexpr int joystick_max = 65534;
  static constexpr int trigger_min = 0;
  static constexpr int trigger_max = 1023;

  using GamepadInput =
      espp::GamepadInputReport<num_buttons, std::uint16_t, std::uint16_t, joystick_min,
                               joystick_max, trigger_min, trigger_max, input_report_id>;
  GamepadInput gamepad_input_report;

  static constexpr uint8_t output_report_id = 2;
  static constexpr size_t num_leds = 4;
  using GamepadLeds = espp::GamepadLedOutputReport<num_leds, output_report_id>;
  GamepadLeds gamepad_leds_report;

  using namespace hid::page;
  using namespace hid::rdf;
  auto raw_descriptor = descriptor(usage_page<generic_desktop>(), usage(generic_desktop::GAMEPAD),
                                   collection::application(gamepad_input_report.get_descriptor(),
                                                           gamepad_leds_report.get_descriptor()));

  // Generate the report descriptor for the gamepad
  auto descriptor = std::vector<uint8_t>(raw_descriptor.begin(), raw_descriptor.end());

  logger.info("Report Descriptor:");
  logger.info("  Size: {}", descriptor.size());
  logger.info("  Data: {::#02x}", descriptor);

  GamepadInput::Hat hat = GamepadInput::Hat::UP_RIGHT;
  int button_index = 5;
  float angle = 2.0f * M_PI * button_index / num_buttons;

  gamepad_input_report.reset();
  gamepad_input_report.set_hat(hat);
  gamepad_input_report.set_button(button_index, true);
  // joystick inputs are in the range [-1, 1] float
  gamepad_input_report.set_right_joystick(cos(angle), sin(angle));
  gamepad_input_report.set_left_joystick(sin(angle), cos(angle));
  // trigger inputs are in the range [0, 1] float
  gamepad_input_report.set_accelerator(std::abs(sin(angle)));
  gamepad_input_report.set_brake(std::abs(cos(angle)));

  button_index = (button_index % num_buttons) + 1;

  // send an input report
  auto report = gamepad_input_report.get_report();
  logger.info("Input report:");
  logger.info("  Size: {}", report.size());
  logger.info("  Data: {::#02x}", report);

Public Types

enum class Hat

Possible Hat switch directions.

Values:

enumerator CENTERED: Centered, no direction pressed.

enumerator UP

enumerator UP_RIGHT

enumerator RIGHT

enumerator DOWN_RIGHT

enumerator DOWN

enumerator DOWN_LEFT

enumerator LEFT

enumerator UP_LEFT

Public Functions

inline constexpr void reset(): Reset the gamepad inputs.

inline constexpr void set_left_joystick(float lx, float ly)

Set the left joystick X and Y axis values

Parameters

lx – left joystick x axis value, in the range [-1, 1]
ly – left joystick y axis value, in the range [-1, 1]

inline constexpr void set_right_joystick(float rx, float ry)

Set the right joystick X and Y axis values

Parameters

rx – right joystick x axis value, in the range [-1, 1]
ry – right joystick y axis value, in the range [-1, 1]

inline constexpr void set_brake(float value)

Set the brake trigger value

Parameters: value – brake trigger value, in the range [0, 1]

inline constexpr void set_accelerator(float value)

Set the accelerator trigger value

Parameters: value – accelerator trigger value, in the range [0, 1]

inline constexpr void set_hat(Hat hat)

Set the hat switch (d-pad) value

Parameters: hat – Hat enum / direction to set

inline constexpr void set_button(int button_index, bool value)

Set the button value

Parameters

button_index – The button for which you want to set the value. Should be between 1 and BUTTON_COUNT, inclusive.
value – The true/false value you want to se the button to.

inline constexpr auto get_report()

Get the input report as a vector of bytes

Note

The report id is not included in the returned vector.

Returns: The input report as a vector of bytes.

Public Static Functions

static inline constexpr auto get_descriptor()

Get the report descriptor as a hid::rdf::descriptor

Note

This is an incomplete descriptor, you will need to add it to a collection::application descriptor to create a complete report descriptor.

using namespace hid::page;
using namespace hid::rdf;
auto gamepad_descriptor = gamepad_input_report.get_descriptor();
auto rdf_descriptor = descriptor(
    usage_page<generic_desktop>(),
    usage(generic_desktop::GAMEPAD),
    collection::application(
        gamepad_descriptor
    )
);
auto descriptor = std::vector<uint8_t>(rdf_descriptor.begin(), rdf_descriptor.end());

Returns: The report descriptor as a hid::rdf::descriptor.

template<size_t LED_COUNT = 4, uint8_t REPORT_ID = 2> class GamepadLedOutputReport : public hid::report::base<hid::report::type::OUTPUT, 2>

HID Gamepad LED Output Report This class implements a HID Gamepad with a configurable number of LEDs. It supports setting the LEDs, as well as serializing the output report and getting the report descriptor.

Public Functions

inline constexpr void set_led(int led_index, bool value)

Set the LED value

Parameters

led_index – The LED for which you want to set the value. Should be between 1 and LED_COUNT, inclusive.
value – The true/false value you want to se the LED to.

inline constexpr auto get_report()

Get the output report as a vector of bytes

Note

The report id is not included in the returned vector.

Returns: The output report as a vector of bytes.

Public Static Functions

static inline constexpr auto get_descriptor()

Get the report descriptor as a hid::rdf::descriptor

Note

This is an incomplete descriptor, you will need to add it to a collection::application descriptor to create a complete report descriptor.

using namespace hid::page;
using namespace hid::rdf;
auto led_descriptor = gamepad_led_report.get_descriptor();
auto rdf_descriptor = descriptor(
    usage_page<generic_desktop>(),
    usage(generic_desktop::GAMEPAD),
    collection::application(
        led_descriptor
    )
);
auto descriptor = std::vector<uint8_t>(rdf_descriptor.begin(), rdf_descriptor.end());

Returns: The report descriptor as a hid::rdf::descriptor.