From 69713f4903ac0dbb45ed8e4025ed0c31aaa8f0d3 Mon Sep 17 00:00:00 2001 From: xwbmcu Date: Thu, 20 Jan 2022 20:19:31 +0800 Subject: [PATCH 1/3] add light API Signed-off-by: xwbmcu --- zh-cn/device-dev/driver/API/light_if.h | 122 ++++++++++++++++++++++ zh-cn/device-dev/driver/API/light_type.h | 127 +++++++++++++++++++++++ 2 files changed, 249 insertions(+) create mode 100644 zh-cn/device-dev/driver/API/light_if.h create mode 100644 zh-cn/device-dev/driver/API/light_type.h diff --git a/zh-cn/device-dev/driver/API/light_if.h b/zh-cn/device-dev/driver/API/light_if.h new file mode 100644 index 00000000000..afdb044a0d3 --- /dev/null +++ b/zh-cn/device-dev/driver/API/light_if.h @@ -0,0 +1,122 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Light + * @{ + * + * @brief 为上层灯的硬件服务提供驱动程序。获取驱动程序对象或代理后， + * 灯的硬件服务使用驱动程序对象或代理提供的功能获取类型，打开或关闭灯 + * + * @since 2.2 + */ + +/** + * @file Light_if.h + * + * @brief 在light模块中声明通用API。这些API可用于获取类型、控制灯打开、关闭、亮度和闪烁模式 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef LIGHT_IF_H +#define LIGHT_IF_H + +#include +#include "light_type.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief 定义对灯执行基本操作的功能 + * + * 操作包括获取灯信息、启用或关闭灯、设置灯亮度，设置灯闪烁模式 + */ + +struct LightInterface { + /** + * @brief 获取有关系统中所有灯的信息 + * + * @param lightInfo表示基本灯信息。有关详细信息，请参考{@link LightInfo} + * @param count表示获取灯信息的个数 + * + * @return 如果获得信息，则返回0；否则返回负值 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*GetLightInfo)(struct LightInfo **lightInfo, uint32_t *count); + + /** + * @brief 根据指定的灯类型打开灯列表中可用的灯 + * + * @param type表示灯类型。有关详细信息，请参考{@link LightType} + * + * @param effect表示设置灯的信息。有关详细信息，请参考{@link LightEffect} + * + * @return 命令执行结果：0成功，-1逻辑灯不支持，-2逻辑灯不支持闪烁设置，-3逻辑灯不支持亮度设置 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*TurnOnLight)(uint32_t type, struct LightEffect *effect); + + /** + * @brief 根据指定的灯类型关闭灯列表中可用的灯 + * + * @param type表示灯类型。有关详细信息，请参考{@link LightType} + * + * @return 如果成功关闭则返回0；否则返回负值 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*TurnOffLight)(uint32_t type); +}; + +/** + * @brief 创建一个LightInterface实例。 + * 使用此实例获取灯信息，并执行打开、关闭指定类型灯的亮度设置和闪烁模式设置 + * + * @return 已成功创建实例返回一个非零值；否则返回0 + * + * @since 2.2 + * @version 1.0 + */ +const struct LightInterface *NewLightInterfaceInstance(void); + +/** + * @brief 释放此LightInterface实例和释放相关资源 + * + * @return 如果操作成功，则返回0；否则返回负值 + * + * @since 2.2 + * @version 1.0 + */ +int32_t FreeLightInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_IF_H */ +/** @} */ diff --git a/zh-cn/device-dev/driver/API/light_type.h b/zh-cn/device-dev/driver/API/light_type.h new file mode 100644 index 00000000000..386a2df6f5f --- /dev/null +++ b/zh-cn/device-dev/driver/API/light_type.h @@ -0,0 +1,127 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Light + * @{ + * + * @brief 为灯的硬件服务提供统一的API以访问灯驱动程序。 + * + * 获取驱动程序对象或代理后，获取灯类型、打开灯服务，关闭灯服务使用驱动程序对象或代理提供的功能 + * + * @version 1.0 + */ + +/** + * @file light_type.h + * + * @brief 定义灯数据结构，包括灯类型、闪烁模式和闪烁时间 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef LIGHT_TYPE_H +#define LIGHT_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief 枚举灯模块的返回值 + * + * @since 2.2 + */ +enum LightStatus { + LIGHT_SUCCESS = 0, /**< 操作成功 */ + LIGHT_NOT_SUPPORT = -1, /**< 不支持类型错误 */ + LIGHT_NOT_FLASH = -2, /**< 不支持闪烁设置 */ + LIGHT_NOT_BRIGHTNESS = -3, /**< 不支持亮度设置 */ +}; + +/** + * @brief 枚举灯类型 + * + * @since 2.2 + */ +enum LightType { + LIGHT_TYPE_NONE = 0, /**< 仅用于测试用例 */ + LIGHT_TYPE_BATTERY = 1, /**< 电源灯 */ + LIGHT_TYPE_NOTIFICATIONS = 2, /**< 通知灯 */ + LIGHT_TYPE_ATTENTION = 3, /**< 告警灯 */ + LIGHT_TYPE_BUTT /**< 表示灯的无效类型 */ +}; + +/** + * @brief 枚举灯打开模式 + * + * @since 2.2 + */ +enum LightFlashMode { + LIGHT_FLASH_NONE = 0, /**< 常量模式 */ + LIGHT_FLASH_TIMED = 1, /**< 闪烁模式 */ + LIGHT_FLASH_BUTT = 2, /**< 表示无效的打开模式 */ +}; + +/** + * @brief 定义灯的闪烁数据 + * + * 数据包括闪烁模式、打开和关闭灯的时间 + * + * @since 2.2 + */ +struct LightFlashEffect { + int32_t flashMode; /**< 闪烁模式，有关详细信息，请参考{@link LightFlashMode} */ + int32_t onTime; /**< 打开持续时间，单位：毫秒 */ + int32_t offTime; /**< 关闭持续时间，单位：毫秒 */ +}; + +/** + * @brief 定义打开灯的效果数据 + * + * 数据包括亮度值，闪烁模式数据 + * + * @since 2.2 + */ +struct LightEffect { + int32_t lightBrightness; /**< 亮度值，RGB最高位表示颜色RGB:R:16-31位、G:8-15位、B:0-7位 */ + struct LightFlashEffect flashEffect; /**< 闪烁模式数据，有关详细信息，请参考{@link LightFlashEffect} */ +}; + +/** + * @brief 定义获取到灯的基本信息。 + * + * 有关灯的信息包括灯类型、用户定义的扩展信息 + * + * @since 2.2 + */ +struct LightInfo { + uint32_t lightType; /**< 获取到的灯类型，有关详细信息，请参考{@link LightType} */ + int32_t reserved; /**< 用户定义的扩展信息 */ +}; + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* LIGHT_TYPE_H */ +/** @} */ -- Gitee From 4b7ec7269f59116768b44a48e5abe2cacf964832 Mon Sep 17 00:00:00 2001 From: xwbmcu Date: Sat, 22 Jan 2022 14:37:30 +0800 Subject: [PATCH 2/3] add light API Signed-off-by: xwbmcu --- zh-cn/device-dev/driver/API/light_if.h | 6 ++++-- zh-cn/device-dev/driver/API/light_type.h | 9 +++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/zh-cn/device-dev/driver/API/light_if.h b/zh-cn/device-dev/driver/API/light_if.h index afdb044a0d3..00b58d985b3 100644 --- a/zh-cn/device-dev/driver/API/light_if.h +++ b/zh-cn/device-dev/driver/API/light_if.h @@ -17,8 +17,10 @@ * @addtogroup Light * @{ * - * @brief 为上层灯的硬件服务提供驱动程序。获取驱动程序对象或代理后， - * 灯的硬件服务使用驱动程序对象或代理提供的功能获取类型，打开或关闭灯 + * @brief 灯设备驱动对灯服务提供通用的接口能力。 + * + * 模块提供灯服务对灯驱动访问统一接口，服务获取驱动程序对象或代理后， + * 通过其提供的各类方法，以灯类型区分访问不同类型灯设备，实现获取灯设备信息、打开或关闭灯、设置闪烁模式。 * * @since 2.2 */ diff --git a/zh-cn/device-dev/driver/API/light_type.h b/zh-cn/device-dev/driver/API/light_type.h index 386a2df6f5f..8242fd1bbb4 100644 --- a/zh-cn/device-dev/driver/API/light_type.h +++ b/zh-cn/device-dev/driver/API/light_type.h @@ -17,11 +17,12 @@ * @addtogroup Light * @{ * - * @brief 为灯的硬件服务提供统一的API以访问灯驱动程序。 + * @brief 灯设备驱动对灯服务提供通用的接口能力。 * - * 获取驱动程序对象或代理后，获取灯类型、打开灯服务，关闭灯服务使用驱动程序对象或代理提供的功能 + * 模块提供灯服务对灯驱动访问统一接口，服务获取驱动程序对象或代理后， + * 通过其提供的各类方法，以灯类型区分访问不同类型灯设备，实现获取灯设备信息、打开或关闭灯、设置闪烁模式。 * - * @version 1.0 + * @since 2.2 */ /** @@ -75,7 +76,7 @@ enum LightType { * @since 2.2 */ enum LightFlashMode { - LIGHT_FLASH_NONE = 0, /**< 常量模式 */ + LIGHT_FLASH_NONE = 0, /**< 常亮模式 */ LIGHT_FLASH_TIMED = 1, /**< 闪烁模式 */ LIGHT_FLASH_BUTT = 2, /**< 表示无效的打开模式 */ }; -- Gitee From 3e1954b210579e573556a4ad6c6be06cf4b3afef Mon Sep 17 00:00:00 2001 From: xwbmcu Date: Sun, 23 Jan 2022 14:58:18 +0800 Subject: [PATCH 3/3] add light API Signed-off-by: xwbmcu --- zh-cn/device-dev/driver/API/light_if.h | 4 ++-- zh-cn/device-dev/driver/API/light_type.h | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/zh-cn/device-dev/driver/API/light_if.h b/zh-cn/device-dev/driver/API/light_if.h index 00b58d985b3..f865567c670 100644 --- a/zh-cn/device-dev/driver/API/light_if.h +++ b/zh-cn/device-dev/driver/API/light_if.h @@ -95,7 +95,7 @@ struct LightInterface { /** * @brief 创建一个LightInterface实例。 - * 使用此实例获取灯信息，并执行打开、关闭指定类型灯的亮度设置和闪烁模式设置 + * 使用实例获取灯信息，并执行打开、关闭指定类型灯的亮度设置和闪烁模式设置 * * @return 已成功创建实例返回一个非零值；否则返回0 * @@ -105,7 +105,7 @@ struct LightInterface { const struct LightInterface *NewLightInterfaceInstance(void); /** - * @brief 释放此LightInterface实例和释放相关资源 + * @brief 释放LightInterface实例和释放相关资源 * * @return 如果操作成功，则返回0；否则返回负值 * diff --git a/zh-cn/device-dev/driver/API/light_type.h b/zh-cn/device-dev/driver/API/light_type.h index 8242fd1bbb4..7aa9c124ff1 100644 --- a/zh-cn/device-dev/driver/API/light_type.h +++ b/zh-cn/device-dev/driver/API/light_type.h @@ -20,7 +20,7 @@ * @brief 灯设备驱动对灯服务提供通用的接口能力。 * * 模块提供灯服务对灯驱动访问统一接口，服务获取驱动程序对象或代理后， - * 通过其提供的各类方法，以灯类型区分访问不同类型灯设备，实现获取灯设备信息、打开或关闭灯、设置闪烁模式。 + * 通过不同灯设备类型，实现获取灯设备信息、打开或关闭灯、设置闪烁模式的操作。 * * @since 2.2 */ @@ -63,7 +63,7 @@ enum LightStatus { * @since 2.2 */ enum LightType { - LIGHT_TYPE_NONE = 0, /**< 仅用于测试用例 */ + LIGHT_TYPE_NONE = 0, /**< 不可知的类型 */ LIGHT_TYPE_BATTERY = 1, /**< 电源灯 */ LIGHT_TYPE_NOTIFICATIONS = 2, /**< 通知灯 */ LIGHT_TYPE_ATTENTION = 3, /**< 告警灯 */ @@ -76,9 +76,9 @@ enum LightType { * @since 2.2 */ enum LightFlashMode { - LIGHT_FLASH_NONE = 0, /**< 常亮模式 */ - LIGHT_FLASH_TIMED = 1, /**< 闪烁模式 */ - LIGHT_FLASH_BUTT = 2, /**< 表示无效的打开模式 */ + LIGHT_FLASH_NONE = 0, /**< 常亮模式 */ + LIGHT_FLASH_TIMED = 1, /**< 闪烁模式 */ + LIGHT_FLASH_BUTT = 2, /**< 表示无效的打开模式 */ }; /** @@ -102,7 +102,7 @@ struct LightFlashEffect { * @since 2.2 */ struct LightEffect { - int32_t lightBrightness; /**< 亮度值，RGB最高位表示颜色RGB:R:16-31位、G:8-15位、B:0-7位 */ + int32_t lightBrightness; /**< 亮度值，RGB最高位bit为1表示颜色RGB:R:16-31位、G:8-15位、B:0-7位 */ struct LightFlashEffect flashEffect; /**< 闪烁模式数据，有关详细信息，请参考{@link LightFlashEffect} */ }; -- Gitee