| ISF 1.1 Intelligent Sensing Framework

- Main Page
- Data Structures
- Files
- Sensor Adapters

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_sm_api.h
Go to the documentation of this file.

    00001 /**
    00002  * @file isf_sm_api.h
    00003  * @brief The \b isf_sm_api.h contains the collection of APIs for the Sensor Manager as well as related defines and data structures
    00004  *        required.
    00005  *
    00006  * @copyright Copyright (c) 2012, Freescale Semiconductor, Inc.
    00007  */
    00008
    00009 #ifndef ISF_SM_API_H_
    00010 #define ISF_SM_API_H_
    00011
    00012 #include "isf.h"
    00013
    00014 /*!
    00015  *   @brief This status code indicates that the API operation was successful.
    00016  */
    00017 #define ISF_SUCCESS                             (0)
    00018
    00019 /*!
    00020  *   @brief This is the maximum number of subscribers allowed per sensor.
    00021  *
    00022  *   \b Note: This define must not be changed by the user.
    00023  */
    00024 #define SM_MAX_SUBSCRIBERS_PER_SENSOR            (3)
    00025
    00026 /*!
    00027  *   @brief This is the maximum allowed depth of the sample FIFO.
    00028  *
    00029  *   \b Note: This define must not be changed by the user.
    00030  */
    00031 #define SM_MAX_FIFO_DEPTH                        (20)
    00032
    00033 //! Sensor Manager API return type
    00034 typedef int32   sm_result_t;
    00035
    00036 typedef enum sm_dsa_return_status
    00037 {
    00038   SM_DSA_RET_SETTINGS_CHANGED = 0x0010
    00039 /*!< Value returned to the user when alternate sensor settings
    00040  *   have been suggested.
    00041  */
    00042
    00043 } sm_dsa_ret_t;
    00044
    00045 /*!
    00046  * @brief This is the status code returned by the Sensor Manager
    00047  * when the sensor cannot be configured based on user
    00048  * requested sensor settings as given in ::SM_SensorSetting_t.
    00049  * Additionally, the Sensor Manager provides a suggestion for
    00050  * the next best alternate rate and other possible settings.
    00051  */
    00052 #define SM_API_ALTERNATE_OFFERED                (sm_result_t)(-10L)
    00053
    00054 /*!
    00055  * @brief This is returned by the Sensor Manager when an invalid
    00056  * token ID is passed into any of the API calls.
    00057  */
    00058 #define SM_API_ERR_TOKEN_ID                     (sm_result_t)(-1L)
    00059
    00060 /*!
    00061  * @brief This is returned by the Sensor Manager  when the passed
    00062  * parameter, sensor ID, does not match an existing sensor.
    00063  */
    00064 #define SM_API_ERR_SENSOR_ID                    (sm_result_t)(-2L)
    00065
    00066 /*!
    00067  * @brief This is returned by the Sensor Manager when the sensor data flow is already enabled.
    00068  */
    00069 #define SM_API_ERR_ALREADY_BEGUN                (sm_result_t)(-3L)
    00070
    00071 /*!
    00072  * @brief This is returned by the Sensor Manager when the sensor
    00073  * data is unavailable because the data stream has not been
    00074  * started.
    00075  */
    00076 #define SM_API_ERR_NOT_YET_BEGUN                (sm_result_t)(-4L)
    00077
    00078 /*!
    00079  *  @brief This is returned by the Sensor Manager when the
    00080  *  maximum number of subscribers as defined in
    00081  *  ::SM_MAX_SUBSCRIBERS_PER_SENSOR for this particular sensor
    00082  *  has been exceeded.
    00083  */
    00084 #define SM_API_ERR_SUBSCRIBER_COUNT             (sm_result_t)(-5L)
    00085
    00086 /*!
    00087  * @brief This is returned by the Sensor Manager when an out-of-
    00088  * memory error status is returned during the execution of the
    00089  * API.
    00090  */
    00091 #define SM_API_ERR_NO_MEMORY                    (sm_result_t)(-6L)
    00092
    00093 /*!
    00094  * @brief This is returned by the Sensor Manager when the
    00095  * requested FIFO depth is larger than the FIFO limit specified
    00096  * in ::SM_MAX_FIFO_DEPTH.
    00097  */
    00098 #define SM_API_ERR_FIFO_OVER_LIMIT              (sm_result_t)(-7L)
    00099
    00100 /*!
    00101  * @brief This is returned by the Sensor Manager when the
    00102  * requested sample tap rate is invalid.
    00103  */
    00104 #define SM_API_ERR_SAMPLE_TAP_RATE              (sm_result_t)(-8L)
    00105
    00106 /*!
    00107  * @brief This is returned by the Sensor Manager when the
    00108  * requested sensor settings are invalid.
    00109  */
    00110 #define SM_API_ERR_SETTINGS_TO_USE              (sm_result_t)(-9L)
    00111
    00112 /*!
    00113  * @brief This is returned by the Sensor Manager when the
    00114  * requested sensor is not available.
    00115  */
    00116 #define SM_API_ERR_SENSOR_NOT_AVAIL             (sm_result_t)(-21L)
    00117
    00118
    00119 /*!
    00120  * @brief This is returned by the Sensor Manager when the sensor
    00121  * is already initialized.
    00122  */
    00123 #define SM_API_ERR_SENSOR_ALREADY_INITIALIZED   (sm_result_t)(-22L)
    00124
    00125 /*!
    00126  * @brief This is returned by the Sensor Manager when the sensor initialization was not successful.
    00127  */
    00128 #define SM_API_ERR_SENSOR_INIT_FAILED           (sm_result_t)(-23L)
    00129 /*! Defines for subscriber setting options. */
    00130 typedef enum SensorSettingChoices
    00131 {
    00132                 SM_CURRENT_SETTINGS   = 1,
    00133 /*!< Use the current sensor settings.  */
    00134                 SM_GIVEN_SETTINGS,
    00135 /*!< Use the user-provided sensor settings if possible.  */
    00136                 SM_BEST_POSSIBLE_SETTINGS
    00137 /*!< Use the given settings, if possible.  If not, use the best
    00138  *   possible settings.
    00139  */
    00140 }SensorSettingsChoices_t;
    00141
    00142 /*! Sensor configuration settings used when subscribing to sensor data.  */
    00143 typedef struct
    00144 {
    00145    uint8                nSettingsToUse;
    00146 //!< 1 = current; 2=given; 3=best possible
    00147    uint8                nFifoDepth;                                                                                                //!< 1 = no FIFO, or another value < ::SM_MAX_FIFO_DEPTH
    00148    uint32               nCurrentReportRate;
    00149 //!< Sample period in microseconds
    00150    uint8                nCurrentResolution;
    00151 //!< Expected sensor resolution.
    00152    uint8                nRange;                                                                                                    //!< Expected sensor dynamic range.
    00153    uint8                nMode;                             //!< sensor specific mode
    00154 } SM_SensorSetting_t;
    00155
    00156
    00157 /*! @brief This is the Sensor Manager API used to subscribe to sensor data.
    00158  *
    00159  * @Purpose  This API allows a subscriber to register for data
    00160  * from this sensor and to define the preferred sensor settings,
    00161  * if necessary.
    00162  *
    00163  * @param[in]     nSensorID         ISF unique sensor obtained from the sensor list.
    00164  * @param[in,out] pRequiredSettings On input, the parameter contains a valid pointer to the
    00165  * desired sensor sample settings.
    00166  *                                  \n On output, alternate sensor sample settings are provided,
    00167  * if the requested settings are not possible.
    00168  *
    00169  * @param[in]     pEventGroup       Pointer to the event group for SM to signal when senor data is ready.
    00170  * @param[in]     nEventFieldIndex  Bit number or index in the event group for SM to signal when senor data is ready.
    00171  * @param[in,out] pTokenAssigned    On input, parameter contains a valid pointer to memory to send
    00172  * the assigned token ID.  \n On successful output, the parameter contains the assigned token ID.
    00173  *
    00174  * @return        ::isf_sm_subscribe_sensor_data() returns a value of type ::sm_result_t indicating the current state
    00175  * of the subscription.
    00176  *
    00177  * @retval        ::ISF_SUCCESS is returned when the subscriber is registered to receive sensor
    00178  * data for the given sampling settings.
    00179  *
    00180  * @retval        ::SM_API_ALTERNATE_OFFERED is returned when an alternate rate is provided.
    00181  * @retval        ::SM_API_ERR_SENSOR_ID is returned when an invalid sensor ID is provided.
    00182  *
    00183  * @Constraints   When the call completes successfully, the subscriber is registered to receive
    00184  * sensor data at the desired sample settings.  The token ID for the subscription is returned to
    00185  * the subscriber.
    00186  *
    00187  * Otherwise, the subscriber is not registered to receive sensor data.  Based on the return status,
    00188  * alternative sample settings may be proposed.
    00189  *
    00190  * @Reentrant       Yes
    00191  * @Libs            isf_core.lib
    00192  *
    00193  */
    00194 sm_result_t  isf_sm_subscribe_sensor_data( uint8 nSensorID, SM_SensorSetting_t *pRequiredSettings,
    00195                                 LWEVENT_STRUCT *pEventGroup, uint32 nEventFieldIndex, uint16 *pTokenAssigned );
    00196 /*!<
    00197  *
    00198  * @Example
    00199  *              AFE Accelerometer subscribes to data at rate of 50 Hz or a period of 20,000 microseconds with no FIFO, using 10-bit resolution, and G-range of 4.
    00200  *
    00201  *              SM_AFE_ACCEL_SENSOR_3D : subscribe to AFE (on-chip) accelerometer data.
    00202  *              gHostProxy_EventGrp    : Event group for Sensor Manager to post events to this task when new AFE Accelerometer data
    00203  *                                       is available.
    00204  *              EV_HOST_ACCEL_DATA_RDY : event flag (bit) in the gHostProxy_EventGrp to be signaled.
    00205  *              SM_GIVEN_SETTINGS      : the sensor settings given in gHostRequestedSensorSettings are used.
    00206  *              hostAccelDataToken     : The Sensor Manager returns a unique token ID for this subscription in this field.
    00207  * <pre>
    00208  * gHostRequestedSensorSettings.nCurrentReportRate  = 20000;
    00209  * gHostRequestedSensorSettings.nCurrentResolution  = AFE_ACCEL_RESOLUTION_10_BIT;
    00210  * gHostRequestedSensorSettings.nRange              = AFE_ACCEL_G_RANGE_4G;
    00211  * gHostRequestedSensorSettings.nFifoDepth          = 1;
    00212  * gHostRequestedSensorSettings.nSettingsToUse      = SM_GIVEN_SETTINGS;
    00213  * </pre>
    00214  * <pre>
    00215  * smApiResult = \a isf_sm_subscribe_sensor_data( SM_AFE_ACCEL_SENSOR_3D,
    00216  *                                             &gHostRequestedSensorSettings,
    00217  *                                             &gHostProxy_EventGrp,
    00218  *                                             EV_HOST_ACCEL_DATA_RDY,
    00219  *                                             &hostAccelDataToken);
    00220  * if ( smApiResult != ISF_SUCCESS)
    00221  * {
    00222  *    // Error handling.
    00223  *    ;
    00224  * }
    00225 * Copyright (c) 2012, Freescale Semiconductor, Inc.
    00226 *</pre>
    00227 *
    00228 */
    00229
    00230
    00231 /*! @brief This Sensor Manager API unsubscribes from
    00232  * receiving sensor data.
    00233  *
    00234  * @details  This API allow the subscriber to unregister from a
    00235  * previously registered subscription to sensor data.
    00236  *
    00237  * @param[in] nTokenID    This is the tokenID received from the
    00238  * SM after subscribing to the sensor.
    00239  *
    00240  * @return   ::isf_sm_unsubscribe_sensor_data() returns a value
    00241  * of type ::sm_result_t indicating the result of the unsubscribe
    00242  * operation.
    00243  *
    00244  * @retval   ::ISF_SUCCESS is returned when the unsubscribe
    00245  * operation completes successfully.
    00246  * @retval   ::SM_API_ERR_TOKEN_ID is returned when the tokenID
    00247  * passed into the function is not valid.
    00248  *
    00249  * @Constraints  If the operation is successful, the caller's
    00250  * subscription to sensor data associated with this tokenID
    00251  * is permanently removed.
    00252  * If the operation is unsuccessful, no change is made to the
    00253  * caller's subscription to this sensor.
    00254  *
    00255  * @Reentrant   Yes
    00256  * @Libs        isf_core.lib
    00257  **/
    00258 sm_result_t  isf_sm_unsubscribe_sensor_data( uint16 nTokenID);
    00259 /*!<
    00260  *
    00261  * @Example
    00262  *              To unsubscribe from sensor data, this API is called with the tokenID received from
    00263  *              the Sensor Manager during subscription.
    00264  ---------------------*         --------------------------------------------------------------------------------------
    00265  *              isf_sm_unsubscribe_sensor_data( hostAccelDataToken);
    00266  * Copyright (c) 2012, Freescale Semiconductor, Inc.
    00267  */
    00268
    00269
    00270 /*! @brief This Sensor Manager API allows a subscriber to
    00271  * receive sensor data.
    00272  *
    00273  * @details This API allows a subscriber to request the Sensor
    00274  * Manager to begin sending subscribed sensor data.
    00275  *
    00276  * @param [in] nTokenID This is the tokenID received from the SM
    00277  * after subscribing to this sensor data.
    00278  *
    00279  * @return  ::isf_sm_begin_sensor_data() returns a value of type
    00280  * ::sm_result_t indicating that sensor data is or is not
    00281  * provided.
    00282  *
    00283  * @retval   ::ISF_SUCCESS  is returned when the current
    00284  * subscriber is capable to receive notifications when data is
    00285  * available from the indicated sensor.
    00286  *
    00287  * @retval   ::SM_API_ERR_TOKEN_ID is returned if the tokenID
    00288  * passed into the function is not valid.
    00289  *
    00290  * @Constraints  If the operation is successful, starting from
    00291  * the next sensor data set, the subscriber registered with this
    00292  * token is notified whenever a new data set is ready to be
    00293  * fetched.
    00294  * If the operation is unsuccessful, no change is made to the
    00295  * caller's subscription to this sensor.
    00296  *
    00297  * @Reentrant   Yes
    00298  * @Libs        isf_core.lib
    00299  **/
    00300 sm_result_t  isf_sm_begin_sensor_data( uint16  nTokenID);
    00301 /*!<
    00302  *
    00303  * @Example
    00304  *              To begin receiving sensor data for this subscription, this  API is called with the tokenID received from
    00305  *              Sensor Manager during subscription.
    00306  ---------------------*         --------------------------------------------------------------------------------------
    00307  *              isf_sm_begin_sensor_data( hostAccelDataToken);
    00308  * Copyright (c) 2012, Freescale Semiconductor, Inc.
    00309  */
    00310
    00311
    00312 /*! @brief This Sensor Manager API is used by a subscriber to
    00313  *  stop receiving sensor data
    00314  *
    00315  * @details This API enables a subscriber to request the Sensor
    00316  * Manager to stop sending subscribed sensor data.
    00317  *
    00318  * @param [in] nTokenID The tokenID of the sensor from which the subscriber no longer wishes to receive data.
    00319  *
    00320  * @return   ::isf_sm_end_sensor_data() returns a value of type
    00321  * ::sm_result_t indicating whether or not the operation was
    00322  * successful.
    00323  *
    00324  * @retval   ::ISF_SUCCESS is returned when the sensor no longer provides data to the subscriber.
    00325  *
    00326  * @retval   ::SM_API_ERR_TOKEN_ID is returned when the tokenID
    00327  * passed into the function is not valid.
    00328  *
    00329  * @Constraints  If the operation is successful, starting from
    00330  * the next sensor data set, the subscriber registered with this
    00331  * token is no longer notified when a new data set is available.
    00332  * If the operation is unsuccessful, no change is made to the
    00333  * caller's subscription to this sensor.
    00334  *
    00335  * @Reentrant   Yes
    00336  * @Libs        isf_core.lib
    00337  **/
    00338 sm_result_t  isf_sm_end_sensor_data( uint16  nTokenID);
    00339 /*!<
    00340  *
    00341  * @Example
    00342  *              To stop receiving sensor data for this subscription, this
    00343  *    API is called with the tokenID received from the
    00344  *              Sensor Manager during subscription.
    00345  *              Note: This does not de-register the subscription. By calling isf_sm_begin_sensor_data(), the user could
    00346  *              resume getting sensor data again at any time in the future.
    00347  ---------------------*         --------------------------------------------------------------------------------------
    00348  *              isf_sm_end_sensor_data( hostAccelDataToken);
    00349  *
    00350  *   Copyright (c) 2012, Freescale Semiconductor, Inc.
    00351  */
    00352
    00353 /*! @brief This Sensor Manager API allows a subscriber to
    00354  *  fetch a new sensor data set.
    00355  *
    00356  *  @details This API allows a subscriber to
    00357  *  fetch the next data set(s) when notified of new data
    00358  *  availability.
    00359  *
    00360  * @param [in] nTokenID The tokenID received from the SM when
    00361  * the subscriber subscribed to this sensor at the given rate.
    00362  * @param [in,out] pSensorData On input,the parameter contains a
    00363  * valid pointer to the memory location to copy sensor sample
    00364  * set(s). \n
    00365  * On successful output, the parameter contains current sensor
    00366  * sample(s).  When there is an error, the parameter is not
    00367  * changed.
    00368  *
    00369  * @return   ::isf_sm_get_sensor_data() returns a value of type
    00370  * ::sm_result_t indicating whether or not the operation was
    00371  * successful.
    00372  *
    00373  * @retval   ::ISF_SUCCESS  is returned upon the sensor data set
    00374  * is copied successfully to the proper location.
    00375  * @retval   ::SM_API_ERR_TOKEN_ID is returned when the tokenID
    00376  * passed into the function is not valid.
    00377  *
    00378  * @Constraints pSensorData must point to a properly allocated
    00379  * memory block large enough to hold the expected
    00380  * sensor sample data.
    00381  * If the operation is successful, current sensor data is copied
    00382  * to the proper memory location.
    00383  * If the operation is unsuccessful, no sensor data is copied.
    00384  * @Reentrant   Yes
    00385  * @Libs        isf_core.lib
    00386  **/
    00387 sm_result_t  isf_sm_get_sensor_data(uint16  nTokenID, void  *pSensorData );
    00388 /*!<
    00389  *
    00390  * @Example
    00391  \verbatim
    00392  The following outlines the sequence of actions occuring when a subscriber receives sensor data:
    00393  1. Subscriber waits for a specific event in its event group to receive sensor data from a given subscription.
    00394  2. The Sensor Manager signals the relevant event after depositing one or more new data sets in the shared memory area.
    00395  3. The subscriber, then, calls this API with the appropriate parameters as described above.
    00396  4. The API copies the sensor data set(s) to the passed in memory buffer with semaphore protection.
    00397  5. The subscriber task is free to use the sensor data as it pleases.
    00398  ------------------------------------------------------------
    00399  Notes:
    00400  - When notified via an event, the subscriber is able to fetch the data with the API.
    00401    Or, the subscriber could decide not to get the data, at its discretion.
    00402  - The Sensor Manager over-writes the shared memory buffer set up during its subscription whenever new data is available based upon the sampling rate of this subscription.
    00403  - When an event notification is made by the Sensor Manager, the sensor data available to fetch is the most recent sample set(s).
    00404
    00405  Notes on the example code:
    00406  - gHostNoFifoAccelData   : The user buffer for receiving accelerometer data when notified by the Sensor Manager that the accelerometer data is ready.
    00407  - EV_HOST_ACCEL_DATA_RDY : The event flag (bit) for the Sensor Manager to notify the user when new accelerometer data is available.
    00408  --------------------------------------------------------------
    00409   AccelData_t        gHostNoFifoAccelData;
    00410   ...
    00411   vuint8             *pv8MailBox;
    00412   uint8              *pSendData;
    00413   uint8              bytes2Write;
    00414   ...
    00415   switch (gCurrentEventID)
    00416   {
    00417     case EV_HOST_ACCEL_DATA_RDY:
    00418         isf_sm_get_sensor_data(hostAccelDataToken, (void  *)&gHostNoFifoAccelData );
    00419         // Now the data is consumed.
    00420         // This data is deposited in the Slave-Port Mailbox for the host application to fetch
    00421         // The accelerometer data packet starts writing from MB24.
    00422         // MB22 - MB25 : time stamp of this data set
    00423         // MB26 - MB31 : xyz data [6 bytes]
    00424         pv8MailBox  = &SP_MB22;
    00425         pSendData   = (uint8 *)&gHostNoFifoAccelData;
    00426         bytes2Write = (uint8)sizeof(gHostNoFifoAccelData);
    00427         while (bytes2Write--)
    00428         {
    00429             *pv8MailBox++ = *pSendData++;
    00430         }
    00431         break;
    00432
    00433   Copyright (c) 2012, Freescale Semiconductor, Inc.
    00434  \endverbatim
    00435  */
    00436
    00437
    00438 #endif /* ISF_SM_API_H_ */