| 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
Data Structures | Defines | Typedefs | Enumerations | Functions
Include/isf_sm_api.h File Reference

The isf_sm_api.h contains the collection of APIs for the Sensor Manager as well as related defines and data structures required. More...

`#include "isf.h"`

Go to the source code of this file.

## Data Structures
struct | SM_SensorSetting_t
## Defines
#define | ISF_SUCCESS (0)
| This status code indicates that the API operation was successful.
#define | SM_MAX_SUBSCRIBERS_PER_SENSOR (3)
| This is the maximum number of subscribers allowed per sensor.
#define | SM_MAX_FIFO_DEPTH (20)
| This is the maximum allowed depth of the sample FIFO.
#define | SM_API_ALTERNATE_OFFERED (sm_result_t)(-10L)
| This is the status code returned by the Sensor Manager when the sensor cannot be configured based on user requested sensor settings as given in SM_SensorSetting_t. Additionally, the Sensor Manager provides a suggestion for the next best alternate rate and other possible settings.
#define | SM_API_ERR_TOKEN_ID (sm_result_t)(-1L)
| This is returned by the Sensor Manager when an invalid token ID is passed into any of the API calls.
#define | SM_API_ERR_SENSOR_ID (sm_result_t)(-2L)
| This is returned by the Sensor Manager when the passed parameter, sensor ID, does not match an existing sensor.
#define | SM_API_ERR_ALREADY_BEGUN (sm_result_t)(-3L)
| This is returned by the Sensor Manager when the sensor data flow is already enabled.
#define | SM_API_ERR_NOT_YET_BEGUN (sm_result_t)(-4L)
| This is returned by the Sensor Manager when the sensor data is unavailable because the data stream has not been started.
#define | SM_API_ERR_SUBSCRIBER_COUNT (sm_result_t)(-5L)
| This is returned by the Sensor Manager when the maximum number of subscribers as defined in SM_MAX_SUBSCRIBERS_PER_SENSOR for this particular sensor has been exceeded.
#define | SM_API_ERR_NO_MEMORY (sm_result_t)(-6L)
| This is returned by the Sensor Manager when an out-of- memory error status is returned during the execution of the API.
#define | SM_API_ERR_FIFO_OVER_LIMIT (sm_result_t)(-7L)
| This is returned by the Sensor Manager when the requested FIFO depth is larger than the FIFO limit specified in SM_MAX_FIFO_DEPTH.
#define | SM_API_ERR_SAMPLE_TAP_RATE (sm_result_t)(-8L)
| This is returned by the Sensor Manager when the requested sample tap rate is invalid.
#define | SM_API_ERR_SETTINGS_TO_USE (sm_result_t)(-9L)
| This is returned by the Sensor Manager when the requested sensor settings are invalid.
#define | SM_API_ERR_SENSOR_NOT_AVAIL (sm_result_t)(-21L)
| This is returned by the Sensor Manager when the requested sensor is not available.
#define | SM_API_ERR_SENSOR_ALREADY_INITIALIZED (sm_result_t)(-22L)
| This is returned by the Sensor Manager when the sensor is already initialized.
#define | SM_API_ERR_SENSOR_INIT_FAILED (sm_result_t)(-23L)
| This is returned by the Sensor Manager when the sensor initialization was not successful.
## Typedefs
typedef int32 | sm_result_t
| Sensor Manager API return type.
typedef enum sm_dsa_return_status | sm_dsa_ret_t
typedef enum SensorSettingChoices | SensorSettingsChoices_t
## Enumerations
enum | sm_dsa_return_status { SM_DSA_RET_SETTINGS_CHANGED = 0x0010 }
enum | SensorSettingChoices { SM_CURRENT_SETTINGS = 1, SM_GIVEN_SETTINGS, SM_BEST_POSSIBLE_SETTINGS }
## Functions
sm_result_t | isf_sm_subscribe_sensor_data (uint8 nSensorID, SM_SensorSetting_t *pRequiredSettings, LWEVENT_STRUCT *pEventGroup, uint32 nEventFieldIndex, uint16 *pTokenAssigned)
| This is the Sensor Manager API used to subscribe to sensor data.
sm_result_t | isf_sm_unsubscribe_sensor_data (uint16 nTokenID)
| This Sensor Manager API unsubscribes from receiving sensor data.
sm_result_t | isf_sm_begin_sensor_data (uint16 nTokenID)
| This Sensor Manager API allows a subscriber to receive sensor data.
sm_result_t | isf_sm_end_sensor_data (uint16 nTokenID)
| This Sensor Manager API is used by a subscriber to stop receiving sensor data.
sm_result_t | isf_sm_get_sensor_data (uint16 nTokenID, void *pSensorData)
| This Sensor Manager API allows a subscriber to fetch a new sensor data set.

