README.md
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
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
README_zh.md
1# vibrator
2
3- [简介](##简介)
4- [目录](##目录)
5- [说明](##说明)
6 - [接口说明](###接口说明)
7 - [使用说明](###使用说明)
8
9- [相关仓](##相关仓)
10
11## 简介
12
13Vibrator驱动模型主要包含Vibrator（马达）相关的HDI接口与实现，提供Vibrator HDI（ Hardware Device Interface ）能力接口，支持三种振动效果：静态HCS配置的时间序列，动态配置持续时间，动态配置持续时间、振动强度、振动频率。调用StartOnce接口动态配置持续振动时间；调用StartEffect接口启动静态配置的振动效果；调用EnableVibratorModulation接口启动动态配置的振动效果。
14
15**图 1** Vibrator驱动模型图
16
17
18
19## 目录
20
21Vibraor驱动下源代码目录结构如下所示：
22
23```
24/drivers/peripheral/vibrator
25├── chipset # vibrator模块器件驱动代码
26├── hal # vibrator模块hal层代码
27│ ├── include # vibrator模块hal层内部头文件
28│ └── src # vibrator模块hal层代码的实现
29├── interfaces # vibrator模块对上层服务提供的驱动能力接口
30│ └── include # vibrator模块对外提供的接口定义
31└── test # vibrator模块测试代码
32 └── unittest # vibrator模块单元测试代码
33```
34
35## 说明
36
37### 接口说明
38
39马达主要提供的功能：触发振动，停止振动。开发能力如下表1：
40
41**表 1**马达的主要接口
42
43| 接口名 | 功能描述 |
44| ------------------------------------------------------------ | ------------------------------------------------------------ |
45| int32_t StartOnce(uint32_t duration) | 按照指定持续时间触发振动，duration为振动持续时长。 |
46| int32_t Start(const char *effectType) | 按照指定预置效果启动马达，effectType表示预置的振动效果串。 |
47| int32_t Stop(enum VibratorMode mode) | 按照指定的振动模式停止振动。 |
48| int32_t EnableVibratorModulation(uint32_t duration, int32_t intensity, int32_t frequency) | 按照指定振幅，频率、持续时间触发振动马达，duration为振动持续时长，intensity为振动强度，frequency为振动频率。 |
49| int32_t GetVibratorInfo(struct VibratorInfo **vibratorInfo); | 获取马达信息，包括是否支持振幅和频率的设置及振幅和频率的设置范围 。 |
50
51### 使用说明
52
53代码示例
54
55```c++
56#include "vibrator_if.h"
57
58enum VibratorMode {
59 VIBRATOR_MODE_ONCE = 0, // 指定时间内的一次振动
60 VIBRATOR_MODE_PRESET = 1, // 指定预置效果的周期性振动
61};
62
63void VibratorSample(void)
64{
65 int32_t startRet;
66 int32_t endRet;
67 uint32_t g_duration = 1000;
68 uint32_t g_sleepTime1 = 2000;
69 uint32_t g_sleepTime2 = 5000;
70 int32_t g_intensity1 = 30;
71 int32_t g_frequency1 = 200;
72 const char *g_timeSequence = "haptic.clock.timer";
73 struct VibratorInfo *g_vibratorInfo = nullptr;
74 /* 创建马达接口实例 */
75 struct VibratorInterface *g_vibratorDev = NewVibratorInterfaceInstance();
76 if (g_vibratorDev == NULL) {
77 return;
78 }
79 /* 获取马达信息，包括是否支持振幅和频率的设置及振幅和频率的设置范围。 */
80 startRet = g_vibratorDev->GetVibratorInfo(&g_vibratorInfo);
81 if (startRet != 0) {
82 return;
83 }
84 /* 按照指定持续时间触发振动*/
85 startRet = g_vibratorDev->StartOnce(g_duration);
86 if (startRet != 0) {
87 return;
88 }
89 OsalMSleep(g_sleepTime1);
90 /* 按照指定的振动模式停止振动 */
91 endRet = g_vibratorDev->Stop(VIBRATOR_MODE_ONCE);
92 if (endRet != 0) {
93 return;
94 }
95 /* 按照指定预置效果启动马达 */
96 startRet = g_vibratorDev->Start(g_timeSequence);
97 if (endRet != 0) {
98 return;
99 }
100 OsalMSleep(g_sleepTime2);
101 /* 按照指定的振动模式停止振动 */
102 endRet = g_vibratorDev->Stop(VIBRATOR_MODE_PRESET);
103 if (endRet != 0) {
104 return;
105 }
106 /* 按照指定振幅，频率、持续时间触发振动马达。 */
107 startRet = g_vibratorDev->EnableVibratorModulation(g_duration, g_intensity1, g_frequency1);
108 if (endRet != 0) {
109 return;
110 }
111 OsalMSleep(g_sleepTime1);
112 /* 按照指定的振动模式停止振动 */
113 startRet = g_vibratorDev->Stop(VIBRATOR_MODE_ONCE);
114 if (endRet != 0) {
115 return;
116 }
117 /* 释放传感器接口实例 */
118 ret = FreeVibratorInterfaceInstance();
119 if (ret != 0) {
120 return;
121 }
122}
123```
124
125## 相关仓
126
127[驱动子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E9%A9%B1%E5%8A%A8%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
128
129[drivers_hdf_core](https://gitee.com/openharmony/drivers_hdf_core/blob/master/README_zh.md)
130
131[drivers_peripheral](https://gitee.com/openharmony/drivers_peripheral)
