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
Go to the documentation of this file.
1 /**
2  * @file isf_sm_api.h
3  * @brief The \b isf_sm_api.h contains the collection of APIs for the Sensor Manager as well as related defines and data structures
4  * required.
5  *
6  * @copyright Copyright (c) 2013, Freescale Semiconductor, Inc.
7  */
8 
9 #ifndef ISF_SM_API_H_
10 #define ISF_SM_API_H_
11 
12 #include "isf.h"
13 #include "isf_dsa_adapter.h"
14 #include "lwevent.h"
15 #include "isf_sm_types.h"
16 
17 
18 /*! @brief This is the Sensor Manager API used to find a sensor of the requested type.
19  *
20  * @Purpose This API allows a subscriber to find a sensor of a given type without knowing
21  * exactly which sensors have been composed into a particular system. A subscriber
22  * may search for a sensor by type with an optional data type constraint. The function
23  * returns the number of sensors found that support the requested types, and fills
24  * the provided list buffer (up to the specified buffer size) with the sensor IDs
25  * of the sensors meeting the specified search criteria.
26  * The function will fill the sensorList with sensorIDs in the same order they exist in
27  * the gSensorList array.
28  * When only a single sensorID is desired, set the sensorListSize to 1.
29  *
30  * @param[in] typeToFind The type of the sensor to search for.
31  * @param[in] dataTypeToFind An additional data type that must be supported by the sensors.
32  * @param[in,out] sensorList Pointer to a buffer for the returned sensor IDs
33  * @param[in] sensorListSize The maximum number of sensorIDs to be returned (the size of the
34  * sensorList)
35  *
36  * @return ::isf_sm_find_sensor_by_type() returns the number of sensors found that match the
37  * specified search criteria.
38  *
39  * @retval A return value of zero indicates that no matching sensors were found.
40 
41  *
42  * @retval A non-zero return value indicates the number of sensorIDs that were placed
43  * in the sensorList that matched the specified search criteria.
44  *
45  * @Reentrant Yes
46  * @Libs isf_core.lib
47  *
48  */
50  uint8 *sensorList, uint8 sensorListSize);
51 
52 /*! @brief This is the Sensor Manager API used to subscribe to sensor data.
53  *
54  * @Purpose This API allows a subscriber to register for data
55  * from this sensor and to define the preferred sensor settings,
56  * if necessary.
57  *
58  * @param[in] nSensorID ISF unique sensor obtained from the sensor list.
59  * @param[in,out] pRequiredSettings On input, the parameter contains a valid pointer to the
60  * desired sensor sample settings. \n On output, alternate
61  * sensor sample settings are provided, if the requested
62  * settings are not possible.
63  * @param[in] pEventGroup Pointer to the event group for SM to signal when sensor data is ready.
64  * @param[in] nEventFieldIndex Bit number or index in the event group for SM to signal when sensor data is ready.
65  * @param[in,out] pTokenAssigned On input, parameter contains a valid pointer to memory to send
66  * the assigned token ID. \n On successful output, the parameter
67  * contains the assigned token ID.
68  *
69  * @return ::isf_sm_subscribe_sensor_data() returns a value of type ::sm_result_t indicating the current state
70  * of the subscription.
71  *
72  * @retval ::ISF_SUCCESS is returned when the subscriber is registered to receive sensor
73  * data for the given sampling settings.
74  *
75  * @retval ::SM_API_ALTERNATE_OFFERED is returned when an alternate rate is provided.
76  * @retval ::SM_API_ERR_SENSOR_ID is returned when an invalid sensor ID is provided.
77  *
78  * @Constraints When the call completes successfully, the subscriber is registered to receive
79  * sensor data at the desired sample settings. The token ID for the subscription is returned to
80  * the subscriber.
81  *
82  * Otherwise, the subscriber is not registered to receive sensor data. Based on the return status,
83  * alternative sample settings may be proposed.
84  *
85  * @Reentrant Yes
86  * @Libs isf_core.lib
87  *
88  */
90  LWEVENT_STRUCT *pEventGroup, uint32 nEventFieldIndex, uint32 *pTokenAssigned );
91 
92 /*!<
93  *
94  * @Example
95  * AFE Accelerometer subscribes to data at rate of 50 Hz or a period of 20,000 microseconds with no FIFO
96  * ------------------------------------------------------------------------------------------
97  * ACCEL_SENSOR_3D : The ID of the accelerometer sensor to subscribe to.
98  * Subscription_EventGrp : Event group for Sensor Manager to post events to this task when new accelerometer
99  * data is available.
100  * EV_ACCEL_DATA_RDY : event flag (bit) in the gHostProxy_EventGrp to be signaled.
101  * SM_GIVEN_SETTINGS : the sensor settings in the subscription must be used exactly.
102  * AccelDataToken : The unique returned token for the subscription.
103  * <pre>
104  * SubscriptionSettings.nSamplePeriod = 20000;
105  * SubscriptionSettings.resultType = TYPE_RAW_ACCELERATION_3D;
106  * SubscriptionSettings.resultFormat = DSA_RESULT_TYPE_RAW_COUNTS;
107  * SubscriptionSettings.nFifoDepth = 1;
108  * SubscriptionSettings.nSettingsToUse = SM_GIVEN_SETTINGS;
109  * </pre>
110  * <pre>
111  * smApiResult = \a isf_sm_subscribe_sensor_data( SM_AFE_ACCEL_SENSOR_3D,
112  * &SubscriptionSettings,
113  * &Subscription_EventGrp,
114  * EV_ACCEL_DATA_RDY,
115  * &AccelDataToken);
116  * if ( smApiResult != ISF_SUCCESS)
117  * {
118  * // Error handling.
119  * ;
120  * }
121 * Copyright (c) 2014, Freescale Semiconductor, Inc.
122 *</pre>
123 *
124 */
125 
126 
127 /*! @brief This Sensor Manager API unsubscribes from
128  * receiving sensor data.
129  *
130  * @details This API allow the subscriber to unregister from a
131  * previously registered subscription to sensor data.
132  *
133  * @param[in] nTokenID This is the tokenID received from the
134  * SM after subscribing to the sensor.
135  *
136  * @return ::isf_sm_unsubscribe_sensor_data() returns a value
137  * of type ::sm_result_t indicating the result of the unsubscribe
138  * operation.
139  *
140  * @retval ::ISF_SUCCESS is returned when the unsubscribe
141  * operation completes successfully.
142  * @retval ::SM_API_ERR_TOKEN_ID is returned when the tokenID
143  * passed into the function is not valid.
144  *
145  * @Constraints If the operation is successful, the caller's
146  * subscription to sensor data associated with this tokenID
147  * is permanently removed.
148  * If the operation is unsuccessful, no change is made to the
149  * caller's subscription to this sensor.
150  *
151  * @Reentrant Yes
152  * @Libs isf_core.lib
153  **/
155 /*!<
156  *
157  * @Example
158  * To unsubscribe from sensor data, this API is called with the tokenID received from
159  * the Sensor Manager during subscription.
160  * ----------------------------------------------------------------------------------------
161  * isf_sm_unsubscribe_sensor_data( hostAccelDataToken);
162  * Copyright (c) 2012, Freescale Semiconductor, Inc.
163  */
164 
165 
166 /*! @brief This Sensor Manager API allows a subscriber to
167  * receive sensor data.
168  *
169  * @details This API allows a subscriber to request the Sensor
170  * Manager to begin sending subscribed sensor data.
171  *
172  * @param [in] nTokenID This is the tokenID received from the SM
173  * after subscribing to this sensor data.
174  *
175  * @return ::isf_sm_begin_sensor_data() returns a value of type
176  * ::sm_result_t indicating that sensor data is or is not
177  * provided.
178  *
179  * @retval ::ISF_SUCCESS is returned when the current
180  * subscriber is capable to receive notifications when data is
181  * available from the indicated sensor.
182  *
183  * @retval ::SM_API_ERR_TOKEN_ID is returned if the tokenID
184  * passed into the function is not valid.
185  *
186  * @Constraints If the operation is successful, starting from
187  * the next sensor data set, the subscriber registered with this
188  * token is notified whenever a new data set is ready to be
189  * fetched.
190  * If the operation is unsuccessful, no change is made to the
191  * caller's subscription to this sensor.
192  *
193  * @Reentrant Yes
194  * @Libs isf_core.lib
195  **/
197 /*!<
198  *
199  * @Example
200  * To begin receiving sensor data for this subscription, this API is called with the tokenID received from
201  * Sensor Manager during subscription.
202  * ----------------------------------------------------------------------------------------
203  * isf_sm_begin_sensor_data( hostAccelDataToken);
204  * Copyright (c) 2012, Freescale Semiconductor, Inc.
205  */
206 
207 
208 /*! @brief This Sensor Manager API is used by a subscriber to
209  * stop receiving sensor data
210  *
211  * @details This API enables a subscriber to request the Sensor
212  * Manager to stop sending subscribed sensor data.
213  *
214  * @param [in] nTokenID The tokenID of the sensor from which the subscriber no longer wishes to receive data.
215  *
216  * @return ::isf_sm_end_sensor_data() returns a value of type
217  * ::sm_result_t indicating whether or not the operation was
218  * successful.
219  *
220  * @retval ::ISF_SUCCESS is returned when the sensor no longer provides data to the subscriber.
221  *
222  * @retval ::SM_API_ERR_TOKEN_ID is returned when the tokenID
223  * passed into the function is not valid.
224  *
225  * @Constraints If the operation is successful, starting from
226  * the next sensor data set, the subscriber registered with this
227  * token is no longer notified when a new data set is available.
228  * If the operation is unsuccessful, no change is made to the
229  * caller's subscription to this sensor.
230  *
231  * @Reentrant Yes
232  * @Libs isf_core.lib
233  **/
235 /*!<
236  *
237  * @Example
238  * To stop receiving sensor data for this subscription, this
239  * API is called with the tokenID received from the
240  * Sensor Manager during subscription.
241  * Note: This does not de-register the subscription. By calling isf_sm_begin_sensor_data(), the user could
242  * resume getting sensor data again at any time in the future.
243  * ----------------------------------------------------------------------------------------
244  * isf_sm_end_sensor_data( hostAccelDataToken);
245  *
246  * Copyright (c) 2012, Freescale Semiconductor, Inc.
247  */
248 
249 /*! @brief This Sensor Manager API allows a subscriber to
250  * fetch a new sensor data set.
251  *
252  * @details This API allows a subscriber to
253  * fetch the next data set(s) when notified of new data
254  * availability.
255  *
256  * @param [in] nTokenID The tokenID received from the SM when
257  * the subscriber subscribed to this sensor at the given rate.
258  * @param [in,out] pSensorData On input,the parameter contains a
259  * valid pointer to the memory location to copy sensor sample
260  * set(s). \n
261  * On successful output, the parameter contains current sensor
262  * sample(s). When there is an error, the parameter is not
263  * changed.
264  *
265  * @return ::isf_sm_get_sensor_data() returns a value of type
266  * ::sm_result_t indicating whether or not the operation was
267  * successful.
268  *
269  * @retval ::ISF_SUCCESS is returned upon the sensor data set
270  * is copied successfully to the proper location.
271  * @retval ::SM_API_ERR_TOKEN_ID is returned when the tokenID
272  * passed into the function is not valid.
273  *
274  * @Constraints pSensorData must point to a properly allocated
275  * memory block large enough to hold the expected
276  * sensor sample data.
277  * If the operation is successful, current sensor data is copied
278  * to the proper memory location.
279  * If the operation is unsuccessful, no sensor data is copied.
280  * @Reentrant Yes
281  * @Libs isf_core.lib
282  **/
283 sm_result_t isf_sm_get_sensor_data(uint32 nTokenID, void *pSensorData );
284 /*!<
285  *
286  * @Example
287  \verbatim
288  The following outlines the sequence of actions occuring when a subscriber receives sensor data:
289  1. Subscriber waits for a specific event in its event group to receive sensor data from a given subscription.
290  2. The Sensor Manager signals the relevant event after depositing one or more new data sets in the shared memory area.
291  3. The subscriber, then, calls this API with the appropriate parameters as described above.
292  4. The API copies the sensor data set(s) to the passed in memory buffer with semaphore protection.
293  5. The subscriber task is free to use the sensor data as it pleases.
294  ------------------------------------------------------------
295  Notes:
296  - When notified via an event, the subscriber is able to fetch the data with the API.
297  Or, the subscriber could decide not to get the data, at its discretion.
298  - 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.
299  - When an event notification is made by the Sensor Manager, the sensor data available to fetch is the most recent sample set(s).
300 
301  Notes on the example code:
302  - gHostNoFifoAccelData : The user buffer for receiving accelerometer data when notified by the Sensor Manager that the accelerometer data is ready.
303  - EV_HOST_ACCEL_DATA_RDY : The event flag (bit) for the Sensor Manager to notify the user when new accelerometer data is available.
304  --------------------------------------------------------------
305  AccelData_t gHostNoFifoAccelData;
306  ...
307  vuint8 *pv8MailBox;
308  uint8 *pSendData;
309  uint8 bytes2Write;
310  ...
311  switch (gCurrentEventID)
312  {
313  case EV_HOST_ACCEL_DATA_RDY:
314  isf_sm_get_sensor_data(hostAccelDataToken, (void *)&gHostNoFifoAccelData );
315  // Now the data is consumed.
316  // This data is deposited in the Slave-Port Mailbox for the host application to fetch
317  // The accelerometer data packet starts writing from MB24.
318  // MB22 - MB25 : time stamp of this data set
319  // MB26 - MB31 : xyz data [6 bytes]
320  pv8MailBox = &SP_MB22;
321  pSendData = (uint8 *)&gHostNoFifoAccelData;
322  bytes2Write = (uint8)sizeof(gHostNoFifoAccelData);
323  while (bytes2Write--)
324  {
325  *pv8MailBox++ = *pSendData++;
326  }
327  break;
328 
329  Copyright (c) 2012, Freescale Semiconductor, Inc.
330  \endverbatim
331  */
332 
333 
334 #endif /* ISF_SM_API_H_ */
unsigned char uint8
This defines uint8 as unsigned char.
Definition: isf_types.h:18
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.
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
sm_result_t isf_sm_begin_sensor_data(uint32 nTokenID)
This Sensor Manager API allows a subscriber to receive sensor data.
isf_SensorTypes_t
sm_result_t isf_sm_unsubscribe_sensor_data(uint32 nTokenID)
This Sensor Manager API unsubscribes from receiving sensor data.
isf_SensorDataTypes_t
Main ISF header file. Contains code common to all ISF components.
sm_result_t isf_sm_end_sensor_data(uint32 nTokenID)
This Sensor Manager API is used by a subscriber to stop receiving sensor data.
int32 sm_result_t
Sensor Manager API return type.
Definition: isf_sm_types.h:38
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.
The isf_sm_types.h contains the collection of type definitions used in the Sensor Manager Interface a...
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.