Transport doc

core/MySensorsCore.cpp

@@ -753,6 +753,10 @@ int8_t smartSleep(const uint8_t interrupt1, const uint8_t mode1, const uint8_t i
 	return _sleep(sleepingMS, true, interrupt1, mode1, interrupt2, mode2);
 }
 
+uint32_t getSleepRemaining(void)
+{
+	return hwGetSleepRemaining();
+}
 
 
 void _nodeLock(const char *str)

core/MySensorsCore.h

@@ -364,6 +364,13 @@ int8_t _sleep(const uint32_t sleepingMS, const bool smartSleep = false,
               const uint8_t interrupt1 = INTERRUPT_NOT_DEFINED, const uint8_t mode1 = MODE_NOT_DEFINED,
               const uint8_t interrupt2 = INTERRUPT_NOT_DEFINED, const uint8_t mode2 = MODE_NOT_DEFINED);
 
+/**
+ * Return the sleep time remaining after waking up from sleep.
+ * Depending on the CPU architecture, the remaining time can be seconds off (e.g. upto roughly 8 seconds on AVR).
+ * @return Time remaining, in ms, when wake from sleep by an interrupt, 0 by timer (@ref MY_WAKE_UP_BY_TIMER), undefined otherwise.
+*/
+uint32_t getSleepRemaining(void);
+
 
 // **** private functions ********
 

core/MyTransport.h

@@ -155,6 +155,46 @@
 * - <b>ft</b>=failed uplink transmission counter
 * - <b>st</b>=send status, OK=success, NACK=no radio ACK received
 *
+* @startuml
+* state top as "Transport" {
+* state Init
+* state Failure
+* state Ready
+* state Parent
+* state ID
+* state Uplink
+* }
+*
+* [*] --> Init
+* Init : entry / Read config from eeprom
+* Init --> Failure : [! transportInit()\n|| ID == 0\n|| ID == 255 ]
+* Init --> Ready : [MY_GATEWAY_FEATURE]
+* Init --> Parent : [else]
+*
+* Parent : entry / Broadcast Find Parent
+* Parent --> ID : [MY_PARENT_NODE_IS_STATIC\n|| MY_PASSIVE_NODE\n|| Parent found]
+* Parent --> Parent : [timeout\n&& retries left]
+* Parent --> Failure : [timeout\n&& no retries left]
+*
+* ID : entry / Request Node ID
+* ID --> Uplink : [ID valid]
+* ID --> ID : [timeout\n&& retries left]
+* ID --> Failure : [timeout\n&& no retries left]
+*
+* Uplink : entry / Check uplink (PING)
+* Uplink --> Uplink : [timeout\n&& retries left]
+* Uplink --> Parent : [timeout\n&& no retries left]
+* Uplink --> Ready : [MY_TRANSPORT_UPLINK_CHECK_DISABLED\n|| Uplink ok (PONG)]
+*
+* Ready : entry / Transport ready callback
+* Ready : MY_GATEWAY_FEATURE && Network discovery required / Send discovery
+* Ready --> Parent : [!MY_PARENT_NODE_IS_STATIC\n&& Uplink failure overflow]
+*
+* Failure : entry / Disable transport
+* Failure --> Init : [timeout]
+* top --> Failure : [MY_TRANSPORT_SANITY_CHECK\n&& !transportSanityCheck]
+* @enduml
+*
 * @brief API declaration for MyTransport
 *
 */

hal/architecture/AVR/MyHwAVR.cpp

@@ -39,6 +39,8 @@ volatile uint8_t _wakeUp1Interrupt  =
 volatile uint8_t _wakeUp2Interrupt  =
     INVALID_INTERRUPT_NUM;    // Interrupt number for wakeUp2-callback.
 
+static uint32_t sleepRemainingMs = 0ul;
+
 void wakeUp1(void)
 {
 	// Disable sleep. When an interrupt occurs after attachInterrupt,
@@ -120,7 +122,7 @@ void hwPowerDown(const uint8_t wdto)
 	ADCSRA |= (1 << ADEN);
 }
 
-void hwInternalSleep(uint32_t ms)
+uint32_t hwInternalSleep(uint32_t ms)
 {
 	// Sleeping with watchdog only supports multiples of 16ms.
 	// Round up to next multiple of 16ms, to assure we sleep at least the
@@ -137,16 +139,21 @@ void hwInternalSleep(uint32_t ms)
 			}
 		}
 	}
