Add nRF24 receive message buffering (#538)

* Add critical section support

Allows defining a code block which is executed as a critical section.
Supports AVR, ESP8266 & SAMD.

* Add receive message buffering

When MY_RF24_IRQ_PIN is defined (and connected), a buffer will be used
to retrieve & store messages received by nRF24 as fast as possible.
This reduces the chance of losing messages due to a busy
microcontroller.
nRF24 SPI rx message transfer is running from interrupt context when
MY_RF24_IRQ_PIN is defined. If this transfer takes too long, serial
characters received will get lost. Therefore serial rx is enabled during
SPI transfer of nRF messages.

Limitations: Only AVR/SAMD & nRF24L01+ combinations can buffer rx
messages.
nRF24L01+ IRQ pin should be connected to AVR.
Tested on W5100- & Serial-gateway.

SAMD has not been tested yet!

* Fix Doxygen warnings

* Fix more Doxygen warnings

core/MyHw.h

@@ -1,4 +1,4 @@
-/**
+/*
  * The MySensors Arduino library handles the wireless radio link and protocol
  * between your home built sensors/actuators and HA controller of choice.
  * The sensors forms a self healing radio network with optional repeaters. Each
@@ -17,6 +17,12 @@
  * version 2 as published by the Free Software Foundation.
  */
 
+ /**
+ * @file MyHw.h
+ *
+ * MySensors hardware abstraction layer
+ */
+ 
 #ifndef MyHw_h
 #define MyHw_h
 
@@ -42,11 +48,67 @@ void hwWriteConfig(int adr, uint8_t value);
 uint8_t hwReadConfig(int adr);
 */
 
+/**
+ * Sleep for a defined time, using minimum power.
+ * @param ms   Time to sleep, in [ms].
+ * @return Nonsense, please ignore.
+ */
 int8_t hwSleep(unsigned long ms);
+
+/**
+ * Sleep for a defined time, using minimum power, or until woken by interrupt.
+ * @param interrupt  Interrupt number, which can wake the mcu from sleep.
+ * @param mode       Interrupt mode, as passed to attachInterrupt.
+ * @param ms         Time to sleep, in [ms].
+ * @return -1 when woken by timer, or interrupt number when woken by interrupt.
+ */
 int8_t hwSleep(uint8_t interrupt, uint8_t mode, unsigned long ms);
+
+/**
+ * Sleep for a defined time, using minimum power, or until woken by one of the interrupts.
+ * @param interrupt1  Interrupt1 number, which can wake the mcu from sleep.
+ * @param mode1       Interrupt1 mode, as passed to attachInterrupt.
+ * @param interrupt2  Interrupt2 number, which can wake the mcu from sleep.
+ * @param mode2       Interrupt2 mode, as passed to attachInterrupt.
+ * @param ms          Time to sleep, in [ms].
+ * @return -1 when woken by timer, or interrupt number when woken by interrupt.
+ */
 int8_t hwSleep(uint8_t interrupt1, uint8_t mode1, uint8_t interrupt2, uint8_t mode2, unsigned long ms);
+
 #ifdef MY_DEBUG
 	void hwDebugPrint(const char *fmt, ... );
 #endif
 
+/** 
+ * @def MY_CRITICAL_SECTION
+ * @brief Creates a block of code that is guaranteed to be executed atomically.
+ * Upon entering the block all interrupts are disabled, and re-enabled upon
+ * exiting the block from any exit path.
+ * A typical example that requires atomic access is a 16 (or more) bit variable
+ * that is shared between the main execution path and an ISR, on an 8-bit
+ * platform (e.g AVR):
+ * @code
+ * volatile uint16_t val = 0;
+ * 
+ * void interrupHandler()
+ * {
+ *   val = ~val;
+ * }
+ * 
+ * void loop()
+ * {
+ *   uint16_t copy_val;
+ *   MY_CRITICAL_SECTION
+ *   {
+ *     copy_val = val;
+ *   }
+ * }
+ * @endcode
+ * All code within the MY_CRITICAL_SECTION block will be protected from being
+ * interrupted during execution.
+ */
+#ifdef DOXYGEN
+	#define MY_CRITICAL_SECTION
+#endif  /* DOXYGEN */
+
 #endif // #ifdef MyHw_h