## Detailed Description

The isf_sm_api.h contains the collection of APIs for the Sensor Manager as well as related defines and data structures required.

Copyright:
  Copyright (c) 2012, Freescale Semiconductor, Inc.

Definition in file isf_sm_api.h.

## Define Documentation

#define ISF_SUCCESS (0)

This status code indicates that the API operation was successful.

Definition at line 17 of file isf_sm_api.h.

#define SM_API_ALTERNATE_OFFERED (sm_result_t)(-10L)

This is the status code returned by the Sensor Manager when the sensor cannot be configured based on user requested sensor settings as given in SM_SensorSetting_t. Additionally, the Sensor Manager provides a suggestion for the next best alternate rate and other possible settings.

Definition at line 52 of file isf_sm_api.h.

#define SM_API_ERR_ALREADY_BEGUN (sm_result_t)(-3L)

This is returned by the Sensor Manager when the sensor data flow is already enabled.

Definition at line 69 of file isf_sm_api.h.

#define SM_API_ERR_FIFO_OVER_LIMIT (sm_result_t)(-7L)

This is returned by the Sensor Manager when the requested FIFO depth is larger than the FIFO limit specified in SM_MAX_FIFO_DEPTH.

Definition at line 98 of file isf_sm_api.h.

#define SM_API_ERR_NO_MEMORY (sm_result_t)(-6L)

This is returned by the Sensor Manager when an out-of- memory error status is returned during the execution of the API.

Definition at line 91 of file isf_sm_api.h.

#define SM_API_ERR_NOT_YET_BEGUN (sm_result_t)(-4L)

This is returned by the Sensor Manager when the sensor data is unavailable because the data stream has not been started.

Definition at line 76 of file isf_sm_api.h.

#define SM_API_ERR_SAMPLE_TAP_RATE (sm_result_t)(-8L)

This is returned by the Sensor Manager when the requested sample tap rate is invalid.

Definition at line 104 of file isf_sm_api.h.

#define SM_API_ERR_SENSOR_ALREADY_INITIALIZED (sm_result_t)(-22L)

This is returned by the Sensor Manager when the sensor is already initialized.

Definition at line 123 of file isf_sm_api.h.

#define SM_API_ERR_SENSOR_ID (sm_result_t)(-2L)

This is returned by the Sensor Manager when the passed parameter, sensor ID, does not match an existing sensor.

Definition at line 64 of file isf_sm_api.h.

#define SM_API_ERR_SENSOR_INIT_FAILED (sm_result_t)(-23L)

This is returned by the Sensor Manager when the sensor initialization was not successful.

Definition at line 128 of file isf_sm_api.h.

#define SM_API_ERR_SENSOR_NOT_AVAIL (sm_result_t)(-21L)

This is returned by the Sensor Manager when the requested sensor is not available.

Definition at line 116 of file isf_sm_api.h.

#define SM_API_ERR_SETTINGS_TO_USE (sm_result_t)(-9L)

This is returned by the Sensor Manager when the requested sensor settings are invalid.

Definition at line 110 of file isf_sm_api.h.

#define SM_API_ERR_SUBSCRIBER_COUNT (sm_result_t)(-5L)

This is returned by the Sensor Manager when the maximum number of subscribers as defined in SM_MAX_SUBSCRIBERS_PER_SENSOR for this particular sensor has been exceeded.

Definition at line 84 of file isf_sm_api.h.

#define SM_API_ERR_TOKEN_ID (sm_result_t)(-1L)

