IRPyro API  (sKEMLIB1)
Collection of routines and data structures covering the functionality of the IRPyro sensor
IRPyro_API_single_device_layer.h
Go to the documentation of this file.
1 /**
2 ******************************************************************************
3 * @file IRPyro_API_single_device_layer.h
4 * @author _KEMET Ltd.
5 * @date March 2018
6 * @version Release 1.0.6
7 * @copyright (c) 2018 _KEMET, Ltd
8 * @brief IRPyro data structures and prototype functions
9 * @verbatim
10  ===============================================================================
11  ##### How to use this driver #####
12  ===============================================================================
13  [..]
14  (#) Declare an IRPyro_sensor_device_type in your code
15  (#) Fill the values for CS, INT and address
16  (#) Fill the values for number_of_active_channels and read_mode
17  (#) AFE, CCP and WUP can be left empty if desired, configuration macros
18  will fill them with default values
19  (#) Call IRPyro_open() to commit the values to the physical IRPyro
20  (#) IRPyro_read() retrieves the values sampled by the IRPyro sensor
21  (#) Modify the IRPyro settings using IRPyro_IOCTL()
22  (#) Close the device when finished using IRPyro_read()
23  [..]
24  @endverbatim
25 ******************************************************************************
26  @attention <h2><center>&copy; COPYRIGHT 2018 _KEMET, Ltd</center></h2>
27  @verbatim
28  Copyright (c) 2018, _KEMET, Ltd
29  All rights reserved.
30 
31  THIS SOFTWARE IS PROVIDED BY _KEMET, Ltd ''AS IS'' AND ANY
32  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
33  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
34  DISCLAIMED. IN NO EVENT SHALL _KEMET, Ltd BE LIABLE FOR ANY
35  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
36  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
37  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
38  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
39  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
40  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
41  @endverbatim
42 ******************************************************************************
43  */
44 
45 /* Define to prevent recursive inclusion -------------------------------------*/
46 #ifndef IRPyro_API_single_device_layer
47 #define IRPyro_API_single_device_layer
48 
49 /* Includes ------------------------------------------------------------------*/
50 #include <stdint.h>
52 
53 /** @defgroup API_G6_IRPyro IRPyro AFE values
54  * @ingroup IRPyro_ctes
55  * @brief Defines to configure the IRPyro AFE register
56  * @verbatim
57  * The analogue front end packet contains the settings that control the
58  * common analogue front end settings using 2 Bytes.
59  * More meaningful defines for configuration.
60  * @endverbatim
61  * @note Do not modify
62  * @{
63  */
64 #define INT_DISABLE 0x00
65 #define INT_ENABLE 0x01
66 #define TEMP_DISABLE 0x00
67 #define TEMP_ENABLE 0x01
68 #define MASTER 0x00
69 #define SLAVE 0x01
70 #define CLK_DISABLE 0x00
71 #define CLK_ENABLE 0x01
72 #define HP_DISABLE 0x00
73 #define HP_ENABLE 0x01
74 #define LOW_POWER_DISABLE 0x00
75 #define LOW_POWER_ENABLE 0x01
76 #define LOW_PASS_180 0x00
77 #define LOW_PASS_90 0x01
78 #define LOW_PASS_45 0x02
79 #define LOW_PASS_22_5 0x03
80 #define LOW_PASS_30 0x00
81 #define LOW_PASS_15 0x01
82 #define LOW_PASS_75 0x02
83 #define LOW_PASS_3_75 0x03
84 
85 /**
86  * @}
87  */
88 
89 /** @defgroup API_G7_IRPyro IRPyro CCP values
90  * @ingroup IRPyro_ctes
91  * @brief Defines to configure the IRPyro CCP register
92  * @verbatim
93  * The channel control packet contains 5 Bytes, each of which corresponds to
94  * a single channel with its individual settings.
95  * More meaningful defines for configuration.
96  * @endverbatim
97  * @note Do not modify
98  * @{
99  */
100 #define CH_DISABLE 0x00
101 #define CH_ENABLE 0x01
102 #define FEEDBACK_50_20 0x00
103 #define FEEDBACK_100_40 0x01
104 #define FEEDBACK_200_80 0x02
105 #define FEEDBACK_400_160 0x03
106 #define FEEDBACK_800_320 0x04
107 #define FEEDBACK_1600_640 0x05
108 #define FEEDBACK_3200_1280 0x07
109 #define GAIN_64 0x00
110 #define GAIN_32 0x01
111 #define GAIN_16 0x02
112 #define GAIN_08 0x03
113 #define GAIN_04 0x04
114 #define GAIN_02 0x05
115 #define GAIN_01 0x07
116 
117 #define HIGH_PASS_1HZ 0x00
118 #define HIGH_PASS_2HZ 0x01
119 #define HIGH_PASS_4HZ 0x02
120 #define HIGH_PASS_8HZ 0x03
121 #define HIGH_PASS_0_17HZ 0x00
122 #define HIGH_PASS_0_33HZ 0x01
123 #define HIGH_PASS_0_66HZ 0x02
124 #define HIGH_PASS_1_30HZ 0x03
125 
126 #define TCONDUCT_1_2T 0x00
127 #define TCONDUCT_0_6T 0x01
128 #define TCONDUCT_0_3T 0x02
129 #define TCONDUCT_0_15T 0x03
130 /**
131  * @}
132  */
133 
134 /** @defgroup API_G8_IRPyro IRPyro WUP values
135  * @ingroup IRPyro_ctes
136  * @brief Defines to configure the IRPyro WUP register
137  * @verbatim
138  * The wake up packet contains the thresholds used in the wake up algorithm.
139  *
140  * More meaningful defines for configuration.
141  * @endverbatim
142  * @note Do not modify
143  * @{
144  */
145 #define REF_CH_0 0x00
146 #define REF_CH_1 0x01
147 #define REF_CH_2 0x02
148 #define REF_CH_3 0x03
149 #define REF_CH_4 0x04
150 #define SEL_CH_0 0x00
151 #define SEL_CH_1 0x01
152 #define SEL_CH_2 0x02
153 #define SEL_CH_3 0x03
154 #define SEL_CH_4 0x04
155 #define SLEEP_MODE_ONE_CH 0x00
156 #define SLEEP_MODE_TWO_CH 0x01
157 #define DEFAULT_NO_EVENTS 0x0A
158 #define NOT_IN_USE_VALUE 0x00
159 #define MAX_WUP_THRESHOLD 0xFF
160 #define MIN_WUP_THRESHOLD 0x00
161 #define SAFE_WUP_THRESHOLD 0xB4
162 /**
163  * @}
164  */
165 /** @defgroup IRPyro_ctes Constants to access IRPyro
166  * @ingroup IRPyro_single
167  * @brief Definitions used by the IRPyro_sensor_device_type
168  * @{
169  */
170 /* Exported constants ------------------------------------------------------------*/
171 #define IRPyro_CHANNEL_DATA_VALUES 6 // 5 channel values + frame counter
172 #define IRPyro_CCP_NUMBER_OF_REGISTERS 5 // one CPP register per channel
173 #define IRPyro_DATA_SIZE 17 // bytes in an IRPyro frame
174 /** end of group IRPyro_ctes
175  * @}
176  */
177 
178 /** @defgroup IRPyro_structs Structures to access IRPyro
179  * @ingroup IRPyro_single
180  * @brief Collection of structs that define an IRPyro_sensor_device_type
181  * @{
182  */
183 /* Exported types ------------------------------------------------------------*/
184 /** @struct AFE_reg IRPyro_API_single_device_layer.h
185  * @brief IRPyro Analog Front End (AFE) register structure definition
186  */
187 struct AFE_reg
188 {
189  uint8_t S7_S0; ///< Sampling rate (8 bit) :Sampling Rate = 1000/(N+1).
190  uint8_t LP; ///< Enable low power mode: 1 Enable, 0 Disable
191  uint8_t HP; ///< Enable high pass filter: 1 Enable, 0 Disable. this is the enable trigger which needs to be set after the filters have been set.
192  uint8_t C_LP; ///< Low pass selection
193  uint8_t CLK_OUT; ///< 1 enable internal clock output on Clk pin, 0 disable internal clock output on the Clk pin (only apply for Master. For Slave, this is ignored, because the Clk pin is used as input).
194  uint8_t SYNC; ///< Sync & Clk Pin option: 0 master, 1 slave.
195  uint8_t TEMP; ///< 0 Normal channel data, 1 temperature data (apply to channel 0 only). When this bit is set, channel 0 will be activated automatically (only apply at normal operation and not in Sleep mode).
196  uint8_t INT; ///< Interrupt output: 1 Enable, 0 Disable (only apply at normal operation and not in Sleep mode).
197 };
198 /** @typedef struct AFE_reg AFE_reg_type;
199  * @brief IRPyro Analog Front End (AFE) register type definition
200  */
201 typedef struct AFE_reg AFE_reg_type;
202 
203 /** @struct CCP_reg IRPyro_API_single_device_layer.h
204  * @brief IRPyro Channel Control Package register structure definition
205  */
206 struct CCP_reg
207 {
208  // The channel control packet contains 5 Bytes, each of which corresponds to a single channel with its individual settings.
209  uint8_t Feedback_cap; ///< Feedback capacitor selection
210  uint8_t High_pass_filter_setting; ///< High pass selection
211  uint8_t Feedback_transconductance; ///< Charge amp. trans-conductance selection
212  uint8_t status_bit; ///< Status bit : Active (1) / Disable (0)
213 };
214 /** @typedef struct CCP_reg CCP_reg_type;
215  * @brief IRPyro Channel Control Package register typedef definition
216  */
217 typedef struct CCP_reg CCP_reg_type;
218 
219 /** @struct WUP_reg IRPyro_API_single_device_layer.h
220  * @brief IRPyro Wake Up Package register structure definition
221  * @note probably give these more meaningful names and then add the data sheet descriptor
222  */
223 struct WUP_reg
224 {
225  // The wake up packet contains the thresholds used in the wake up algorithm
226  uint8_t UHT; ///< Byte 0 to 3 (Upper and Lower thresholds) are the 8 MSB of channel ADC data (unsigned value).
227  uint8_t ULT;
228  uint8_t LHT;
229  uint8_t LLT;
230  uint8_t WT_Threshold; ///< Byte 4 is the number of samples required to trigger the wake up algorithm. ? UHT and ULT to detect positive wake-up event (UHT > ULT) ? LHT and LLT to detect negative wake-up event (LHT > LLT) ? Number of sample where the signal is in between threshold (WT).
231  uint8_t DP0_DP2; ///< Reference channel coding DP0-DP2: The Reference channel coding, and CH0-CH2: the selected channel coding
232  // 000 : select channel 0
233  // 001 : select channel 1
234  // 010 : select channel 2
235  // 011 : select channel 3
236  // 1xx : select channel 4
237  uint8_t CH0_CH2; ///< Selected channel coding
238  uint8_t ST; ///< Sleep_mode_type
239  // ST: Sleep mode type
240  // 0 : one channel sleep type, set by ch0-ch2
241  // 1 : two channel sleep type, set by both dp0-dp2 and ch0-ch2
242 };
243 /** @typedef struct WUP_reg WUP_reg_type;
244  * @brief IRPyro Wake Up Package register typedef definition
245  */
246 typedef struct WUP_reg WUP_reg_type;
247 
248 /** @struct FIFO_reg IRPyro_API_single_device_layer.h
249  * @brief IRPyro FIFO packet structure definition
250  */
251 struct FIFO_reg
252 {
253  uint8_t WAKE; ///<
254  uint8_t STATUS_CODE; ///< response to read operation: 00 no error, 01 fifo full, 10 i2c master read less, 11 i2c master read more
255  uint8_t COUNT; ///< Number of frames available
256  uint8_t DATA_READY; ///< Data ready
257 };
258 /** @typedef struct FIFO_reg FIFO_reg_type;
259  * @brief IRPyro FIFO Package register typedef definition
260  */
261 typedef struct FIFO_reg FIFO_reg_type;
262 
263 /** @struct CCP_filter IRPyro_API_single_device_layer.h
264  * @brief IRPyro Channel filter configuration structure
265  */
267 {
268  uint8_t High_pass_filter_setting; ///< High pass selection
269 };
270 /** @typedef struct CCP_filter CCP_filter_type;
271  * @brief Typedef for filter channel definition
272  */
274 
275 /** @struct power_settings IRPyro_API_single_device_layer.h
276  * @ingroup IRPyro_structs
277  * @brief IRPyro Power Settings structure definition
278  */
280 {
281  //AFE reg
282  uint8_t S7_S0; ///< sample rate value
283  uint8_t LP; ///< Enable low power mode: 1 Enable, 0 Disable
284  uint8_t C_LP; ///< Low pass filter selection
285  //CPP reg
286  CCP_filter_type CCP_High_pass[IRPyro_CCP_NUMBER_OF_REGISTERS]; ///< High pass filter configuration for each channel on the IRPyro device
287  //WUP reg
288  uint8_t UHT; // probably give these more meaningful names and then add the data sheet descriptor
289  uint8_t ULT;
290  uint8_t LHT;
291  uint8_t LLT;
292  uint8_t WT_Threshold; //number of samples
293 };
294 /** @typedef struct power_settings power_settings_type;
295  * @brief
296  */
298 
299 /** @struct IRPyro_sensor_device IRPyro_API_single_device_layer.h
300  * @brief IRPyro device structure definition
301  *
302  * Sensor data sampling into the FIFO (SECTION 12.6.1 )
303  * There are two methods of sampling the data available in the FIFO:
304  * Polling mode or Interrupt mode.
305  * - In interrupt mode the host can wait till the interrupt line goes
306  * low in order to read data from the FIFO. The interrupt remains
307  * low till the FIFO is cleared from data.
308  * - In polling mode the host has to read the FIFO status packet to
309  * determine if data is available in order to read it. The number of
310  * data packets available can also be determined from the status
311  * packet allowing multiple reads without having to keep reading the
312  * status packet.
313  * Interrupt mode is a single step operation, polling mode is a two step
314  * operation.
315  *
316  * IMPORTANT:
317  * FIFO data collected is stored in the first available position of the
318  * channel_value array.
319  *
320  * One channel active:
321  * channel 2 -> channel_value[0]
322  * Four channels active:
323  * channel 1 -> channel_value[0]
324  * channel 2 -> channel_value[1]
325  * channel 3 -> channel_value[2]
326  * channel 4 -> channel_value[3]
327  * For both cases:
328  * frame counter -> channel_value[5]
329  */
331 {
332  uint8_t CS_Port; ///< CS (Chip select) port
333  uint8_t INT_Port; ///< INT (Interrupt / Data Ready ) port
334  uint8_t CS_Pin; ///< CS pin
335  uint8_t INT_Pin; ///< INT pin
336  uint8_t address; ///< I2C address in 7 bit format
337 
338  uint8_t number_of_active_channels; ///< useful for read()
339  uint8_t read_mode; ///< interrupt (0), polled (1) or synchronized sampling (2)
340 
341  AFE_reg_type AFE_register; ///< AFE (analog front end) configuration register
342  CCP_reg_type CCP_register[IRPyro_CCP_NUMBER_OF_REGISTERS]; ///< Channel configuration registers 0 - 4
343  WUP_reg_type WUP_register; ///< WUP (Wake Up) configuration register
344 
345  FIFO_reg_type FIFO_register; ///< FIFO status register
346 
347  power_settings_type normal_power; ///< normal power configuration
348  power_settings_type low_power; ///< low power configuration
349 
350  uint32_t channel_value[IRPyro_CHANNEL_DATA_VALUES]; ///< Active frame decoded channel data
351  uint8_t channel_saturation_byte; ///< Active frame saturation byte
352  uint8_t raw_data[IRPyro_DATA_SIZE];
353 
354 };
355 /** @typedef struct IRPyro_sensor_device IRPyro_sensor_device_type;
356  * @brief
357  */
359 
360 /**@brief Used by the IOCTL function to act a command that modifies AFE and CCP
361  */
362 typedef enum IRPyro_command
363 {
380 
381 /** @struct IRPyro_cmd IRPyro_API_single_device_layer.h
382  * @brief IRPyro commands
383  */
384 typedef struct IRPyro_cmd
385 {
386  uint8_t cmd_return_code; ///< command result
387  AFE_reg_type AFE_register; ///< AFE (analog front end) configuration register
388  CCP_reg_type CCP_register[IRPyro_CCP_NUMBER_OF_REGISTERS]; ///< Channel configuration register
389  WUP_reg_type WUP_register; ///< WUP (Wake Up) configuration register
390  IRPyro_command_type cmd; ///< command
392 
393 /** @struct IRPyro_arg IRPyro_API_single_device_layer.h
394  * @brief IRPyro command argument
395  */
396 typedef struct IRPyro_arg
397 {
398  uint8_t arg; ///< argument
399  uint8_t channel; ///< selected channel
401 
402 /** end of group IRPyro_structs
403  * @}
404  */
405 /* Exported functions ------------------------------------------------------- */
406 uint8_t IRPyro_open(IRPyro_sensor_device_type* this_device);
407 uint8_t IRPyro_close(IRPyro_sensor_device_type* this_device);
408 uint8_t IRPyro_read(IRPyro_sensor_device_type* this_device);
410 /*----------------------------------------------------------------------------*/
411 #endif
412 
413 /* ********** Copyright (c) 2018 _KEMET, Ltd. **********END OF FILE************/
uint8_t CS_Port
CS (Chip select) port.
uint8_t ST
Sleep_mode_type.
uint8_t LP
Enable low power mode: 1 Enable, 0 Disable.
power_settings_type normal_power
normal power configuration
WUP_reg_type WUP_register
WUP (Wake Up) configuration register.
uint8_t Feedback_transconductance
Charge amp. trans-conductance selection.
IRPyro Power Settings structure definition
uint8_t C_LP
Low pass selection.
IRPyro Channel filter configuration structure
IRPyro device structure definition
uint8_t IRPyro_open(IRPyro_sensor_device_type *this_device)
Initializes the IRPyro device.
uint8_t C_LP
Low pass filter selection.
uint8_t COUNT
Number of frames available.
IRPyro Channel Control Package register structure definition
uint8_t address
I2C address in 7 bit format.
uint8_t CLK_OUT
1 enable internal clock output on Clk pin, 0 disable internal clock output on the Clk pin (only apply...
uint8_t number_of_active_channels
useful for read()
uint8_t UHT
Byte 0 to 3 (Upper and Lower thresholds) are the 8 MSB of channel ADC data (unsigned value)...
uint8_t IRPyro_ioctl(IRPyro_sensor_device_type *this_device, IRPyro_cmd_type *cmd, IRPyro_arg_type arg)
access to IRPyro registers
FIFO_reg_type FIFO_register
FIFO status register.
uint8_t STATUS_CODE
response to read operation: 00 no error, 01 fifo full, 10 i2c master read less, 11 i2c master read mo...
uint8_t S7_S0
Sampling rate (8 bit) :Sampling Rate = 1000/(N+1).
uint8_t S7_S0
sample rate value
uint8_t CH0_CH2
Selected channel coding.
uint8_t High_pass_filter_setting
High pass selection.
uint8_t Feedback_cap
Feedback capacitor selection.
power_settings_type low_power
low power configuration
#define IRPyro_CHANNEL_DATA_VALUES
uint8_t TEMP
0 Normal channel data, 1 temperature data (apply to channel 0 only). When this bit is set...
#define IRPyro_DATA_SIZE
IRPyro Wake Up Package register structure definition
uint8_t status_bit
Status bit : Active (1) / Disable (0)
#define IRPyro_CCP_NUMBER_OF_REGISTERS
IRPyro Analog Front End (AFE) register structure definition
struct IRPyro_arg IRPyro_arg_type
uint8_t IRPyro_read(IRPyro_sensor_device_type *this_device)
Reads a frame of data from the IRPyro.
uint8_t DATA_READY
Data ready.
uint8_t IRPyro_close(IRPyro_sensor_device_type *this_device)
Stops streaming, deallocates memory and disable the IRPyro sensor.
uint8_t SYNC
Sync & Clk Pin option: 0 master, 1 slave.
enum IRPyro_command IRPyro_command_type
Used by the IOCTL function to act a command that modifies AFE and CCP.
uint8_t read_mode
interrupt (0), polled (1) or synchronized sampling (2)
uint8_t channel
selected channel
IRPyro command argument
IRPyro_command
Used by the IOCTL function to act a command that modifies AFE and CCP.
WUP_reg_type WUP_register
WUP (Wake Up) configuration register.
uint8_t DP0_DP2
Reference channel coding DP0-DP2: The Reference channel coding, and CH0-CH2: the selected channel cod...
Public functions of Micro controller specific code to access the IRPyro sensor.
uint8_t WT_Threshold
Byte 4 is the number of samples required to trigger the wake up algorithm. ? UHT and ULT to detect po...
uint8_t channel_saturation_byte
Active frame saturation byte.
uint8_t INT
Interrupt output: 1 Enable, 0 Disable (only apply at normal operation and not in Sleep mode)...
uint8_t HP
Enable high pass filter: 1 Enable, 0 Disable. this is the enable trigger which needs to be set after ...
AFE_reg_type AFE_register
AFE (analog front end) configuration register.
IRPyro FIFO packet structure definition
uint8_t INT_Port
INT (Interrupt / Data Ready ) port.
uint8_t cmd_return_code
command result
uint8_t High_pass_filter_setting
High pass selection.
uint8_t LP
Enable low power mode: 1 Enable, 0 Disable.
struct IRPyro_cmd IRPyro_cmd_type
IRPyro_command_type cmd
command
AFE_reg_type AFE_register
AFE (analog front end) configuration register.