boards/xtensa/esp32s2-kaluga-1: Add support for the ES8311 codec

Adds support for the ES8311 codec on the ESP32-S2-Kaluga-1 board. This commit also adds basic configurations for testing and updates the board documentation.

Author: lucasssvaz

Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst

@@ -602,7 +602,7 @@ The ``nxlooper`` application captures data from the audio device with receiving
 capabilities (the I2S1 on this example) and forwards the audio data frame to
 the audio device with transmitting capabilities (the I2S0 on this example).
 
-After successfully built and flashed, run on the boards's terminal::
+After successfully built and flashed, run on the boards' terminal::
 
   nsh> nxlooper
   nxlooper> loopback

Documentation/platforms/xtensa/esp32s2/boards/esp32s2-kaluga-1/index.rst

@@ -180,11 +180,41 @@ Configurations
 All of the configurations presented below can be tested by running the following commands::
 
     $ ./tools/configure.sh esp32s2-kaluga-1:<config_name>
-    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB1 -j
 
 Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
 Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
+audio
+-----
+
+This configuration uses the I2S peripheral and the ES8311 audio
+codec to play an audio file. The easiest way of playing an uncompressed file
+is embedding into the firmware. This configuration selects
+`romfs example <https://github.com/apache/nuttx-apps/tree/master/examples/romfs>`__
+to allow that.
+
+**ROMFS example**
+
+Prepare and build the ``audio`` defconfig::
+
+  $ make -j distclean && ./tools/configure.sh esp32s2-kaluga-1:audio && make
+
+This will create a temporary folder in ``apps/examples/romfs/testdir``. Move
+a PCM-encoded (``.wav``) audio file with 16 or 24 bits/sample (sampled at 16~48kHz)
+to this folder.
+
+.. note:: You can use :download:`this 440 Hz sinusoidal tone <tone.wav>`.
+   The audio file should be located at ``apps/examples/romfs/testdir/tone.wav``
+
+Build the project again and flash it (make sure not to clean it, just build)
+
+After successfully built and flashed, load the romfs and play it::
+
+    nsh> romfs
+    nsh> nxplayer
+    nxplayer> play /usr/share/local/tone.wav
+
 buttons
 -------
 
@@ -210,6 +240,14 @@ the ``buttons`` application and pressing on any of the available board buttons a
     Sample = 64
     Sample = 0
 
+i2c
+---
+
+This configuration can be used to scan and manipulate I2C devices.
+You can scan for all I2C devices using the following command::
+
+    nsh> i2c dev 0x00 0x7f
+
 lvgl_ili9341
 ------------
 
@@ -219,8 +257,8 @@ driver with the ILI9341 display. You can find LVGL here::
     https://www.lvgl.io/
     https://github.com/lvgl/lvgl
 
-This configuration uses the LVGL demonstration at `apps/examples/lvgldemo` and
-can be executed by running the `lvgldemo` application.
+This configuration uses the LVGL demonstration at ``apps/examples/lvgldemo`` and
+can be executed by running the ``lvgldemo`` application.
 
 lvgl_st7789
 -----------
@@ -231,11 +269,30 @@ driver with the ST7799 display. You can find LVGL here::
     https://www.lvgl.io/
     https://github.com/lvgl/lvgl
 
-This configuration uses the LVGL demonstration at `apps/examples/lvgldemo` and
-can be executed by running the `lvgldemo` application.
+This configuration uses the LVGL demonstration at ``apps/examples/lvgldemo`` and
+can be executed by running the ``lvgldemo`` application.
 
 nsh
 ---
 
 Basic NuttShell configuration (console enabled in UART0, exposed via
-USB connection by means of CP2102 converter, at 115200 bps).
+USB connection by means of CP2102 converter, at 115200 bps).
+
+nxlooper
+--------
+
+The ``nxlooper`` application captures data from the audio device with receiving
+capabilities and forwards the audio data frame to the audio device with transmitting
+capabilities.
+
+After successfully built and flashed, run on the boards' terminal::
+
+    nsh> nxlooper
+    nxlooper> loopback
+
+.. note:: ``loopback`` command default arguments for the channel configuration,
+  the data width and the sample rate are, respectively, 2 channels,
+  16 bits/sample and 48KHz. These arguments can be supplied to select
+  different audio formats, for instance::
+
+    nxlooper> loopback 2 8 44100

boards/xtensa/esp32s2/common/include/esp32s2_es8311.h

@@ -0,0 +1,90 @@
+/****************************************************************************
+ * boards/xtensa/esp32s2/common/include/esp32s2_es8311.h
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+#ifndef __BOARDS_XTENSA_ESP32S2_COMMON_INCLUDE_ESP32S2_ES8311_H
+#define __BOARDS_XTENSA_ESP32S2_COMMON_INCLUDE_ESP32S2_ES8311_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <stdint.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Type Definitions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+#ifdef __cplusplus
+#define EXTERN extern "C"
+extern "C"
+{
+#else
+#define EXTERN extern
+#endif
+
+/****************************************************************************
+ * Inline Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: esp32s2_es8311_initialize
+ *
+ * Description:
+ *   This function is called by platform-specific, setup logic to configure
+ *   and register the ES8311 device. This function will register the driver
+ *   as /dev/audio/pcm[x] where x is determined by the I2S port number.
+ *
+ * Input Parameters:
+ *   i2c_port  - The I2C port used for the device;
+ *   i2c_addr  - The I2C address used by the device;
+ *   i2c_freq  - The I2C frequency used for the device.
+ *
+ * Returned Value:
+ *   Zero is returned on success. Otherwise, a negated errno value is
+ *   returned to indicate the nature of the failure.
+ *
+ ****************************************************************************/
+
+int esp32s2_es8311_initialize(int i2c_port, uint8_t i2c_addr, int i2c_freq);
+
+#undef EXTERN
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __BOARDS_XTENSA_ESP32S2_COMMON_INCLUDE_ESP32S2_ES8311_H */

boards/xtensa/esp32s2/common/src/Make.defs

@@ -44,6 +44,10 @@ ifeq ($(CONFIG_LCD_ST7789),y)
   CSRCS += esp32s2_st7789.c
 endif
 
+ifeq ($(CONFIG_AUDIO_ES8311),y)
+  CSRCS += esp32s2_es8311.c
+endif
+
 DEPPATH += --dep-path src
 VPATH += :src
 CFLAGS += $(shell $(INCDIR) "$(CC)" $(TOPDIR)$(DELIM)arch$(DELIM)$(CONFIG_ARCH)$(DELIM)src$(DELIM)board$(DELIM)src)

boards/xtensa/esp32s2/common/src/esp32s2_board_i2sdev.c

@@ -37,7 +37,8 @@
 
 #include "esp32s2_i2s.h"
 
-#if defined(CONFIG_ESP32S2_I2S) && !defined(CONFIG_AUDIO_CS4344)
+#if defined(CONFIG_ESP32S2_I2S) && !defined(CONFIG_AUDIO_CS4344) && \
+    !defined(CONFIG_AUDIO_ES8311)
 
 /****************************************************************************
  * Public Functions
@@ -152,4 +153,5 @@ int board_i2sdev_initialize(bool enable_tx, bool enable_rx)
   return ret;
 }
 
-#endif /* (CONFIG_ESP32S2_I2S) && !defined (CONFIG_AUDIO_CS4344) */
+#endif /* (CONFIG_ESP32S2_I2S) && !(CONFIG_AUDIO_CS4344)  *
+        * !(CONFIG_AUDIO_ES8311)                          */