• This repository has been archived on 14/Jan/2022
  • Stars
    star
    739
  • Rank 61,358 (Top 2 %)
  • Language
    C
  • License
    Other
  • Created over 9 years ago
  • Updated about 8 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A demo that should be run with ESP8266 Non-OS SDK

I2S MP3 webradio streaming example

This is an example of how to use the I2S module inside the ESP8266 to output sound. In this case, it is used to output decoded MP3 data (actually, more accurately: MPEG2 layer III data): the code described here basically is a webradio streamer which can connect to an Icecast server, take the MP3 data the server sends out, decode it and output it over the I2S bus to a DAC. The MP3 decoder has been tested for bitrates up to 320KBit/s and sample rates of up to 48KHz.

Configuration options, building

All high-level options can be configured in mp3/user/playerconfig.h. Edit that file to set up your access point and a webradio stream or other source of MP3 data served over HTTP.

To build the code, try running make.sh in the mp3/ directory. Alternatively, the way to use 'make' to build this code is: make COMPILE=gcc BOOT=none APP=0 SPI_SPEED=40 SPI_MODE=QIO SPI_SIZE=1024

The resulting binaries will be in the bin/ folder. Please disregard the message that pops up at the end of the make process: the addresses it mentions are wrong. The correct addresses to load the resulting files are:

bin/eagle.flash.bin     - 0x00000
bin/eagle.irom0text.bin - 0xA0000

Needed hardware

If you want to have nice, high-quality buffered audio output, you will need to connect two ICs to your ESP: a 128KByte SPI RAM and an I2S codec. Both ICs are optional, but you will get stuttering and low-quality sound if you leave them off.

The SPI RAM is a Microchip 23LC1024 part and is used to buffer the incoming MP3 data. This guards against latency isuues that are present in all but the most quiet networks and closest connections. It is connected to the same bus as the SPI flash:

ESP pin   - 23LC1024 pin
------------------------
GPIO0     - /CS (1)
SD_D0     - SO/SI1 (2)
SD_D3     - SIO2 (3) *
gnd       - gnd (4)
SD_D1     - SI/SIO0 (5)
SD_CLK    - SCK (6)
SD_D2     - /HOLD/SIO3 (7) *
3.3V      - VCC (8)

*=optional, may also be connected to Vcc on 23LC1024 side.

One way to make these connections is to take the SSOIC version of the 23LC1024, bend up pin 1 (/CS) and piggyback it on the SPI flash chip that already is on the ESP module. Solder all the pins to the same pins on the SPI flash chip except for the bent /CS pin; use a wire to connect that to GPIO0.

As Github user milkpirate correctly remarked, GPIO0 is also used to enter programming mode on the ESP8266 and will interfere with correct flashing if kept low. The correct way of flashing the module is to make GPIO0 low, reset the ESP8266 to enter programming mode, then make GPIO0 high again. Tools like esptool.py generally follow this method to automatically enter programming mode; if you manually enter programming mode you may have to adjust your methodology.

For the I2S codec, pick whatever chip or board works for you; this code was written using a ES9023 chip, but other I2S boards and chips will probably work as well. The connections to make here are:

ESP pin   - I2S signal
----------------------
GPIO2/TX1   - LRCK
GPIO3/RX0   - DATA
GPIO15      - BCLK

Also, don't forget to hook up any supply voltages and grounds needed.

Running without the SPI RAM part

To not use the SPI RAM chip, please edit mp3/user/playerconfig.h and define FAKE_SPI_BUFF. This will use a much smaller buffer in the main memory of the ESP8266. Because the buffer is much smaller, the code will be very sensitive to network latency; also, clock synchronization with live streaming stations will not work. Expect the sound to cut out a fair amount of times unless you have a quiet network and connect to a server very close to you.

Running without the I2S DAC

To not use an I2S DAC chip, please edit mp3/user/playerconfig.h and define PWM_HACK. This uses some code to abuse the I2S module as a 5-bit PWM generator. You can now connect an amplifier to the I2S data pin (GPIO3/RX0) of the ESP module. Connecting a speaker directly may also work but is not advised: the GPIOs of the ESP are not meant to drive inductive loads directly.

