HarmonyOS鸿蒙开发 (5.0 ) Vibrator马达驱动模型详解

  鸿蒙开发往期必看：

HarmonyOS NEXT应用开发性能实践总结

一分钟了解”纯血版！鸿蒙HarmonyOS Next应用开发！

“非常详细的” 鸿蒙HarmonyOS Next应用开发学习路线！（从零基础入门到精通）

 “一杯冰美式的时间” 了解鸿蒙HarmonyOS Next应用开发路径！

---

功能简介

为了快速开发马达驱动，基于HDF（Hardware Driver Foundation）驱动框架开发了马达（Vibrator）驱动模型。马达驱动模型，屏蔽设备驱动与系统交互的实现，为硬件服务层提供统一稳定的驱动接口能力，为驱动开发者提供开放的接口和解析接口的能力，用于不同操作系统马达设备部件的部署指导和马达设备部件驱动的开发。马达驱动模型如图1所示：

图 1 马达驱动模型图

基本概念

根据振动原理的不同，目前马达可以分为两种：

• 转子马达

  转子马达依靠旋转带动配重振动，分为普通转子和币型转子两种。转子马达的启停反应慢，并且无法实现多种振动模式，但其优点是成本低且体积小。

• 线性马达

  线性马达依靠磁力快速抖动配重来振动，分为纵向线性马达和横向线性马达两种。线性马达的启停都非常快，可以实现不同振感且具有良好的方向性。

系统通过调用马达驱动接口实现对设备的振动控制。目前，马达只有两种振动方式：

• 单次振动

  单次振动是指按照指定的时间控制振动时长。

• 周期振动

  周期振动是指按照预置的效果模式控制振动。例如：预置效果为“haptic.clock.timer” = [600, 600, 200, 600]，表示等待600ms，振动600ms，等待200ms，振动600ms。

运作机制

通过介绍马达驱动模型的加载以及运行流程，对模型内部关键组件以及关联组件之间的关系进行了划分，整体加载流程如图2所示：

图2 马达驱动运行图

以标准系统RK3568产品为例，介绍马达模块驱动加载及运行流程：

1. Device Manager从device_info.hcs配置文件中读取Vibrator管理配置信息。
2. HCS Parser解析Vibrator管理配置信息，并加载对应的马达抽象驱动。
3. Device Manager从linear_vibrator_config.hcs配置文件中读取Vibrator数据配置信息。
4. HCS Parser解析Vibrator数据配置信息，并加载对应的Haptic驱动。
5. Vibrator Proxy获取到Vibrator HDI接口服务实例后，通过IPC（Inter-Process Communication）调用到Vibrator Stub。
6. Vibrator Stub主要处理与IPC相关的业务逻辑，完成参数反序列化后调用Vibrator Controller。
7. Vibrator Controller中是HDI接口的真正实现，通过IPC调用Vibrator抽象驱动接口。
8. 在Haptic驱动中起线程，解析效果模块。
9. Haptic驱动调用马达抽象驱动中的Start接口。
10. 马达抽象驱动进一步调用马达差异化驱动中的Start接口，控制马达设备以给定的效果振动。

开发指导

场景介绍

当设备需要设置不同的振动效果时，可以调用Vibrator模块，例如，设备的按键可以设置不同强度和时长的振动，闹钟和来电可以设置不同强度和时长的单次或周期性振动。

接口说明

马达驱动模型支持静态HCS配置和动态参数两种振动效果配置能力。马达硬件服务调用StartOnce接口动态配置持续振动，调用Start接口启动静态配置的振动效果。马达驱动模型对外开放的API接口能力，如下表所示。

表 1 马达驱动模型对外API接口能力介绍

注：以下接口列举的为C接口，接口声明见文件/drivers/peripheral/vibrator/interfaces/include。

接口名	功能描述
int32_t (*StartOnce)(uint32_t duration)	控制马达以执行给定持续时间的单次振动，duration表示单次振动的持续时间。
int32_t (*Start)(const char *effectType)	控制马达以预置效果执行周期性振动，effectType表示指向预设效果类型的指针。
int32_t (*Stop)(enum VibratorMode mode)	停止马达振动，mode表示振动模式，可以是单次或周期性的。
int32_t (*EnableVibratorModulation)(uint32_t duration, int32_t intensity, int32_t frequency)	根据传入的振动效果启动马达，duration表示马达振动的持续时间，intensity表示振动周期内的马达振幅，frequency表示振动周期内的马达频率。
int32_t (*GetVibratorInfo)(struct VibratorInfo **vibratorInfo)	获取系统中支持设置振幅和频率的所有马达信息，vibratorInfo表示指向马达信息的指针。
int32_t (*EnableCompositeEffect)(struct CompositeEffect *effect);	控制马达以自定义复合效果进行周期性振动。
int32_t (*GetEffectInfo)(const char *effectType, struct EffectInfo *effectInfo);	获取指定效果类型的振动效果信息。
int32_t (*IsVibratorRunning)(bool state);	获取到的马达当前是否正在振动。
int32_t (*PlayHapticPattern)(const HapticPaket& pkg);	以pkg数据包的形式下发高清振动数据进行振动。
int32_t (*GetHapticCapacity)(HapticCapacity& hapticCapacity);	获取马达振动能力，包含是否支持高清振动、是否支持预定义波形、是否支持延时振动。
int32_t (*GetHapticStartUpTime)(int32_t mode, int32_t& startUpTime);	获取起振延时，mode表示振动模式，startUpTime是出参，表示起振延时。

开发步骤

Vibrator驱动模型为上层马达硬件服务层提供稳定的马达控制能力接口，包括马达一次振动、马达效果配置震动、马达停止。基于HDF驱动框架开发的马达驱动模型，实现跨操作系统迁移、器件差异配置等功能。以