+	if (interruptWakeUp()) {
+		return ms;
+	}
+	return 0ul;
 }
 
 int8_t hwSleep(uint32_t ms)
 {
 	// Return what woke the mcu.
 	// Default: no interrupt triggered, timer wake up
 	int8_t ret = MY_WAKE_UP_BY_TIMER;
+	sleepRemainingMs = 0ul;
 	if (ms > 0u) {
 		// sleep for defined time
-		hwInternalSleep(ms);
+		sleepRemainingMs = hwInternalSleep(ms);
 	} else {
 		// sleep until ext interrupt triggered
 		hwPowerDown(WDTO_SLEEP_FOREVER);
@@ -192,9 +199,10 @@ int8_t hwSleep(const uint8_t interrupt1, const uint8_t mode1, const uint8_t inte
 		attachInterrupt(interrupt2, wakeUp2, mode2);
 	}
 
+	sleepRemainingMs = 0ul;
 	if (ms > 0u) {
 		// sleep for defined time
-		hwInternalSleep(ms);
+		sleepRemainingMs = hwInternalSleep(ms);
 	} else {
 		// sleep until ext interrupt triggered
 		hwPowerDown(WDTO_SLEEP_FOREVER);
@@ -220,6 +228,11 @@ int8_t hwSleep(const uint8_t interrupt1, const uint8_t mode1, const uint8_t inte
 	return ret;
 }
 
+uint32_t hwGetSleepRemaining(void)
+{
+	return sleepRemainingMs;
+}
+
 inline void hwRandomNumberInit(void)
 {
 	// This function initializes the random number generator with a seed

hal/architecture/AVR/MyHwAVR.h

@@ -77,7 +77,7 @@ bool hwInit(void);
 #define hwWriteConfigBlock(__buf, __pos, __length) eeprom_update_block((const void *)__buf, (void *)__pos, (uint32_t)__length)
 
 inline void hwRandomNumberInit(void);
-void hwInternalSleep(uint32_t ms);
+uint32_t hwInternalSleep(uint32_t ms);
 
 #if defined(MY_SOFTSPI)
 SoftSPI<MY_SOFT_SPI_MISO_PIN, MY_SOFT_SPI_MOSI_PIN, MY_SOFT_SPI_SCK_PIN, 0> hwSPI; //!< hwSPI

hal/architecture/ESP32/MyHwESP32.h

@@ -74,6 +74,7 @@
 #define hwMillis() millis()
 #define hwMicros() micros()
 #define hwRandomNumberInit() randomSeed(esp_random())
+#define hwGetSleepRemaining() (0ul)
 
 bool hwInit(void);
 void hwReadConfigBlock(void *buf, void *addr, size_t length);

hal/architecture/ESP8266/MyHwESP8266.h

@@ -49,6 +49,7 @@
 #define hwMillis() millis()
 // The use of randomSeed switch to pseudo random number. Keep hwRandomNumberInit empty
 #define hwRandomNumberInit()
+#define hwGetSleepRemaining() (0ul)
 
 bool hwInit(void);
 void hwReadConfigBlock(void *buf, void *addr, size_t length);

hal/architecture/Linux/MyHwLinuxGeneric.h

@@ -54,6 +54,7 @@ StdInOutStream Serial = StdInOutStream();
 // Define these as macros (do nothing)
 #define hwWatchdogReset()
 #define hwReboot()
+#define hwGetSleepRemaining() (0ul)
 
 inline void hwDigitalWrite(uint8_t, uint8_t);
 inline int hwDigitalRead(uint8_t);

hal/architecture/NRF5/MyHwNRF5.h

@@ -114,6 +114,8 @@
 #define hwDigitalRead(__pin) digitalRead(__pin)
 #define hwPinMode(__pin, __value) nrf5_pinMode(__pin, __value)
 #define hwMillis() millis()
+// TODO: Can nrf5 determine time slept?
+#define hwGetSleepRemaining() (0ul)
 
 bool hwInit(void);
 void hwWatchdogReset(void);

hal/architecture/SAMD/MyHwSAMD.h

@@ -63,6 +63,7 @@ extEEPROM eep(MY_EXT_EEPROM_SIZE, 1, MY_EXT_EEPROM_PAGE_SIZE,
 #define hwPinMode(__pin, __value) pinMode(__pin, __value)
 #define hwMillis() millis()
 #define hwRandomNumberInit() randomSeed(analogRead(MY_SIGNING_SOFT_RANDOMSEED_PIN))
+#define hwGetSleepRemaining() (0ul)
 
 bool hwInit(void);
 void hwWatchdogReset(void);

hal/architecture/STM32F1/MyHwSTM32F1.h

@@ -69,6 +69,7 @@
 #define hwWatchdogReset() iwdg_feed()
 #define hwReboot() nvic_sys_reset()
 #define hwMillis() millis()
+#define hwGetSleepRemaining() (0ul)
 
 extern void serialEventRun(void) __attribute__((weak));
 bool hwInit(void);

hal/architecture/Teensy3/MyHwTeensy3.h

@@ -62,6 +62,7 @@
 #define hwDigitalRead(__pin) digitalReadFast(__pin)
 #define hwPinMode(__pin, __value) pinMode(__pin, __value)
 #define hwMillis() millis()
+#define hwGetSleepRemaining() (0ul)
 
 void hwRandomNumberInit(void);
 bool hwInit(void);