The Architecture Divide: Why Array Portability Fails

When makers first learn about arrays in Arduino, they are typically using an classic Uno R3. The code works perfectly, so they upload the exact same sketch to an ESP32-S3 or a Nano 33 IoT, only to be met with silent reboots, corrupted data, or compilation errors. This is not a bug in the IDE; it is a fundamental clash of microcontroller architectures. Memory mapping, default data type sizes, and flash storage protocols vary wildly between 8-bit AVR chips and 32-bit ARM or Xtensa processors.

As of 2026, the Arduino ecosystem spans dozens of distinct silicon families. Writing robust, cross-platform code requires understanding how arrays interact with the underlying hardware. This compatibility guide dissects the hidden traps of array management and provides actionable frameworks for writing universal sketches.

Memory Architectures: SRAM Limits and Array Bounds

The most immediate point of failure when porting arrays is Static Random Access Memory (SRAM) exhaustion. Unlike desktop environments where RAM is measured in gigabytes, microcontrollers operate in kilobytes. A global array that barely fits on an ATmega2560 will instantly trigger an out-of-memory exception on an ATmega328P.

Board Model Microcontroller Total SRAM Max Safe Global Array Size Architecture
Uno R3 / Nano ATmega328P 2 KB ~1,200 bytes (leaving room for stack/heap) 8-bit AVR
Mega 2560 ATmega2560 8 KB ~6,500 bytes 8-bit AVR
Uno R4 WiFi Renesas RA4M1 32 KB ~28,000 bytes 32-bit ARM Cortex-M4
ESP32-S3 DevKit ESP32-S3 (Dual-core) 512 KB (Internal) ~400 KB (OS and WiFi buffers consume the rest) 32-bit Xtensa LX7
Teensy 4.1 NXP i.MX RT1062 1 MB (Internal) ~800 KB (Plus 8MB external PSRAM available) 32-bit ARM Cortex-M7

Note: The 'Max Safe Global Array Size' is an approximation. The system stack, hardware abstraction layer (HAL) buffers, and dynamic heap allocations will consume a portion of the advertised SRAM.

The 'Int' Illusion: Data Type Sizing Compatibility

One of the most insidious compatibility issues with arrays in Arduino stems from the C++ standard's loose definition of the int data type. The standard only dictates that an int must be at least 16 bits. It does not mandate an exact size.

The 8-Bit vs. 32-Bit Trap

  • AVR Boards (Uno, Mega): An int is 16 bits (2 bytes). An array of 100 integers consumes 200 bytes of SRAM.
  • 32-Bit Boards (ESP32, SAMD, Teensy): An int is 32 bits (4 bytes). That same array of 100 integers consumes 400 bytes of SRAM.

If your code relies on binary file reading, network packet parsing, or the sizeof() operator to calculate array lengths, porting from an Uno to an ESP32 will silently double your memory footprint and misalign your data buffers. According to the official Arduino language reference, relying on platform-specific type sizes is a primary cause of cross-board data corruption.

Expert Fix: Never use int, long, or short for arrays that interact with hardware registers, SD card files, or network streams. Always include <stdint.h> and use explicit types like int16_t, uint32_t, or int8_t. This guarantees identical memory footprints across all architectures.

Flash Storage: PROGMEM vs. Modern MMU Mapping

When you need to store large, read-only arrays—such as lookup tables for thermistors, audio waveforms, or bitmap graphics—storing them in SRAM is wasteful. Historically, Arduino developers used the PROGMEM keyword to force arrays into Flash memory.

AVR Harvard Architecture

The ATmega328P uses a Harvard architecture, meaning RAM and Flash have separate address spaces. The CPU cannot read Flash memory using standard pointers. You must use the PROGMEM attribute and specialized macros like pgm_read_byte() or pgm_read_word() from the avr-libc pgmspace library to fetch array elements.

// AVR Specific
#include <avr/pgmspace.h>
const uint8_t waveTable[256] PROGMEM = { /* data */ };
uint8_t val = pgm_read_byte(&waveTable[i]);

ESP32 and ARM Von Neumann / MMU Mapping

