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