1# Vibrator
2
3## Introduction
4
5The vibrator driver model provides and implements vibrator-related Hardware Device Interfaces (HDIs). It supports vibration of the following types:
6
7- One-shot vibration for a specified duration (**StartOnce**).
8- Vibration with the specified effect (**StartEffect**). The effect is configured in the HDF Configuration Source (HCS).
9- Vibration with the specified duration, intensity, and frequency (**EnableVibratorModulation**).
10
11**Figure 1** Vibrator driver model
12
13![Vibrator driver model](figures/vibrator_driver_model.png)
14
15## Directory Structure
16
17The directory structure of the vibrator module is as follows:
18
19```
20/drivers/peripheral/vibrator
21├── chipset          # Driver code of the vibrator module
22├── hal              # HAL code
23│   ├── include      # HAL header files
24│   └── src          # HAL code implementation
25├── interfaces       # Driver APIs provided for upper-layer services
26│   └── include      # APIs exposed externally
27└── test             # Test code
28    └── unittest     # Unit test code
29```
30
31## Usage
32
33### Available APIs
34
35The APIs provided for the vibrator are used to start and stop vibration. The following table describes these APIs.
36
37**Table 1** Main APIs of the vibrator module
38
39| API                                                      | Description                                                    |
40| ------------------------------------------------------------ | ------------------------------------------------------------ |
41| int32_t  StartOnce(uint32_t duration)                        | Starts vibration for a given **duration**.          |
42| int32_t  Start(const char *effectType)                       | Starts vibration with a given effect, which is specified by **effectType**.  |
43| int32_t  Stop(enum VibratorMode mode)                        | Stops vibration based on the specified vibration mode.                                |
44| int32_t EnableVibratorModulation(uint32_t duration, int32_t intensity, int32_t frequency) | Starts vibration with a given **duration**, **intensity**, and **frequency**.|
45| int32_t GetVibratorInfo(struct VibratorInfo **vibratorInfo); | Obtains vibrator information, including whether the intensity and frequency can be set and the intensity and frequency range.|
46
47### How to Use
48
49The sample code is as follows:
50
51```c++
52#include "vibrator_if.h"
53
54enum VibratorMode {
55    VIBRATOR_MODE_ONCE   = 0,    // Start one-shot vibration for a specified period.
56    VIBRATOR_MODE_PRESET = 1,    // Start periodic vibration with the preset effect.
57};
58
59void VibratorSample(void)
60{
61    int32_t startRet;
62    int32_t endRet;
63    uint32_t g_duration = 1000;
64    uint32_t g_sleepTime1 = 2000;
65    uint32_t g_sleepTime2 = 5000;
66    int32_t g_intensity1 = 30;
67    int32_t g_frequency1 = 200;
68    const char *g_timeSequence = "haptic.clock.timer";
69    struct VibratorInfo *g_vibratorInfo = nullptr;
70    /* Create a VibratorInterface instance. */
71    struct VibratorInterface *g_vibratorDev = NewVibratorInterfaceInstance();
72    if (g_vibratorDev == NULL) {
73        return;
74    }
75    /* Obtain vibrator information, including whether the intensity and frequency can be set and the intensity and frequency range. */
76    startRet = g_vibratorDev->GetVibratorInfo(&g_vibratorInfo);
77    if (startRet != 0) {
78        return;
79    }
80    /* Start vibration with the specified duration. */
81    startRet = g_vibratorDev->StartOnce(g_duration);
82    if (startRet != 0) {
83        return;
84    }
85    OsalMSleep(g_sleepTime1);
86    /* Stop vibration based on the specified vibration mode. */
87    endRet = g_vibratorDev->Stop(VIBRATOR_MODE_ONCE);
88    if (endRet != 0) {
89        return;
90    }
91    /* Start vibration with the preset effect. */
92    startRet = g_vibratorDev->Start(g_timeSequence);
93    if (endRet != 0) {
94        return;
95    }
96    OsalMSleep(g_sleepTime2);
97    /* Stop vibration based on the specified vibration mode. */
98    endRet = g_vibratorDev->Stop(VIBRATOR_MODE_PRESET);
99    if (endRet != 0) {
100        return;
101    }
102    /* Start vibration based on the specified duration, intensity, and frequency. */
103    startRet = g_vibratorDev->EnableVibratorModulation(g_duration, g_intensity1, g_frequency1);
104    if (endRet != 0) {
105        return;
106    }
107    OsalMSleep(g_sleepTime1);
108    /* Stop vibration based on the specified vibration mode. */
109    startRet = g_vibratorDev->Stop(VIBRATOR_MODE_ONCE);
110    if (endRet != 0) {
111        return;
112    }
113    /* Release the VibratorInterface instance. */
114    ret = FreeVibratorInterfaceInstance();
115    if (ret != 0) {
116        return;
117    }
118}
119```
120
121## Repositories Involved
122
123[Drive Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/driver.md)
124
125[drivers_hdf_core](https://gitee.com/openharmony/drivers_hdf_core/blob/master/README_zh.md)
126
127[drivers_peripheral](https://gitee.com/openharmony/drivers_peripheral)
128