Readme.md
1# Motion
2
3## Introduction
4
5The motion driver is developed based on the Hardware Driver Foundation (HDF). It shields hardware differences and provides stable motion capabilities for upper-layer services. The motion capabilities include enabling or disabling motion and subscribing to or unsubscribing from motion data.
6
7The figure below shows the motion driver architecture. The framework layer provides MSDP services, and interacts with the Motion Hardware Device Interface (HDI) Server through the Motion HDI Client. The Motion HDI Server calls the Motion HDI Impl APIs to provide motion recognition capabilities for upper-layer services.
8
9**Figure 1** Architecture of the motion module
10
11
12
13## Directory Structure
14
15The directory structure of the motion module is as follows:
16
17```
18/drivers/peripheral/motion
19├── hdi_service # Driver capability provided by the motion module for upper-layer services
20├── test # Test codes for the motion module
21│ └── unittest\hdi # HDI unit test code of the motion driver module
22```
23
24## Description
25
26### Available APIs
27
28The motion driver module provides upper-layer services with APIs that can be directly called for various purposes, such as enabling or disabling motion and subscribing to or unsubscribing from motion data. Table 1 lists the APIs provided by the motion driver module.
29
30**Table 1** Motion HDI APIs
31
32| API | Description |
33| ------------------------------------------------------------ | ------------------------------------------------------------ |
34| int32_t EnableMotion(int32_t motionType) | Enables a motion type. The motion data can be obtained only when motion is enabled.|
35| int32_t DisableMotion(int32_t motionType) | Disables a motion type. |
36| int32_t Register(const sptr<IMotionCallback> &callbackObj) | Registers the callback for motion data. When the registration is successful, the system will report the motion data to the subscriber.|
37| int32_t Unregister(const sptr<IMotionCallback> &callbackObj) | Unregisters from the callback for motion data. |
38
39### How to Use
40
41This section describes how to subscribe to pickup data.
42
43Sample Code
44
45```
46#include "v1_0/imotion_interface.h"
47
48/* MotionCallbackService class */
49class MotionCallbackService : public IMotionCallback {
50public:
51 MotionCallbackService() = default;
52 virtual ~MotionCallbackService() = default;
53 int32_t OnDataEvent(const HdfMotionEvent &event) override;
54};
55
56/* Callback */
57int32_t MotionCallbackService::OnDataEvent(const HdfMotionEvent &event)
58{
59 printf("moton :[%d], result[%d]:, status[%d]\n\r", event.motion, event.result, event.status);
60 return HDF_SUCCESS;
61}
62
63void MotionSample(void)
64{
65 int32_t ret;
66 sptr<IMotionInterface> g_motionInterface = nullptr;
67 sptr<IMotionCallback> g_motionCallback = new MotionCallbackService();
68 sptr<IMotionCallback> g_motionCallbackUnregistered = new MotionCallbackService();
69
70 /* 1. Obtain the motion service. */
71 g_motionInterface = IMotionInterface::Get();
72 if (g_motionInterface == nullptr) {
73 return;
74 }
75 /* 2. Register the callback for motion data. */
76 ret = g_motionInterface->Register(g_motionCallback);
77 if (ret != 0) {
78 return;
79 }
80 /* 3. Enable motion. */
81 ret = g_motionInterface->EnableMotion(HDF_MOTION_TYPE_PICKUP);
82 if (ret != 0) {
83 return;
84 }
85 /* 4. Disable motion. */
86 ret = g_motionInterface->DisableMotion(HDF_MOTION_TYPE_PICKUP);
87 if (ret != 0) {
88 return;
89 }
90 /* 5. Unregister from the callback for motion data. */
91 ret = g_motionInterface->Unregister(g_motionCallback);
92 if (ret != 0) {
93 return;
94 }
95}
96```
97
98## Repositories Involved
99
100[Driver](https://gitee.com/openharmony/docs/blob/master/en/readme/driver.md)
101
102[drivers_hdf_core](https://gitee.com/openharmony/drivers_hdf_core)
103
104[drivers_interface](https://gitee.com/openharmony/drivers_interface)
105
106[**drivers\_peripheral**](https://gitee.com/openharmony/drivers_peripheral)
107
Readme_zh.md
1# Motion
2
3## 简介
4
5基于HDF（Hardware Driver Foundation）驱动框架开发的Motion驱动，能够屏蔽硬件器件差异，为上层服务提供稳定的手势识别基础能力接口，包括Motion使能/去使能、Motion订阅/取消订阅等稳定的接口。
6
7Motion驱动模块如图1所示，上层为Framework层，提供MSDP服务，通过UHDF（User Hardware Driver Foundation）层的Motion Proxy与Motion Stub进行交互；而Motion Stub可调用Motion HDI实现类接口，从而实现上层服务的手势识别使能/去使能、手势识别订阅/取消订阅等能力。
8
9**图 1** Motion驱动模块架构图
10
11
12
13## 目录
14
15Motion驱动源代码目录结构如下所示：
16
17```
18/drivers/peripheral/motion
19├── hdi_service # motion模块对上层服务提供的驱动能力
20├── test # motion模块测试代码
21│ └── unittest\hdi # motion模块hdi单元测试代码
22```
23
24## 说明
25
26### 接口说明
27
28Motion驱动模块为上层服务提供可直接调用的能力接口，涉及的主要功能有：使能/去使能手势识别、订阅/取消订阅手势识别数据等操作。Motion驱动模型对HDI开放的API接口功能如表1：
29
30**表 1** Motion HDI 接口列表
31
32| 接口名 | 功能描述 |
33| ------------------------------------------------------------ | ------------------------------------------------------------ |
34| int32_t EnableMotion(int32_t motionType) | 使能一种手势识别类型，只有数据订阅者使能手势识别后，才能获取订阅的手势识别数据。 |
35| int32_t DisableMotion(int32_t motionType) | 去使能一种手势识别类型。 |
36| int32_t Register(const sptr\<IMotionCallback\> &callbackObj) | 订阅者成功注册手势识别数据回调函数，系统会将获取到的手势识别数据上报给订阅者。 |
37| int32_t Unregister(const sptr\<IMotionCallback\> &callbackObj) | 订阅者取消注册手势识别数据回调函数。 |
38
39### 使用说明
40
41本节以订阅拿起手势识别数据为例进行介绍。
42
43代码示例
44
45```
46#include "v1_0/imotion_interface.h"
47
48/* 手势识别回调服务类 */
49class MotionCallbackService : public IMotionCallback {
50public:
51 MotionCallbackService() = default;
52 virtual ~MotionCallbackService() = default;
53 int32_t OnDataEvent(const HdfMotionEvent &event) override;
54};
55
56/* 回调函数 */
57int32_t MotionCallbackService::OnDataEvent(const HdfMotionEvent &event)
58{
59 printf("moton :[%d], result[%d]:, status[%d]\n\r", event.motion, event.result, event.status);
60 return HDF_SUCCESS;
61}
62
63void MotionSample(void)
64{
65 int32_t ret;
66 sptr<IMotionInterface> g_motionInterface = nullptr;
67 sptr<IMotionCallback> g_motionCallback = new MotionCallbackService();
68 sptr<IMotionCallback> g_motionCallbackUnregistered = new MotionCallbackService();
69
70 /* 1.获取motion服务 */
71 g_motionInterface = IMotionInterface::Get();
72 if (g_motionInterface == nullptr) {
73 return;
74 }
75 /* 2.订阅者注册手势识别数据回调处理函数 */
76 ret = g_motionInterface->Register(g_motionCallback);
77 if (ret != 0) {
78 return;
79 }
80 /* 3.使能手势识别 */
81 ret = g_motionInterface->EnableMotion(HDF_MOTION_TYPE_PICKUP);
82 if (ret != 0) {
83 return;
84 }
85 /* 4.去使能手势识别 */
86 ret = g_motionInterface->DisableMotion(HDF_MOTION_TYPE_PICKUP);
87 if (ret != 0) {
88 return;
89 }
90 /* 5.取消手势识别数据订阅函数 */
91 ret = g_motionInterface->Unregister(g_motionCallback);
92 if (ret != 0) {
93 return;
94 }
95}
96```
97
98## 相关仓
99
100[驱动子系统](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)
101
102[drivers_hdf_core](https://gitee.com/openharmony/drivers_hdf_core)
103
104[drivers_interface](https://gitee.com/openharmony/drivers_interface)
105
106[**drivers\_peripheral**](https://gitee.com/openharmony/drivers_peripheral)
