{"id":18041670,"url":"https://github.com/katyo/hid_def","last_synced_at":"2025-04-09T19:22:14.392Z","repository":{"id":66335198,"uuid":"90223585","full_name":"katyo/hid_def","owner":"katyo","description":"HID Report Descriptor macros definitions for C language.","archived":false,"fork":false,"pushed_at":"2019-05-26T18:30:46.000Z","size":62,"stargazers_count":28,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-23T21:11:52.547Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/katyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-04T05:05:12.000Z","updated_at":"2024-11-24T12:59:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"8ca00bf6-094c-4572-af99-68cb5d9c3430","html_url":"https://github.com/katyo/hid_def","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fhid_def","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fhid_def/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fhid_def/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katyo%2Fhid_def/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/katyo","download_url":"https://codeload.github.com/katyo/hid_def/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248095512,"owners_count":21046860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T16:11:22.343Z","updated_at":"2025-04-09T19:22:14.341Z","avatar_url":"https://github.com/katyo.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HID report descriptors on C\n\nThis C-header (*hid_def.h*) declares simple [DSL](https://en.wikipedia.org/wiki/Domain-specific_language), which helps to define **[HID](https://en.wikipedia.org/wiki/USB_HID) report descriptors** immediately in **C source code** in human readable form without using any additional tools like [hidrd](https://github.com/DIGImend/hidrd).\n\nThe language itself is quite similar to the examples from specification ([HID1_11.pdf](https://www.usb.org/developers/hidpage/HID1_11.pdf)), so it is easy to sense and use to declare the HID reports of any complexity.\n\nOf course, you **must** understand how HID report descriptors arranged and how to construct it using elements, but more you don't need to think about its internal binary representation.\n\n*IMPORTANT NOTE*: Because this DSL was developed for and using GCC/CLang so it haven't tested with other kind compilers.\nSo PRs with support for other compilers are welcome.\n\n## The usage example\n\nIn order to get first notion about this library look the example below.\n\nThis is HID report descriptor from official specification **HID 1.11** for standard three button mouse:\n\n```\nUsage Page (Generic Desktop),\nUsage (Mouse),\nCollection (Application),\n  Usage (Pointer),\n  Collection (Physical),\n    Usage Page (Buttons),\n    Usage Minimum (01),\n    Usage Maximun (03),\n    Logical Minimum (0),\n    Logical Maximum (1),\n    Report Count (3),\n    Report Size (1),\n    Input (Data, Variable, Absolute),\n    Report Count (1),\n    Report Size (5),\n    Input (Constant),\n    Usage Page (Generic Desktop),\n    Usage (X),\n    Usage (Y),\n    Logical Minimum (-127),\n    Logical Maximum (127),\n    Report Size (8),\n    Report Count (2),\n    Input (Data, Variable, Relative),\n  End Collection,\nEnd Collection\n```\n\nThis is same example, but rewritten to C using our HID reports definition:\n\n```C\nstatic const uint8_t mouse_hid_report_descriptor[] = {\n  HID_USAGE_PAGE (GENERIC_DESKTOP),\n  HID_USAGE (MOUSE),\n  HID_COLLECTION (APPLICATION),\n    HID_USAGE (POINTER),\n    HID_COLLECTION (PHYSICAL),\n      HID_USAGE_PAGE (BUTTONS),\n      HID_USAGE_MINIMUM (1, 1),\n      HID_USAGE_MAXIMUM (1, 3),\n      HID_LOGICAL_MINIMUM (1, 0),\n      HID_LOGICAL_MAXIMUM (1, 1),\n      HID_REPORT_COUNT (3),\n      HID_REPORT_SIZE (1),\n      HID_INPUT (DATA, VARIABLE, ABSOLUTE),\n      HID_REPORT_COUNT (1),\n      HID_REPORT_SIZE (5),\n      HID_INPUT (CONSTANT),\n      HID_USAGE_PAGE (GENERIC_DESKTOP),\n      HID_USAGE (X),\n      HID_USAGE (Y),\n      HID_LOGICAL_MINIMUM (1, -127),\n      HID_LOGICAL_MAXIMUM (1, 127),\n      HID_REPORT_SIZE (8),\n      HID_REPORT_COUNT (2),\n      HID_INPUT (DATA, VARIABLE, RELATIVE),\n    HID_END_COLLECTION (PHYSICAL),\n  HID_END_COLLECTION (APPLICATION),\n};\n```\n\nThis is quite similar to original example, but elements have a prefix *HID_* to avoid collisions with other identifiers in your sources. Also the elements with values (like `HID_LOGICAL_MINIMUM`, `HID_LOGICAL_MAXIMUM` and etc.) get two arguments: the first means a size of value in bytes, the second is the value itself. The elements, which defines reports (like `HID_INPUT`, `HID_OUTPUT` and `HID_FEATURE`), can get any number of flags. The argument of `HID_END_COLLECTION` elements was added in usability purposes, so it is optional and can be away.\n\nThis is a binary output which get for that descriptor as result of compilation:\n\n```\n00000000  05 01 09 02 a1 01 09 01  a1 00 05 09 19 01 29 03  |..............).|\n00000010  15 00 25 01 95 03 75 01  81 02 95 01 75 05 81 01  |..%...u.....u...|\n00000020  05 01 09 30 09 31 15 81  25 7f 75 08 95 02 81 06  |...0.1..%.u.....|\n00000030  c0 c0                                             |..|\n```\n\nThis is result of converting binary representation back to text using `hidrd-convert` utility:\n\n```\nUsage Page (Desktop),               ; Generic desktop controls (01h)\nUsage (Mouse),                      ; Mouse (02h, application collection)\nCollection (Application),\n    Usage (Pointer),                ; Pointer (01h, physical collection)\n    Collection (Physical),\n        Usage Page (Button),        ; Button (09h)\n        Usage Minimum (01h),\n        Usage Maximum (03h),\n        Logical Minimum (0),\n        Logical Maximum (1),\n        Report Count (3),\n        Report Size (1),\n        Input (Variable),\n        Report Count (1),\n        Report Size (5),\n        Input (Constant),\n        Usage Page (Desktop),       ; Generic desktop controls (01h)\n        Usage (X),                  ; X (30h, dynamic value)\n        Usage (Y),                  ; Y (31h, dynamic value)\n        Logical Minimum (-127),\n        Logical Maximum (127),\n        Report Size (8),\n        Report Count (2),\n        Input (Variable, Relative),\n    End Collection,\nEnd Collection\n```\n\nAs you can see, both textual representation of report for mouse from example and result of decompilation is identical.\n\n## Unit definition\n\nIn some report descriptors you need use measurement units. The HID specification define some basic units which can be used to derive any derivative units. See example below:\n\n```C\n/* Ampere is a basic unit */\nHID_UNIT(SI(LIN), A(1)), HID_UNIT_EXPONENT(0),\n/* Volt can be derived as cm^2 x g^1 x s^-3 x A^-1 x 10^7 */\nHID_UNIT(SI(LIN), CM(2), G(1), S(-3), A(-1)), HID_UNIT_EXPONENT(7),\n/* Watt can be derived as cm^2 x g^1 x s^-3 */\nHID_UNIT(SI(LIN), CM(2), G(1), S(-3)), HID_UNIT_EXPONENT(7),\n/* Joule can be derived as cm^2 x g^1 x s^-2 */\nHID_UNIT(SI(LIN), CM(2), G(1), S(-2)), HID_UNIT_EXPONENT(7),\n```\n\nIn example above we used linear Si measurement system (SI(LIN)) and the next basic units: Centimeter (CM), Gram (G), Second (S), Ampere (A). With it we derived the next derivative units: Volt (V), Watt (W), Joule (J). Moreover we required to use unit exponent to fit value order.\n\n## Additional examples\n\nTo get more usage examples look in *[tests](test/hid_def.c)*.\n\n## How it works\n\nThe implementation uses some advanced C pre-processor techniques, which defined by macros from *macro.h* header.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatyo%2Fhid_def","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatyo%2Fhid_def","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatyo%2Fhid_def/lists"}