background image

Read the Docs Template Documentation, Release

1.1 ESP32-LyraT V4.3 Getting Started Guide

This guide provides users with functional descriptions, configuration options for ESP32-LyraT V4.3 audio develop-
ment board, as well as how to get started with the ESP32-LyraT board. Check section

Other Versions of LyraT

if you

have different version of this board.

The ESP32-LyraT is a hardware platform designed for the dual-core ESP32 audio applications, e.g., Wi-Fi or BT
audio speakers, speech-based remote controllers, smart-home appliances with audio functionality(ies), etc.

1.1.1 What You Need

• 1 ×

ESP32 LyraT V4.3 board

• 2 x 4-ohm speakers with Dupont female jumper wires or headphones with a 3.5 mm jack

• 2 x Micro-USB 2.0 cables, Type A to Micro B

• 1 × PC loaded with Windows, Linux or Mac OS

If you like to start using this board right now, go directly to section

Start Application Development

.

Overview

The ESP32-LyraT V4.3 is an audio development board produced by

Espressif

built around ESP32. It is intended for

audio applications, by providing hardware for audio processing and additional RAM on top of what is already onboard
of the ESP32 chip. The specific hardware includes:

ESP32-WROVER Module

Audio Codec Chip

• Dual

Microphones

on board

Headphone

input

2 x 3-watt Speaker

output

• Dual

Auxiliary Input

MicroSD Card

slot (1 line or 4 lines)

Six buttons

(2 physical buttons and 4 touch buttons)

JTAG

header

• Integrated

USB-UART Bridge Chip

• Li-ion

Battery-Charge Management

The block diagram below presents main components of the ESP32-LyraT and interconnections between components.

Components

The following list and figure describe key components, interfaces and controls of the ESP32-LyraT used in this guide.
This covers just what is needed now. For detailed technical documentation of this board, please refer to

ESP32-LyraT

V4.3 Hardware Reference

and

ESP32 LyraT V4.3 schematic

(PDF).

ESP32-WROVER Module

The ESP32-WROVER module contains ESP32 chip to provide Wi-Fi / BT connectivity

and data processing power as well as integrates 32 Mbit SPI flash and 32 Mbit PSRAM for flexible data storage.

4

Chapter 1. Get Started

Summary of Contents for ESP32-LyraT

Page 1: ...Read the Docs Template Documentation Release Read the Docs Jul 01 2018...

Page 2: ......

Page 3: ...ash and Monitor 10 1 9 Update ESP ADF 10 1 10 Related Documents 11 2 API Reference 27 2 1 Audio Framework 28 2 2 Audio Streams 53 2 3 Codecs 57 2 4 Peripherals 58 2 5 Abstraction Layer 62 2 6 Configur...

Page 4: ...ii...

Page 5: ...Read the Docs Template Documentation Release This is the documentation for Espressif Audio Development Framework Get Started API Reference Design Guide Contents 1...

Page 6: ...Read the Docs Template Documentation Release 2 Contents...

Page 7: ...32 by Espressif Through a simple example we would like to illustrate how to use ESP ADF Espressif Audio Development Framework To make the start with ESP ADF quicker Espressif designed ESP32 LyraT a de...

Page 8: ...y Espressif built around ESP32 It is intended for audio applications by providing hardware for audio processing and additional RAM on top of what is already onboard of the ESP32 chip The specific hard...

Page 9: ...sets the system Audio Codec Chip The Audio Codec Chip ES8388 is a low power stereo audio codec with a headphone amplifier It consists of 2 channel ADC 2 channel DAC microphone amplifier headphone ampl...

Page 10: ...Read the Docs Template Documentation Release Fig 1 3 ESP32 LyraT V4 3 Board Layout Overview 6 Chapter 1 Get Started...

Page 11: ...ally set up and checked you can proceed with preparation of the development tools Go to section Get Started which will walk you through the following steps Setup ESP IDF in your PC that provides a com...

