ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
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"
#include "isf_dsa_adapter.h"
#include "lwevent.h"
#include "isf_sm_types.h"
Include dependency graph for isf_sm_api.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

uint8 isf_sm_find_sensor_by_type (isf_SensorTypes_t typeToFind, isf_SensorDataTypes_t dataTypeToFind, uint8 *sensorList, uint8 sensorListSize)
 This is the Sensor Manager API used to find a sensor of the requested type. More...
 
sm_result_t isf_sm_subscribe_sensor_data (uint8 nSensorID, isf_SubscriptionSettings_t *pRequiredSettings, LWEVENT_STRUCT *pEventGroup, uint32 nEventFieldIndex, uint32 *pTokenAssigned)
 This is the Sensor Manager API used to subscribe to sensor data. More...
 
sm_result_t isf_sm_unsubscribe_sensor_data (uint32 nTokenID)
 This Sensor Manager API unsubscribes from receiving sensor data. More...
 
sm_result_t isf_sm_begin_sensor_data (uint32 nTokenID)
 This Sensor Manager API allows a subscriber to receive sensor data. More...
 
sm_result_t isf_sm_end_sensor_data (uint32 nTokenID)
 This Sensor Manager API is used by a subscriber to stop receiving sensor data. More...
 
sm_result_t isf_sm_get_sensor_data (uint32 nTokenID, void *pSensorData)
 This Sensor Manager API allows a subscriber to fetch a new sensor data set. More...
 

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.

Definition in file isf_sm_api.h.

Function Documentation

sm_result_t isf_sm_begin_sensor_data ( uint32  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]nTokenIDThis 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_SUCCESSis returned when the current subscriber is capable to receive notifications when data is available from the indicated sensor.
SM_API_ERR_TOKEN_IDis 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 ( uint32  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]nTokenIDThe 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_SUCCESSis returned when the sensor no longer provides data to the subscriber.
SM_API_ERR_TOKEN_IDis 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.

uint8 isf_sm_find_sensor_by_type ( isf_SensorTypes_t  typeToFind,
isf_SensorDataTypes_t  dataTypeToFind,
uint8 sensorList,
uint8  sensorListSize 
)

This is the Sensor Manager API used to find a sensor of the requested type.

Purpose:
This API allows a subscriber to find a sensor of a given type without knowing exactly which sensors have been composed into a particular system. A subscriber may search for a sensor by type with an optional data type constraint. The function returns the number of sensors found that support the requested types, and fills the provided list buffer (up to the specified buffer size) with the sensor IDs of the sensors meeting the specified search criteria. The function will fill the sensorList with sensorIDs in the same order they exist in the gSensorList array. When only a single sensorID is desired, set the sensorListSize to 1.
Parameters
[in]typeToFindThe type of the sensor to search for.
[in]dataTypeToFindAn additional data type that must be supported by the sensors.
[in,out]sensorListPointer to a buffer for the returned sensor IDs
[in]sensorListSizeThe maximum number of sensorIDs to be returned (the size of the sensorList)
Returns
isf_sm_find_sensor_by_type() returns the number of sensors found that match the specified search criteria.
Return values
Areturn value of zero indicates that no matching sensors were found.
Anon-zero return value indicates the number of sensorIDs that were placed in the sensorList that matched the specified search criteria.
Reentrant: Yes
Link Libraries:
isf_core.lib
sm_result_t isf_sm_get_sensor_data ( uint32  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]nTokenIDThe tokenID received from the SM when the subscriber subscribed to this sensor at the given rate.
[in,out]pSensorDataOn 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_SUCCESSis returned upon the sensor data set is copied successfully to the proper location.
SM_API_ERR_TOKEN_IDis 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,
isf_SubscriptionSettings_t pRequiredSettings,
LWEVENT_STRUCT *  pEventGroup,
uint32  nEventFieldIndex,
uint32 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]nSensorIDISF unique sensor obtained from the sensor list.
[in,out]pRequiredSettingsOn 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]pEventGroupPointer to the event group for SM to signal when sensor data is ready.
[in]nEventFieldIndexBit number or index in the event group for SM to signal when sensor data is ready.
[in,out]pTokenAssignedOn 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_SUCCESSis returned when the subscriber is registered to receive sensor data for the given sampling settings.
SM_API_ALTERNATE_OFFEREDis returned when an alternate rate is provided.
SM_API_ERR_SENSOR_IDis 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

ACCEL_SENSOR_3D : The ID of the accelerometer sensor to subscribe to. Subscription_EventGrp : Event group for Sensor Manager to post events to this task when new accelerometer data is available. EV_ACCEL_DATA_RDY : event flag (bit) in the gHostProxy_EventGrp to be signaled. SM_GIVEN_SETTINGS : the sensor settings in the subscription must be used exactly. AccelDataToken : The unique returned token for the subscription.

   SubscriptionSettings.nSamplePeriod   = 20000;   
   SubscriptionSettings.resultType      = TYPE_RAW_ACCELERATION_3D;
   SubscriptionSettings.resultFormat    = DSA_RESULT_TYPE_RAW_COUNTS;
   SubscriptionSettings.nFifoDepth      = 1;
   SubscriptionSettings.nSettingsToUse  = SM_GIVEN_SETTINGS;
   
   smApiResult = isf_sm_subscribe_sensor_data( SM_AFE_ACCEL_SENSOR_3D,
                                                 &SubscriptionSettings,
                                                 &Subscription_EventGrp,
                                                 EV_ACCEL_DATA_RDY,
                                                 &AccelDataToken);
   if ( smApiResult != ISF_SUCCESS)
   {
      // Error handling.
      ;
   }
  Copyright (c) 2014, Freescale Semiconductor, Inc.
*
sm_result_t isf_sm_unsubscribe_sensor_data ( uint32  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]nTokenIDThis 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_SUCCESSis returned when the unsubscribe operation completes successfully.
SM_API_ERR_TOKEN_IDis 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.