Flash Firmware

Flash the latest OmiGlass firmware using PlatformIO

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:

Environment	Upload Speed	Debug Level	Use Case
seeed_xiao_esp32s3	115200 baud	Low (Level 1)	Recommended - Standard build for most users
seeed_xiao_esp32s3_slow	57600 baud	High (Level 5)	Connection issues or detailed debugging

Advanced: Build Without Uploading

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

Upload Failed - Device Not Found

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

Permission Denied Error

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.

Compilation Errors

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
  

Upload Hangs or Times Out

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