Program MATRIX Voice ESP32 with VS Code Using PlatformIO

Required Hardware

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)

Let's Get Started

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 Setup

Run 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 Extension

Here 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) Deployment

Open 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.

Windows Specific Instruction

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 Deploy

To 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 Upload

After 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 Up

Your 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 Libraries

To update PlatformIO and PlatformIO libraries run the following commands.

pio update
pio lib update

How to Connect to the ESP32 UART From Raspberry Pi

Reading 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.

Troubleshooting

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