Page 12: ...choice to compile and upload code to the ESP32 by command line with make or using Eclipse IDE Note We are using esp directory to install the toolchain ESP IDF ESP ADF and sample applications You can...

Page 13: ...ESP ADF components by using the ADF_PATH variable Note ESP ADF is based on a specific release of the ESP IDF You will see this release cloned with ESP ADF as a subdirectory or more specifically as a s...

Page 14: ...T i2s RESUME Element has not running state 3 task_run 1 I 403 PLAY_MP3_FLASH Receive music info from mp3 decoder sample_rates 44100 bits 16 ch 2 W 433 AUDIO_ELEMENT i2s RESUME Element has not running...

Page 15: ...aT development board is a hardware platform designed for the dual core ESP32 audio applications e g Wi Fi or BT audio speakers speech based remote controllers smart home appliances with audio function...

Page 16: ...MicroSD Card is enabled with all switches in OFF position To enable the JTAG Header instead switches in positions 3 4 5 and 6 should be put ON If JTAG is not used and MicroSD Card is operated in the...

Page 17: ...Microphone Onboard microphone connected to IN1 of the Audio Codec Chip AUX Input Auxiliary input socket connected to IN2 left and right channel of the Audio Codec Chip Use a 3 5 mm stereo jack to con...

Page 18: ...her on both IO0 and EN headers Function Press Keys Two key labeled Rec and Mode They are routed to ESP32 WROVER Module and intended for developing and testing a UI for audio applications using dedicat...

Page 19: ...functionality is not available Vol touch button is available for use with the API Enable MicroSD Card in 4 wire Mode DIP SW Position 1 ON 2 ON 3 OFF 4 OFF 5 OFF 6 OFF 7 OFF 8 n a In this mode JTAG fun...

Page 20: ...tiple functions Please refer to the tables below or ESP32 LyraT V4 2 schematic for specific details Red Green LEDs ESP32 Pin LED Color 1 GPIO19 Red LED 2 GPIO22 Green LED Touch Pads ESP32 Pin Touch Pa...

Page 21: ...Pin Header Pin 1 n a IO0_Auto 2 GPIO0 IO0 I2S Header JP4 I2C Header Pin ESP32 Pin 1 MCLK GPI0 2 SCLK GPIO5 1 LRCK GPIO25 2 DSDIN GPIO26 3 ASDOUT GPIO35 3 GND GND I2C Header JP5 I2C Header Pin ESP32 P...

Page 22: ...ut Connecting headphones to the Headphone Output is an option 3 Plug in the Micro USB cables to the PC and to both USB ports of the ESP32 LyraT 4 The Standby LED green should turn on Assuming that a b...

Page 23: ...sed remote controllers smart home appliances with audio functionality ies etc If you like to start using this board right now go directly to section Start Application Development What You Need 1 ESP32...

Page 24: ...efault MicroSD Card is enabled with all switches in OFF position To enable JTAG Header instead switches in positions 3 4 5 and 6 should be put ON If JTAG is not used and MicroSD Card is operated in on...

Page 25: ...ft Microphone Onboard microphone connected to IN1 of the Audio Codec Chip AUX Input Auxiliary input socket connected to IN2 left and right channels of the Audio Codec Chip Use a 3 5 mm stereo jack to...

Page 26: ...RT bridge provides up to 1 Mbps transfer rate Micro USB Port USB interface It functions as the power supply for the board and the communication interface between a PC and the ESP32 module Standby Char...

Page 27: ...om the API is not available Enable JTAG DIP SW Position 1 OFF 2 OFF 3 ON 4 ON 5 ON 6 ON 7 ON 8 n a In this mode MicroSD Card functionality is not available remove the card from the slot Vol touch butt...

Page 28: ...AG is used It is also not available for the MicroSD Card configured to operate in 4 wire mode MicroSD Card J5 ESP32 Pin MicroSD Signal 1 MTDI GPIO12 DATA2 2 MTCK GPIO13 CD DATA3 3 MTDO GPIO15 CMD 4 MT...