This is returned by the Sensor Manager when an invalid token ID is passed into any of the API calls.

Definition at line 58 of file isf_sm_api.h.

#define SM_MAX_FIFO_DEPTH (20)

This is the maximum allowed depth of the sample FIFO.

Note: This define must not be changed by the user.

Definition at line 31 of file isf_sm_api.h.

#define SM_MAX_SUBSCRIBERS_PER_SENSOR (3)

This is the maximum number of subscribers allowed per sensor.

Note: This define must not be changed by the user.

Definition at line 24 of file isf_sm_api.h.

## Typedef Documentation

typedef enum SensorSettingChoices SensorSettingsChoices_t

Defines for subscriber setting options.

typedef enum sm_dsa_return_status sm_dsa_ret_t

typedef int32 sm_result_t

Sensor Manager API return type.

Definition at line 34 of file isf_sm_api.h.

## Enumeration Type Documentation

enum SensorSettingChoices

Defines for subscriber setting options.

Enumerator:

  SM_CURRENT_SETTINGS | Use the current sensor settings.
  SM_GIVEN_SETTINGS | Use the user-provided sensor settings if possible.
  SM_BEST_POSSIBLE_SETTINGS | Use the given settings, if possible. If not, use the best possible settings.

Definition at line 130 of file isf_sm_api.h.

enum sm_dsa_return_status

Enumerator:

  SM_DSA_RET_SETTINGS_CHANGED | Value returned to the user when alternate sensor settings have been suggested.

Definition at line 36 of file isf_sm_api.h.

## Function Documentation

sm_result_t isf_sm_begin_sensor_data | ( | uint16 | nTokenID | ) |

This Sensor Manager API allows a subscriber to receive sensor data.

This API allows a subscriber to request the Sensor Manager to begin sending subscribed sensor data.

Parameters:

  [in] | nTokenID | This is the tokenID received from the SM after subscribing to this sensor data.

Returns:
  isf_sm_begin_sensor_data() returns a value of type sm_result_t indicating that sensor data is or is not provided.

Return values:

  ISF_SUCCESS | is returned when the current subscriber is capable to receive notifications when data is available from the indicated sensor.
  SM_API_ERR_TOKEN_ID | is returned if the tokenID passed into the function is not valid.

Constraints:
  If the operation is successful, starting from the next sensor data set, the subscriber registered with this token is notified whenever a new data set is ready to be fetched. If the operation is unsuccessful, no change is made to the caller's subscription to this sensor.

Reentrant: Yes

Link Libraries:
  isf_core.lib

Example:

                 To begin receiving sensor data for this subscription, this  API is called with the tokenID received from
                 Sensor Manager during subscription.

  ---------------------* -------------------------------------------------------------------------------------- isf_sm_begin_sensor_data( hostAccelDataToken); Copyright (c) 2012, Freescale Semiconductor, Inc.

sm_result_t isf_sm_end_sensor_data | ( | uint16 | nTokenID | ) |

This Sensor Manager API is used by a subscriber to stop receiving sensor data.

This API enables a subscriber to request the Sensor Manager to stop sending subscribed sensor data.

Parameters:

  [in] | nTokenID | The tokenID of the sensor from which the subscriber no longer wishes to receive data.

Returns:
  isf_sm_end_sensor_data() returns a value of type sm_result_t indicating whether or not the operation was successful.

Return values:

  ISF_SUCCESS | is returned when the sensor no longer provides data to the subscriber.
  SM_API_ERR_TOKEN_ID | is returned when the tokenID passed into the function is not valid.

Constraints:
  If the operation is successful, starting from the next sensor data set, the subscriber registered with this token is no longer notified when a new data set is available. If the operation is unsuccessful, no change is made to the caller's subscription to this sensor.

Reentrant: Yes

Link Libraries:
  isf_core.lib

Example:

                 To stop receiving sensor data for this subscription, this

  API is called with the tokenID received from the Sensor Manager during subscription. Note: This does not de-register the subscription. By calling isf_sm_begin_sensor_data(), the user could resume getting sensor data again at any time in the future. ---------------------* -------------------------------------------------------------------------------------- isf_sm_end_sensor_data( hostAccelDataToken);

