+/**
+ * @}
+ *
+ * @addtogroup CAPI_SYSTEM_SENSOR_ROTATION_VECTOR_MODULE
+ * @{
+ */
+
+/**
+ * @brief Called when an rotation vector event occurs.
+ * @details
+ * The values of rotation vector represents orientation of the device as a combination of an angle and an axis.
+ * Each value of the rotation vector is not have unit. the x,y,z axis is same unit as accelerometer.
+ *
+ * @param[in] accuracy The accuracy of @a x, @a y, and @a z values
+ * @param[in] x x*sin(θ/2)
+ * @param[in] y y*sin(θ/2)
+ * @param[in] z z*sin(θ/2)
+ * @param[in] w cos(θ/2)
+ * @param[in] user_data The user data passed from the callback registration function
+ *
+ * @pre sensor_start() will invoke this callback if you register this callback using sensor_rotation_vector_set_cb().
+ *
+ * @see sensor_rotation_vector_set_cb()
+ * @see sensor_rotation_vector_unset_cb()
+ */
+typedef void (*sensor_rotation_vector_event_cb)(
+ sensor_data_accuracy_e accuracy, float x, float y, float z, float w, void *user_data);
+
+/**
+ * @brief Registers a callback function to be invoked when an rotation vector event occurs.
+ *
+ * @param[in] sensor The sensor handle
+ * @param[in] interval_ms The interval sensor events are delivered at (in milliseconds) \n
+ * If @a rate is zero, it uses default value(100ms)
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_IO_ERROR I/O error
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @post sensor_accelerometer_event_cb() will be invoked.
+ *
+ * @see sensor_accelerometer_event_cb()
+ * @see sensor_accelerometer_unset_cb()
+ */
+int sensor_rotation_vector_set_cb(sensor_h sensor, int interval_ms, sensor_rotation_vector_event_cb callback, void* user_data);
+
+/**
+ * @brief Unregister the rotation vector callback function.
+ *
+ * @param[in] sensor The sensor handle
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_IO_ERROR I/O error
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_rotation_vector_set_cb()
+ */
+int sensor_rotation_vector_unset_cb(sensor_h sensor);
+
+/**
+ * @brief Gets sensor data from the rotation vector sensor.
+ *
+ * @details
+ * The rotation vector sensor retrieves quaternion elements <cos(θ/2), x*sin(θ/2), y*sin(θ/2), z*sin(θ/2)>. \n
+ * Last three elements of the quaternion represents rotation vector. \n
+ * Each axis value of rotation vector is composed of the angle from magnitude equal to sin(θ/2) and the axis. \n
+ * The value of rotation vector in each axis don't have unit. the axis x,y and z have same unit as the acceleration sensor.
+ *
+ *
+ *
+ * @param[in] sensor The sensor handle
+ * @param[out] accuracy The accuracy of this data
+ * @param[in] x x*sin(θ/2)
+ * @param[in] y y*sin(θ/2)
+ * @param[in] z z*sin(θ/2)
+ * @param[in] w cos(θ/2)
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_IO_ERROR I/O error
+ *
+ * @pre In order to read sensor data, an application should call sensor_start().
+ */
+int sensor_rotation_vector_read_data(sensor_h sensor, sensor_data_accuracy_e* accuracy, float* x, float* y, float* z, float* w);
+/**
+ * @}
+ */
+
+
+/**
+ * @addtogroup CAPI_SYSTEM_SENSOR_GRAVITY_MODULE
+ * @{
+ */
+
+/**
+ * @brief Called when an gravity event occurs.
+ *
+ * @param[in] accuracy The accuracy of @a x, @a y, and @a z values
+ * @param[in] x m/s^2
+ * @param[in] y m/s^2
+ * @param[in] z m/s^2
+ * @param[in] user_data The user data passed from the callback registration function
+ *
+ * @pre sensor_start() will invoke this callback if you register this callback using sensor_rotation_vector_set_cb().
+ *
+ * @see sensor_rotation_vector_set_cb()
+ * @see sensor_rotation_vector_unset_cb()
+ */
+typedef void (*sensor_gravity_event_cb)(
+ sensor_data_accuracy_e accuracy, float x, float y, float z, void *user_data);
+
+/**
+ * @brief Registers a callback function to be invoked when an gravity event occurs.
+ *
+ * @param[in] sensor The sensor handle
+ * @param[in] interval_ms The interval sensor events are delivered at (in milliseconds) \n
+ * If @a rate is zero, it uses default value(100ms)
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_IO_ERROR I/O error
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @post sensor_accelerometer_event_cb() will be invoked.
+ *
+ * @see sensor_accelerometer_event_cb()
+ * @see sensor_accelerometer_unset_cb()
+ */
+int sensor_gravity_set_cb(sensor_h sensor, int interval_ms, sensor_gravity_event_cb callback, void* user_data);
+
+/**
+ * @brief Unregister the gravity callback function.
+ *
+ * @param[in] sensor The sensor handle
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_IO_ERROR I/O error
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_rotation_vector_set_cb()
+ */
+int sensor_gravity_unset_cb(sensor_h sensor);
+
+/**
+ * @brief change the interval at gravity measurements.
+ *
+ * @param[in] sensor The sensor handle
+ * @param[in] interval_ms in milliseconds.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_IO_ERROR I/O error
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_gravity_set_cb()
+ */
+int sensor_gravity_set_interval(sensor_h sensor, int interval_ms);
+
+/**
+ * @brief Gets sensor data from the gravity sensor.
+ *
+ * @param[in] sensor The sensor handle
+ * @param[out] accuracy The accuracy of this data
+ * @param[in] x m/s^2
+ * @param[in] y m/s^2
+ * @param[in] z m/s^2
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_IO_ERROR I/O error
+ *
+ * @pre In order to read sensor data, an application should call sensor_start().
+ */
+int sensor_gravity_read_data(sensor_h sensor, sensor_data_accuracy_e* accuracy, float* x, float* y, float* z);
+
+
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup CAPI_SYSTEM_SENSOR_UTILITY_MODULE
+ * @{
+ */
+
+/**
+ * @brief Enumerations of Axis used in #sensor_util_remap_coordinate_system
+ *
+ * @see #sensor_util_remap_coordinate_system
+ */
+typedef enum
+{
+ sensor_util_axis_minus_x,
+ sensor_util_axis_minus_y,
+ sensor_util_axis_minus_z,
+ sensor_util_axis_x,
+ sensor_util_axis_y,
+ sensor_util_axis_z,
+} sensor_util_axis_e;
+/**
+ * @}
+ */
+
+/**
+ * @brief
+ * Getting Inclination matrix "I" and Rotation matrix "R" transforming a vector from the device coordinate to the world's coordinate.
+ *
+ * @details
+ * [0 0 g] = R * gravity (g = magnitude of gravity) \n
+ * [0 m 0] = I * R * geomagnetic (m = magnitude of geomagnetic field) \n
+ * R is the identity matrix when the device is aligned with the world's coordinate system, that is, when the device's X axis points toward East, the Y axis points to the North Pole and the device is facing the sky. \n
+ * I is a rotation matrix transforming the geomagnetic vector into the same coordinate space as gravity (the world's coordinate space). I is a simple rotation around the X axis. \n
+ *
+ * @remark
+ * Parameter Gx, Gy, Gz can be got from the values returned by a #sensor_gravity_event_cb or #sensor_gravity_read_data. \n
+ * Parameter Mx, My, Mz can be got from the values returned by a #sensor_magnetic_event_cb or #sensor_magnetic_read_data.
+ * Output parameter R and I is always returned 3x3 matrix array of 9 floats like this form:
+ * <pre>
+ * { R[0], R[1], R[2],
+ * R[3], R[4], R[5],
+ * R[6], R[7], R[6] }
+ * </pre>
+ *
+ *
+ * @param[in] Gx X-axis gravity vector in the device's coordinate.
+ * @param[in] Gy Y-axis gravity vector in the device's coordinate.
+ * @param[in] Gz Z-axis gravity vector in the device's coordinate.
+ * @param[in] Mx X-axis geomagnetic vector in the device's coordinate.
+ * @param[in] My Y-axis geomagnetic vector in the device's coordinate.
+ * @param[in] Mz Z-axis geomagnetic vector in the device's coordinate.
+ * @param[out] R Array of 9 floats that represents the rotation matrix "R". It can be null.
+ * @param[out] I Array of 9 floats that represents the inclination matrix "I". It can be null.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ */
+int sensor_util_get_rotation_matrix(float Gx, float Gy, float Gz,
+ float Mx, float My, float Mz,
+ float R[], float I[]);
+
+/**
+ * @brief
+ * Convert a rotation vector to a rotation matrix.
+ *
+ * @details
+ * rotation vectors (Vx, Vy, Vz) can be got from #sensor_rotation_vector_event_cb or #sensor_rotation_vector_read_data.
+ * It returns a 9 elements rotation matrix in the array R. R must have langth 9.
+ *
+ * @param[in] Vx X-axis rotation vector.
+ * @param[in] Vy Y-axis rotation vector.
+ * @param[in] Vz Z-axis rotation vector.
+ * @param[out] R A 9 elements ration matrix in the array R that must have length 9.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @see sensor_util_rotation_matrix3
+ * @see sensor_util_rotation_matrix4
+ */
+int sensor_util_get_rotation_matrix_from_vector(float Vx, float Vy, float Vz, float R[]);
+
+/**
+ * @brief
+ * Rotates the supplied rotation matrix so it is expressed in a different coordinate system.
+ *
+ * @details
+ * This is typically used when an application needs to compute the three orientation angles of the device in a different coordinate system.
+ *
+ * @remark
+ * inR and outR can be the same array, but it is not recommended for performance reason.
+ * Return error when X and Y defines the same axis.
+ *
+ * @param[in] inR the rotation matrix (3x3) to be transformed. Usually it is the matrix returned by get #sensor_util_rotation_matrix3 or #sensor_util_rotation_matrix4.
+ * @param[in] x defines on which world axis and direction the X axis of the device is mapped.
+ * @param[in] y defines on which world axis and direction the Y axis of the device is mapped.
+ * @param[out] outR the transformed rotation matrix (3x3).
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @see sensor_util_rotation_matrix3
+ * @see sensor_util_rotation_matrix4
+ * @see sensor_util_rotation_matrix_from_vector
+ * @see sensor_util_rotation_matrix_from_quaternion
+ */
+int sensor_util_remap_coordinate_system(float inR[], sensor_util_axis_e x, sensor_util_axis_e y, float outR[]);
+
+/**
+ * @brief
+ * Computes the geomagnetic inclination angle in radians from the inclination matrix I returned by #sensor_util_get_rotation_matrix()
+ *
+ * @param[in] I inclination matrix from #sensor_util_get_rotation_matrix()
+ * @param[out] inclination The geomagnetic inclination angle in radians.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @see sensor_util_get_rotation_matrix()
+ */
+int sensor_util_get_inclination(float I[], float* inclination);
+
+/**
+ * @brief
+ * Compute the device's orientation based on the rotation matrix
+ *
+ * @details
+ * When it returns, they array values is filled with the result:
+ * - values[0]: azimuth, rotation around the Z axis.
+ * - values[1]: pitch, rotation around the X axis.
+ * - values[2]: roll, rotation around the Y axis.
+ *
+ * @remark
+ * Parameter R must be array of 9 floats from #sensor_util_get_rotation_matrix() \n
+ * Returned values are always array of 3 floats.
+ *
+ *
+ * @param[in] R A 9 elements ration matrix in the array.
+ * @param[values] values An array of 3 floats to hold the result.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @see sensor_util_get_rotation_matrix()
+ *
+ */
+int sensor_util_get_orientation(float R[], float values[]);
+
+/**
+ * @brief
+ * Helper function to compute the angle change between two rotation matrices.
+ *
+ * @details
+ * Given a current rotation matrix (R) and a previous rotation matrix (prevR) computes
+ * the rotation around the x,y, and z axes which transforms prevR to R.
+ * outputs a 3 element vector containing the x,y, and z angle change at indexes 0, 1, and 2 respectively. \n
+ *
+ * @remark
+ * Each input matrix is 3x3 matrix like this form:
+ * <pre>
+ * { R[0], R[1], R[2],
+ * R[3], R[4], R[5],
+ * R[6], R[7], R[6] }
+ * </pre>
+ *
+ * @param[in] R current rotation matrix
+ * @param[in] prevR previous rotation matrix
+ * @param[out] angleChange an array of floats in which the angle change is stored
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ */
+int sensor_util_get_angle_change(float R[], float prevR[], float angleChange[]);
+
+/**
+ * @brief
+ * Getting the declination of the horizontal component of the magnetic field from true north, in degrees
+ *
+ * @param[in] latitude Latitude in geodetic coordinates
+ * @param[in] longitude Longitude in geodetic coordinates
+ * @param[in] altitude Altitude in geodetic coordinates
+ * @param[out] declination The declination of the horizontal component of the magnetic field in degrees.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ */
+int sensor_util_get_declination(float latitude, float longitude, float altitude, float* declination);
+
+/**
+ * @brief Determines whether or not to be near from proximity sensor's distance value.
+ *
+ * @remark
+ * This function can be used to determine the proximity to device from other object like human face.
+ *
+ * @param[in] distance Distance in centimeter from proximity sensor.
+ * @param[out] is_near proximity to device from other object.
+ */
+int sensor_util_is_near(float distance, bool *is_near);
+
+/**
+ * @}
+ */
+
+
projects / platform / core / api / sensor.git / commitdiff