Page 29: ...plugged in when the system powers up Otherwise the ESP32 may not be able to boot correctly Start Application Development Before powering up the ESP32 LyraT please make sure that the board has been rec...

Page 30: ...u through the following steps Setup ESP IDF in your PC that provides a common framework to develop applications for the ESP32 in C language Get ESP ADF to have the API specific for the audio applicati...

Page 31: ...Elements of the Audio Development Framework The application is developed by combining the Elements into a Pipeline A diagram below presents organization of two elements MP3 decoder and I2S stream in...

Page 32: ...control on particular stages of the data lifecycle from the input during processing and up to the output the audio_element object provides possibility to trigger callbacks per stage There are seven ty...

Page 33: ...handle object Return data pointer Parameters el The audio element handle esp_err_t audio_element_set_tag audio_element_handle_t el const char tag Set elemenet tag name or clear if tag NULL Return ESP_...

Page 34: ..._element_get_uri audio_element_handle_t el Get audio element URI Return URI pointer Parameters el The audio element handle esp_err_t audio_element_run audio_element_handle_t el Start Audio Element wit...

Page 35: ...es This function will be blocked until Element Task has done and exit Return ESP_OK ESP_FAIL Parameters el The audio element handle esp_err_t audio_element_pause audio_element_handle_t el Request audi...

Page 36: ...ent will be listen to esp_err_t audio_element_msg_remove_listener audio_element_handle_t el au dio_event_iface_handle_t listener Remove listener out of el no new events will be sent to the listene Ret...

Page 37: ...t_state_t audio_element_get_state audio_element_handle_t el Get current Element state Return audio_element_state_t Parameters el The audio element handle esp_err_t audio_element_abort_input_ringbuf au...

Page 38: ...element_handle_t el audio_element_status_t sta tus Element will sendout event status to event by this function Return ESP_OK ESP_FAIL Parameters el The audio element handle status The status esp_err_t...

Page 39: ...ent_handle_t el Reset inputbuffer Return ESP_OK ESP_FAIL Parameters el The audio element handle esp_err_t audio_element_reset_output_ringbuf audio_element_handle_t el Reset outputbuffer Return ESP_OK...

Page 40: ...data to be processed Return ESP_OK ESP_FAIL Parameters el The audio element handle fn Callback read function The callback function should return number of bytes read or 1 in case of error in reading N...

Page 41: ..._element_set_ringbuf_done audio_element_handle_t el Set inputbuffer and outputbuffer have finished Return ESP_OK ESP_FAIL Parameters el The audio element handle esp_err_t audio_element_reset_state aud...

Page 42: ...ck functions are provided by the user corresponding to this configuration Public Members io_func open Open callback function io_func seek Seek callback function process_func process Process callback f...

Page 43: ...lement_err_t process_func audio_element_handle_t self char el_buffer int el_buf_len typedef audio_element_err_t stream_func audio_element_handle_t self char buffer int len Tick Type_t ticks_to_wait vo...

Page 44: ...EPORT_CODEC_FMT 10 enum audio_element_status_t Audio element status report Values AEL_STATUS_NONE 0 AEL_STATUS_ERROR_OPEN 1 AEL_STATUS_ERROR_INPUT 2 AEL_STATUS_ERROR_PROCESS 3 AEL_STATUS_ERROR_OUTPUT...

Page 45: ...audio_pipeline_cfg_t config Initialize audio_pipeline_handle_t object audio_pipeline is responsible for controlling the audio data stream and connecting the audio elements with the ringbuffer It will...

Page 46: ...peline remove it from the list Return ESP_OK on success ESP_FAIL when any errors Parameters pipeline The Audio Pipeline Handle el The Audio Element Handle esp_err_t audio_pipeline_run audio_pipeline_h...

Page 47: ..._err_t audio_pipeline_stop audio_pipeline_handle_t pipeline Stop all elements and clear information of items Free up memory for all task items The link state of the elements in the pipeline is kept ev...

