| /* |
| * The MIT License (MIT) |
| * |
| * Copyright (c) 2019 Ha Thach (tinyusb.org) |
| * |
| * Permission is hereby granted, free of charge, to any person obtaining a copy |
| * of this software and associated documentation files (the "Software"), to deal |
| * in the Software without restriction, including without limitation the rights |
| * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| * copies of the Software, and to permit persons to whom the Software is |
| * furnished to do so, subject to the following conditions: |
| * |
| * The above copyright notice and this permission notice shall be included in |
| * all copies or substantial portions of the Software. |
| * |
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
| * THE SOFTWARE. |
| * |
| * This file is part of the TinyUSB stack. |
| */ |
| |
| #ifndef _TUSB_HID_DEVICE_H_ |
| #define _TUSB_HID_DEVICE_H_ |
| |
| #include "hid.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| //--------------------------------------------------------------------+ |
| // Class Driver Default Configure & Validation |
| //--------------------------------------------------------------------+ |
| |
| #if !defined(CFG_TUD_HID_EP_BUFSIZE) & defined(CFG_TUD_HID_BUFSIZE) |
| // TODO warn user to use new name later on |
| // #warning CFG_TUD_HID_BUFSIZE is renamed to CFG_TUD_HID_EP_BUFSIZE, please update to use the new name |
| #define CFG_TUD_HID_EP_BUFSIZE CFG_TUD_HID_BUFSIZE |
| #endif |
| |
| #ifndef CFG_TUD_HID_EP_BUFSIZE |
| #define CFG_TUD_HID_EP_BUFSIZE 64 |
| #endif |
| |
| //--------------------------------------------------------------------+ |
| // Application API (Multiple Instances) |
| // CFG_TUD_HID > 1 |
| //--------------------------------------------------------------------+ |
| |
| // Check if the interface is ready to use |
| bool tud_hid_n_ready(uint8_t instance); |
| |
| // Get interface supported protocol (bInterfaceProtocol) check out hid_interface_protocol_enum_t for possible values |
| uint8_t tud_hid_n_interface_protocol(uint8_t instance); |
| |
| // Get current active protocol: HID_PROTOCOL_BOOT (0) or HID_PROTOCOL_REPORT (1) |
| uint8_t tud_hid_n_get_protocol(uint8_t instance); |
| |
| // Send report to host |
| bool tud_hid_n_report(uint8_t instance, uint8_t report_id, void const* report, uint8_t len); |
| |
| // KEYBOARD: convenient helper to send keyboard report if application |
| // use template layout report as defined by hid_keyboard_report_t |
| bool tud_hid_n_keyboard_report(uint8_t instance, uint8_t report_id, uint8_t modifier, uint8_t keycode[6]); |
| |
| // MOUSE: convenient helper to send mouse report if application |
| // use template layout report as defined by hid_mouse_report_t |
| bool tud_hid_n_mouse_report(uint8_t instance, uint8_t report_id, uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal); |
| |
| // Gamepad: convenient helper to send gamepad report if application |
| // use template layout report TUD_HID_REPORT_DESC_GAMEPAD |
| bool tud_hid_n_gamepad_report(uint8_t instance, uint8_t report_id, int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint32_t buttons); |
| |
| //--------------------------------------------------------------------+ |
| // Application API (Single Port) |
| //--------------------------------------------------------------------+ |
| static inline bool tud_hid_ready(void); |
| static inline uint8_t tud_hid_interface_protocol(void); |
| static inline uint8_t tud_hid_get_protocol(void); |
| static inline bool tud_hid_report(uint8_t report_id, void const* report, uint8_t len); |
| static inline bool tud_hid_keyboard_report(uint8_t report_id, uint8_t modifier, uint8_t keycode[6]); |
| static inline bool tud_hid_mouse_report(uint8_t report_id, uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal); |
| static inline bool tud_hid_gamepad_report(uint8_t report_id, int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint32_t buttons); |
| |
| //--------------------------------------------------------------------+ |
| // Callbacks (Weak is optional) |
| //--------------------------------------------------------------------+ |
| |
| // Invoked when received GET HID REPORT DESCRIPTOR request |
| // Application return pointer to descriptor, whose contents must exist long enough for transfer to complete |
| uint8_t const * tud_hid_descriptor_report_cb(uint8_t instance); |
| |
| // Invoked when received GET_REPORT control request |
| // Application must fill buffer report's content and return its length. |
| // Return zero will cause the stack to STALL request |
| uint16_t tud_hid_get_report_cb(uint8_t instance, uint8_t report_id, hid_report_type_t report_type, uint8_t* buffer, uint16_t reqlen); |
| |
| // Invoked when received SET_REPORT control request or |
| // received data on OUT endpoint ( Report ID = 0, Type = 0 ) |
| void tud_hid_set_report_cb(uint8_t instance, uint8_t report_id, hid_report_type_t report_type, uint8_t const* buffer, uint16_t bufsize); |
| |
| // Invoked when received SET_PROTOCOL request |
| // protocol is either HID_PROTOCOL_BOOT (0) or HID_PROTOCOL_REPORT (1) |
| TU_ATTR_WEAK void tud_hid_set_protocol_cb(uint8_t instance, uint8_t protocol); |
| |
| // Invoked when received SET_IDLE request. return false will stall the request |
| // - Idle Rate = 0 : only send report if there is changes, i.e skip duplication |
| // - Idle Rate > 0 : skip duplication, but send at least 1 report every idle rate (in unit of 4 ms). |
| TU_ATTR_WEAK bool tud_hid_set_idle_cb(uint8_t instance, uint8_t idle_rate); |
| |
| // Invoked when sent REPORT successfully to host |
| // Application can use this to send the next report |
| // Note: For composite reports, report[0] is report ID |
| TU_ATTR_WEAK void tud_hid_report_complete_cb(uint8_t instance, uint8_t const* report, uint8_t len); |
| |
| |
| //--------------------------------------------------------------------+ |
| // Inline Functions |
| //--------------------------------------------------------------------+ |
| static inline bool tud_hid_ready(void) |
| { |
| return tud_hid_n_ready(0); |
| } |
| |
| static inline uint8_t tud_hid_interface_protocol(void) |
| { |
| return tud_hid_n_interface_protocol(0); |
| } |
| |
| static inline uint8_t tud_hid_get_protocol(void) |
| { |
| return tud_hid_n_get_protocol(0); |
| } |
| |
| static inline bool tud_hid_report(uint8_t report_id, void const* report, uint8_t len) |
| { |
| return tud_hid_n_report(0, report_id, report, len); |
| } |
| |
| static inline bool tud_hid_keyboard_report(uint8_t report_id, uint8_t modifier, uint8_t keycode[6]) |
| { |
| return tud_hid_n_keyboard_report(0, report_id, modifier, keycode); |
| } |
| |
| static inline bool tud_hid_mouse_report(uint8_t report_id, uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal) |
| { |
| return tud_hid_n_mouse_report(0, report_id, buttons, x, y, vertical, horizontal); |
| } |
| |
| static inline bool tud_hid_gamepad_report(uint8_t report_id, int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint32_t buttons) |
| { |
| return tud_hid_n_gamepad_report(0, report_id, x, y, z, rz, rx, ry, hat, buttons); |
| } |
| |
| /* --------------------------------------------------------------------+ |
| * HID Report Descriptor Template |
| * |
| * Convenient for declaring popular HID device (keyboard, mouse, consumer, |
| * gamepad etc...). Templates take "HID_REPORT_ID(n)" as input, leave |
| * empty if multiple reports is not used |
| * |
| * - Only 1 report: no parameter |
| * uint8_t const report_desc[] = { TUD_HID_REPORT_DESC_KEYBOARD() }; |
| * |
| * - Multiple Reports: "HID_REPORT_ID(ID)" must be passed to template |
| * uint8_t const report_desc[] = |
| * { |
| * TUD_HID_REPORT_DESC_KEYBOARD( HID_REPORT_ID(1) ) , |
| * TUD_HID_REPORT_DESC_MOUSE ( HID_REPORT_ID(2) ) |
| * }; |
| *--------------------------------------------------------------------*/ |
| |
| // Keyboard Report Descriptor Template |
| #define TUD_HID_REPORT_DESC_KEYBOARD(...) \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_KEYBOARD ) ,\ |
| HID_COLLECTION ( HID_COLLECTION_APPLICATION ) ,\ |
| /* Report ID if any */\ |
| __VA_ARGS__ \ |
| /* 8 bits Modifier Keys (Shfit, Control, Alt) */ \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_KEYBOARD ) ,\ |
| HID_USAGE_MIN ( 224 ) ,\ |
| HID_USAGE_MAX ( 231 ) ,\ |
| HID_LOGICAL_MIN ( 0 ) ,\ |
| HID_LOGICAL_MAX ( 1 ) ,\ |
| HID_REPORT_COUNT ( 8 ) ,\ |
| HID_REPORT_SIZE ( 1 ) ,\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) ,\ |
| /* 8 bit reserved */ \ |
| HID_REPORT_COUNT ( 1 ) ,\ |
| HID_REPORT_SIZE ( 8 ) ,\ |
| HID_INPUT ( HID_CONSTANT ) ,\ |
| /* Output 5-bit LED Indicator Kana | Compose | ScrollLock | CapsLock | NumLock */ \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_LED ) ,\ |
| HID_USAGE_MIN ( 1 ) ,\ |
| HID_USAGE_MAX ( 5 ) ,\ |
| HID_REPORT_COUNT ( 5 ) ,\ |
| HID_REPORT_SIZE ( 1 ) ,\ |
| HID_OUTPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) ,\ |
| /* led padding */ \ |
| HID_REPORT_COUNT ( 1 ) ,\ |
| HID_REPORT_SIZE ( 3 ) ,\ |
| HID_OUTPUT ( HID_CONSTANT ) ,\ |
| /* 6-byte Keycodes */ \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_KEYBOARD ) ,\ |
| HID_USAGE_MIN ( 0 ) ,\ |
| HID_USAGE_MAX_N ( 255, 2 ) ,\ |
| HID_LOGICAL_MIN ( 0 ) ,\ |
| HID_LOGICAL_MAX_N( 255, 2 ) ,\ |
| HID_REPORT_COUNT ( 6 ) ,\ |
| HID_REPORT_SIZE ( 8 ) ,\ |
| HID_INPUT ( HID_DATA | HID_ARRAY | HID_ABSOLUTE ) ,\ |
| HID_COLLECTION_END \ |
| |
| // Mouse Report Descriptor Template |
| #define TUD_HID_REPORT_DESC_MOUSE(...) \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_MOUSE ) ,\ |
| HID_COLLECTION ( HID_COLLECTION_APPLICATION ) ,\ |
| /* Report ID if any */\ |
| __VA_ARGS__ \ |
| HID_USAGE ( HID_USAGE_DESKTOP_POINTER ) ,\ |
| HID_COLLECTION ( HID_COLLECTION_PHYSICAL ) ,\ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_BUTTON ) ,\ |
| HID_USAGE_MIN ( 1 ) ,\ |
| HID_USAGE_MAX ( 5 ) ,\ |
| HID_LOGICAL_MIN ( 0 ) ,\ |
| HID_LOGICAL_MAX ( 1 ) ,\ |
| /* Left, Right, Middle, Backward, Forward buttons */ \ |
| HID_REPORT_COUNT( 5 ) ,\ |
| HID_REPORT_SIZE ( 1 ) ,\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) ,\ |
| /* 3 bit padding */ \ |
| HID_REPORT_COUNT( 1 ) ,\ |
| HID_REPORT_SIZE ( 3 ) ,\ |
| HID_INPUT ( HID_CONSTANT ) ,\ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP ) ,\ |
| /* X, Y position [-127, 127] */ \ |
| HID_USAGE ( HID_USAGE_DESKTOP_X ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_Y ) ,\ |
| HID_LOGICAL_MIN ( 0x81 ) ,\ |
| HID_LOGICAL_MAX ( 0x7f ) ,\ |
| HID_REPORT_COUNT( 2 ) ,\ |
| HID_REPORT_SIZE ( 8 ) ,\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_RELATIVE ) ,\ |
| /* Verital wheel scroll [-127, 127] */ \ |
| HID_USAGE ( HID_USAGE_DESKTOP_WHEEL ) ,\ |
| HID_LOGICAL_MIN ( 0x81 ) ,\ |
| HID_LOGICAL_MAX ( 0x7f ) ,\ |
| HID_REPORT_COUNT( 1 ) ,\ |
| HID_REPORT_SIZE ( 8 ) ,\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_RELATIVE ) ,\ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_CONSUMER ), \ |
| /* Horizontal wheel scroll [-127, 127] */ \ |
| HID_USAGE_N ( HID_USAGE_CONSUMER_AC_PAN, 2 ), \ |
| HID_LOGICAL_MIN ( 0x81 ), \ |
| HID_LOGICAL_MAX ( 0x7f ), \ |
| HID_REPORT_COUNT( 1 ), \ |
| HID_REPORT_SIZE ( 8 ), \ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_RELATIVE ), \ |
| HID_COLLECTION_END , \ |
| HID_COLLECTION_END \ |
| |
| // Consumer Control Report Descriptor Template |
| #define TUD_HID_REPORT_DESC_CONSUMER(...) \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_CONSUMER ) ,\ |
| HID_USAGE ( HID_USAGE_CONSUMER_CONTROL ) ,\ |
| HID_COLLECTION ( HID_COLLECTION_APPLICATION ) ,\ |
| /* Report ID if any */\ |
| __VA_ARGS__ \ |
| HID_LOGICAL_MIN ( 0x00 ) ,\ |
| HID_LOGICAL_MAX_N( 0x03FF, 2 ) ,\ |
| HID_USAGE_MIN ( 0x00 ) ,\ |
| HID_USAGE_MAX_N ( 0x03FF, 2 ) ,\ |
| HID_REPORT_COUNT ( 1 ) ,\ |
| HID_REPORT_SIZE ( 16 ) ,\ |
| HID_INPUT ( HID_DATA | HID_ARRAY | HID_ABSOLUTE ) ,\ |
| HID_COLLECTION_END \ |
| |
| /* System Control Report Descriptor Template |
| * 0x00 - do nothing |
| * 0x01 - Power Off |
| * 0x02 - Standby |
| * 0x03 - Wake Host |
| */ |
| #define TUD_HID_REPORT_DESC_SYSTEM_CONTROL(...) \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_SYSTEM_CONTROL ) ,\ |
| HID_COLLECTION ( HID_COLLECTION_APPLICATION ) ,\ |
| /* Report ID if any */\ |
| __VA_ARGS__ \ |
| /* 2 bit system power control */ \ |
| HID_LOGICAL_MIN ( 1 ) ,\ |
| HID_LOGICAL_MAX ( 3 ) ,\ |
| HID_REPORT_COUNT ( 1 ) ,\ |
| HID_REPORT_SIZE ( 2 ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_SYSTEM_POWER_DOWN ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_SYSTEM_SLEEP ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_SYSTEM_WAKE_UP ) ,\ |
| HID_INPUT ( HID_DATA | HID_ARRAY | HID_ABSOLUTE ) ,\ |
| /* 6 bit padding */ \ |
| HID_REPORT_COUNT ( 1 ) ,\ |
| HID_REPORT_SIZE ( 6 ) ,\ |
| HID_INPUT ( HID_CONSTANT ) ,\ |
| HID_COLLECTION_END \ |
| |
| // Gamepad Report Descriptor Template |
| // with 32 buttons, 2 joysticks and 1 hat/dpad with following layout |
| // | X | Y | Z | Rz | Rx | Ry (1 byte each) | hat/DPAD (1 byte) | Button Map (4 bytes) | |
| #define TUD_HID_REPORT_DESC_GAMEPAD(...) \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_GAMEPAD ) ,\ |
| HID_COLLECTION ( HID_COLLECTION_APPLICATION ) ,\ |
| /* Report ID if any */\ |
| __VA_ARGS__ \ |
| /* 8 bit X, Y, Z, Rz, Rx, Ry (min -127, max 127 ) */ \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_X ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_Y ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_Z ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_RZ ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_RX ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_RY ) ,\ |
| HID_LOGICAL_MIN ( 0x81 ) ,\ |
| HID_LOGICAL_MAX ( 0x7f ) ,\ |
| HID_REPORT_COUNT ( 6 ) ,\ |
| HID_REPORT_SIZE ( 8 ) ,\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) ,\ |
| /* 8 bit DPad/Hat Button Map */ \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_DESKTOP ) ,\ |
| HID_USAGE ( HID_USAGE_DESKTOP_HAT_SWITCH ) ,\ |
| HID_LOGICAL_MIN ( 1 ) ,\ |
| HID_LOGICAL_MAX ( 8 ) ,\ |
| HID_PHYSICAL_MIN ( 0 ) ,\ |
| HID_PHYSICAL_MAX_N ( 315, 2 ) ,\ |
| HID_REPORT_COUNT ( 1 ) ,\ |
| HID_REPORT_SIZE ( 8 ) ,\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) ,\ |
| /* 32 bit Button Map */ \ |
| HID_USAGE_PAGE ( HID_USAGE_PAGE_BUTTON ) ,\ |
| HID_USAGE_MIN ( 1 ) ,\ |
| HID_USAGE_MAX ( 32 ) ,\ |
| HID_LOGICAL_MIN ( 0 ) ,\ |
| HID_LOGICAL_MAX ( 1 ) ,\ |
| HID_REPORT_COUNT ( 32 ) ,\ |
| HID_REPORT_SIZE ( 1 ) ,\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ) ,\ |
| HID_COLLECTION_END \ |
| |
| // HID Generic Input & Output |
| // - 1st parameter is report size (mandatory) |
| // - 2nd parameter is report id HID_REPORT_ID(n) (optional) |
| #define TUD_HID_REPORT_DESC_GENERIC_INOUT(report_size, ...) \ |
| HID_USAGE_PAGE_N ( HID_USAGE_PAGE_VENDOR, 2 ),\ |
| HID_USAGE ( 0x01 ),\ |
| HID_COLLECTION ( HID_COLLECTION_APPLICATION ),\ |
| /* Report ID if any */\ |
| __VA_ARGS__ \ |
| /* Input */ \ |
| HID_USAGE ( 0x02 ),\ |
| HID_LOGICAL_MIN ( 0x00 ),\ |
| HID_LOGICAL_MAX_N ( 0xff, 2 ),\ |
| HID_REPORT_SIZE ( 8 ),\ |
| HID_REPORT_COUNT( report_size ),\ |
| HID_INPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ),\ |
| /* Output */ \ |
| HID_USAGE ( 0x03 ),\ |
| HID_LOGICAL_MIN ( 0x00 ),\ |
| HID_LOGICAL_MAX_N ( 0xff, 2 ),\ |
| HID_REPORT_SIZE ( 8 ),\ |
| HID_REPORT_COUNT( report_size ),\ |
| HID_OUTPUT ( HID_DATA | HID_VARIABLE | HID_ABSOLUTE ),\ |
| HID_COLLECTION_END \ |
| |
| //--------------------------------------------------------------------+ |
| // Internal Class Driver API |
| //--------------------------------------------------------------------+ |
| void hidd_init (void); |
| void hidd_reset (uint8_t rhport); |
| uint16_t hidd_open (uint8_t rhport, tusb_desc_interface_t const * itf_desc, uint16_t max_len); |
| bool hidd_control_xfer_cb (uint8_t rhport, uint8_t stage, tusb_control_request_t const * request); |
| bool hidd_xfer_cb (uint8_t rhport, uint8_t ep_addr, xfer_result_t event, uint32_t xferred_bytes); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* _TUSB_HID_DEVICE_H_ */ |