Hal/Hal.h

   1 /**
   2  * Hal.h -- HAL Interface Definitions
   3  *
   4  * This example HAL is intentionally simple.  The implementation is limited to:
   5  *
   6  * BUTTON -- a single button that when pressed will cause an interrupt.
   7  * DEBUG -- two debug GPIOs that are available as outputs from the EAP and under user control.
   8  * DELAY -- a delay routine that can delay by n milliseconds.
   9  * INIT -- set the hardware up to its initial state
  10  * LED -- a user LED that is available for application control.
  11  * TICK -- a timer that can be set to interrupt every n milliseconds
  12  * IDLE LOOP -- an event driven idle loop for controlling the EAP
  13  *
  14  * For information on Hal implementations for specific target hardware platforms,
  15  * visit the http://wiki.em-hub.com/display/ED.
  16  *
  17  **/
  18
  19 #ifndef Hal__H
  20 #define Hal__H
  21
  22 #include <stdint.h>
  23 #include <stdbool.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 typedef void (*Hal_Handler)(void);
  30
  31 /**
  32  * --------- Hal_buttonEnable ---------
  33  *
  34  * Enable the button interrupt and connect it to the user's buttonHandler
  35  *
  36  * When the button is pressed, it will cause an interrupt that will cause BUTTON event
  37  * to be entered into the event list.  Once dispatched by the idle loop, the user's
  38  * buttonHandler will be called.
  39  *
  40  * Inputs:
  41  *   buttonHandler - pointer to the user's handler to be called after interrupt
  42  *
  43  * Returns:
  44  *   None
  45  *
  46  * Side effects:
  47  *   BUTTON interrupt enabled
  48  *
  49  **/
  50 extern void Hal_buttonEnable(Hal_Handler handler);
  51 /**
  52  * --------- Hal_connected ---------
  53  *
  54  * Called whenever the MCM peripheral connects to a central.
  55  *
  56  * Could do other things associated with connection to the central.
  57  *
  58  * Inputs:
  59  *   None
  60  *
  61  * Returns:
  62  *   None
  63  *
  64  **/
  65 extern void Hal_connected(void);
  66 /**
  67  * --------- Hal_debugOff ---------
  68  *
  69  * Turns the selected DEBUG line off.
  70  *
  71  * The two DEBUG lines are output GPIOs that are available to the user for
  72  * debug purposes.
  73  *
  74  * Inputs:
  75  *   line - the index value of the debug line to turn off
  76  *
  77  * Returns:
  78  *   None
  79  *
  80  * Side Effects:
  81  *   DEBUG line off.
  82  *
  83  **/
  84 extern void Hal_debugOff(uint8_t line);
  85 /**
  86  * --------- Hal_debugOn ---------
  87  *
  88  * Turns the selected DEBUG line on.
  89  *
  90  * The two DEBUG lines are output GPIOs that are available to the user for
  91  * debug purposes.
  92  *
  93  * Inputs:
  94  *   line - the index value of the debug line to turn on
  95  *
  96  * Returns:
  97  *   None
  98  *
  99  * Side Effects:
 100  *   DEBUG line on.
 101  *
 102  **/
 103 extern void Hal_debugOn(uint8_t line);
 104 /**
 105  * --------- Hal_debugPulse ---------
 106  *
 107  * Emits a pulse on the selected DEBUG line.
 108  *
 109  * The two DEBUG lines are output GPIOs that are available to the user for
 110  * debug purposes.
 111  *
 112  * Inputs:
 113  *   line - the index value of the debug line to emit a pulse
 114  *
 115  * Returns:
 116  *   None
 117  *
 118  * Side Effects:
 119  *   DEBUG line turns on then off.
 120  *
 121  **/
 122 extern void Hal_debugPulse(uint8_t line);
 123 /**
 124  * --------- Hal_delay ---------
 125  *
 126  * Delays for the specified number of milliseconds.
 127  *
 128  * In this example, delay is done with CPU spinning for simplicity's sake.
 129  * This could easily use a timer interrupt for more power savings.
 130  *
 131  * Inputs:
 132  *   msecs - the number of milliseconds to delay
 133  *
 134  * Returns:
 135  *   None
 136  *
 137  * Side Effects:
 138  *   None
 139  *
 140  **/
 141 extern void Hal_delay(uint16_t msecs);
 142 /**
 143  * --------- Hal_disconnected ---------
 144  *
 145  * Called whenever the MCM peripheral disconnects from a central.
 146  *
 147  * Could do other things associated with connection to the central.
 148  *
 149  * Inputs:
 150  *   None
 151  *
 152  * Returns:
 153  *   None
 154  *
 155  **/
 156 extern void Hal_disconnected(void);
 157 /**
 158  * --------- Hal_idleLoop ---------
 159  *
 160  * The idle loop that controls EAP operations.
 161  *
 162  * The hal implements an event driven "idle loop" scheduler.
 163  * When there are no events pending, the idle loop sleeps.
 164  * When an event happens, the idle loop wakes up, and dispatches
 165  * to the appropriate event handler.
 166  *
 167  * The dispatching is done through a handlerTab that has one entry for each type of event.
 168  * Each handlerTab entry should be a handler of type hal_handler *.
 169  * There are currently three types of events, i.e. entries in the handlerTab:
 170  *   BUTTON_HANDLER_ID:    handler to call upon a button press
 171  *   TICK_HANDLER_ID:      handler to call upon a timer interrupt
 172  *   DISPATCH_HANDLER_ID:  handler to call upon a received message from the MCM
 173  *
 174  * Inputs:
 175  *   None
 176  *
 177  * Returns:
 178  *   None
 179  *
 180  * Side Effects:
 181  *   dispatches events as they come in
 182  *
 183  **/
 184 extern void Hal_idleLoop(void);
 185 /**
 186  * --------- Hal_init ---------
 187  *
 188  * Initialize the hardware
 189  *
 190  * Initializes the EAP and MCM into their reset state.  Should be called first.
 191  * Sets up the clock, ports, watchdog timer, etc.
 192  *
 193  *
 194  * Inputs:
 195  *   None
 196  *
 197  * Returns:
 198  *   None
 199  *
 200  * Side Effects:
 201  *   EAP and MCM in their initial state.
 202  *
 203  **/
 204 extern void Hal_init(void);
 205 /**
 206  * --------- Hal_ledOff ---------
 207  *
 208  * Turns the user LED off.
 209  *
 210  * Inputs:
 211  *   None
 212  *
 213  * Returns:
 214  *   None
 215  *
 216  * Side Effects:
 217  *   User LED off.
 218  *
 219  **/
 220 extern void Hal_greenLedOff(void);
 221 extern void Hal_redLedOff(void);
 222 /**
 223  * --------- Hal_ledOn ---------
 224  *
 225  * Turns the user LED on.
 226  *
 227  * Inputs:
 228  *   None
 229  *
 230  * Returns:
 231  *   None
 232  *
 233  * Side Effects:
 234  *   User LED on.
 235  *
 236  **/
 237 extern void Hal_greenLedOn(void);
 238 extern void Hal_redLedOn(void);
 239 /**
 240  * --------- Hal_ledRead ---------
 241  *
 242  * Returns the user LED state.
 243  *
 244  * Inputs:
 245  *   None
 246  *
 247  * Returns:
 248  *   Bool -  (true = user LED is on, false = user LED is off)
 249  *
 250  * Side Effects:
 251  *   None
 252  *
 253  **/
 254 extern bool Hal_greenLedRead(void);
 255 extern bool Hal_redLedRead(void);
 256 /**
 257  * --------- Hal_ledToggle ---------
 258  *
 259  * Toggles the user LED.
 260  *
 261  * Inputs:
 262  *   None
 263  *
 264  * Returns:
 265  *   None
 266  *
 267  * Side Effects:
 268  *   User LED toggles state.
 269  *
 270  **/
 271 extern void Hal_greenLedToggle(void);
 272 extern void Hal_redLedToggle(void);
 273 /**
 274  * --------- Hal_tickStart ---------
 275  *
 276  * Sets up the timer to interrupt every msecs milliseconds and the user's tickHandler
 277  * that will be called upon interrupt.
 278  *
 279  * Enable a timer interrupt every msecs ms.  The interrupt will cause a TICK event
 280  * to be entered into the event list.  Once dispatched by the idle loop, the user's
 281  * tickHandler will be called.
 282  *
 283  * Inputs:
 284  *   msecs - the number of milliseconds between tick interrupts
 285  *   tickHandler - the address of the user's tick handler that will be called
 286  *
 287  * Returns:
 288  *   None
 289  *
 290  * Side Effects:
 291  *   tickhandler called by the idle loop
 292  *
 293  **/
 294 extern void Hal_tickStart(uint16_t msecs, Hal_Handler Handler);
 295 extern void Hal_tickStop(void);
 296
 297 #ifdef __cplusplus
 298 }
 299 #endif
 300
 301 #endif /* Hal__H */