Page 48: ..._register link_num Total number of elements of the link_tag array esp_err_t audio_pipeline_unlink audio_pipeline_handle_t pipeline Removes the connection of the elements as well as unsubscribe events...

Page 49: ...irst Previous element is first input element need to set true prev Previous element conect_rb Connect ring buffer next Next element esp_err_t audio_pipeline_register_more audio_pipeline_handle_t pipel...

Page 50: ...K ESP_FAIL Parameters pipeline The audio pipeline handle element_1 The element event to subscribe to the audio_pipeline Additional elements event to subscribe to the audio_pipeline esp_err_t audio_pip...

Page 51: ...def struct audio_pipeline_cfg audio_pipeline_cfg_t Audio Pipeline configurations 2 1 3 Event Interface The ADF provides the Event Interface API to establish communication between Audio Elements in a p...

Page 52: ...vt au dio_event_iface_handle_t listener Add audio event evt to the listener then we can listen evt event from listen Return ESP_OK ESP_FAIL Parameters listener The event can listen another event evt T...

Page 53: ...t_iface_msg_t msg Trigger an event for internal queue with a message Return ESP_OK ESP_FAIL Parameters evt The event msg The message esp_err_t audio_event_iface_cmd_from_isr audio_event_iface_handle_t...

Page 54: ...essage wait_time The wait time QueueHandle_t audio_event_iface_get_queue_handle audio_event_iface_handle_t evt Get External queue handle of Emmitter Return External QueueHandle_t Parameters evt The ex...

Page 55: ...en evt event from listen Return ESP_OK ESP_FAIL Parameters listener The event can listen another event evt The event to be added to Structures struct audio_event_iface_msg_t Event message Public Membe...

Page 56: ...face_msg_t source_type To know where it came from Macros DEFAULT_AUDIO_EVENT_IFACE_SIZE AUDIO_EVENT_IFACE_DEFAULT_CFG Type Definitions typedef esp_err_t on_event_iface_func audio_event_iface_msg_t voi...

Page 57: ...O_CODEC_TYPE_ENCODER enum audio_codec_t Values AUDIO_CODEC_NONE 0 AUDIO_CODEC_RAW AUDIO_CODEC_WAV AUDIO_CODEC_MP3 AUDIO_CODEC_AAC AUDIO_CODEC_OPUS 2 1 5 ESP Audio This component provides several simpl...

Page 58: ...2s_stream h Functions audio_element_handle_t i2s_stream_init i2s_stream_cfg_t config Create a handle to an Audio Element to stream data from I2S to another Element or get data from other elements sent...

Page 59: ...cros I2S_STREAM_CFG_DEFAULT I2S_STREAM_INTERNAL_DAC_CFG_DEFAULT 2 2 2 HTTP Stream Header File audio_stream include http_stream h Functions audio_element_handle_t http_stream_init http_stream_cfg_t con...

Page 60: ...ok function for HTTP Stream void user_data User data context Macros HTTP_STREAM_CFG_DEFAULT Type Definitions typedef int http_stream_event_handle_t http_stream_event_msg_t msg Enumerations enum http_s...

Page 61: ...header and ready to read HTTP body 2 2 3 FatFs Stream Header File audio_stream include fatfs_stream h Functions audio_element_handle_t fatfs_stream_init fatfs_stream_cfg_t config Create a handle to an...

Page 62: ..._wav recorder pipeline_wav_sdcard API Reference Decoder API Reference Encoder 2 3 3 Resample Filter The Resample Filter is an Audio Element designed to downsample or upsample the incoming data stream...

Page 63: ...released when pressed for a long time and released after long press To get information on particular event establish a callback function with button_dev_add_tap_cb or button_dev_add_press_cb API Refer...

Page 64: ..._cfg const periph_console_cmd_t cmd cmd play id 1 help Play audio cmd stop id 2 help Stop audio cmd test help test console func console_test_cb periph_console_cfg_t console_cfg command_num sizeof cmd...

