Program Over the Air on ESP32 MATRIX Voice w/ Arduino IDE

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

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

voice_esp32_enable

If you get a permission denied, execute the command again with the keyword sudo before it.

Reset the ESP32 flash memory.

esptool.py --chip esp32 --port /dev/ttyS0 --baud 115200 --before default_reset --after hard_reset erase_flash

Reboot the Pi.

sudo reboot 

Personal Computer Setup

Here we're installing the requirements needed to allow your PC to develop and compile ESP32 projects.

Install Git:

• https://git-scm.com/downloads

Install ESP32 toolchain:

The ESP32 toolchain setup steps were recently updated. This guide will be updated to reflect those changes soon. For now, follow the legacy steps to get setup with your MATRIX Voice ESP32.

• Stop Following when you reach "Next Steps"
• Linux Legacy Setup: https://docs.espressif.com/projects/esp-idf/en/latest/get-started-legacy/linux-setup.html
• Mac Legacy Setup: https://docs.espressif.com/projects/esp-idf/en/latest/get-started-legacy/macos-setup.html
• Windows Legacy Setup: https://docs.espressif.com/projects/esp-idf/en/latest/get-started-legacy/windows-setup.html

Get ESP-IDF (from Espressif Docs)

Besides the toolchain, you also need ESP32-specific API (software libraries and source code). They are provided by Espressif in ESP-IDF repository.

To get a local copy of ESP-IDF, navigate to your installation directory and clone the repository with git clone.

Open Terminal, and run the following commands:

cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git

ESP-IDF will be downloaded into ~/esp/esp-idf.

Add IDF_PATH to User Profile (from Espressif Docs)

To preserve setting of IDF_PATH environment variable between system restarts, add it to the user profile, following instructions below.

Windows

The user profile scripts are contained in C:/msys32/etc/profile.d/ directory. They are executed every time you open an MSYS2 window.

• Create a new script file in C:/msys32/etc/profile.d/ directory. Name it export_idf_path.sh.
• Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like C:\msys32\home\user-name\esp\esp-idf
• Add the export command to the script file. Remember to replace back-slashes with forward-slashes in the original Windows path. E.g.:export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
• Save the script file.

Close MSYS2 window and open it again. Check if IDF_PATH is set, by typing: printenv IDF_PATH. The path previously entered in the script file should be printed out.

If you do not like to have IDF_PATH set up permanently in user profile, you should enter it manually on opening of an MSYS2 window:

export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"

Linux and MacOS

Set up IDF_PATH by adding the following line to ~/.profile file:

export IDF_PATH=~/esp/esp-idf

Log off and log in back to make this change effective.

Note: If you have /bin/bash set as login shell, and both .bash_profile and .profile exist, then update .bash_profile instead.

Run the following command to check if IDF_PATH is set:

printenv IDF_PATH

The path previously entered in ~/.profile file (or set manually) should be printed out.

If you do not like to have IDF_PATH set up permanently, you should enter it manually in terminal window on each restart or logout:

export IDF_PATH=~/esp/esp-idf

Install Arduino IDE on your PC w/ ESP32 Board Support

Starting with 1.6.4, Arduino allows installation of third-party platform packages using Boards Manager. Espressif has packages available for Windows, Mac OS, and Linux (32 and 64 bit).

• Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the Arduino website.
• Start Arduino. Go to File > Preferences (Arduino > Preferences for Mac).
• Enter https://dl.espressif.com/dl/package_esp32_index.json into Additional Board Manager URLs field. You can add multiple URLs, separating them with commas. Click "OK".
• Go to Tools > Board > Boards Manager. In the "Filter your search..." bar, type esp32, and install the latest version of esp32 by Espressif Systems platform.

Flash the First Program w/ Over the Air Code (on PC)

• Clone the following repo with MATRIX HAL code for the ESP32 (any location)

git clone https://github.com/matrix-io/matrixio_hal_esp32

• Once you have the Arduino IDE on your computer, there will be a folder called "Arduino" either in your PC's home directory or Documents directory. Copy the folder "hal" to "Arduino" > "libraries" manually or using the command below.

cp -r matrixio_hal_esp32/components/hal ~/Documents/Arduino/libraries

• Clone the following repo with MATRIX Voice OTA code to your PC (any location)

git clone https://github.com/matrix-io/esp32-arduino-ota

• Copy the folder "MATRIXVoiceOTA" to "Arduino" > "libraries" manually or using the command below.

cp -r esp32-arduino-ota/MATRIXVoiceOTA ~/Documents/Arduino/libraries

• Go into the starter directory in esp32-arduino-ota, and open the Starter.ino file in the Arduino IDE. For command line follow below.

cd esp32-arduino-ota/starter
open Starter.ino

• In the Arduino IDE, go to the "Tools" tab in the menubar, select ESP32 Dev Module as Board, set flash size to 4MB and Upload speed to 115200

• Change the SSID, and password for your WiFi, your ESP32 ID, and ESP32 password (this is of your choosing, you will be asked to enter password when uploading over OTA) to fit your needs.

• In the menubar, go to "Sketch" -> "Export compiled binary". This will create a file called Starter.ino.esp32.bin. Move the file to the esp32-arduino-ota/starter folder in case Arduino creates it inside esp32-arduino-ota/starter/Starter.

Note:Starter.ino.esp32.bin & deploy_ota.sh need to be in the same directory.

• In the starter directory, edit the file deploy_ota.sh, and change the IP address to the IP address of your Pi. You can edit the file in your terminal using nano.

nano deploy_ota.sh

After editing, you can exit nano by pressing Ctrl-X, then Y.

• In your terminal, ensure you are in the correct directory

cd esp32-arduino-ota/starter
sh deploy_ota.sh

• You will be prompted to enter your Raspberry Pi's password. Once you enter it, you should see the message: "esptool.py wrapper for MATRIX Voice".
• Watch how it flashes and when it restarts, the LED ring should turn blue.
• Remove the MATRIX Voice from the Pi and plug the power into the MATRIX Voice with a micro-USB cable, the MATRIX Voice should start
• Close & restart the Arduino IDE. After about a minute, the Matrix Voice should show up as a network port ("Tools" -> "Port"). Select this port.

• You can make changes to your code, and as long as you have the MATRIX Voice OTA methods, you can click on "Sketch" -> "Upload", and the code will upload over WiFi to your MATRIX Voice ESP32.
• The first time you upload over the air, the Arduino IDE will prompt you for your password. This is YOUR_CHOSEN_ESP32_PASSWORD that you set in the program.

You can now upload files to your standalone ESP32 MATRIX Voice over the air!