• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Vibrator Development (C/C++)
2<!--Kit: Sensor Service Kit-->
3<!--Subsystem: Sensors-->
4<!--Owner: @dilligencer-->
5<!--Designer: @butterls-->
6<!--Tester: @murphy84-->
7<!--Adviser: @hu-zhiqiong-->
8
9## When to Use
10
11You can set different vibration effects as needed, for example, customizing the vibration intensity, frequency, and duration for button touches, alarm clocks, and incoming calls.
12
13For details about the APIs, see [Vibrator API Reference](../../reference/apis-sensor-service-kit/vibrator_8h.md).
14
15
16## Function Description
17
18| Name                                                        | Description                          |
19| ------------------------------------------------------------ | ------------------------------ |
20| OHOS::Sensors::OH_Vibrator_PlayVibration(int32_t duration, Vibrator_Attribute attribute) | Configures the vibrator to vibrate continuously for a given duration.|
21| OHOS::Sensors::OH_Vibrator_PlayVibrationCustom(Vibrator_FileDescription fileDescription, Vibrator_Attribute vibrateAttribute) | Configures the vibrator to vibrate with the custom sequence.          |
22| OHOS::Sensors::OH_Vibrator_Cancel()                          | Stops the vibration.                |
23
24## Vibration Effect Description
25
26Currently, two types of vibration effects are supported.
27
28### Fixed-Duration Vibration
29
30Only a fixed duration is passed in, and the device vibrates based on the default intensity and frequency.
31
32### Custom Vibration
33
34Custom vibration enables you to design desired vibration effects by customizing a vibration configuration file and orchestrating vibration forms based on the corresponding rules.
35
36
37## How to Develop
38
391. Create a native C++ project.
40
41   ![Create a project](figures/004.png)
42
432. Before using the vibrator on a device, you must declare the **ohos.permission.VIBRATE** permission. For details, see [Declaring Permissions](../../security/AccessToken/declare-permissions.md).
44
45   ```json
46   "requestPermissions": [
47         {
48           "name": "ohos.permission.VIBRATE",
49         },
50       ]
51   ```
52
533. Add the dynamic dependency libraries into the **CMakeLists.txt** file.
54
55   ```c
56   target_link_libraries(entry PUBLIC libace_napi.z.so)
57   target_link_libraries(entry PUBLIC libhilog_ndk.z.so)
58   target_link_libraries(entry PUBLIC libohvibrator.z.so)
59   ```
60
614. Import modules.
62
63   ```c
64   #include <sensors/vibrator.h>
65   #include "napi/native_api.h"
66   #include "hilog/log.h"
67   #include <thread>
68   #include <fcntl.h>
69   #include <unistd.h>
70   #include <sys/stat.h>
71   ```
72
735. Define constants.
74
75   ```c
76   const int GLOBAL_RESMGR = 0xFF00;
77   const char *TAG = "[NativeVibratorTest]";
78   constexpr int32_t TIME_WAIT_FOR_OP = 2;
79   ```
80
816. Configure the vibrator to vibrate continuously for a given duration.
82
83   ```c
84   static napi_value Vibration_Test(napi_env env, napi_callback_info info)
85   {
86       Vibrator_Attribute vibrateAttribute;
87       vibrateAttribute.usage = VIBRATOR_USAGE_ALARM;
88
89       int32_t ret = OH_Vibrator_PlayVibration(0, vibrateAttribute); // Configure the vibrator to vibrate continuously for a given duration.
90       OH_LOG_Print(LOG_APP, LOG_INFO, GLOBAL_RESMGR, TAG, "Vibration successful");
91       if (ret != 0) {
92           return nullptr;
93       }
94       std::this_thread::sleep_for(std::chrono::milliseconds(TIME_WAIT_FOR_OP));
95       ret = OH_Vibrator_Cancel(); // Stop vibration.
96       if (ret != 0) {
97           return nullptr;
98       }
99       napi_value result = nullptr;
100       napi_create_int32(env, ret, &result);
101       return result;
102   }
103   ```
104
1058. Configure the vibrator to vibrate with the custom sequence.
106
107   ```c
108   static napi_value VibrationCustom_Test(napi_env env, napi_callback_info info)
109   {
110       int32_t ret = 0;
111       int32_t fd = open("/data/test/vibrator/coin_drop.json", O_RDONLY);
112       OH_LOG_Print(LOG_APP, LOG_INFO, GLOBAL_RESMGR, TAG, "Test fd:%{public}d", fd);
113       struct stat64 statbuf = { 0 };
114       if (fd < 0) {
115           OH_LOG_Print(LOG_APP, LOG_INFO, GLOBAL_RESMGR, TAG, "File open failed");
116           return nullptr;
117       }
118       if (fstat64(fd, &statbuf) == 0) {
119           Vibrator_FileDescription fileDescription = {
120               .fd = fd,
121               .offset = 0,
122               .length = statbuf.st_size
123           };
124           Vibrator_Attribute vibrateAttribute = {
125               .usage = VIBRATOR_USAGE_RING
126           };
127           ret = OH_Vibrator_PlayVibrationCustom(fileDescription, vibrateAttribute); // Configure the vibrator to vibrate with the custom sequence.
128           OH_LOG_Print(LOG_APP, LOG_INFO, GLOBAL_RESMGR, TAG, "Vibratecustom successful");
129           bool isSuccess = ((ret != 0) || (ret == UNSUPPORTED));
130           if (isSuccess == true) {
131               close(fd);
132               return nullptr;
133           }
134       }
135       std::this_thread::sleep_for(std::chrono::milliseconds(TIME_WAIT_FOR_OP));
136       close(fd);
137       OH_Vibrator_Cancel(); // Stop vibration.
138       napi_value result = nullptr;
139       napi_create_int32(env, ret, &result);
140       return result;
141   }
142   ```
143
1448. Introduce the NAPI APIs to the **index.d.ts** file in **types/libentry**.
145
146   ```c
147   export const vibration_Test: () => number;
148   export const vibrationCustom_Test: () => number;
149   ```
150
1519. Write JavaScript test cases to test the APIs.
152