1# sensor<a name="EN-US_TOPIC_0000001078202098"></a>
2
3-   [Introduction](#section11660541593)
4-   [Directory Structure](#section161941989596)
5-   [Usage](#section45490312053)
6    -   [Available APIs](#section14840627279)
7    -   [Usage Guidelines](#section460510231888)
8
9-   [Repositories Involved](#section12495154795416)
10
11## Introduction<a name="section11660541593"></a>
12
13The sensor driver module provides and implements sensor-related Hardware Driver Interfaces \(HDIs\), including obtaining sensor information, enabling or disabling a sensor, subscribing to or unsubscribing from sensor data, and setting sensor options. These APIs make service development easier.
14
15**Figure  1**  Sensor driver module architecture<a name="fig1292918466322"></a>
16![](figures/sensor-driver-module-architecture.png "sensor-driver-module-architecture")
17
18## Directory Structure<a name="section161941989596"></a>
19
20The directory structure of the sensor driver module is as follows:
21
22```
23/drivers/peripheral/sensor
24├── hal                # HAL code
25│   └── include       # HAL header files
26│   └── src           # HAL code implementation
27├── interfaces         # Driver capability APIs provided for upper-layer services
28│   └── include       # APIs exposed externally
29├── test               # Test code
30│   └── unittest      # Unit test code
31```
32
33## Usage<a name="section45490312053"></a>
34
35This section uses the acceleration sensor as an example to describe how to use sensor APIs.
36
37### Available APIs<a name="section14840627279"></a>
38
39The HAL module of the sensor driver provides APIs that can be directly called by sensor services to obtain, set, and subscribe to or unsubscribe from sensor data. The following table lists the APIs provided by the sensor driver module.
40
41**Table  1**  Major HDIs of the sensor module
42
43<a name="table132511511499"></a>
44<table><thead align="left"><tr id="row22545164911"><th class="cellrowborder" valign="top" width="9.85098509850985%" id="mcps1.2.4.1.1"><p id="p17401913133218"><a name="p17401913133218"></a><a name="p17401913133218"></a>Category</p>
45</th>
46<th class="cellrowborder" valign="top" width="53.88538853885388%" id="mcps1.2.4.1.2"><p id="p20921103144918"><a name="p20921103144918"></a><a name="p20921103144918"></a>API</p>
47</th>
48<th class="cellrowborder" valign="top" width="36.26362636263626%" id="mcps1.2.4.1.3"><p id="p109216317495"><a name="p109216317495"></a><a name="p109216317495"></a>Description</p>
49</th>
50</tr>
51</thead>
52<tbody><tr id="row9256564919"><td class="cellrowborder" valign="top" width="9.85098509850985%" headers="mcps1.2.4.1.1 "><p id="p8437193673211"><a name="p8437193673211"></a><a name="p8437193673211"></a>Query</p>
53</td>
54<td class="cellrowborder" valign="top" width="53.88538853885388%" headers="mcps1.2.4.1.2 "><p id="p11001322173912"><a name="p11001322173912"></a><a name="p11001322173912"></a>int32_t <strong id="b935414557240"><a name="b935414557240"></a><a name="b935414557240"></a>GetAllSensors</strong>(struct SensorInformation **sensorInfo, int32_t *count)</p>
55</td>
56<td class="cellrowborder" valign="top" width="36.26362636263626%" headers="mcps1.2.4.1.3 "><p id="p199227318499"><a name="p199227318499"></a><a name="p199227318499"></a>Obtains information about all sensors in the system. The information about a sensor generally includes the sensor name, sensor vendor, firmware version, hardware version, sensor type ID, sensor ID, maximum measurement range, accuracy, and power.</p>
57</td>
58</tr>
59<tr id="row1026352493"><td class="cellrowborder" rowspan="5" valign="top" width="9.85098509850985%" headers="mcps1.2.4.1.1 "><p id="p06071477324"><a name="p06071477324"></a><a name="p06071477324"></a>Setting</p>
60</td>
61<td class="cellrowborder" valign="top" width="53.88538853885388%" headers="mcps1.2.4.1.2 "><p id="p38874252376"><a name="p38874252376"></a><a name="p38874252376"></a>int32_t <strong id="b199602219271"><a name="b199602219271"></a><a name="b199602219271"></a>Enable</strong>(int32_t sensorId)</p>
62</td>
63<td class="cellrowborder" valign="top" width="36.26362636263626%" headers="mcps1.2.4.1.3 "><p id="p5922331114916"><a name="p5922331114916"></a><a name="p5922331114916"></a>Enables the sensor that has been subscribed to. The subscriber can obtain the sensor data only after the sensor is enabled.</p>
64</td>
65</tr>
66<tr id="row42612518492"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p6923143184914"><a name="p6923143184914"></a><a name="p6923143184914"></a>int32_t <strong id="b84601875330"><a name="b84601875330"></a><a name="b84601875330"></a>Disable</strong>(int32_t sensorId)</p>
67</td>
68<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p139231531184912"><a name="p139231531184912"></a><a name="p139231531184912"></a>Disables a sensor.</p>
69</td>
70</tr>
71<tr id="row14261659498"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p992473112496"><a name="p992473112496"></a><a name="p992473112496"></a>int32_t <strong id="b16691194511438"><a name="b16691194511438"></a><a name="b16691194511438"></a>SetBatch</strong>(iint32_t sensorId, int64_t samplingInterval, int64_t reportInterval)</p>
72</td>
73<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p14924203134910"><a name="p14924203134910"></a><a name="p14924203134910"></a>Sets the data sampling interval and data reporting interval for the specified sensor.</p>
74</td>
75</tr>
76<tr id="row82615144912"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p170411511281"><a name="p170411511281"></a><a name="p170411511281"></a>int32_t <strong id="b170414153284"><a name="b170414153284"></a><a name="b170414153284"></a>SetMode</strong>(int32_t sensorTypeId, SensorUser *user, int32_t mode)</p>
77</td>
78<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p107051159281"><a name="p107051159281"></a><a name="p107051159281"></a>Sets the data reporting mode for the specified sensor.</p>
79</td>
80</tr>
81<tr id="row7260574918"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p492513120494"><a name="p492513120494"></a><a name="p492513120494"></a>int32_t <strong id="b7501191019330"><a name="b7501191019330"></a><a name="b7501191019330"></a>SetOption</strong>(int32_t sensorId, uint32_t option)</p>
82</td>
83<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p5926031124914"><a name="p5926031124914"></a><a name="p5926031124914"></a>Sets options for the specified sensor, including its measurement range and accuracy.</p>
84</td>
85</tr>
86<tr id="row5261957493"><td class="cellrowborder" rowspan="2" valign="top" width="9.85098509850985%" headers="mcps1.2.4.1.1 "><p id="p1039815743211"><a name="p1039815743211"></a><a name="p1039815743211"></a>Data subscription and unsubscription</p>
87</td>
88<td class="cellrowborder" valign="top" width="53.88538853885388%" headers="mcps1.2.4.1.2 "><p id="p11530101054411"><a name="p11530101054411"></a><a name="p11530101054411"></a>int32_t <strong id="b0569161217334"><a name="b0569161217334"></a><a name="b0569161217334"></a>Register</strong>(RecordDataCallback cb)</p>
89</td>
90<td class="cellrowborder" valign="top" width="36.26362636263626%" headers="mcps1.2.4.1.3 "><p id="p892633118493"><a name="p892633118493"></a><a name="p892633118493"></a>Registers the callback for reporting sensor data to the subscriber.</p>
91</td>
92</tr>
93<tr id="row10900102644918"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p196491214133110"><a name="p196491214133110"></a><a name="p196491214133110"></a>int32_t <strong id="b13758151483317"><a name="b13758151483317"></a><a name="b13758151483317"></a>Unregister</strong>(void)</p>
94</td>
95<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p5817133119"><a name="p5817133119"></a><a name="p5817133119"></a>Unregisters the callback for reporting sensor data.</p>
96</td>
97</tr>
98<tr id="row0353356768"><td class="cellrowborder" rowspan="2" valign="top" width="9.85098509850985%" headers="mcps1.2.4.1.1 "><p id="p6596162112564"><a name="p6596162112564"></a><a name="p6596162112564"></a>Instance creation</p>
99</td>
100<td class="cellrowborder" valign="top" width="53.88538853885388%" headers="mcps1.2.4.1.2 "><p id="p13679191616561"><a name="p13679191616561"></a><a name="p13679191616561"></a>const struct SensorInterface *<strong id="b334310134717"><a name="b334310134717"></a><a name="b334310134717"></a>NewSensorInterfaceInstance</strong>(void)</p>
101</td>
102<td class="cellrowborder" valign="top" width="36.26362636263626%" headers="mcps1.2.4.1.3 "><p id="p19679181612563"><a name="p19679181612563"></a><a name="p19679181612563"></a>Creates a <strong id="b166561232174515"><a name="b166561232174515"></a><a name="b166561232174515"></a>SensorInterface</strong> instance.</p>
103</td>
104</tr>
105<tr id="row53542561265"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p15680111655611"><a name="p15680111655611"></a><a name="p15680111655611"></a>int32_t <strong id="b99024181871"><a name="b99024181871"></a><a name="b99024181871"></a>FreeSensorInterfaceInstance</strong>(void)</p>
106</td>
107<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p18680916165620"><a name="p18680916165620"></a><a name="p18680916165620"></a>Releases the <strong id="b1067184719453"><a name="b1067184719453"></a><a name="b1067184719453"></a>SensorInterface</strong> instance.</p>
108</td>
109</tr>
110</tbody>
111</table>
112
113### Usage Guidelines<a name="section460510231888"></a>
114
115Sample code
116
117```
118#include "sensor_if.h"
119#include "sensor_type.h"
120
121/* Create a callback. */
122void SensorDataCallback(struct SensorEvents *event)
123{
124    if(event == NULL){
125        return;
126    }
127    float *sensorData=(float *)event->data;
128    printf("sensor data[%f]", *sensorData);
129}
130
131void SensorSample(void)
132{
133    int ret;
134    struct SensorInformation *sensorInfo = NULL;
135    int32_t count = 0;
136    int32_t sensorInterval = 200000000; /* Set the data sampling rate to 200000000, in the unit of nanoseconds (200 ms). */
137
138    /* 1. Create a SensorInterface instance. */
139    const struct SensorInterface *sensorDev = NewSensorInterfaceInstance();
140    if (sensorDev == NULL) {
141        return;
142    }
143     /* 2. Register a sensor data callback. */
144    ret = sensorDev->Register(0, SensorDataCallback);
145    if (ret != 0) {
146        return;
147    }
148    /* 3. Obtain the list of sensors supported by the device. */
149    ret = sensorDev->GetAllSensors(&sensorInfo, &count);
150    if (ret != 0) {
151        return;
152    }
153    /* 4. Set the sensor sampling rate. */
154    ret = sensorDev->SetBatch(SENSOR_TYPE_ACCELEROMETER, sensorInterval, 0);
155    if (ret != 0) {
156        return;
157    }
158    /* 5. Enable the sensor. */
159    ret = sensorDev->Enable(SENSOR_TYPE_ACCELEROMETER);
160    if (ret != 0) {
161        return;
162    }
163      /* 6. Disable the sensor. */
164    ret = sensorDev->Disable(SENSOR_TYPE_ACCELEROMETER);
165    if (ret != 0) {
166        return;
167    }
168    /* 7. Unregister the sensor data callback. */
169    ret = sensorDev->Unregister(0);
170    if (ret != 0) {
171        return;
172    }
173    /* 8. Release the SensorInterface instance.
174    ret = FreeSensorInterfaceInstance();
175    if (ret != 0) {
176        return;
177    }
178}
179```
180
181## Repositories Involved<a name="section12495154795416"></a>
182
183[Driver subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/driver.md)
184
185[drivers\_framework](https://gitee.com/openharmony/drivers_framework/blob/master/README.md)
186
187[drivers\_adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README.md)
188
189[drivers\_adapter\_khdf\_linux](https://gitee.com/openharmony/drivers_adapter_khdf_linux/blob/master/README.md)
190
191[drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral)
192
193