src/lib/DEVICE/device.h

   1 #pragma once
   2
   3 #include <stdint.h>
   4
   5 // duration constants which can be returned from start(), event() or timeout()
   6 #define DURATION_IGNORE -2      // when returned from event() does not update the current timeout
   7 #define DURATION_NEVER -1       // timeout() will not be called, only event()
   8 #define DURATION_IMMEDIATELY 0  // timeout() will be called each loop
   9
  10 typedef struct {
  11     /**
  12      * @brief Called at the beginning of setup() so the device can configure IO pins etc.
  13      */
  14     void (*initialize)();
  15
  16     /**
  17      * @brief called at the end of setup() and returns the number of milliseconds when
  18      * to call timeout() function.
  19      */
  20     int (*start)();
  21
  22     /**
  23      * @brief An event was fired in the main code, perform any requierd action that this
  24      * device requires and return new duration for timeout() call.
  25      * If DURATION_IGNORE is returned, then the current timeout value kept and timeout()
  26      * will be called when it expires.
  27      */
  28     int (*event)();
  29
  30     /**
  31      * @brief The current timeout duration has expired so take appropriate action and return
  32      * a new duration, this function should not return DURATION_IGNORE.
  33      */
  34     int (*timeout)();
  35 } device_t;
  36
  37 typedef struct {
  38   /**
  39    * @brief pointer to the device handler functions
  40    */
  41   device_t *device;
  42   /**
  43    * @brief The core on which this device is executing on a multi-core SoC
  44    */
  45   int8_t core; // 0 = alternate core or 1 = loop core
  46 } device_affinity_t;
  47
  48 /**
  49  * @brief register a list of devices to be actioned
  50  *
  51  * @param devices list of devices to register with the device framework
  52  * @param count number of devices in the list
  53  */
  54 void devicesRegister(device_affinity_t *devices, uint8_t count);
  55
  56 /**
  57  * @brief Call initialize() on all the devices registered on their appropriately registerd core.
  58  */
  59 void devicesInit();
  60
  61 /**
  62  * @brief Call start() on all the devices registered on their appropriately registerd core.
  63  */
  64 void devicesStart();
  65
  66 /**
  67  * @brief This function is called in the main loop of the application and only
  68  * processes devices register to the loop-core. Devices registered on alternate core(s)
  69  * are processing in a seperate FreeRTOS task running on the alternate core(s).
  70  *
  71  * @param now current time in millisecods
  72  */
  73 void devicesUpdate(unsigned long now);
  74
  75 /**
  76  * @brief Notify the device framework that an event has occurred and on the next call to
  77  * deviceUpdate() the event() function of the devices should be called.
  78  */
  79 void devicesTriggerEvent();
  80
  81 /**
  82  * @brief Stop all the devices.
  83  * This destroys the FreeRTOS task runnin on the alternate core(s).
  84  */
  85 void devicesStop();