Sound quality

In the default configuration, this code will output 16-bit mono audio. Stereo audio is possible but hasn't been implemented yet: a stereo synth is available but has not been modified for ESP8266 use yet. In PWM mode, the output is a dithered 5-bit PWM output. Furthermore, the ESP can decode a pretty wide range of bitrates: 96KBit to 320KBit MP3s have been tested and seem to work fine. Sound quality in general is not bad, but the scaling and clock adaption algorithms can use some improvement if the decoder needs to output real high-quality sound: Patches are welcome.

About the FreeRTOS SDK used

The MP3 example is a very memory-sensitive piece of code: the MP3 decoder uses almost all the RAM and the needed buffers for input and output buffering take up the rest: when using no external SPI RAM, only a few bytes of memory are left. The SDK libs that come with this example are libraries that have been optimized for memory usage and are known to work.

Technical details on this implementation

The biggest part of this code consists of a modified version of libmad, a fixed-point mp3 decoder. The specific version we use here has already been modified by NXP to use less memory (source: www.nxp.com/documents/application_note/AN10583.pdf) and has been massaged by Espressif to store as much constants in flash as possible in order to decrease RAM use even more. The MP3 decoder is fed from a FIFO realized in the external 23LC1024 SPI RAM. This RAM is filled from a network socket in a separate thread.

On the output side, the MP3 samples are fed into the I2S subsystem using DMA. The I2S DMA basically consists of a circular buffer consisting of a number of smaller buffers. As soon as the DMA is done emptying one of the smaller buffers into the I2S subsystem, it will fire an interrupt. This interrupt will put the buffer address in a queue.

When the MP3 decoder has a bunch of samples ready, it will pop a buffer off this queue and put the samples in it until it is full, then take the next buffer etc. The MP3 decoder generally is faster than the I2S output, so at a certain moment there will be no free buffers left. The queue system of FreeRTOS will suspend the mp3 decoding task when that happens, allowing the ESP8266 to attend to other tasks.

While the ESP8266 is able to run at 160MHz, we're leaving it at its default speed of 80MHz here: it seems that at that speed the ESP8266 is perfectly capable of decoding even 320KBit MP3 data.

More Repositories

1

esp-idf

Espressif IoT Development Framework. Official development framework for Espressif SoCs.
C
13,620
star
2

arduino-esp32

Arduino core for the ESP32
C++
13,280
star
3

esptool

Espressif SoC serial bootloader utility
Python
5,521
star
4

ESP8266_RTOS_SDK

Latest ESP8266 SDK based on FreeRTOS, esp-idf style.
C
3,333
star
5

esp-iot-solution

Espressif IoT Library. IoT Device Drivers, Documentations And Solutions.
C
1,856
star
6

esp-who

Face detection and recognition framework
C
1,660
star
7

esp-adf

Espressif Audio Development Framework
C
1,523
star
8

esp32-camera

C
1,259
star
9

vscode-esp-idf-extension

Visual Studio Code extension for ESP-IDF projects
TypeScript
1,032
star
10

ESP8266_NONOS_SDK

ESP8266 nonOS SDK
C
926
star
11

esp-at

AT application for ESP32/ESP32-C2/ESP32-C3/ESP32-C6/ESP8266
C
860
star
12

esp-mdf

Espressif Mesh Development Framework, limited maintain, recommend to use https://github.com/espressif/esp-mesh-lite
C
774
star
13

esp-drone

Mini Drone/Quadcopter Firmware for ESP32 and ESP32-S Series SoCs.
C
766
star
14

esp-box

The ESP-BOX is a new generation AIoT development platform released by Espressif Systems.
HTML
757
star
15

kicad-libraries

KiCad libraries for Espressif SoCs, modules, and DevKits.
Python
703
star
16

esp-csi

Applications based on Wi-Fi CSI (Channel state information), such as indoor positioning, human detection
C
690
star
17