Page 65: ...source_type case PERIPH_ID_BUTTON ESP_LOGI TAG BUTTON d event event_id d int event data event cmd break case PERIPH_ID_SDCARD ESP_LOGI TAG SDCARD status event event_id d event cmd break case PERIPH_I...

Page 66: ...on again esp_periph_start button_handle vTaskDelay 10 1000 portTICK_RATE_MS Stop destroy all peripherals esp_periph_destroy API Reference 2 5 Abstraction Layer 2 5 1 Ring Buffer Ringbuffer is designed...

Page 67: ...and free all memory created by ringbuf_handle_t Return ESP_OK ESP_FAIL Parameters rb The Ringbuffer handle esp_err_t rb_abort ringbuf_handle_t rb Abort waiting until there is space for reading or wri...

Page 68: ...it tick_to_wait ticks until enough bytes to read if the ring buffer bytes available is less than len Return Number of bytes read Parameters rb The Ringbuffer handle buf The buffer pointer to read out...

Page 69: ...and the hardware driver for specific audio board like ESP32 LyraT The API provides data structures to configure sampling rates of ADC and DAC signal conversion data bit widths I2C stream parameters an...

Page 70: ...mponent config ESP HTTP client This option will enable https protocol by linking mbedtls library and initializing SSL transport 2 6 2 Audio HAL AUDIO_BOARD Audio board Found in Audio HAL Select an aud...

Page 71: ...audio data stream from the internet Bluetooth interface to obtain an audio data stream from e g a BT headset I2S interface to obtain audio data stream from a codec chip Ethernet interface to obtain a...

Page 72: ...e may consider two project groups Minimum having minimum additional components assuming using on board I2S or PDM interface as well as DAC if no high qualify audio on the output is required Typical wi...

Page 73: ...The ESP32 LyraT board is an example of such a project The software interfacing with the board is done by Audio HAL and a driver The codec chip used on the ESP32 LyraT is ES8388 Boards with a differen...

Page 74: ...leave enough memory for an audio application Optimization of Internal RAM and Use of PSRAM Internal RAM is more valuable asset since there are some restrictions on PSRAM Here are some tips for optimiz...

Page 75: ...IDF libraries including libc doing only calculations and using FreeRTOS primitives to talk to other threads Memory Usage by Component Overview Below is a table that contains ESP ADF components and the...

Page 76: ...ash SPI mode as QIO Flash SPI speed as 80MHz CPU frequency as 240MHz Set Default receive window size as 5 times greater than Maximum Segment Size in Component config LWIP TCP If external antenna is us...

Page 77: ...io_event_handle_t evt1 audio_event_cfg_t cfg AUDIO_EVENT_IFACE_DEFAULT_CFG cfg dispatcher evt_process cfg queue_size 10 cfg context evt1 cfg type AUDIO_EVENT_TYPE_ELEMENT evt1 audio_event_init cfg TES...

Page 78: ...AL ESP_OK audio_pipeline_register pipeline first_el mid_el last_ el TEST_ASSERT_EQUAL ESP_OK audio_pipeline_link pipeline const char first mid last 3 Audio Peripheral Example esp_periph_config_t perip...

Page 79: ...v_decoder_init wav_cfg fatfs_stream_cfg_t fatfs_cfg type AUDIO_STREAM_READER root_path sdcard i2s_stream_cfg_t i2s_cfg I2S_STREAM_CFG_DEFAULT esp_audio_input_stream_add player fatfs_stream_init fatfs_...

Page 80: ...ctional Description The following list and figure describe key components interfaces and controls of the ESP32 LyraT board ESP32 WROVER Module The ESP32 WROVER module contains ESP32 chip to provide Wi...

Page 81: ...eader JP5 for pinout details MicroSD Slot The development board supports a MicroSD card in SPI 1 bit 4 bit modes and can store or play audio files in the MicroSD card Note that JTAG cannot be used and...

Page 82: ...Read the Docs Template Documentation Release Fig 3 5 ESP32 LyraT V4 3 Board Layout 78 Chapter 3 Design Guide...

