From 30ada6f084fd2bbe86a54b00260a4311605e3ac9 Mon Sep 17 00:00:00 2001
From: devsaurus <devsaurus@users.noreply.github.com>
Date: Fri, 2 Nov 2018 22:30:45 +0100
Subject: [PATCH] add i2s.mute()

---
 components/modules/i2s.c | 20 +++++++++++++++-
 docs/en/modules/i2s.md   | 52 +++++++++++++++++++++++++++-------------
 2 files changed, 54 insertions(+), 18 deletions(-)

diff --git a/components/modules/i2s.c b/components/modules/i2s.c
index c9b673ba..f8a0bcfc 100644
--- a/components/modules/i2s.c
+++ b/components/modules/i2s.c
@@ -272,7 +272,9 @@ static int node_i2s_read( lua_State *L )
   int wait_ms = luaL_optint(L, 3, 0);
   char * data = luaM_malloc( L, bytes );
   size_t read;
-  i2s_read(i2s_id, data, bytes, &read, wait_ms / portTICK_RATE_MS);
+  if (i2s_read(i2s_id, data, bytes, &read, wait_ms / portTICK_RATE_MS) != ESP_OK)
+    return luaL_error( L, "I2S driver error" );
+
   lua_pushlstring(L, data, read);
   luaM_free(L, data);
 
@@ -298,6 +300,21 @@ static int node_i2s_write( lua_State *L )
   return 0;
 }
 
+// Lua: mute( i2s_id )
+static int node_i2s_mute( lua_State *L )
+{
+  int stack = 0;
+
+  int i2s_id = luaL_checkinteger( L, ++stack );
+  I2S_CHECK_ID( i2s_id );
+
+  if (i2s_zero_dma_buffer( i2s_id ) != ESP_OK)
+    return luaL_error( L, "I2S driver error" );
+
+  return 0;
+}
+
+
 // Module function map
 static const LUA_REG_TYPE i2s_map[] =
 {
@@ -305,6 +322,7 @@ static const LUA_REG_TYPE i2s_map[] =
   { LSTRKEY( "stop" ),  LFUNCVAL( node_i2s_stop ) },
   { LSTRKEY( "read" ),  LFUNCVAL( node_i2s_read ) },
   { LSTRKEY( "write" ), LFUNCVAL( node_i2s_write ) },
+  { LSTRKEY( "mute" ),  LFUNCVAL( node_i2s_mute ) },
 
   { LSTRKEY( "FORMAT_I2S" ),       LNUMVAL( I2S_COMM_FORMAT_I2S  ) },
   { LSTRKEY( "FORMAT_I2S_MSB" ),   LNUMVAL( I2S_COMM_FORMAT_I2S_MSB ) },
diff --git a/docs/en/modules/i2s.md b/docs/en/modules/i2s.md
index 5900b685..d426f058 100644
--- a/docs/en/modules/i2s.md
+++ b/docs/en/modules/i2s.md
@@ -11,6 +11,39 @@ The I2S module provides access to the in-built two I2S controllers.
 !!! note "ADC mode configuration"
     Only ADC1 is available for ADC built-in mode.
 
+
+## i2s.mute()
+Mute the I2S channel. The hardware buffer is instantly filled with silence.
+
+#### Syntax
+`i2s.mute(i2s_num)
+
+#### Parameters
+- `i2s_num` I2S peripheral 0 or 1
+
+#### Returns
+`nil`
+
+An error is thrown in case of invalid parameters or if the i2s driver failed.
+
+
+## i2s.read()
+Read data from I2S receive buffer.
+
+#### Syntax
+`i2s.read(i2s_num, size[, wait_ms])`
+
+#### Parameters
+- `i2s_num` I2S peripheral 0 or 1
+- `size` Bytes to read
+- `wait_ms` Millisecond to wait if data is not ready. Optional, defaults to 0 (not to wait) when omitted.
+
+#### Returns
+Data read from data-in pin. If data is not ready in `wait_ms` millisecond, less than `size` bytes can be returned.
+
+An error is thrown in case of invalid parameters or if the i2s driver failed.
+
+
 ## i2s.start()
 Configuration and start I2S bus.
 
@@ -65,7 +98,7 @@ i2s.start(i2s_num, cfg, cb)
 #### Returns
 `nil`
 
-An error is thrown in case of invalid parameters or if the channel failed.
+An error is thrown in case of invalid parameters or if the i2s driver failed.
 
 
 ## i2s.stop()
@@ -80,22 +113,7 @@ Stop I2S bus.
 #### Returns
 `nil`
 
-An error is thrown in case of invalid parameters or if the channel failed.
-
-
-## i2s.read()
-Read data from I2S receive buffer.
-
-#### Syntax
-`i2s.read(i2s_num, size[, wait_ms])`
-
-#### Parameters
-- `i2s_num` I2S peripheral 0 or 1
-- `size` Bytes to read
-- `wait_ms` Millisecond to wait if data is not ready. Optional, defaults to 0 (not to wait) when omitted.
-
-#### Returns
-Data read from data-in pin. If data is not ready in `wait_ms` millisecond, less than `size` bytes can be returned.
+An error is thrown in case of invalid parameters or if the i2s driver failed.
 
 
 ## i2s.write()