README.md
1# Misc Device<a name="EN-US_TOPIC_0000001148523206"></a>
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section44981327519)
5- [Constraints](#section98068674513)
6- [Usage](#section1581412211528)
7 - [Available APIs](#section15684191115524)
8 - [How to Use](#section79302049192310)
9
10- [Repositories Involved](#section96071132185310)
11
12## Introduction<a name="section11660541593"></a>
13
14Misc devices, including vibrators and LED indicators, are used to send signals externally. You can call APIs to control the vibration of vibrators and lighting-on and lighting-off of LED indicators.
15
16**Figure 1** Misc device architecture<a name="fig4460722185514"></a>
17
18
19
20
21## Directory Structure<a name="section44981327519"></a>
22
23```
24/base/sensors/miscdevice
25├── frameworks # Framework code
26│ └── native # Native methods for the client to connect to services
27├── interfaces # External APIs
28│ ├── native # Native implementation
29│ └── plugin # JS APIs
30├── sa_profile # Configuration file of system ability names and dynamic libraries
31├── services # Code of services
32│ └── miscdevice_service # Misc device service, which is used to control the vibration of vibrators and lighting-on and lighting-off of LED lights
33└── utils # Common code, including permissions and communication capabilities
34```
35
36## Constraints<a name="section98068674513"></a>
37
38- The APIs are valid only when your hardware is equipped with the required misc devices.
39- To use vibrators, you need to request the required permissions.
40
41 **Table 1** Permissions required by misc devices
42
43 <a name="table1379101653916"></a>
44 <table><thead align="left"><tr id="row137911161397"><th class="cellrowborder" valign="top" width="15.728427157284273%" id="mcps1.2.5.1.1"><p id="p15138132134118"><a name="p15138132134118"></a><a name="p15138132134118"></a>Misc Device</p>
45 </th>
46 <th class="cellrowborder" valign="top" width="28.537146285371463%" id="mcps1.2.5.1.2"><p id="p2798169398"><a name="p2798169398"></a><a name="p2798169398"></a>Permission Name</p>
47 </th>
48 <th class="cellrowborder" valign="top" width="18.168183181681833%" id="mcps1.2.5.1.3"><p id="p14791716163914"><a name="p14791716163914"></a><a name="p14791716163914"></a>Sensitivity</p>
49 </th>
50 <th class="cellrowborder" valign="top" width="37.56624337566243%" id="mcps1.2.5.1.4"><p id="p379171633919"><a name="p379171633919"></a><a name="p379171633919"></a>Permission Description</p>
51 </th>
52 </tr>
53 </thead>
54 <tbody><tr id="row12791216173912"><td class="cellrowborder" valign="top" width="15.728427157284273%" headers="mcps1.2.5.1.1 "><p id="p18658132191310"><a name="p18658132191310"></a><a name="p18658132191310"></a>Vibrator</p>
55 </td>
56 <td class="cellrowborder" valign="top" width="28.537146285371463%" headers="mcps1.2.5.1.2 "><p id="p8826341131218"><a name="p8826341131218"></a><a name="p8826341131218"></a>ohos.permission.VIBRATE</p>
57 </td>
58 <td class="cellrowborder" valign="top" width="18.168183181681833%" headers="mcps1.2.5.1.3 "><p id="p207991683914"><a name="p207991683914"></a><a name="p207991683914"></a>system_grant</p>
59 </td>
60 <td class="cellrowborder" valign="top" width="37.56624337566243%" headers="mcps1.2.5.1.4 "><p id="p118061614399"><a name="p118061614399"></a><a name="p118061614399"></a>Allows an application to use the vibrator.</p>
61 </td>
62 </tr>
63 </tbody>
64 </table>
65
66
67## Usage<a name="section1581412211528"></a>
68
69This section describes the features and usage of the vibrator APIs.
70
71### Available APIs<a name="section15684191115524"></a>
72
73The APIs provided for the vibrator are used to trigger and stop vibration. The following table describes these APIs.
74
75**Table 2** JS APIs for the vibrator
76
77<a name="table1738121244713"></a>
78<table><thead align="left"><tr id="row4381111254710"><th class="cellrowborder" valign="top" width="31.209999999999997%" id="mcps1.2.3.1.1"><p id="p1738116127470"><a name="p1738116127470"></a><a name="p1738116127470"></a>API</p>
79</th>
80<th class="cellrowborder" valign="top" width="68.78999999999999%" id="mcps1.2.3.1.2"><p id="p10381161224717"><a name="p10381161224717"></a><a name="p10381161224717"></a>Description</p>
81</th>
82</tr>
83</thead>
84<tbody><tr id="row18381121274715"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p15297217910"><a name="p15297217910"></a><a name="p15297217910"></a>vibrate(duration: number, callback?: AsyncCallback<void>)</p>
85</td>
86<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p143812128476"><a name="p143812128476"></a><a name="p143812128476"></a>Triggers vibration based on the duration specified by <strong id="b137434619532"><a name="b137434619532"></a><a name="b137434619532"></a>duration</strong>. This API uses a callback to indicate whether the vibration is triggered successfully.</p>
87</td>
88</tr>
89<tr id="row29912332312"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p599153172316"><a name="p599153172316"></a><a name="p599153172316"></a>vibrate(duration: number): Promise<void></p>
90</td>
91<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p1099114392316"><a name="p1099114392316"></a><a name="p1099114392316"></a>Triggers vibration based on the duration specified by <strong id="b0770125017531"><a name="b0770125017531"></a><a name="b0770125017531"></a>duration</strong>. This API uses a promise to indicate whether the vibration is triggered successfully.</p>
92</td>
93</tr>
94<tr id="row1938113125470"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p13811121475"><a name="p13811121475"></a><a name="p13811121475"></a>vibrate(effectId: EffectId, callback?: AsyncCallback<void>)</p>
95</td>
96<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p538120127476"><a name="p538120127476"></a><a name="p538120127476"></a>Triggers vibration based on the vibration effect specified by <strong id="b1757143012530"><a name="b1757143012530"></a><a name="b1757143012530"></a>effectId</strong>. This API uses a callback to indicate whether the vibration is triggered successfully.</p>
97</td>
98</tr>
99<tr id="row15109898239"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p181101197234"><a name="p181101197234"></a><a name="p181101197234"></a>vibrate(effectId: EffectId): Promise<void></p>
100</td>
101<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p12110159112310"><a name="p12110159112310"></a><a name="p12110159112310"></a>Triggers vibration based on the vibration effect specified by <strong id="b680313655410"><a name="b680313655410"></a><a name="b680313655410"></a>effectId</strong>. This API uses a promise to indicate whether the vibration is triggered successfully.</p>
102</td>
103</tr>
104<tr id="row10382181218477"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p764313511343"><a name="p764313511343"></a><a name="p764313511343"></a>stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>)</p>
105</td>
106<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p1738291234712"><a name="p1738291234712"></a><a name="p1738291234712"></a>Stops vibration based on the mode specified by <strong id="b1019916113564"><a name="b1019916113564"></a><a name="b1019916113564"></a>stopMode</strong>. There are two modes: <strong id="b1784893665611"><a name="b1784893665611"></a><a name="b1784893665611"></a>VIBRATOR_STOP_MODE_TIME</strong> and <strong id="b157644016560"><a name="b157644016560"></a><a name="b157644016560"></a>VIBRATOR_STOP_MODE_PRESET</strong>, which are used to stop vibration triggered by <strong id="b1217141320585"><a name="b1217141320585"></a><a name="b1217141320585"></a>duration</strong> and <strong id="b1639019514578"><a name="b1639019514578"></a><a name="b1639019514578"></a>effectId</strong>, respectively. This API uses a callback to indicate whether the vibration is stopped successfully.</p>
107</td>
108</tr>
109<tr id="row2087541618235"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p13875201620231"><a name="p13875201620231"></a><a name="p13875201620231"></a>stop(stopMode: VibratorStopMode): Promise<void></p>
110</td>
111<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p14875916142317"><a name="p14875916142317"></a><a name="p14875916142317"></a>Stops vibration based on the mode specified by <strong id="b128871517589"><a name="b128871517589"></a><a name="b128871517589"></a>stopMode</strong>. There are two modes: <strong id="b16566172217582"><a name="b16566172217582"></a><a name="b16566172217582"></a>VIBRATOR_STOP_MODE_TIME</strong> and <strong id="b1757216228581"><a name="b1757216228581"></a><a name="b1757216228581"></a>VIBRATOR_STOP_MODE_PRESET</strong>, which are used to stop vibration triggered by <strong id="b257214227586"><a name="b257214227586"></a><a name="b257214227586"></a>duration</strong> and <strong id="b457362275812"><a name="b457362275812"></a><a name="b457362275812"></a>effectId</strong>, respectively. This API uses a promise to indicate whether the vibration is stopped successfully.</p>
112</td>
113</tr>
114</tbody>
115</table>
116
117### How to Use<a name="section79302049192310"></a>
118
1191. Import the **vibrator** package.
1202. Trigger vibration with a specific duration.
1213. Stop vibration that is triggered with a specific duration.
1224. Trigger vibration with a specific effect.
1235. Stop vibration that is triggered with a specific effect.
124
125The following sample code provides a complete process of using the vibrator APIs:
126
127```
128//Step 1 Import the vibrator package.
129import vibrator from '@ohos.vibrator';
130export default {
131 onCreate() {
132 console.info('MiscdeviceJsAPI AceApplication onCreate');
133 // Step 2 Trigger vibration with a specific duration.
134 vibrator.vibrate(100, function(error) {
135 if (error) {
136 console.error("Failed to trigger vibration. Error code: " + error.code);
137 return;
138 }
139 console.info("Succeeded in triggering vibration.");
140 });
141 // Step 3 Stop vibration that is triggered with a specific duration.
142 vibrator.stop("time", function(error) {
143 if (error) {
144 console.error("Failed to stop vibration. Error code: " + error.code);
145 return;
146 }
147 console.info("Succeeded in stopping vibration.");
148 });
149 // Step 4 Trigger vibration based on with a specific effect.
150 vibrator.vibrate("haptic.clock.timer", function(error) {
151 if (error) {
152 console.error("Failed to trigger vibration. Error code: " + error.code);
153 return;
154 }
155 console.info("Succeeded in triggering vibration.");
156 });
157 // Step 54 Stop vibration that is triggered with a specific effect.
158 vibrator.stop("preset", function(error) {
159 if (error) {
160 console.error("Failed to stop vibration. Error code: " + error.code);
161 return;
162 }
163 console.info("Succeeded in stopping vibration.");
164 });
165 }
166 onDestroy() {
167 console.info('AceApplication onDestroy');
168 }
169}
170```
171
172## Repositories Involved<a name="section96071132185310"></a>
173
174Pan-sensor subsystem
175
176[sensors\_sensor](https://gitee.com/openharmony/sensors_sensor)
177
178**sensors\_miscdevice**
README_zh.md
1# Miscdevice<a name="ZH-CN_TOPIC_0000001148523206"></a>
2
3- [简介](#section11660541593)
4- [Sensors\_miscdevice组件目录](#section44981327519)
5- [约束](#section98068674513)
6- [使用](#section1581412211528)
7 - [接口说明](#section15684191115524)
8 - [使用说明](#section79302049192310)
9
10- [相关仓](#section96071132185310)
11
12## 简介<a name="section11660541593"></a>
13
14小器件是指用于向外传递信号的设备，包括马达和LED灯，本组件对开发者提供控制马达振动和LED灯开关的能力，其架构图如下所示：
15
16**图 1** 小器件架构图<a name="fig4460722185514"></a>
17
18
19
20
21## Sensors\_miscdevice组件目录<a name="section44981327519"></a>
22
23```
24/base/sensors/miscdevice
25├── frameworks # 框架代码
26│ └── native # 客户端连接服务的Native方法
27├── interfaces # 对外接口存放目录
28│ ├── native # native 实现
29│ └── plugin # Js API
30├── sa_profile # 服务名称和服务的动态库的配置文件
31├── services # 服务的代码目录
32│ └── miscdevice_service # 小器件服务，包含马达和Led灯，控制马达振动和灯的开关
33└── utils # 公共代码，包括权限、通信等能力
34```
35
36## 约束<a name="section98068674513"></a>
37
38- 要使用器件的功能，设备必须具有对应的器件。
39- 针对马达，开发者需要请求相应的权限才能使用。
40
41 **表 1** 器件权限列表
42
43 <a name="table1379101653916"></a>
44 <table><thead align="left"><tr id="row137911161397"><th class="cellrowborder" valign="top" width="15.728427157284273%" id="mcps1.2.5.1.1"><p id="p15138132134118"><a name="p15138132134118"></a><a name="p15138132134118"></a>器件</p>
45 </th>
46 <th class="cellrowborder" valign="top" width="28.537146285371463%" id="mcps1.2.5.1.2"><p id="p2798169398"><a name="p2798169398"></a><a name="p2798169398"></a>权限名</p>
47 </th>
48 <th class="cellrowborder" valign="top" width="18.168183181681833%" id="mcps1.2.5.1.3"><p id="p14791716163914"><a name="p14791716163914"></a><a name="p14791716163914"></a>敏感级别</p>
49 </th>
50 <th class="cellrowborder" valign="top" width="37.56624337566243%" id="mcps1.2.5.1.4"><p id="p379171633919"><a name="p379171633919"></a><a name="p379171633919"></a>权限描述</p>
51 </th>
52 </tr>
53 </thead>
54 <tbody><tr id="row12791216173912"><td class="cellrowborder" valign="top" width="15.728427157284273%" headers="mcps1.2.5.1.1 "><p id="p18658132191310"><a name="p18658132191310"></a><a name="p18658132191310"></a>马达</p>
55 </td>
56 <td class="cellrowborder" valign="top" width="28.537146285371463%" headers="mcps1.2.5.1.2 "><p id="p8826341131218"><a name="p8826341131218"></a><a name="p8826341131218"></a>ohos.permission.VIBRATE</p>
57 </td>
58 <td class="cellrowborder" valign="top" width="18.168183181681833%" headers="mcps1.2.5.1.3 "><p id="p207991683914"><a name="p207991683914"></a><a name="p207991683914"></a>system_grant</p>
59 </td>
60 <td class="cellrowborder" valign="top" width="37.56624337566243%" headers="mcps1.2.5.1.4 "><p id="p118061614399"><a name="p118061614399"></a><a name="p118061614399"></a>允许应用程序使用马达</p>
61 </td>
62 </tr>
63 </tbody>
64 </table>
65
66
67## 使用<a name="section1581412211528"></a>
68
69本节以马达为例，说明其提供的接口功能以及使用流程。
70
71### 接口说明<a name="section15684191115524"></a>
72
73马达主要提供的功能有：触发震动，停止震动。JS API类开放能力如下：
74
75**表 2** 马达JS API的主要接口
76
77<a name="table1738121244713"></a>
78<table><thead align="left"><tr id="row4381111254710"><th class="cellrowborder" valign="top" width="31.209999999999997%" id="mcps1.2.3.1.1"><p id="p1738116127470"><a name="p1738116127470"></a><a name="p1738116127470"></a>接口名</p>
79</th>
80<th class="cellrowborder" valign="top" width="68.78999999999999%" id="mcps1.2.3.1.2"><p id="p10381161224717"><a name="p10381161224717"></a><a name="p10381161224717"></a>描述</p>
81</th>
82</tr>
83</thead>
84<tbody><tr id="row18381121274715"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p15297217910"><a name="p15297217910"></a><a name="p15297217910"></a>vibrate(duration: number, callback?: AsyncCallback<void>)</p>
85</td>
86<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p143812128476"><a name="p143812128476"></a><a name="p143812128476"></a>按照指定持续时间触发震动。duration为振动持续时长，callback为触发振动是否成功。</p>
87</td>
88</tr>
89<tr id="row29912332312"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p599153172316"><a name="p599153172316"></a><a name="p599153172316"></a>vibrate(duration: number): Promise<void></p>
90</td>
91<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p1099114392316"><a name="p1099114392316"></a><a name="p1099114392316"></a>按照指定持续时间触发震动，返回Promise表示触发振动是否成功。</p>
92</td>
93</tr>
94<tr id="row1938113125470"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p13811121475"><a name="p13811121475"></a><a name="p13811121475"></a>vibrate(effectId: EffectId, callback?: AsyncCallback<void>)</p>
95</td>
96<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p538120127476"><a name="p538120127476"></a><a name="p538120127476"></a>按照指定振动效果字符串触发震动。effectId表示预置的振动效果串，callback为触发振动是否成功。</p>
97</td>
98</tr>
99<tr id="row15109898239"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p181101197234"><a name="p181101197234"></a><a name="p181101197234"></a>vibrate(effectId: EffectId): Promise<void></p>
100</td>
101<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p12110159112310"><a name="p12110159112310"></a><a name="p12110159112310"></a>按照指定振动效果字符串触发震动。effectId表示预置的振动效果串，返回Promise表示触发振动是否成功。</p>
102</td>
103</tr>
104<tr id="row10382181218477"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p764313511343"><a name="p764313511343"></a><a name="p764313511343"></a>stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>)</p>
105</td>
106<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p1738291234712"><a name="p1738291234712"></a><a name="p1738291234712"></a>按照指定的要停止的振动模式来停止震动。stopMode为枚举马达两种振动类型，VIBRATOR_STOP_MODE_TIME、VIBRATOR_STOP_MODE_PRESET分别为停止duration模式的振动和停止预置EffectId模式的振动，callback为停止振动是否成功。</p>
107</td>
108</tr>
109<tr id="row2087541618235"><td class="cellrowborder" valign="top" width="31.209999999999997%" headers="mcps1.2.3.1.1 "><p id="p13875201620231"><a name="p13875201620231"></a><a name="p13875201620231"></a>stop(stopMode: VibratorStopMode): Promise<void></p>
110</td>
111<td class="cellrowborder" valign="top" width="68.78999999999999%" headers="mcps1.2.3.1.2 "><p id="p14875916142317"><a name="p14875916142317"></a><a name="p14875916142317"></a>按照指定的要停止的振动模式来停止震动。stopMode为枚举马达两种振动类型，VIBRATOR_STOP_MODE_TIME、VIBRATOR_STOP_MODE_PRESET分别为停止duration模式的振动和停止预置EffectId模式的振动，返回Promise表示触发振动是否成功。</p>
112</td>
113</tr>
114</tbody>
115</table>
116
117### 使用说明<a name="section79302049192310"></a>
118
1191. 导入vibrator包。
1202. 触发马达按照指定持续时间振动。
1213. 停止马达按照指定持续时间振动。
1224. 触发按照指定振动效果字符串振动。
1235. 停止按照指定振动效果字符串振动。
124
125下述的代码示例中，提供了马达震动使用的完整流程。
126
127```
128//步骤1 导包
129import vibrator from '@ohos.vibrator';
130export default {
131 onCreate() {
132 console.info('MiscdeviceJsAPI AceApplication onCreate');
133 //步骤2 触发马达按照指定持续的时间振动
134 vibrator.vibrate(100, function(error) {
135 if (error) {
136 console.error("Failed to trigger vibration. Error code: " + error.code);
137 return;
138 }
139 console.info("Succeeded in triggering vibration.");
140 });
141 //步骤3 停止马达按照指定持续的时间振动
142 vibrator.stop("time", function(error) {
143 if (error) {
144 console.error("Failed to stop vibration. Error code: " + error.code);
145 return;
146 }
147 console.info("Succeeded in stopping vibration.");
148 });
149 //步骤4 触发马达按照指定的字符串效果振动
150 vibrator.vibrate("haptic.clock.timer", function(error) {
151 if (error) {
152 console.error("Failed to trigger vibration. Error code: " + error.code);
153 return;
154 }
155 console.info("Succeeded in triggering vibration.");
156 });
157 //步骤5 停止马达按照指定的字符串效果振动
158 vibrator.stop("preset", function(error) {
159 if (error) {
160 console.error("Failed to stop vibration. Error code: " + error.code);
161 return;
162 }
163 console.info("Succeeded in stopping vibration.");
164 });
165 }
166 onDestroy() {
167 console.info('AceApplication onDestroy');
168 }
169}
170```
171
172## 相关仓<a name="section96071132185310"></a>
173
174泛Sensor子系统
175
176[sensors\_sensor](https://gitee.com/openharmony/sensors_sensor)
177
178**sensors\_miscdevice**
179
180
