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)
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.
SSH back into the pi, execute this command.
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.
Personal Computer Setup
Here we're installing the requirements needed to allow your PC to develop and compile ESP32 projects.
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
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
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.
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
- Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like
- Add the
exportcommand 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:
Linux and MacOS
IDF_PATH by adding the following line to
Log off and log in back to make this change effective.
Note: If you have
/bin/bashset as login shell, and both
.profileexist, then update
Run the following command to check if
IDF_PATH is set:
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:
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).
https://dl.espressif.com/dl/package_esp32_index.jsoninto 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.
- 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/starterfolder in case Arduino creates it inside
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.
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_PASSWORDthat you set in the program.
You can now upload files to your standalone ESP32 MATRIX Voice over the air!