flight/uavobjects/inc/uavobjectmanager.h

   1 /**
   2  ******************************************************************************
   3  * @addtogroup UAVObjects OpenPilot UAVObjects
   4  * @{
   5  * @addtogroup UAV Object Manager
   6  * @brief The core UAV Objects functions, most of which are wrappered by
   7  * autogenerated defines
   8  * @{
   9  *
  10  * @file       uavobjectmanager.h
  11  * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
  12  * @brief      Include files of the uavobjectlist library
  13  * @see        The GNU Public License (GPL) Version 3
  14  *
  15  *****************************************************************************/
  16 /*
  17  * This program is free software; you can redistribute it and/or modify
  18  * it under the terms of the GNU General Public License as published by
  19  * the Free Software Foundation; either version 3 of the License, or
  20  * (at your option) any later version.
  21  *
  22  * This program is distributed in the hope that it will be useful, but
  23  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  24  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  25  * for more details.
  26  *
  27  * You should have received a copy of the GNU General Public License along
  28  * with this program; if not, write to the Free Software Foundation, Inc.,
  29  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  30  */
  31
  32 #ifndef UAVOBJECTMANAGER_H
  33 #define UAVOBJECTMANAGER_H
  34
  35 #define UAVOBJ_ALL_INSTANCES                   0xFFFF
  36 #define UAVOBJ_MAX_INSTANCES                   1000
  37
  38 /*
  39  * Shifts and masks used to read/write metadata flags.
  40  */
  41 #define UAVOBJ_ACCESS_SHIFT                    0
  42 #define UAVOBJ_GCS_ACCESS_SHIFT                1
  43 #define UAVOBJ_TELEMETRY_ACKED_SHIFT           2
  44 #define UAVOBJ_GCS_TELEMETRY_ACKED_SHIFT       3
  45 #define UAVOBJ_TELEMETRY_UPDATE_MODE_SHIFT     4
  46 #define UAVOBJ_GCS_TELEMETRY_UPDATE_MODE_SHIFT 6
  47 #define UAVOBJ_LOGGING_UPDATE_MODE_SHIFT       8
  48 #define UAVOBJ_UPDATE_MODE_MASK                0x3
  49
  50 typedef void *UAVObjHandle;
  51
  52 #define MetaObjectId(id) ((id) + 1)
  53
  54 /**
  55  * helper macro to access multi-element fields as array
  56  */
  57 #define UAVObjectFieldToArray(type, var) \
  58     (*({ type *const dummy = &(var); \
  59          &(((type##Array *)dummy)->array); } \
  60        ))
  61
  62 // we have limited trust in our compiler
  63 // make sure this macro actually works on all platforms
  64
  65 typedef struct __attribute__((__packed__)) {
  66     uint16_t element1;
  67     uint16_t element2;
  68     uint16_t element3;
  69 }
  70 __DummyUAVObjectFieldData;
  71
  72 typedef struct __attribute__((__packed__)) {
  73     uint16_t array[3];
  74 }
  75 __DummyUAVObjectFieldDataArray;
  76
  77 #define __DummyTA(var) UAVObjectFieldToArray(__DummyUAVObjectFieldData, var)
  78
  79 __attribute__((unused)) static void __DummyTAtest(void)
  80 {
  81     __DummyUAVObjectFieldData t;
  82
  83     PIOS_STATIC_ASSERT(sizeof(t) == sizeof(__DummyTA(t)));
  84     PIOS_STATIC_ASSERT(sizeof(t.element1) == sizeof(__DummyTA(t)[0]));
  85     PIOS_STATIC_ASSERT((void *)&t == (void *)&__DummyTA(t));
  86     PIOS_STATIC_ASSERT((void *)&t.element1 == (void *)&__DummyTA(t)[0]);
  87     PIOS_STATIC_ASSERT((void *)&t.element2 == (void *)&__DummyTA(t)[1]);
  88     PIOS_STATIC_ASSERT((void *)&t.element3 == (void *)&__DummyTA(t)[2]);
  89 }
  90
  91 /**
  92  * Object update mode, used by multiple modules (e.g. telemetry and logger)
  93  */
  94 typedef enum {
  95     UPDATEMODE_MANUAL    = 0, /** Manually update object, by calling the updated() function */
  96     UPDATEMODE_PERIODIC  = 1, /** Automatically update object at periodic intervals */
  97     UPDATEMODE_ONCHANGE  = 2, /** Only update object when its data changes */
  98     UPDATEMODE_THROTTLED = 3 /** Object is updated on change, but not more often than the interval time */
  99 } UAVObjUpdateMode;
 100
 101 /**
 102  * Object metadata, each object has a meta object that holds its metadata. The metadata define
 103  * properties for each object and can be used by multiple modules (e.g. telemetry and logger)
 104  *
 105  * The object metadata flags are packed into a single 16 bit integer.
 106  * The bits in the flag field are defined as:
 107  *
 108  *   Bit(s)  Name                     Meaning
 109  *   ------  ----                     -------
 110  *      0    access                   Defines the access level for the local transactions (readonly=1 and readwrite=0)
 111  *      1    gcsAccess                Defines the access level for the local GCS transactions (readonly=1 and readwrite=0), not used in the flight s/w
 112  *      2    telemetryAcked           Defines if an ack is required for the transactions of this object (1:acked, 0:not acked)
 113  *      3    gcsTelemetryAcked        Defines if an ack is required for the transactions of this object (1:acked, 0:not acked)
 114  *    4-5    telemetryUpdateMode      Update mode used by the telemetry module (UAVObjUpdateMode)
 115  *    6-7    gcsTelemetryUpdateMode   Update mode used by the GCS (UAVObjUpdateMode)
 116  *    8-9    loggingUpdateMode        Update mode used by the logging module (UAVObjUpdateMode)
 117  */
 118 typedef struct {
 119     uint16_t flags; /** Defines flags for update and logging modes and whether an update should be ACK'd (bits defined above) */
 120     uint16_t telemetryUpdatePeriod; /** Update period used by the telemetry module (only if telemetry mode is PERIODIC) */
 121     uint16_t gcsTelemetryUpdatePeriod; /** Update period used by the GCS (only if telemetry mode is PERIODIC) */
 122     uint16_t loggingUpdatePeriod; /** Update period used by the logging module (only if logging mode is PERIODIC) */
 123 } __attribute__((packed)) UAVObjMetadata;
 124
 125 /**
 126  * Event types generated by the objects.
 127  */
 128 typedef enum {
 129     EV_NONE     = 0x00, /** No event */
 130     EV_UNPACKED = 0x01, /** Object data updated by unpacking */
 131     EV_UPDATED  = 0x02, /** Object data updated by changing the data structure */
 132     EV_UPDATED_MANUAL   = 0x04, /** Object update event manually generated */
 133     EV_UPDATED_PERIODIC = 0x08, /** Object update from periodic event */
 134     EV_LOGGING_MANUAL   = 0x10, /** Object update event manually generated */
 135     EV_LOGGING_PERIODIC = 0x20, /** Object update from periodic event */
 136     EV_UPDATE_REQ = 0x40 /** Request to update object data */
 137 } UAVObjEventType;
 138
 139 /**
 140  * Helper macros for event masks
 141  */
 142 #define EV_MASK_ALL         0
 143 #define EV_MASK_ALL_UPDATES (EV_UNPACKED | EV_UPDATED | EV_UPDATED_MANUAL | EV_UPDATED_PERIODIC | EV_LOGGING_MANUAL | EV_LOGGING_PERIODIC)
 144
 145 /**
 146  * Access types
 147  */
 148 typedef enum {
 149     ACCESS_READWRITE = 0,
 150     ACCESS_READONLY  = 1
 151 } UAVObjAccessType;
 152
 153 /**
 154  * Event message, this structure is sent in the event queue each time an event is generated
 155  */
 156 typedef struct {
 157     UAVObjHandle    obj;
 158     uint16_t        instId;
 159     UAVObjEventType event;
 160     bool lowPriority; /* if true prevents raising warnings */
 161 } UAVObjEvent;
 162
 163 /**
 164  * Event callback, this function is called when an event is invoked. The function
 165  * will be executed in the event task. The ev parameter should be copied if needed
 166  * after the function returns.
 167  */
 168 typedef void (*UAVObjEventCallback)(UAVObjEvent *ev);
 169
 170 /**
 171  * Callback used to initialize the object fields to their default values.
 172  */
 173 typedef void (*UAVObjInitializeCallback)(UAVObjHandle obj_handle, uint16_t instId);
 174
 175 /**
 176  * Event manager statistics
 177  */
 178 typedef struct {
 179     uint32_t eventQueueErrors;
 180     uint32_t eventCallbackErrors;
 181     uint32_t lastCallbackErrorID;
 182     uint32_t lastQueueErrorID;
 183 } UAVObjStats;
 184
 185 typedef struct {
 186     uint32_t id;
 187     UAVObjInitializeCallback init_callback;
 188     uint16_t instance_size;
 189 } __attribute__((packed, aligned(4))) UAVObjType;
 190
 191 int32_t UAVObjInitialize();
 192 void UAVObjGetStats(UAVObjStats *statsOut);
 193 void UAVObjClearStats();
 194 UAVObjHandle UAVObjRegister(const UAVObjType *type, bool isSingleInstance, bool isSettings, bool isPriority);
 195 UAVObjHandle UAVObjGetByID(uint32_t id);
 196 uint32_t UAVObjGetID(UAVObjHandle obj);
 197 uint32_t UAVObjGetNumBytes(UAVObjHandle obj);
 198 uint16_t UAVObjGetNumInstances(UAVObjHandle obj);
 199 UAVObjHandle UAVObjGetLinkedObj(UAVObjHandle obj);
 200 uint16_t UAVObjCreateInstance(UAVObjHandle obj_handle);
 201 bool UAVObjIsSingleInstance(UAVObjHandle obj);
 202 bool UAVObjIsMetaobject(UAVObjHandle obj);
 203 bool UAVObjIsSettings(UAVObjHandle obj);
 204 bool UAVObjIsPriority(UAVObjHandle obj);
 205 int32_t UAVObjUnpack(UAVObjHandle obj_handle, uint16_t instId, const uint8_t *dataIn, bool create);
 206 int32_t UAVObjPack(UAVObjHandle obj_handle, uint16_t instId, uint8_t *dataOut);
 207 uint8_t UAVObjUpdateCRC(UAVObjHandle obj_handle, uint16_t instId, uint8_t crc);
 208 int32_t UAVObjSave(UAVObjHandle obj_handle, uint16_t instId);
 209 int32_t UAVObjLoad(UAVObjHandle obj_handle, uint16_t instId);
 210 int32_t UAVObjDelete(UAVObjHandle obj_handle, uint16_t instId);
 211 int32_t UAVObjSaveSettings();
 212 int32_t UAVObjLoadSettings();
 213 int32_t UAVObjDeleteSettings();
 214 int32_t UAVObjSaveMetaobjects();
 215 int32_t UAVObjLoadMetaobjects();
 216 int32_t UAVObjDeleteMetaobjects();
 217 int32_t UAVObjSetDefaults(UAVObjHandle obj_handle);
 218 int32_t UAVObjSetData(UAVObjHandle obj_handle, const void *dataIn);
 219 int32_t UAVObjSetDataField(UAVObjHandle obj_handle, const void *dataIn, uint32_t offset, uint32_t size);
 220 int32_t UAVObjGetData(UAVObjHandle obj_handle, void *dataOut);
 221 int32_t UAVObjGetDataField(UAVObjHandle obj_handle, void *dataOut, uint32_t offset, uint32_t size);
 222 int32_t UAVObjSetInstanceDefaults(UAVObjHandle obj_handle, uint16_t instId);
 223 int32_t UAVObjSetInstanceData(UAVObjHandle obj_handle, uint16_t instId, const void *dataIn);
 224 int32_t UAVObjSetInstanceDataField(UAVObjHandle obj_handle, uint16_t instId, const void *dataIn, uint32_t offset, uint32_t size);
 225 int32_t UAVObjGetInstanceData(UAVObjHandle obj_handle, uint16_t instId, void *dataOut);
 226 int32_t UAVObjGetInstanceDataField(UAVObjHandle obj_handle, uint16_t instId, void *dataOut, uint32_t offset, uint32_t size);
 227 int32_t UAVObjSetMetadata(UAVObjHandle obj_handle, const UAVObjMetadata *dataIn);
 228 int32_t UAVObjGetMetadata(UAVObjHandle obj_handle, UAVObjMetadata *dataOut);
 229 uint8_t UAVObjGetMetadataAccess(const UAVObjMetadata *dataOut);
 230 UAVObjAccessType UAVObjGetAccess(const UAVObjMetadata *dataOut);
 231 void UAVObjSetAccess(UAVObjMetadata *dataOut, UAVObjAccessType mode);
 232 UAVObjAccessType UAVObjGetGcsAccess(const UAVObjMetadata *dataOut);
 233 void UAVObjSetGcsAccess(UAVObjMetadata *dataOut, UAVObjAccessType mode);
 234 uint8_t UAVObjGetTelemetryAcked(const UAVObjMetadata *dataOut);
 235 void UAVObjSetTelemetryAcked(UAVObjMetadata *dataOut, uint8_t val);
 236 uint8_t UAVObjGetGcsTelemetryAcked(const UAVObjMetadata *dataOut);
 237 void UAVObjSetGcsTelemetryAcked(UAVObjMetadata *dataOut, uint8_t val);
 238 UAVObjUpdateMode UAVObjGetTelemetryUpdateMode(const UAVObjMetadata *dataOut);
 239 void UAVObjSetTelemetryUpdateMode(UAVObjMetadata *dataOut, UAVObjUpdateMode val);
 240 UAVObjUpdateMode UAVObjGetGcsTelemetryUpdateMode(const UAVObjMetadata *dataOut);
 241 void UAVObjSetTelemetryGcsUpdateMode(UAVObjMetadata *dataOut, UAVObjUpdateMode val);
 242 UAVObjUpdateMode UAVObjGetLoggingUpdateMode(const UAVObjMetadata *dataOut);
 243 void UAVObjSetLoggingUpdateMode(UAVObjMetadata *dataOut, UAVObjUpdateMode val);
 244 int8_t UAVObjReadOnly(UAVObjHandle obj);
 245 int32_t UAVObjConnectQueue(UAVObjHandle obj_handle, xQueueHandle queue, uint8_t eventMask);
 246 int32_t UAVObjDisconnectQueue(UAVObjHandle obj_handle, xQueueHandle queue);
 247 int32_t UAVObjConnectCallback(UAVObjHandle obj_handle, UAVObjEventCallback cb, uint8_t eventMask, bool fast);
 248 int32_t UAVObjDisconnectCallback(UAVObjHandle obj_handle, UAVObjEventCallback cb);
 249 void UAVObjRequestUpdate(UAVObjHandle obj);
 250 void UAVObjRequestInstanceUpdate(UAVObjHandle obj_handle, uint16_t instId);
 251 void UAVObjUpdated(UAVObjHandle obj);
 252 void UAVObjInstanceUpdated(UAVObjHandle obj_handle, uint16_t instId);
 253 void UAVObjLogging(UAVObjHandle obj);
 254 void UAVObjInstanceLogging(UAVObjHandle obj_handle, uint16_t instId);
 255 void UAVObjIterate(void (*iterator)(UAVObjHandle obj));
 256 void UAVObjInstanceWriteToLog(UAVObjHandle obj_handle, uint16_t instId);
 257
 258 #endif // UAVOBJECTMANAGER_H
 259
 260 /**
 261  * @}
 262  * @}
 263  */