This is a PlatformIO library for the generic VS1053 Breakout by VLSI Solution.
A powerful Ogg Vorbis / MP3 / AAC / WMA / FLAC / MIDI Audio Codec chip.
Read more: http://www.vlsi.fi/en/products/vs1053.html.
The library enables the possibility to play audio files (recording is not supported).
Eg. it may be a base to build your own webradio player or different audio device.
Designed specifically to work with the Espressif ESP8266 and ESP32 boards.
Don't hesitate to create issues or pull requests if you want to improve ESP_VS1053_Library!
There are currently two official methods to program the ESP boards: the ESP-IDF and the ESP8266/ESP32 arduino Core. The library was created to work with the arduino Core.
The ESP8266 is the most popular Wi-Fi MCU (known also as ESP12, NodeMCU, WeMos, ...).
As mentioned in first paragraph, the library was prepared to be used with PlatformIO, which is kind of dependency management tool. It is highly recommended environment to be used while developing your electronics/IoT projects. The build automation lets you deal much easier while working with the project. It will help you to have all project dependencies simply resolved out of the box. What more, it provides very good IDE integration (any of popular), debugging possibility, remote unit testing and firmware updates. Learn more about PlatformIO here.
To use this library in your PlatformIO project, simply add to your platformio.ini a dependency (id=1744) as following:
lib_deps =
ESP_VS1053_LibraryFrom your .cpp or .ino code include VS1053 library.
#include <VS1053.h>Afterwards simply instantiate an object of VS1053 player as below:
VS1053 player(CS, DCS, DREQ);Then initialize the player and use as in following example:
player.begin();
if (player.getChipVersion() == 4) { // Only perform an update if we really are using a VS1053, not. eg. VS1003
player.loadDefaultVs1053Patches();
}
player.setVolume(VOLUME);
player.switchToMp3Mode();
player.playChunk(sampleMp3, sizeof(sampleMp3));For complete code please check examples folder. The example plays the sound like this (click to listen to the sound) every three seconds.
Please note that player.switchToMp3Mode() is an optional switch. Some of VS1053 modules will start up in MIDI mode. The result is no audio when playing MP3.
You can modify the board, but there is a more elegant way without soldering. For more details please read a discussion here: http://www.bajdi.com/lcsoft-vs1053-mp3-module/#comment-33773.
No side effects for boards which do not need this switch, so you can call it just in case.
Below briefly described. For detailed information please see VS1053b Datasheet specification.
To check if the VS1053 chip is connected and able to exchange data to the microcontroller use the player.isChipConnected().
This is a lightweight method to check if VS1053 is correctly wired up (power supply and connection to SPI interface).
For additional information please see this issue.
A lot of the VS1003 and VS1053 devices completely look the same. They are even both labeled with "VS1003/1053 MP3 CODEC". To check which chip you are using use the player.getChipVersion(). It should return 4 for VS1053 and 3 for VS1003. This is also a lightweight method to check whether your VS10xx device is wired up correctly.
uint16_t seconds = player.getDecodedTime();
Above example and self-explanatory method name tells everything. It simply provides current decoded time in full seconds (from SCI_DECODE_TIME register value).
Optionally available is also player.clearDecodedTime() which clears decoded time (sets SCI_DECODE_TIME register to 0x00).
player.enableI2sOut(/* i2sRate: optional sampling rate, default is 48kHz */);
player.disableI2sOut();
I2S output of the VS1053 chip can be enabled/disabled using methods enableI2sOut and disableI2sOut. When enabled, the gpio lines won't be available for other purposes. On reset the I2S output is disabled. The assignment to I2S lines is according to the table below:
| VS1053 GPIO | I2S |
|---|---|
| 4 | LROUT / WSEL |
| 5 | MCLCK |
| 6 | SCLK / BCLK |
| 7 | SDATA / DOUT |
Refer to the VS1053 datasheet for details: the pin assignment is specified in section 5.1 on page 12, the I2S DAC interface is described in section 11.14 on page 83.
The library uses ESP Arduino framework built in logger (Arduino core for ESP32 and ESP8266).
To see debug messages please add build flags to your platformio.ini as below (depending on platform):
- for ESP8266:
build_flags = -D DEBUG_ESP_PORT=Serial
- for ESP32:
build_flags = -DCORE_DEBUG_LEVEL=ARDUHAL_LOG_LEVEL_DEBUG
The Serial Interface needs to be initialized in the setup().
void setup() {
Serial.begin(115200);
}Now if something is wrong, you'll see the output like below (from ESP32):
[I][main.cpp:117] setup(): Hello # VS1053!
[D][VS1053.cpp:156] begin():
[D][VS1053.cpp:157] begin(): Reset VS1053...
[D][VS1053.cpp:161] begin(): End reset VS1053...
[D][VS1053.cpp:119] testComm(): VS1053 not properly installed!In successful case it would start with something like this:
[I][main.cpp:117] setup(): Hello # VS1053!
[D][VS1053.cpp:156] begin():
[D][VS1053.cpp:157] begin(): Reset VS1053...
[D][VS1053.cpp:161] begin(): End reset VS1053...
[D][VS1053.cpp:132] testComm(): Slow SPI,Testing VS1053 read/write registers...
[D][VS1053.cpp:132] testComm(): Fast SPI, Testing VS1053 read/write registers again...
[D][VS1053.cpp:183] begin(): endFillByte is 0An example for ESP8266 based board like eg. LoLin NodeMCU V3 or WeMos D1 R2.
| VS1053 | ESP8266 |
|---|---|
| SCK | D5 |
| MISO | D6 |
| MOSI | D7 |
| XRST | RST |
| CS | D1 |
| DCS | D0 |
| DREQ | D3 |
| 5V | VU |
| GND | G |
For ESP32 and other boards wiring examples please see thread Supported hardware and Tested boards list.
Please feel invited to provide your pull request with improvement or a bug fix.
A hint for CLion developers.
The IDE files are added to .gitignore, but once you clone the code you should be able to develop the
library easily with CLion after calling the command from terminal as below:
$ platformio init --ide=clionThen please import the project and run the PIO task: PLATFORMIO_REBUILD_PROJECT_INDEX.
Read more here: PlatformIO & CLion integration.
If you think how to convert the mp3 file into C header file, please find a thread here. It's as simple as calling:
xxd -i your-sound.mp3 ready-to-use-c-header.h
The xxd is available for any platform like Linux or Windows (distributed with Vim editor).
It will produce something like in the example here.
Of course as the file will be a part of firmware, it should be small enough according to limited microcontroller's resources The memory is at a premium ;-) I would suggest to use mp3 instead of wave, convert file from stereo to mono and use lower MP3 bit rate if possible (like 112kbps or less instead of 320kbps). Please also find additional hints here.
Based on library/applications:
Copyright (C) 2017
Licensed under GNU GPLv3