flight/pios/inc/pios_sensors.h

   1 /**
   2  ******************************************************************************
   3  *
   4  * @file       pios_sensors.h
   5  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2014.
   6  * @brief      PiOS sensors handling
   7  *             --
   8  * @see        The GNU Public License (GPL) Version 3
   9  *
  10  *****************************************************************************/
  11 /*
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 3 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  20  * for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License along
  23  * with this program; if not, write to the Free Software Foundation, Inc.,
  24  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  25  */
  26 #ifndef PIOS_SENSORS_H
  27 #define PIOS_SENSORS_H
  28 #include <pios.h>
  29 #include <utlist.h>
  30 #include <stdint.h>
  31 #include <vectors.h>
  32 // needed for debug APIs.
  33
  34 typedef bool (*PIOS_SENSORS_test_function)(uintptr_t context);
  35 typedef void (*PIOS_SENSORS_reset_function)(uintptr_t context);
  36 typedef bool (*PIOS_SENSORS_poll_function)(uintptr_t context);
  37 typedef void (*PIOS_SENSORS_fetch_function)(void *samples, uint8_t size, uintptr_t context);
  38 /**
  39  * return an array with current scale for the instance.
  40  * Instances with multiples sensors returns several value in the same
  41  * order as they appear in PIOS_SENSORS_TYPE enums.
  42  */
  43 typedef void (*PIOS_SENSORS_get_scale_function)(float *, uint8_t size, uintptr_t context);
  44 typedef QueueHandle_t (*PIOS_SENSORS_get_queue_function)(uintptr_t context);
  45
  46 typedef struct PIOS_SENSORS_Driver {
  47     PIOS_SENSORS_test_function      test; // called at startup to test the sensor
  48     PIOS_SENSORS_poll_function      poll; // called to check whether data are available for polled sensors
  49     PIOS_SENSORS_fetch_function     fetch; // called to fetch data for polled sensors
  50     PIOS_SENSORS_reset_function     reset; // reset sensor. for example if data are not received in the allotted time
  51     PIOS_SENSORS_get_queue_function get_queue; // get the queue reference
  52     PIOS_SENSORS_get_scale_function get_scale; // return scales for the sensors
  53     bool is_polled;
  54 } PIOS_SENSORS_Driver;
  55
  56 typedef enum PIOS_SENSORS_TYPE {
  57     PIOS_SENSORS_TYPE_3AXIS_ACCEL      = 0x01,
  58     PIOS_SENSORS_TYPE_3AXIS_GYRO       = 0x02,
  59     PIOS_SENSORS_TYPE_3AXIS_GYRO_ACCEL = 0x03,
  60     PIOS_SENSORS_TYPE_3AXIS_MAG        = 0x04,
  61     PIOS_SENSORS_TYPE_3AXIS_AUXMAG     = 0x08,
  62     PIOS_SENSORS_TYPE_1AXIS_BARO       = 0x10,
  63 } PIOS_SENSORS_TYPE;
  64
  65 #define PIOS_SENSORS_TYPE_1D (PIOS_SENSORS_TYPE_1AXIS_BARO)
  66 #define PIOS_SENSORS_TYPE_3D (PIOS_SENSORS_TYPE_3AXIS_ACCEL | PIOS_SENSORS_TYPE_3AXIS_GYRO | PIOS_SENSORS_TYPE_3AXIS_MAG | PIOS_SENSORS_TYPE_3AXIS_AUXMAG)
  67
  68 typedef struct PIOS_SENSORS_Instance {
  69     const PIOS_SENSORS_Driver    *driver;
  70     uintptr_t context;
  71     struct PIOS_SENSORS_Instance *next;
  72     uint8_t type;
  73 } PIOS_SENSORS_Instance;
  74
  75 /**
  76  * A 3d Accel sample with temperature
  77  */
  78 typedef struct PIOS_SENSORS_3Axis_SensorsWithTemp {
  79     uint32_t   timestamp;    // PIOS_DELAY_GetRaw() time of sensor read
  80     uint16_t   count;        // number of sensor instances
  81     int16_t    temperature;  // Degrees Celsius * 100
  82     Vector3i16 sample[];
  83 } PIOS_SENSORS_3Axis_SensorsWithTemp;
  84
  85 typedef struct PIOS_SENSORS_1Axis_SensorsWithTemp {
  86     float sample; // sample
  87     float temperature; // Degrees Celsius
  88 } PIOS_SENSORS_1Axis_SensorsWithTemp;
  89
  90 /**
  91  * Register a new sensor instance with sensor subsystem
  92  * @param driver sensor driver
  93  * @param type sensor type @ref PIOS_SENSORS_TYPE
  94  * @param context context to be passed to sensor driver
  95  * @return the new sensor instance
  96  */
  97
  98 PIOS_SENSORS_Instance *PIOS_SENSORS_Register(const PIOS_SENSORS_Driver *driver, PIOS_SENSORS_TYPE type, uintptr_t context);
  99 /**
 100  * return the list of registered sensors.
 101  * @return the first sensor instance in the list.
 102  */
 103 PIOS_SENSORS_Instance *PIOS_SENSORS_GetList();
 104
 105 /**
 106  * Perform sensor test and return true if passed
 107  * @param sensor instance to test
 108  * @return true if test passes
 109  */
 110 static inline bool PIOS_SENSORS_Test(const PIOS_SENSORS_Instance *sensor)
 111 {
 112     PIOS_Assert(sensor);
 113
 114     if (!sensor->driver->test) {
 115         return true;
 116     } else {
 117         return sensor->driver->test(sensor->context);
 118     }
 119 }
 120
 121 /**
 122  * Poll sensor for new values
 123  * @param sensor instance to poll
 124  * @return true if sensor has samples available
 125  */
 126 static inline bool PIOS_SENSORS_Poll(const PIOS_SENSORS_Instance *sensor)
 127 {
 128     PIOS_Assert(sensor);
 129
 130     if (!sensor->driver->poll) {
 131         return true;
 132     } else {
 133         return sensor->driver->poll(sensor->context);
 134     }
 135 }
 136 /**
 137  *
 138  * @param sensor
 139  * @param samples
 140  * @param size
 141  */
 142 static inline void PIOS_SENSOR_Fetch(const PIOS_SENSORS_Instance *sensor, void *samples, uint8_t size)
 143 {
 144     PIOS_Assert(sensor);
 145     sensor->driver->fetch(samples, size, sensor->context);
 146 }
 147
 148 static inline void PIOS_SENSOR_Reset(const PIOS_SENSORS_Instance *sensor)
 149 {
 150     PIOS_Assert(sensor);
 151     sensor->driver->reset(sensor->context);
 152 }
 153
 154 /**
 155  * retrieve the sensor queue
 156  * @param sensor
 157  * @return sensor queue or null if not supported
 158  */
 159 static inline QueueHandle_t PIOS_SENSORS_GetQueue(const PIOS_SENSORS_Instance *sensor)
 160 {
 161     PIOS_Assert(sensor);
 162     if (!sensor->driver->get_queue) {
 163         return NULL;
 164     }
 165     return sensor->driver->get_queue(sensor->context);
 166 }
 167 /**
 168  * Get the sensor scales.
 169  * @param sensor sensor instance
 170  * @param scales float array that will contains scales
 171  * @param size number of floats within the array
 172  */
 173 static inline void PIOS_SENSORS_GetScales(const PIOS_SENSORS_Instance *sensor, float *scales, uint8_t size)
 174 {
 175     PIOS_Assert(sensor);
 176     sensor->driver->get_scale(scales, size, sensor->context);
 177 }
 178 /**
 179  * return head of sensor list
 180  * @return head of sensor list
 181  */
 182 PIOS_SENSORS_Instance *PIOS_SENSORS_GetList();
 183
 184 /**
 185  * Return the first occurrence of specified sensor type
 186  * @param previous_instance last instance found or 0
 187  * @param type type of sensor to find
 188  * @return the first occurence found or NULL
 189  */
 190 PIOS_SENSORS_Instance *PIOS_SENSORS_GetInstanceByType(const PIOS_SENSORS_Instance *previous_instance, PIOS_SENSORS_TYPE type);
 191
 192 #endif /* PIOS_SENSORS_H */