Platforms and Drivers¶

PixelRoot32 supports multiple platforms through driver abstraction. This guide covers supported platforms, display drivers, audio backends, and build configuration.

Platform Feature Matrix¶

Feature	ESP32 Classic	ESP32-S3	ESP32-C3	ESP32-S2	ESP32-C6	Native (PC)
CPU Architecture	Dual Core Xtensa	Dual Core Xtensa	Single Core RISC-V	Single Core Xtensa	Single Core RISC-V	Multi-core x86/ARM
FPU (Floating Point Unit)	✅ Available	✅ Available	❌ Not Available	❌ Not Available	❌ Not Available	✅ Available
Scalar Math Backend	Float	Float	Fixed16	Fixed16	Fixed16	Float
Dual Core Support	✅ Yes	✅ Yes	❌ No	❌ No	❌ No	✅ Yes (threads)
Audio DAC Output	✅ Available	❌ Not Available	❌ Not Available	❌ Not Available	❌ Not Available	❌ N/A
Audio I2S Output	✅ Available	✅ Available	✅ Available	✅ Available	✅ Available	❌ N/A
SDL2 Audio	❌ N/A	❌ N/A	❌ N/A	❌ N/A	❌ N/A	✅ Available
WiFi	✅ Available	✅ Available	✅ Available	✅ Available	✅ Available	❌ N/A
Bluetooth	✅ Available	✅ Available	❌ Not Available	✅ Available	✅ Available	❌ N/A
Recommended Audio Core	0	0	0	0	0	N/A
Recommended Main Core	1	1	0	0	0	N/A

Supported Platforms¶

ESP32 Classic (Original)¶

Target ID: esp32dev

Key Features: - Audio DAC: Internal DAC on GPIO 25/26 for direct speaker connection - Audio I2S: Full I2S support for external DACs (e.g., PAM8302A) - Dual Core: True dual-core processing with core affinity - FPU: Hardware floating-point unit for optimal Scalar performance - Memory: Typically 520KB SRAM

Configuration:

[env:esp32dev]
platform = espressif32
board = esp32dev
build_flags = 
    -std=gnu++17
    -fno-exceptions

Audio Backend Priority: 1. DAC (simplest wiring, no external components) 2. I2S (higher quality, external amplifier required)

ESP32-S3¶

Target ID: esp32s3

Key Features: - No DAC: Internal DAC not available - I2S only for audio - Dual Core: Enhanced dual-core performance - FPU: Hardware floating-point unit - AI Instructions: Vector instructions for ML workloads - USB OTG: Native USB support - Memory: Up to 512KB SRAM + external PSRAM support

Configuration:

[env:esp32s3]
platform = espressif32
board = esp32-s3-devkitc-1
build_flags = 
    -std=gnu++17
    -fno-exceptions
    -D PIXELROOT32_NO_DAC_AUDIO  // Disable DAC since not available

Audio: I2S only (external amplifier required)

ESP32-C3¶

Target ID: esp32-c3

Key Features: - Single Core: RISC-V architecture - No FPU: Uses Fixed16 math backend automatically - No Bluetooth: WiFi only - Lower Power: Optimized for power efficiency - Memory: 400KB SRAM

Performance Impact: - Uses Fixed16 (Q16.16) math instead of float - ~30% performance improvement over software float emulation - Slightly reduced precision for physics calculations

Configuration:

[env:esp32-c3]
platform = espressif32
board = esp32-c3-devkitm-1
build_flags = 
    -std=gnu++17
    -fno-exceptions
    -D PIXELROOT32_NO_DAC_AUDIO

Audio: I2S only

ESP32-S2¶

Target ID: esp32s2

Key Features: - Single Core: Xtensa architecture - No FPU: Uses Fixed16 math backend - USB OTG: Native USB device/host/OTG - Lower Power: Optimized for battery operation - Memory: 320KB SRAM

Configuration:

