Add uart.txflush() (#3390)

components/base_nodemcu/uart.c

@@ -271,6 +271,14 @@ static int uart_wakeup (lua_State *L)
   return 0;
 }
 
+static int luart_tx_flush (lua_State *L)
+{
+  uint32_t id = luaL_checkinteger(L, 1);
+  MOD_CHECK_ID(uart, id);
+  uart_tx_flush(id);
+  return 0;
+}
+
 // Module function map
 LROT_BEGIN(uart)
   LROT_FUNCENTRY( setup,                      uart_setup )
@@ -281,6 +289,7 @@ LROT_BEGIN(uart)
   LROT_FUNCENTRY( setmode,                    uart_setmode )
   LROT_FUNCENTRY( getconfig,                  uart_getconfig )
   LROT_FUNCENTRY( wakeup,                     uart_wakeup )
+  LROT_FUNCENTRY( txflush,                    luart_tx_flush )
   LROT_NUMENTRY( STOPBITS_1,                  PLATFORM_UART_STOPBITS_1 )
   LROT_NUMENTRY( STOPBITS_1_5,                PLATFORM_UART_STOPBITS_1_5 )
   LROT_NUMENTRY( STOPBITS_2,                  PLATFORM_UART_STOPBITS_2 )

docs/modules/node.md

@@ -395,7 +395,7 @@ node.setcpufreq(node.CPU80MHZ)
 
 Enters light sleep mode, which saves power without losing state. The state of the CPU and peripherals is preserved during light sleep and is resumed once the processor wakes up. When the processor wakes back up depends on the supplied `options`. Wake up from light sleep can be triggered by a time period, or when a GPIO (or GPIOs) change level, when a touchpad event occurs, when data is received on a UART, or by the ULP (ultra low power processor, generally not used by NodeMCU). If multiple different wakeup sources are specified, the processor will wake when any of them occur. The return value of the function can be used to determine which source caused the wakeup. The function does not return until a wakeup occurs (and therefore may not return at all if a wakeup trigger never happens).
 
-UART buffers are not flushed on entering light sleep, rather they are suspended and resumed on wakeup, meaning that some data written before entering light sleep may not be output over the UART until after wakeup.
+UART buffers are not flushed on entering light sleep, rather they are suspended and resumed on wakeup, meaning that some data written before entering light sleep may not be output over the UART until after wakeup. Call [`uart.txflush()`](uart.md#uarttxflush) immediately before the `node.sleep()` call to ensure any pending data is output prior to the sleep.
 
 Timers created with `tmr` will not fire during light sleep, and the time spent sleeping is not factored in to their remaining time after wakeup. They are paused, and resumed automatically after wakeup. For example, if a timer has 2 seconds remaining when light sleep starts, it will still have 2 seconds remaining after wakeup, regardless of how much time elapsed during the sleep or what triggered the wakeup. The value returned by [`node.uptime()`](#nodeuptime) however _is_ updated by however long is spent in light sleep, and can therefore be used to calculate how much time was spent asleep.
 

docs/modules/uart.md

@@ -176,6 +176,30 @@ Set UART controllers communication mode
 `nil`
 
 
+## uart.txflush()
+
+Wait for any data currently in the UART transmit buffers to be written out. It can be useful to call this immediately before a call to [`node.sleep()`](node.md#nodesleep) because otherwise data might not get written until after wakeup.
+
+#### Syntax
+`uart.txflush(id)`
+
+#### Parameters
+- `id` uart id
+
+#### Returns
+`nil`
+
+#### Example
+```lua
+print("I want this to show up now not in 5 seconds")
+uart.txflush(0) -- assuming 0 is the console uart
+node.sleep({secs=5})
+```
+
+#### See also
+[`node.sleep()`](node.md#nodesleep)
+
+
 ## uart.wakeup()
 
 Configure the light sleep wakeup threshold. This is the number of positive edges that must be seen on the UART RX pin before a light sleep wakeup will be triggered. The minimum value is 3. The default value is undefined, therefore you should always call this function before the first time you call `node.sleep()` with the uart option set.
@@ -196,7 +220,7 @@ uart.wakeup(0, 5)
 ```
 
 #### See also
-[`node.sleep()`](node/#nodesleep)
+[`node.sleep()`](node.md#nodesleep)
 
 
 ## uart.write()