Copyright (c) 2012, Freescale Semiconductor, Inc.

sm_result_t isf_sm_get_sensor_data | ( | uint16 | nTokenID,
|  | void * | pSensorData
| ) |  |

This Sensor Manager API allows a subscriber to fetch a new sensor data set.

This API allows a subscriber to fetch the next data set(s) when notified of new data availability.

Parameters:

  [in] | nTokenID | The tokenID received from the SM when the subscriber subscribed to this sensor at the given rate.
  [in,out] | pSensorData | On input,the parameter contains a valid pointer to the memory location to copy sensor sample set(s). On successful output, the parameter contains current sensor sample(s). When there is an error, the parameter is not changed.

Returns:
  isf_sm_get_sensor_data() returns a value of type sm_result_t indicating whether or not the operation was successful.

Return values:

  ISF_SUCCESS | is returned upon the sensor data set is copied successfully to the proper location.
  SM_API_ERR_TOKEN_ID | is returned when the tokenID passed into the function is not valid.

Constraints:
  pSensorData must point to a properly allocated memory block large enough to hold the expected sensor sample data. If the operation is successful, current sensor data is copied to the proper memory location. If the operation is unsuccessful, no sensor data is copied.

Reentrant: Yes

Link Libraries:
  isf_core.lib

Example:

     The following outlines the sequence of actions occuring when a subscriber receives sensor data:
     1. Subscriber waits for a specific event in its event group to receive sensor data from a given subscription.
     2. The Sensor Manager signals the relevant event after depositing one or more new data sets in the shared memory area.
     3. The subscriber, then, calls this API with the appropriate parameters as described above.
     4. The API copies the sensor data set(s) to the passed in memory buffer with semaphore protection.
     5. The subscriber task is free to use the sensor data as it pleases.
     ------------------------------------------------------------
     Notes:
     - When notified via an event, the subscriber is able to fetch the data with the API.
       Or, the subscriber could decide not to get the data, at its discretion.
     - 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.
     - When an event notification is made by the Sensor Manager, the sensor data available to fetch is the most recent sample set(s).

     Notes on the example code:
     - gHostNoFifoAccelData   : The user buffer for receiving accelerometer data when notified by the Sensor Manager that the accelerometer data is ready.
     - EV_HOST_ACCEL_DATA_RDY : The event flag (bit) for the Sensor Manager to notify the user when new accelerometer data is available.
     --------------------------------------------------------------
      AccelData_t        gHostNoFifoAccelData;
      ...
      vuint8             *pv8MailBox;
      uint8              *pSendData;
      uint8              bytes2Write;
      ...
      switch (gCurrentEventID)
      {
        case EV_HOST_ACCEL_DATA_RDY:
            isf_sm_get_sensor_data(hostAccelDataToken, (void  *)&gHostNoFifoAccelData );
            // Now the data is consumed.
            // This data is deposited in the Slave-Port Mailbox for the host application to fetch
            // The accelerometer data packet starts writing from MB24.
            // MB22 - MB25 : time stamp of this data set
            // MB26 - MB31 : xyz data [6 bytes]
            pv8MailBox  = &SP_MB22;
            pSendData   = (uint8 *)&gHostNoFifoAccelData;
            bytes2Write = (uint8)sizeof(gHostNoFifoAccelData);
            while (bytes2Write--)
            {
                *pv8MailBox++ = *pSendData++;
            }
            break;

      Copyright (c) 2012, Freescale Semiconductor, Inc.

sm_result_t isf_sm_subscribe_sensor_data | ( | uint8 | nSensorID,
|  | SM_SensorSetting_t * | pRequiredSettings,
|  | LWEVENT_STRUCT * | pEventGroup,
|  | uint32 | nEventFieldIndex,
|  | uint16 * | pTokenAssigned
| ) |  |

This is the Sensor Manager API used to subscribe to sensor data.

Purpose:
  This API allows a subscriber to register for data from this sensor and to define the preferred sensor settings, if necessary.

Parameters:

  [in] | nSensorID | ISF unique sensor obtained from the sensor list.
  [in,out] | pRequiredSettings | On input, the parameter contains a valid pointer to the desired sensor sample settings. On output, alternate sensor sample settings are provided, if the requested settings are not possible.
  [in] | pEventGroup | Pointer to the event group for SM to signal when senor data is ready.
  [in] | nEventFieldIndex | Bit number or index in the event group for SM to signal when senor data is ready.
  [in,out] | pTokenAssigned | On input, parameter contains a valid pointer to memory to send the assigned token ID. On successful output, the parameter contains the assigned token ID.

Returns:
  isf_sm_subscribe_sensor_data() returns a value of type sm_result_t indicating the current state of the subscription.

Return values:

  ISF_SUCCESS | is returned when the subscriber is registered to receive sensor data for the given sampling settings.
  SM_API_ALTERNATE_OFFERED | is returned when an alternate rate is provided.
  SM_API_ERR_SENSOR_ID | is returned when an invalid sensor ID is provided.

Constraints:
  When the call completes successfully, the subscriber is registered to receive sensor data at the desired sample settings. The token ID for the subscription is returned to the subscriber.

Otherwise, the subscriber is not registered to receive sensor data. Based on the return status, alternative sample settings may be proposed.

Reentrant: Yes

Link Libraries:
  isf_core.lib

Example:

                 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.

                 SM_AFE_ACCEL_SENSOR_3D : subscribe to AFE (on-chip) accelerometer data.
                 gHostProxy_EventGrp    : Event group for Sensor Manager to post events to this task when new AFE Accelerometer data
                                          is available.
                 EV_HOST_ACCEL_DATA_RDY : event flag (bit) in the gHostProxy_EventGrp to be signaled.
                 SM_GIVEN_SETTINGS      : the sensor settings given in gHostRequestedSensorSettings are used.
                 hostAccelDataToken     : The Sensor Manager returns a unique token ID for this subscription in this field.

       gHostRequestedSensorSettings.nCurrentReportRate  = 20000;
       gHostRequestedSensorSettings.nCurrentResolution  = AFE_ACCEL_RESOLUTION_10_BIT;
       gHostRequestedSensorSettings.nRange              = AFE_ACCEL_G_RANGE_4G;
       gHostRequestedSensorSettings.nFifoDepth          = 1;
       gHostRequestedSensorSettings.nSettingsToUse      = SM_GIVEN_SETTINGS;

       smApiResult = isf_sm_subscribe_sensor_data( SM_AFE_ACCEL_SENSOR_3D,
                                                   &gHostRequestedSensorSettings,
                                                   &gHostProxy_EventGrp,
                                                   EV_HOST_ACCEL_DATA_RDY,
                                                   &hostAccelDataToken);
       if ( smApiResult != ISF_SUCCESS)
       {
          // Error handling.
          ;
       }
       Copyright (c) 2012, Freescale Semiconductor, Inc.

sm_result_t isf_sm_unsubscribe_sensor_data | ( | uint16 | nTokenID | ) |

This Sensor Manager API unsubscribes from receiving sensor data.

This API allow the subscriber to unregister from a previously registered subscription to sensor data.

Parameters:

  [in] | nTokenID | This is the tokenID received from the SM after subscribing to the sensor.

Returns:
  isf_sm_unsubscribe_sensor_data() returns a value of type sm_result_t indicating the result of the unsubscribe operation.

Return values:

  ISF_SUCCESS | is returned when the unsubscribe operation completes successfully.
  SM_API_ERR_TOKEN_ID | is returned when the tokenID passed into the function is not valid.

Constraints:
  If the operation is successful, the caller's subscription to sensor data associated with this tokenID is permanently removed. If the operation is unsuccessful, no change is made to the caller's subscription to this sensor.

Reentrant: Yes

Link Libraries:
  isf_core.lib

Example:

                 To unsubscribe from sensor data, this API is called with the tokenID received from
                 the Sensor Manager during subscription.

  ---------------------* -------------------------------------------------------------------------------------- isf_sm_unsubscribe_sensor_data( hostAccelDataToken); Copyright (c) 2012, Freescale Semiconductor, Inc.