1# HID DDK Development
2
3## When to Use
4
5The HID driver development kit (DDK) is a toolset that helps you develop HID device drivers at the application layer based on the user mode. It provides interfaces for accessing devices from a host, including creating a device, sending events to a device, and destroying a device.
6
7## Constraints
8
9* The open APIs of the HID DDK can be used to develop drivers of non-standard HID peripherals.
10
11* The open APIs of the HID DDK can be used only within the DriverExtensionAbility lifecycle.
12
13* To use the open APIs of the HID DDK, you need to declare the matching ACL permissions in **module.json5**, for example, **ohos.permission.ACCESS_DDK_HID**.
14
15## Available APIs
16
17| Name| Description|
18| -------- | -------- |
19| OH_Hid_CreateDevice(Hid_Device *hidDevice, Hid_EventProperties *hidEventProperties) | Creates a HID device. When the device is no longer needed, use **OH_Hid_DestroyDevice** to destroy it.|
20| OH_Hid_EmitEvent(int32_t deviceId, const Hid_EmitItem items[], uint16_t length) | Sends events to a HID device.|
21| OH_Hid_DestroyDevice(int32_t deviceId) | Destroys a HID device.|
22
23For details about the APIs, see [HID DDK](../reference/apis-driverdevelopment-kit/_hid_ddk.md).
24
25## How to Develop
26
27The following steps you through the development of a HID device driver with the HID DDK.
28
29**Adding the Dynamic Link Library**
30
31Add the following library to **CMakeLists.txt**.
32```txt
33libhid.z.so
34```
35
36**Including Header Files**
37```c++
38#include <hid/hid_ddk_api.h>
39#include <hid/hid_ddk_types.h>
40```
41
421. Create a device.
43
44    Use **OH_Hid_CreateDevice** in **hid_ddk_api.h** to create a HID device. If the operation is successful, **deviceId** (a non-negative number) is returned. If the operation fails, an error code (a negative number) is returned.
45
46    ```c++
47   // Construct HID device properties.
48   std::vector<Hid_DeviceProp> deviceProp = {HID_PROP_DIRECT};
49   std::string deviceName = "keyboard"
50   Hid_Device hidDevice = {
51       .deviceName = deviceName.c_str(),
52       .vendorId = 0x6006,
53       .productId = 0x6006,
54       .version = 1,
55       .bustype = 3,
56       .properties = deviceProp.data(),
57       .propLength = (uint16_t)deviceProp.size()
58   };
59   // Construct the event properties related to the HID device.
60   std::vector<Hid_EventType> eventType = {HID_EV_ABS, HID_EV_KEY, HID_EV_SYN, HID_EV_MSC};
61   Hid_EventTypeArray eventTypeArray = {.hidEventType = eventType.data(), .length = (uint16_t)eventType.size()};
62   std::vector<Hid_KeyCode> keyCode = {HID_BTN_TOOL_PEN, HID_BTN_TOOL_RUBBER, HID_BTN_TOUCH, HID_BTN_STYLUS, HID_BTN_RIGHT};
63   Hid_KeyCodeArray keyCodeArray = {.hidKeyCode = keyCode.data(), .length = (uint16_t)keyCode.size()};
64   std::vector<Hid_MscEvent> mscEvent = {HID_MSC_SCAN};
65   Hid_MscEventArray mscEventArray = {.hidMscEvent = mscEvent.data(), .length = (uint16_t)mscEvent.size()};
66   std::vector<Hid_AbsAxes> absAxes = {HID_ABS_X, HID_ABS_Y, HID_ABS_PRESSURE};
67   Hid_AbsAxesArray absAxesArray = {.hidAbsAxes = absAxes.data(), .length = (uint16_t)absAxes.size()};
68   Hid_EventProperties hidEventProp = {
69       .hidEventTypes = eventTypeArray,
70       .hidKeys = keyCodeArray,
71       .hidAbs = absAxesArray,
72       .hidMiscellaneous = mscEventArray
73    };
74    // Create a device. The device ID of the device created is returned.
75    int32_t deviceId = OH_Hid_CreateDevice(&hidDevice, &hidEventProp);
76    ```
77
782. Send an event to a HID device.
79
80    Use **OH_Hid_EmitEvent** of **hid_ddk_api.h** to send an event to the device with the specified **deviceId**.
81
82    ```c++
83    // Construct the event to be sent.
84    Hid_EmitItem event = {.type = HID_EV_MSC, .code = HID_MSC_SCAN, .value = 0x000d0042};
85    std::vector<Hid_EmitItem> itemVec;
86    itemVec.push_back(event);
87    // Send the event to a HID device.
88    int32_t ret = OH_Hid_EmitEvent(deviceId, itemVec.data(), (uint16_t)itemVec.size());
89    ```
90
913. Release resources.
92
93    Use **OH_Hid_DestroyDevice** of **hid_ddk_api.h** to destroy the device after all requests are processed and before the application exits.
94
95    ```c++
96    // Destroy a HID device.
97    int32_t ret = OH_Hid_DestroyDevice(deviceId);
98    ```
99