esp-matter

Espressif's SDK for Matter
C++
638
star
18

esp-mqtt

ESP32 mqtt component
C
602
star
19

esp-apple-homekit-adk

This is a port for Apple's Open Source HomeKit ADK
C
599
star
20

esp-skainet

Espressif intelligent voice assistant
C
570
star
21

esp-hosted

Hosted Solution (Linux/MCU) with ESP32 (Wi-Fi + BT + BLE)
C
562
star
22

esp-homekit-sdk

C
552
star
23

esp-sr

Speech recognition
C
551
star
24

esp-now

A connectionless Wi-Fi communication protocol
C
503
star
25

ESP8266_AT

This project is not maintained, please use https://github.com/espressif/esp-at.
C
472
star
26

esp32-nesemu

Proof-of-concept NES emulator for the ESP32
C
471
star
27

esp-dsp

DSP library for ESP-IDF
C
458
star
28

esp-rainmaker

ESP RainMaker Agent for firmware development
C
442
star
29

rust-esp32-example

Example of Rust integration into an ESP-IDF project, for ESP32 series of chips
Rust
432
star
30

esp-serial-flasher

Library for flashing Espressif SoCs from other MCUs.
C
371
star
31

esp-dl

Espressif deep-learning library for AIoT applications
C++
369
star
32

openocd-esp32

OpenOCD branch with ESP32 JTAG support
C
355
star
33

esp-tflite-micro

TensorFlow Lite Micro for Espressif Chipsets
C++
348
star
34

esp-dev-kits

Docs, Schematics, Factory Firmwares for ESP Development Kits
C
343
star
35

esp-aliyun

Aliyun Iotkit-embedded, support esp32 & esp8266.
C
338
star
36

esp-idf-template

Template application for https://github.com/espressif/esp-idf
Makefile
336
star
37

idf-eclipse-plugin

Espressif-IDE (based on Eclipse CDT) for ESP-IDF CMake based projects 4.x and above
Java
306
star
38

esp-usb-bridge

USB to UART&JTAG bridge, implemented on ESP32-S2 or ESP32-S3
C
292
star
39

esp-va-sdk

Espressif's Voice Assistant SDK: Alexa, Google Voice Assistant, Google DialogFlow
C
290
star
40

esptool-js

Javascript implementation of flasher tool for Espressif chips, running in web browser using WebSerial.
TypeScript
276
star
41

esp-aws-iot

AWS IoT SDK for ESP32 based chipsets
C
266
star
42

ESP31_RTOS_SDK

ESP31B SDK based on FreeRTOS. For ESP32 please see http://github.com/espressif/esp-idf
HTML
189
star
43

esp-protocols

Collection of ESP-IDF components related to networking protocols
C
185
star
44

esp-idf-provisioning-android

Android Provisioning application for ESP-IDF Unified provisioning
Java
184
star
45

esp-azure

SDK to connect ESP8266 and ESP32 to Microsoft Azure IoT services
C
174
star
46

esp-jumpstart

Jumpstart from concept to production
C
173
star
47

esp-bsp

Board support components for Espressif development boards
C
172
star
48

esp32-wifi-lib

ESP32 WiFi stack precompiled libraries
Shell
165
star
49

esp-gdbstub

C
157
star
50

esp-iot-bridge

A smart bridge to make both ESP and the other MCU or smart device can access the Internet.
C
153
star
51

idf-extra-components

Additional components for ESP-IDF, maintained by Espressif
C
151
star
52

esp32-doom

A proof-of-concept port of PrBoom to the ESP32. Needs psram hardware.
C++
151
star
53

esp-zigbee-sdk

Espressif Zigbee SDK
C
144
star
54

esp-google-iot

Google Cloud IoT SDK as an ESP-IDF Component
C
142
star
55

esp-nn

Optimised Neural Network functions for Espressif chipsets
Assembly
130
star
56

esp8266-rtos-sample-code

C
129
star
57

esp-idf-provisioning-ios