[env:esp32-s2]
platform = espressif32
board = esp32-s2-saola-1
build_flags = 
    -std=gnu++17
    -fno-exceptions
    -D PIXELROOT32_NO_DAC_AUDIO

Audio: I2S only

ESP32-C6¶

Target ID: esp32-c6

Key Features: - Single Core: RISC-V architecture with extensions - No FPU: Uses Fixed16 math backend - WiFi 6: 2.4GHz WiFi 6 support - Bluetooth 5.0: LE and mesh support - Memory: 512KB SRAM

Configuration:

[env:esp32-c6]
platform = espressif32
board = esp32-c6-devkitc-1
build_flags = 
    -std=gnu++17
    -fno-exceptions
    -D PIXELROOT32_NO_DAC_AUDIO

Audio: I2S only

Native (PC/Mac/Linux)¶

Target ID: native

Key Features: - SDL2 Backend: Cross-platform windowing and input - Native Audio: SDL2 audio subsystem - Multi-threading: Full thread support - Hardware Acceleration: GPU rendering when available - Development Tools: Full debugging and profiling support

Configuration:

[env:native]
platform = native
build_flags = 
    -std=gnu++17
    -fno-exceptions
    -D PLATFORM_NATIVE

Audio: SDL2 audio (software mixing)

Build Configuration Flags¶

PixelRoot32 uses several preprocessor defines to control core assignment, driver selection, and hardware features. These can be set in your platformio.ini file using build_flags.

Core Affinity (ESP32 Only)¶

On multi-core ESP32 systems, PixelRoot32 automatically separates audio processing from the main game loop to prevent audio glitches and maximize performance.

Flag	Default	Description
`PR32_DEFAULT_AUDIO_CORE`	`0`	The ESP32 core index (0 or 1) dedicated to audio mixing and sequencing.
`PR32_DEFAULT_MAIN_CORE`	`1`	The ESP32 core index (0 or 1) where the main game loop (`run()`) executes.

Example:

build_flags = 
    -D PR32_DEFAULT_AUDIO_CORE=1
    -D PR32_DEFAULT_MAIN_CORE=0

Driver and Feature Control¶

Flag	Description
`PIXELROOT32_USE_U8G2_DRIVER`	Enables the U8G2 display driver for monochromatic OLEDs.
`PIXELROOT32_NO_TFT_ESPI`	Disables the default TFT_eSPI driver on ESP32 to save binary space.
`PIXELROOT32_ENABLE_PROFILING`	Enables low-level timing logs in the Serial monitor for drivers.
`PIXELROOT32_NO_DAC_AUDIO`	Disables the internal DAC audio backend on classic ESP32.
`PIXELROOT32_NO_I2S_AUDIO`	Disables the I2S audio backend.
`PIXELROOT32_ENABLE_DEBUG_OVERLAY`	Enables the performance overlay (FPS/Memory) when using `Engine::run()`.

Platform-Specific Configuration Examples¶

ESP32 with DAC Audio (Simplest Setup)¶

[env:esp32_dac]
platform = espressif32
board = esp32dev
build_flags = 
    -std=gnu++17
    -fno-exceptions
    ; DAC audio is enabled by default on ESP32

ESP32-S3 with I2S Audio (Recommended)¶

[env:esp32s3_i2s]
platform = espressif32
board = esp32-s3-devkitc-1
build_flags = 
    -std=gnu++17
    -fno-exceptions
    -D PIXELROOT32_NO_DAC_AUDIO  ; Explicitly disable DAC
    ; I2S is enabled by default

ESP32-C3 (Fixed16 Math)¶

[env:esp32c3_fixed16]
platform = espressif32
board = esp32-c3-devkitm-1
build_flags = 
    -std=gnu++17
    -fno-exceptions
    -D PIXELROOT32_NO_DAC_AUDIO
    ; Fixed16 math is automatic (no FPU)

Performance Characteristics¶

Scalar Math Performance¶

