/* * 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, uint16_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, uint16_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, /*uint16_t*/ 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, uint16_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 (Shift, 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_ */