Modern 32-bit chips like the ESP32 and SAMD21 use Memory Management Units (MMUs) or unified address spaces that map Flash memory directly into the CPU's readable memory range. On an ESP32, any const array is automatically placed in Flash by the linker. You do not need PROGMEM, and you do not need pgm_read_byte(). Standard pointer arithmetic works perfectly.

However, if you attempt to compile AVR-specific pgmspace macros on an ESP32, the Arduino core provides a compatibility wrapper that translates them to standard reads. While this prevents compilation errors, it introduces unnecessary overhead. For true cross-platform compatibility, use compiler directives:

#if defined(__AVR__)
  #include <avr/pgmspace.h>
  #define FLASH_ARRAY const PROGMEM
  #define READ_FLASH_BYTE(addr) pgm_read_byte(addr)
#else
  #define FLASH_ARRAY const
  #define READ_FLASH_BYTE(addr) *(addr)
#endif

FLASH_ARRAY uint8_t myLookup[1024] = { /* data */ };
// Usage: uint8_t val = READ_FLASH_BYTE(&myLookup[index]);

Real-World Failure Mode: Stack Overflow in FreeRTOS Tasks

Moving from a bare-metal AVR to an ESP32 introduces an entirely new paradigm: Real-Time Operating Systems (RTOS). The ESP32 Arduino core runs on top of FreeRTOS. This fundamentally changes how local arrays are allocated.

On an Uno, declaring a local array inside loop() places it on a single, relatively large hardware stack. On an ESP32, every task created by xTaskCreate() (including the default loopTask) is assigned a strictly limited stack size, often defaulting to 8,192 bytes (8 KB).

The Crash Scenario

Consider the following function:

void processSensorData() {
  int16_t rawBuffer[3000]; // Consumes 6,000 bytes
  // ... processing logic ...
}

If this function is called within a custom FreeRTOS task on an ESP32 with a default 8 KB stack, the 6,000-byte array will instantly overflow the stack, triggering a Guru Meditation Error: Core 1 panic'ed (Unhandled debug exception) and rebooting the board.

The Compatibility Solution: For arrays larger than 1 KB on 32-bit RTOS boards, never declare them as local variables. Either declare them as static inside the function, make them global, or allocate them dynamically on the heap using malloc() or new (ensuring you free() them to prevent heap fragmentation). For deep insights into ESP32 memory allocation strategies, consult the Espressif ESP-IDF Memory Allocation documentation.

Function Passing: Array Decay and Pointer Safety

When you pass an array to a function in C++, it 'decays' into a pointer to its first element. The receiving function loses all knowledge of the array's original size. A common mistake is attempting to use the sizeof() trick inside the receiving function:

void printArray(int16_t data[]) {
  // BUG: On a 32-bit board, sizeof(data) is 4 (pointer size).
  // sizeof(data[0]) is 2. Length calculates as 2, not the actual array size.
  size_t len = sizeof(data) / sizeof(data[0]); 
}

This code will compile without warnings on every Arduino board but will yield completely incorrect lengths. To maintain cross-board compatibility, always pass the array length as an explicit secondary parameter, or use C++ std::span if your specific Arduino core supports C++20 standards (available on newer ESP32 and Teensy cores).

Cross-Platform Array Checklist

Before migrating your sketch to a new microcontroller family, run your arrays through this compatibility matrix:

  • Sizing: Are all hardware-facing arrays using <stdint.h> types (uint8_t, int32_t) instead of generic int?
  • Capacity: Does the total byte footprint of global arrays exceed 60% of the target board's SRAM? (Leaving 40% for stack/heap/OS overhead).
  • Storage: Are read-only arrays utilizing conditional PROGMEM macros to ensure Flash storage on AVR without breaking ESP32 compilation?
  • Scope: Are large buffers (>1KB) removed from local function scopes to prevent RTOS stack overflows on 32-bit boards?
  • Decay: Are array lengths being passed explicitly to functions rather than relying on sizeof() calculations inside the parameter list?

By respecting the silicon boundaries of your target hardware, you transform fragile, board-specific scripts into resilient, professional-grade firmware capable of running across the entire modern Arduino ecosystem.