Before getting started, let's review what you'll need.
- Raspberry Pi 3 (Recommended) or Pi 3 Model B+ (Supported).
- MATRIX Voice ESP32 version - Buy the MATRIX Voice.
- Micro-USB power adapter for Raspberry Pi.
- Micro-SD Card (Minimum 8 GB)
- Micro-USB Cable
- A computer with monitor to SSH into your Raspberry Pi.
- Internet connection (Ethernet or WiFi)
If you are starting with a fresh install of Raspbian on your Raspberry Pi, first you must setup your OS with the basic MATRIX device packages.
1. Raspberry Pi SetupRun the following commands inside your Raspberry Pi terminal to install the MATRIX Voice Software. This will keep the FPGA firmware updated and install a few tools to flash the ESP-WROOM-32.
Add the MATRIX repository and key.
curl https://apt.matrix.one/doc/apt-key.gpg | sudo apt-key add - && echo "deb https://apt.matrix.one/raspbian $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/matrixlabs.list
Update your repository and packages.
sudo apt-get update
sudo apt-get upgrade
Install the MATRIX init package.
sudo apt install matrixio-creator-init
Reboot your Raspberry Pi.
sudo reboot
SSH back into the pi, execute this command.
sudo voice_esp32_enable
Reset the ESP32 flash memory.
esptool.py --chip esp32 --port /dev/ttyS0 --baud 115200 --before default_reset --after hard_reset erase_flash
2. Setting Up Visual Studio Code and the PlatformIO ExtensionHere we're installing the requirements needed to allow your PC to develop and compile ESP32 projects.First install git from https://git-scm.com/downloads.
You can install the Visual Studio Code text editor here and the PlatformIO extension here. PlatformIO also has support for the Atom text editor.
PlatformIO comes preinstalled with Espressif IDF, the library necessary to develop on the ESP32.
To execute PlatformIO commands from any terminal please follow the instructions here.
Once you have completed the above items, run the following command to clone the PlatformIO project.
git clone https://github.com/matrix-io/esp32-platformio
3. Set Up WiFi Parameters for OTA (Over The Air) DeploymentOpen Visual Studio Code and open the PlatformIO home hub.
Click on Open Project
and select the esp32-platformio
folder.
Once inside the esp32-platformio
folder, open platformio.ini
.The example code in the initial src/main.cpp
file uses OTA updates to easily re-deploy code to the ESP32.To enable OTA updates, make sure to change the "SSID_GOES_HERE" and "PASSWORD_GOES_HERE" to your actual WiFi SSID and password.
If you are using Windows, also replace the upload_port
parameter inside platformio.ini
with the IP of your MATRIX VOICE ESP32.
For example, if your IP is 192.168.1.1
then change
upload_port = 'MVESP.local'
to
upload_port = 192.168.1.1
4. Initial Build and DeployTo compile the code, click on the button with the check mark on the bottom left corner of Visual Studio Code. This will build and compile the code to .pio/build/lolin32/firmware.bin
in the esp32-platformio
directory.Alternatively you can run pio run
while in the esp32-platformio
directory.
To deploy the compiled firmware, run the commands below. Replace YOUR_PI_IP_HERE
with the IP of your Raspberry Pi. If you are running Windows, please use Git Bash
as your terminal for the following commands.
cd esp32-platformio/ota
./install.sh YOUR_PI_IP_HERE
Deploying After Initial UploadAfter the initial upload, all successive uploads can be done through OTA or through the install.sh script above.
To upload using OTA, open a terminal, go into the project directory, and run this command.
pio run --target upload
Finishing UpYour MATRIX Voice ESP32 should now be running the deployed example. With the program properly flashed in the ESP32, the Voice can now run without the Pi if you choose to do so. Ensure the MATRIX Voice and Pi are not powered before connecting or disconnecting.
The deployed code can be found in the src/main.cpp
file inside the esp32-platformio
directory.
More examples can be found here.
Updating PlatformIO LibrariesTo update PlatformIO and PlatformIO libraries run the following commands.
pio update
pio lib update
How to Connect to the ESP32 UART From Raspberry PiReading the serial output from the ESP32 can be useful for debugging. In order to do so, you can use minicom
and the MATRIX VOICE ESP32 must be connected to the Pi.
First install minicom
on your Raspberry Pi.
sudo apt install minicom
Then to connect and read from serial, run the following command.
sudo minicom -D /dev/ttyS0
To close minicom, press Ctrl+A
then X
.
If the pio run --target upload
command does not work, please check the MVID
parameter inside platformio.ini
, it should have a maximum length of 8 characters. Alternatively, you can pass the ESP32's IP in the upload_port
parameter inside platformio.ini
.If pio run --target upload
still does not work, try running the below command instead, replacing 'MVESP.local'
with the data from the upload_port
parameter inside platformio.ini
.
~/.platformio/packages/framework-arduinoespressif32/tools/espota.py --port=3232 --auth=voice --debug --progress -i 'MVESP.local' -f .pio/build/esp32dev/firmware.bin
If you encounter issues with building try removing build files, reinstalling libraries, and rebuilding project with the following commands.
pio run -t clean && rm -r .pio
pio run
Comments