diff --git a/en/device_api/sensor/sensor_if.h b/en/device_api/sensor/sensor_if.h index bca34655e1ab30418cd2456e433c8b9d073d91eb..642b88c25a0a1a37c7bc4e081061714ca2c3fc06 100644 --- a/en/device_api/sensor/sensor_if.h +++ b/en/device_api/sensor/sensor_if.h @@ -17,10 +17,10 @@ * @addtogroup Sensor * @{ * - * @brief Provides unified APIs for sensor services to access sensor drivers. + * @brief Provides APIs for sensor services to access the sensor driver. * * A sensor service can obtain a sensor driver object or agent and then call APIs provided by this object or agent to - * access different types of sensor devices based on the sensor IDs, thereby obtaining sensor information, + * access different types of sensor devices, thereby obtaining sensor information, * subscribing to or unsubscribing from sensor data, enabling or disabling a sensor, * setting the sensor data reporting mode, and setting sensor options such as the accuracy and measurement range. * @@ -50,7 +50,7 @@ extern "C" { #endif /* __cplusplus */ /** - * @brief Defines the functions for performing basic operations on sensors. + * @brief Defines the interface for performing basic operations on sensors. * * The operations include obtaining sensor information, subscribing to or unsubscribing from sensor data, * enabling or disabling a sensor, setting the sensor data reporting mode, and setting sensor options such as @@ -75,8 +75,8 @@ struct SensorInterface { int32_t (*GetAllSensors)(struct SensorInformation **sensorInfo, int32_t *count); /** - * @brief Enables the sensor available in the sensor list based on the specified sensor ID. - * The subscriber can obtain the sensor data only after the sensor is enabled. + * @brief Enables a sensor available in the sensor list. + * Subscribers can obtain sensor data only after the sensor is enabled. * * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. * @@ -89,7 +89,7 @@ struct SensorInterface { int32_t (*Enable)(int32_t sensorId); /** - * @brief Disables an enabled sensor. + * @brief Disables a sensor. * * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. * @@ -102,7 +102,7 @@ struct SensorInterface { int32_t (*Disable)(int32_t sensorId); /** - * @brief Sets the data sampling interval and data reporting interval for the specified sensor. + * @brief Sets the data sampling interval and data reporting interval for a sensor. * * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. * @param samplingInterval Indicates the sensor data sampling interval to set, in nanoseconds. @@ -117,13 +117,13 @@ struct SensorInterface { int32_t (*SetBatch)(int32_t sensorId, int64_t samplingInterval, int64_t reportInterval); /** - * @brief Sets the data reporting mode for the specified sensor. + * @brief Sets the data reporting mode for a sensor. * * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. * @param mode Indicates the data reporting mode to set. For details, see {@link SensorModeType}. * - * @return Returns 0 if the sensor data reporting mode is successfully set. - * @return Returns a negative value if the sensor data reporting mode is failed set. + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. * * @since 2.2 * @version 1.0 @@ -131,13 +131,13 @@ struct SensorInterface { int32_t (*SetMode)(int32_t sensorId, int32_t mode); /** - * @brief Sets options for the specified sensor, including its measurement range and accuracy. + * @brief Sets options for a sensor, including its measurement range and accuracy. * * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. * @param option Indicates the options to set, such as the measurement range and accuracy. * - * @return Returns 0 if the options are successfully set. - * @return Returns 0 if the options are failed set. + * @return Returns 0 if the operation is successful. + * @return Returns 0 if the operation fails. * * @since 2.2 * @version 1.0 @@ -145,17 +145,19 @@ struct SensorInterface { int32_t (*SetOption)(int32_t sensorId, uint32_t option); /** - * @brief Registers the callback for reporting sensor data to the subscriber. + * @brief Registers a callback for reporting sensor data. * * @param groupId Indicates the sensor group ID. - * The sensorId enumeration value range is 128-160, which means that the medical sensor service is subscribed. - * It only needs to be subscribed once successfully, and there is no need to subscribe repeatedly. - * The sensorId enumeration value range is not within 128-160, which means that the traditional sensor - * is subscribed, and the subscription is successful once. + * If groupId is set to a value within the range 128-160, this function is used to + * register a callback for reporting data of medical sensors. + * You only need to register a callback once for all medical sensors. + * If groupId is set to a value outside the range 128-160, this function is used to + * register a callback for reporting data of traditional sensors. + * You only need to register a callback once for all traditional sensors. * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. * - * @return Returns 0 if the callback is successfully registered. - * @return Returns a negative value if the callback is failed registered.. + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. * * @since 2.2 * @version 1.0 @@ -166,14 +168,16 @@ struct SensorInterface { * @brief Deregisters the callback for reporting sensor data. * * @param groupId Indicates the sensor group ID. - * The sensorId enumeration value range is 128-160, which means that the medical sensor service is subscribed. - * It only needs to cancel the subscription once successfully, and there is no need to - * cancel the subscription repeatedly. The sensorId enumeration value range is not within 128-160, - * which means that the traditional sensor is subscribed. You can cancel the subscription once successfully. - * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. + * If groupId is set to a value within the range 128-160, this function is used to + * register a callback for reporting data of medical sensors. + * You only need to register a callback once for all medical sensors. + * If groupId is set to a value outside the range 128-160, this function is used to + * register a callback for reporting data of traditional sensors. + * You only need to register a callback once for all traditional sensors. + * @param cb Indicates the callback to deregister. For details, see {@link RecordDataCallback}. * - * @return Returns 0 if the callback is successfully deregistered. - * @return Returns a negative value if the callback is failed deregistered. + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. * * @since 2.2 * @version 1.0 @@ -184,14 +188,9 @@ struct SensorInterface { /** * @brief Creates a SensorInterface instance. * - * @param sensorId Indicates the sensor ID. For details, see {@link SensorTypeTag}. - * You can use the instance to obtain sensor information, subscribe to or unsubscribe from sensor data, - * enable or disable a sensor, set the sensor data reporting mode, and set the sensor options such as the accuracy and - * measurement range. - * @param cb Indicates the callback to register. For details, see {@link RecordDataCallback}. * - * @return Returns a non-zero value if the instance is successfully created. - * @return Returns a negative value if the instance is failed created. + * @return Returns a non-zero value if the operation is successful. + * @return Returns a negative value if the operation fails. * * @since 2.2 * @version 1.0 @@ -199,10 +198,10 @@ struct SensorInterface { const struct SensorInterface *NewSensorInterfaceInstance(void); /** - * @brief Releases the SensorInterface instance. + * @brief Releases this SensorInterface instance. * - * @return Returns 0 if the instance is successfully released. - * @return Returns a negative value if the instance is failed released. + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. * * @since 2.2 * @version 1.0 diff --git a/en/device_api/sensor/sensor_type.h b/en/device_api/sensor/sensor_type.h index c7af7feddc2101d3b184f34b178f7b54a2f7a6e8..13eb20089d8024de3eef9c9d6098c20faf1a2171 100644 --- a/en/device_api/sensor/sensor_type.h +++ b/en/device_api/sensor/sensor_type.h @@ -17,10 +17,10 @@ * @addtogroup Sensor * @{ * - * @brief Provides unified APIs for sensor services to access sensor drivers. + * @brief Provides APIs for sensor services to access the sensor driver. * * A sensor service can obtain a sensor driver object or agent and then call APIs provided by this object or agent to - * access different types of sensor devices based on the sensor IDs, thereby obtaining sensor information, + * access different types of sensor devices, thereby obtaining sensor information, * subscribing to or unsubscribing from sensor data, enabling or disabling a sensor, * setting the sensor data reporting mode, and setting sensor options such as the accuracy and measurement range. * @@ -30,7 +30,7 @@ /** * @file sensor_type.h * - * @brief Defines the data used by the sensor module, including the sensor types, sensor information, + * @brief Defines the data used by the sensor module, including the sensor type, sensor information, * and reported sensor data. * * @since 2.2 @@ -54,7 +54,7 @@ extern "C" { #define SENSOR_VERSION_MAX_LEN 16 /** - * @brief Enumerates return values of the sensor module. + * @brief Enumerates the return values of the sensor module. * * @since 2.2 */ @@ -65,7 +65,7 @@ enum SensorStatus { SENSOR_FAILURE = -1, /**< The operation is not supported. */ SENSOR_NOT_SUPPORT = -2, - /**< The sensor parameter is invalid. */ + /**< A parameter is invalid. */ SENSOR_INVALID_PARAM = -3, /**< The sensor service is invalid. */ SENSOR_INVALID_SERVICE = -4, @@ -74,7 +74,7 @@ enum SensorStatus { }; /** - * @brief Enumerates sensor types. + * @brief Enumerates the sensor types. * * @since 2.2 */ @@ -85,7 +85,7 @@ enum SensorTypeTag { SENSOR_TYPE_ACCELEROMETER = 1, /**< Gyroscope sensor */ SENSOR_TYPE_GYROSCOPE = 2, - /**< Photoplethysmography sensor */ + /**< Photoplethysmography (PPG) sensor */ SENSOR_TYPE_PHOTOPLETHYSMOGRAPH = 3, /**< Electrocardiogram (ECG) sensor */ SENSOR_TYPE_ELECTROCARDIOGRAPH = 4, @@ -107,11 +107,11 @@ enum SensorTypeTag { SENSOR_TYPE_PROXIMITY = 12, /**< Humidity sensor */ SENSOR_TYPE_HUMIDITY = 13, - /**< The begin of medical sensorId enumeration value range */ + /**< Start ID of medical sensors */ SENSOR_TYPE_MEDICAL_BEGIN = 128, - /**< The end of medical sensorId enumeration value range */ + /**< End ID of medical sensors */ SENSOR_TYPE_MEDICAL_END = 160, - /**< Maximum type of a physical sensor */ + /**< Maximum ID of physical sensors */ SENSOR_TYPE_PHYSICAL_MAX = 255, /**< Orientation sensor */ SENSOR_TYPE_ORIENTATION = 256, @@ -150,7 +150,7 @@ enum SensorTypeTag { }; /** - * @brief Enumerates accuracy types of sensors. + * @brief Enumerates the accuracy types of sensors. * * @since 2.2 */ @@ -168,7 +168,7 @@ enum SensorAccuracyType { }; /** - * @brief Enumerates measurement ranges of sensors. + * @brief Enumerates the measurement ranges of sensors. * * @since 2.2 */ @@ -179,48 +179,48 @@ enum SensorRangeType { SENSOR_RANGE_LEVEL2 = 1, /**< Measurement range level 3 */ SENSOR_RANGE_LEVEL3 = 2, - /**< Maximum measurement range level */ + /**< Maximum measurement range */ SENSOR_RANGE_LEVEL_MAX, }; /** - * @brief Enumerates data reporting modes of sensors. + * @brief Enumerates the data reporting modes of sensors. * * @since 2.2 */ enum SensorModeType { /**< Default data reporting mode */ SENSOR_MODE_DEFAULT = 0, - /**< Real-time data reporting mode to report a group of data each time */ + /**< Reporting a group of data each time in real-time data reporting mode */ SENSOR_MODE_REALTIME = 1, - /**< Real-time data reporting mode to report data upon status changes */ + /**< Reporting data upon status changes in real-time data reporting mode */ SENSOR_MODE_ON_CHANGE = 2, - /**< Real-time data reporting mode to report data only once */ + /**< Reporting data only once in real-time data reporting mode */ SENSOR_MODE_ONE_SHOT = 3, - /**< FIFO-based data reporting mode to report data based on the configured cache size */ + /**< Reporting data based on the configured buffer size in FIFO-based data reporting mode */ SENSOR_MODE_FIFO_MODE = 4, /**< Maximum sensor data reporting mode */ SENSOR_MODE_MAX, }; /** - * @brief Enumerates hardware service group for sensors. + * @brief Enumerates the sensor groups. * * @since 2.2 */ enum SensorGroupType { - /**< traditional sensor type, the sensorId enumeration value range is 128-160 */ + /**< Traditional sensor group, whose value range is not within 128-160 */ TRADITIONAL_SENSOR_TYPE = 0, - /**< medical sensor type, the sensorId enumeration value range is not within 128-160 */ + /**< Medical sensor group, whose value range is 128-160 */ MEDICAL_SENSOR_TYPE = 1, - /**< Maximum sensor type */ + /**< Maximum sensor group type */ SENSOR_GROUP_TYPE_MAX, }; /** - * @brief Defines basic sensor information. + * @brief Defines the basic sensor information. * - * Information about a sensor includes the sensor name, vendor, firmware version, hardware version, sensor type ID, + * The basic sensor information includes the sensor name, vendor, firmware version, hardware version, sensor type ID, * sensor ID, maximum measurement range, accuracy, and power. * * @since 2.2 @@ -236,7 +236,7 @@ struct SensorInformation { char hardwareVersion[SENSOR_VERSION_MAX_LEN]; /**< Sensor type ID (described in {@link SensorTypeTag}) */ int32_t sensorTypeId; - /**< Sensor ID, defined by the sensor driver developer */ + /**< Sensor ID, defined by sensor driver developers */ int32_t sensorId; /**< Maximum measurement range of the sensor */ float maxRange; @@ -247,10 +247,10 @@ struct SensorInformation { }; /** - * @brief Defines the data reported by the sensor. + * @brief Defines the data reported by sensors. * * The reported sensor data includes the sensor ID, sensor algorithm version, data generation time, - * data options (such as the measurement range and accuracy), data reporting mode, data address, and data length. + * data options, data reporting mode, data address, and data length. * * @since 2.2 */ @@ -272,9 +272,9 @@ struct SensorEvents { }; /** - * @brief Defines the callback for reporting sensor data. This callback needs to be registered when - * a sensor user subscribes to sensor data. Only after the sensor is enabled, the sensor data subscriber can receive - * sensor data. For details, see {@link SensorInterface}. + * @brief Defines the callback for reporting sensor data. A sensor user must register this callback + * when subscribing to sensor data. The subscriber can receive + * sensor data only after the sensor is enabled. For details, see {@link SensorInterface}. * * @since 2.2 */