FPU Platforms (ESP32, S3): Native float performance
Non-FPU Platforms (C3, S2, C6): Fixed16 optimized performance
Performance Gain: ~30% FPS improvement on C3 vs software float emulation

Memory Usage by Platform¶

ESP32 Classic: 520KB SRAM baseline
ESP32-S3: 512KB SRAM + PSRAM option
ESP32-C3: 400KB SRAM (most constrained)
ESP32-S2: 320KB SRAM
ESP32-C6: 512KB SRAM

Audio Capabilities¶

DAC Output: 8-bit, direct GPIO drive (PAM8302A recommended)
I2S Output: 16-bit, external DAC required
Sample Rate: 44.1kHz (configurable)
Latency: <5ms typical

Troubleshooting Platform Issues¶

DAC Audio Not Working¶

Symptoms: No sound output on GPIO 25/26
Likely Cause: Using ESP32 variant without DAC (S3, C3, S2, C6)
Solution: Switch to I2S audio with external amplifier

Compilation Errors with Float¶

Symptoms: Linker errors or slow performance on C3/S2/C6
Likely Cause: Using float instead of Scalar
Solution: Always use Scalar type and toScalar() conversion

Dual Core Issues¶

Symptoms: Audio glitches or main loop instability
Likely Cause: Incorrect core assignment on single-core variants
Solution: Use PlatformCapabilities to detect core count

Memory Constraints¶

Symptoms: Crashes or allocation failures
Likely Cause: Running out of SRAM on constrained platforms
Solution: Use lower logical resolution, reduce entity count

Migration Between Platforms¶

Upgrading from ESP32 to ESP32-S3¶

Disable DAC audio: Add -D PIXELROOT32_NO_DAC_AUDIO
Add I2S amplifier if using audio
No code changes needed (same FPU support)

Downgrading to ESP32-C3¶

Expect Fixed16 math automatically
Single-core operation (no task pinning)
Reduce memory usage if needed
Test physics precision requirements

Porting to Native Platform¶

Use SDL2 for window management
Audio switches to SDL2 backend automatically
Full float precision available
Multi-threading fully supported

Platform Detection Code¶

#include "platforms/PlatformCapabilities.h"

auto caps = pixelroot32::platforms::PlatformCapabilities::detect();

if (caps.hasDualCore) {
    // Use dual-core optimizations
    xTaskCreatePinnedToCore(audioTask, "Audio", 4096, nullptr, 5, nullptr, caps.audioCoreId);
}

if (!caps.hasFPU) {
    // Use Fixed16-friendly algorithms
    useFixedPointOptimizations();
}

Display Drivers¶

TFT_eSPI (ESP32)¶

TFT_eSPI is the display driver for ESP32, supporting many TFT displays.

Offset and Alignment¶

Some displays (like certain ST7735 or ST7789 modules) require coordinate offsets to align the image correctly on the screen. These can be configured in DisplayConfig:

pixelroot32::graphics::DisplayConfig config(
    pixelroot32::graphics::ST7789,
    0, 240, 240, 0, 0, 
    0, 0 // xOffset, yOffset
);

U8G2 (ESP32)¶

The U8G2 driver provides support for monochrome OLED displays like SSD1306 and SH1106.

Configuration¶

// Enable in platformio.ini
build_flags = 
    -D PIXELROOT32_USE_U8G2_DRIVER

// Configure in code
pixelroot32::graphics::DisplayConfig config(
    pixelroot32::graphics::SSD1306,  // OLED type
    0, 128, 64, 0, 0,               // 128x64 resolution
    0, 0                            // No offset
);

References¶

ESP32 Arduino Core Documentation: https://docs.espressif.com/projects/arduino-esp32/
PlatformIO ESP32 Platforms: https://docs.platformio.org/en/latest/platforms/espressif32.html
PixelRoot32 Engine Configuration: See platforms/PlatformDefaults.h
Audio Backend Configuration: See audio/AudioConfig.h