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