Swift
125
star
58

esp32-arduino-lib-builder

C
120
star
59

esp-mesh-lite

A lite version Wi-Fi Mesh, each node can access the network over the IP layer.
C
115
star
60

esp-modbus

ESP-Modbus - the officially suppported library for Modbus protocol (serial RS485 + TCP over WiFi or Ethernet).
C
110
star
61

esp-thread-br

Espressif Thread Border Router SDK
C
105
star
62

idf-installer

ESP IDF Windows Installer
Inno Setup
102
star
63

esp-insights

ESP Insights: A remote diagnostics/observability framework for connected devices
C
99
star
64

book-esp32c3-iot-projects

《ESP32-C3 物联网工程开发实战》配套代码
Swift
96
star
65

esp-rainmaker-android

ESP RainMaker Android app sources
Java
87
star
66

usb-pids

Customer-allocated USB PIDs under the Espressif VID
Shell
85
star
67

esp-lwip

Fork of lwIP (https://savannah.nongnu.org/projects/lwip/) with ESP-IDF specific patches
C
83
star
68

pytest-embedded

A pytest plugin that designed for embedded testing
Python
80
star
69

esp-ali-smartliving

阿里云生活物联网平台 & 天猫精灵 IoT 开放平台
C
77
star
70

esp-idf-cxx

C++ wrapper classes for ESP-IDF components.
C++
77
star
71

esp32c3-direct-boot-example

Example of ESP32-C3 (rev. 3 and later) "direct boot" feature.
CMake
68
star
72

esp32-bt-lib

ESP32 Bluetooth stack (below HCI layer) precompiled libraries
67
star
73

esp8266-nonos-sample-code

C
66
star
74

esp-qcloud

基于 ESP-IDF 原生开发接入腾讯 IoT Explorer,支持 ESP32/ESP32S2,快速实现腾讯连连控制。
C
65
star
75

esp-wasmachine

The Machine which can run WASM applications.
C
61
star
76

freertos-gdb

Python module for operating with freeRTOS kernel objects in GDB
Python
56
star
77

esp-moonlight

C
54
star
78

svd

SVD files for Espressif devices
54
star
79

openocd-on-esp32

OpenOCD port running on ESP32-S3 microcontrollers
C
54
star
80

xtensa-isa-doc

TeX
48
star
81

binutils-esp32ulp

Binutils fork with support for the ESP32 ULP co-processor
C
46
star
82

idf-component-manager

Tool for installing ESP-IDF components
Python
43
star
83

esp-rainmaker-ios

ESP RainMaker iOS app sources
Swift
41
star
84

esp-privilege-separation

Espressif Privilege Separation Framework
C
39
star
85

esp-adf-libs

C
38
star
86

esp-launchpad

Configurable Browser-based Image Flasher
CSS
38
star
87

esp-wolfssl

WolfSSL port for ESP-IDF & ESP8266_RTOS_SDK
C
38
star
88

ESP8266_RTOS_ALINK_DEMO

Alink 1.0 早期版本
Assembly
36
star
89

esp-faq

Python
35
star
90

esp-wdf

Espressif WASM Development Framework.
C
34
star
91

esp31-smsemu

C
34
star
92

esp-joylink

Demo project for JD joylink, support esp32 & esp8266.
C
34
star
93

esp8266-alink-v1.0

alink v1.0
C
32
star
94

newlib-esp32

Version of newlib used in ESP32 ROM and ESP-IDF
C
31
star
95

idf-env

idf-env tool helps set up and manage ESP-IDF installations
Rust
31
star
96

esp32-c3-book-en

Read the book here:
HTML
30
star
97

esp32-alink-demo

Demo project for alink, include embed and SDS
C
30
star
98

esp32-iotivity

Guide you to make your ESP32 support OCF/OIC.
C
29
star
99

esp8266-alink-sds

Demo project for alink SDS
C
27
star
100

esp-cryptoauthlib

Release only fork of https://github.com/MicrochipTech/cryptoauthlib
C
27
star