Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/baldram/esp_vs1053_library
A library for VS1053 MP3 Codec Breakout adapted for Espressif ESP8266 and ESP32 boards.
https://github.com/baldram/esp_vs1053_library
arduino-library esp32 esp8266 esp8266-arduino platformio vs1053
Last synced: 3 days ago
JSON representation
A library for VS1053 MP3 Codec Breakout adapted for Espressif ESP8266 and ESP32 boards.
- Host: GitHub
- URL: https://github.com/baldram/esp_vs1053_library
- Owner: baldram
- License: gpl-3.0
- Fork: true (Edzelf/Esp-radio)
- Created: 2017-07-02T15:36:15.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-01-06T13:59:36.000Z (9 months ago)
- Last Synced: 2024-09-30T04:05:47.856Z (3 days ago)
- Topics: arduino-library, esp32, esp8266, esp8266-arduino, platformio, vs1053
- Language: C
- Homepage: https://platformio.org/lib/show/1744/ESP_VS1053_Library
- Size: 31.8 MB
- Stars: 113
- Watchers: 11
- Forks: 37
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# VS1053 library
This is a PlatformIO library for the generic **[VS1053 Breakout](http://www.vlsi.fi/en/products/vs1053.html)** 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](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!
## Introduction
#### How to use the 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, ...).
#### Why PlatformIO?
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](https://platformio.org/).
## Usage
#### Configure and use the library
To use this library in your PlatformIO project, simply add to your `platformio.ini` a dependency (id=1744) as following:
```ini
lib_deps =
ESP_VS1053_Library
```
From your `.cpp` or `.ino` code include VS1053 library.
```c++
#include
```
Afterwards simply instantiate an object of VS1053 player as below:
```c++
VS1053 player(CS, DCS, DREQ);
```
Then initialize the player and use as in following example:
```c++
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](https://github.com/baldram/ESP_VS1053_Library/tree/master/examples) folder.
The example plays the sound like this [(click to listen to the sound)](https://drive.google.com/open?id=1Mm4dc-sM7KjZcKmv5g1nwhe3-qtm7yUl) 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](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.
#### Additionall functionality
Below briefly described. For detailed information please see [VS1053b Datasheet specification](http://www.vlsi.fi/fileadmin/datasheets/vs1053.pdf).
##### Test VS1053 chip via `SCI_STATUS`
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](https://github.com/baldram/ESP_VS1053_Library/issues/24).
##### Get chip version via `SCI_STATUS`
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.
##### Check and reset decoding time by `SCI_DECODE_TIME`
`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`).
##### Enable I2S output
```
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](https://www.vlsi.fi/fileadmin/datasheets/vs1053.pdf) 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.
#### Logging / debugging
The library uses ESP Arduino framework built in logger (Arduino core for [ESP32](https://github.com/espressif/arduino-esp32/issues/893#issuecomment-348069135) and [ESP8266](https://github.com/esp8266/Arduino/blob/master/doc/Troubleshooting/debugging.rst#debug-level)).
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()`.
```c++
void setup() {
Serial.begin(115200);
}
```
Now if something is wrong, you'll see the output like below (from ESP32):
```shell
[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:
```shell
[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 0
```
## Example wiring
An 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](https://github.com/baldram/ESP_VS1053_Library/issues/1) and [Tested boards](https://github.com/baldram/ESP_VS1053_Library/blob/master/doc/tested-boards.md) list.
## Library developement
**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:
```sh
$ platformio init --ide=clion
```
Then please import the project and run the PIO task: `PLATFORMIO_REBUILD_PROJECT_INDEX`.
Read more here: [PlatformIO & CLion integration](http://docs.platformio.org/en/latest/ide/clion.html).
## Additional hints
If you think how to convert the mp3 file into C header file, please find a [thread here](https://www.avrfreaks.net/comment/884247#comment-884247). 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](https://github.com/baldram/ESP_VS1053_Library/blob/master/examples/Mp3PlayerDemo/SampleMp3.h).
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](https://github.com/baldram/ESP_VS1053_Library/issues/18#issuecomment-408984920).
## Credits
Based on library/applications:
* [maniacbug/VS1053](https://github.com/maniacbug/VS1053) by [J. Coliz](https://github.com/maniacbug)
* [Esp-radio](https://github.com/Edzelf/Esp-radio) by [Ed Smallenburg](https://github.com/Edzelf)
* [smart-pod](https://github.com/MagicCube/smart-pod) by [Henry Li](https://github.com/MagicCube)
## License
Copyright (C) 2017
Licensed under GNU GPLv3