Page 83: ...o the ESP32 Install all jumpers together on all three headers Remove all jumpers after upload is complete Function Press Keys Two key labeled Rec and Mode They are routed to ESP32 WROVER Module and in...

Page 84: ...therwise the ESP32 may not be able to boot correctly In this mode JTAG functionality is not available Vol touch button is available for use with the API Enable MicroSD Card in 4 wire Mode DIP SW Posit...

Page 85: ...after upload is complete Allocation of ESP32 Pins Several pins ESP32 module are allocated to the on board hardware Some of them like GPIO0 or GPIO2 have multiple functions Please refer to the table b...

Page 86: ...ESP32 Pin 1 MCLK GPI0 2 SCLK GPIO5 1 LRCK GPIO25 2 DSDIN GPIO26 3 ASDOUT GPIO35 3 GND GND I2C Header JP5 I2C Header Pin ESP32 Pin 1 SCL GPIO23 2 SDA GPIO18 3 GND GND JTAG Header JP7 ESP32 Pin JTAG Sig...

Page 87: ...Module To provide enough current the ESP32 the development board adopts LD1117S33CTR LDO capable to supply the maximum output current of 800mA MicroSD Card and Audio Codec Two separate LDOs are provid...

Page 88: ...Read the Docs Template Documentation Release Fig 3 7 ESP32 LyraT V4 3 Dedicated LDO for the ESP32 Module Fig 3 8 ESP32 LyraT V4 3 Dedicated LDO for the MicroSD Card 84 Chapter 3 Design Guide...

Page 89: ...8 Audio output supports two external speakers An optional audio output is a pair of headphones feed from the same DACs as the amplifier ICs To switch between using headphones and speakers the board pr...

Page 90: ...Read the Docs Template Documentation Release ESP32 WROVER Datasheet PDF JTAG Debugging 86 Chapter 3 Design Guide...

Page 91: ...bug or have a feature request Please check existing Issues before opening a new one If you re interested in contributing to ESP Audio Development Framework please check the Contributions Guide Severa...

Page 92: ...Read the Docs Template Documentation Release 88 Chapter 4 Resources...

Page 93: ...d in the file LICENSE Additional third party copyrighted code is included under the following licenses esp stagefright is Copyright c 2005 2008 The Android Open Source Project and is licensed under th...

Page 94: ...Read the Docs Template Documentation Release 90 Chapter 5 Copyrights and Licenses...

Page 95: ...DF software provide a powerful platform to implement audio applications including native wireless networking and powerful user interface The ESP ADF provides a range of API components including Audio...

Page 96: ...Read the Docs Template Documentation Release Fig 6 1 Espressif Audio Development Framework 92 Chapter 6 About...

Page 97: ...G C enumera tor 40 AEL_STATUS_INPUT_DONE C enumerator 40 AEL_STATUS_MOUNTED C enumerator 40 AEL_STATUS_NONE C enumerator 40 AEL_STATUS_OUTPUT_BUFFERING C enumera tor 40 AEL_STATUS_OUTPUT_DONE C enumer...

Page 98: ...n 29 audio_element_set_uri C function 30 audio_element_set_write_cb C function 36 audio_element_setdata C function 29 audio_element_setinfo C function 29 audio_element_state_t C type 39 audio_element_...

Page 99: ...EMENT_TASK_PRIO C macro 39 DEFAULT_PIPELINE_RINGBUF_SIZE C macro 47 E ELEMENT_SUB_TYPE_OFFSET C macro 52 F fatfs_stream_cfg_t C class 57 fatfs_stream_cfg_t buf_sz C member 57 fatfs_stream_cfg_t type C...

Page 100: ...ite C function 65 RB_FAIL C macro 65 rb_get_size C function 64 RB_OK C macro 65 rb_read C function 64 rb_reset C function 63 rb_size_get C function 64 RB_TIMEOUT C macro 65 rb_write C function 64 ring...

Reviews: