Skip to main content
This guide walks you through flashing the OmiGlass firmware to your ESP32 S3 XIAO board using PlatformIO.

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Install PlatformIO

PlatformIO is required to build and flash the firmware. Install it using one of these methods:Using Homebrew (macOS/Linux):
brew install platformio
Using pip (All platforms):
pip install platformio
Verify installation:
platformio --version
2

Install Required Libraries

PlatformIO will automatically install the required libraries when you build the firmware. The dependencies include:
  • NimBLE-Arduino (v1.4.1+) - Bluetooth Low Energy stack
  • esp32-camera (v2.0.0+) - Camera driver for ESP32
  • arduino-libopus - Audio codec for voice encoding
These are automatically downloaded from the platformio.ini configuration.
3

Connect Your Device

Connect your ESP32 S3 XIAO board to your computer via USB-C cable.
Use a quality USB-C cable that supports data transfer, not just charging.

​
Flash the Firmware

Navigate to the firmware directory and flash using PlatformIO:
1

Navigate to Firmware Directory

cd omiGlass/firmware
2

Build and Upload Firmware

Try the standard build environment first:
platformio run -e seeed_xiao_esp32s3 --target upload
If you experience connection issues, use the slower upload environment:
platformio run -e seeed_xiao_esp32s3_slow --target upload
The seeed_xiao_esp32s3_slow environment uses a slower upload speed (57600 baud) which is more reliable for some USB connections.
3

Wait for Upload

PlatformIO will:
  1. Install dependencies (first time only)
  2. Compile the firmware
  3. Upload to your device
  4. Reset the device automatically
The process takes 1-3 minutes depending on your connection.

​
Build Environments

The firmware supports two build environments:
EnvironmentUpload SpeedDebug LevelUse Case
seeed_xiao_esp32s3115200 baudLow (Level 1)Recommended - Standard build for most users
seeed_xiao_esp32s3_slow57600 baudHigh (Level 5)Connection issues or detailed debugging
If you only want to compile the firmware without uploading:
platformio run -e seeed_xiao_esp32s3
The compiled binary will be in .pio/build/seeed_xiao_esp32s3/firmware.bin

​
Troubleshooting

Problem: PlatformIO cannot find your ESP32 device.Solutions:
  • Check USB cable is properly connected
  • Try a different USB port (connect directly, not through a hub)
  • On macOS: Check System Settings > Privacy & Security for any blocked devices
  • Verify device appears with ls /dev/tty.* or ls /dev/cu.*
Problem: Cannot access the serial port.Solutions (macOS/Linux):
sudo chmod 666 /dev/tty.usbserial-*
Or add your user to the dialout group (Linux):
sudo usermod -a -G dialout $USER
Then log out and back in.
Problem: Build fails with compilation errors.Solutions:
  • Clean the build and try again: 
    platformio run --target clean
platformio run -e seeed_xiao_esp32s3 --target upload
  • Update PlatformIO: 
    pip install -U platformio
  • Delete .pio folder and rebuild: 
    rm -rf .pio
platformio run -e seeed_xiao_esp32s3 --target upload
Problem: Upload process starts but never completes.Solutions:
  • Use the slower environment: 
    platformio run -e seeed_xiao_esp32s3_slow --target upload
  • Try a different USB cable
  • Restart your computer and device

​
Next Steps

After successfully flashing the firmware:

Monitor Device

Learn how to monitor logs and test your device

Hardware Assembly

Complete hardware setup and assembly guide