Struct FlashArray 

pub struct FlashArray<const N: usize>;

Available on non-crate feature host only.

A device abstraction for type-safe persistent storage in flash memory.

This struct provides a generic flash-block storage system for Raspberry Pi Pico, allowing you to store any serde-compatible type in the device’s internal flash.

You choose the number of storage blocks at compile time. Each block holds up to 3900 bytes of postcard-serialized data (a hardware-determined 4 KB flash block minus metadata space).

Features

• Type safety: Hash-based type checking prevents reading data written under a different Rust type name. The hash is derived from the full type path (for example, app1::BootCounter). Trying to read a different types returns Ok(None). Structural changes (adding or removing fields) do not change the hash, but may cause deserialization to fail and return an error.
• Postcard serialization: A compact, no_std-friendly binary format.

Block allocation

Conceptually, flash is treated as an array of fixed-size erase blocks counted from the end of memory backward. Your code can split that array using destructuring assignment and hand individual blocks to subsystems that need persistent storage.

⚠️ Warning: Pico 1 and Pico 2 store firmware, vector tables, and user data in the same flash device. Allocating too many blocks can overwrite your firmware.

Example

use device_envoy::flash_array::FlashArray;

/// Boot counter (newtype) that wraps at 10.
/// Stored with `postcard` (Serde).
#[derive(serde::Serialize, serde::Deserialize, Debug, Clone, Copy)]
struct BootCounter(u8);

impl BootCounter {
    const fn new(value: u8) -> Self {
        Self(value)
    }

    fn increment(self) -> Self {
        Self((self.0 + 1) % 10)
    }
}

async fn example() -> device_envoy::Result<Infallible> {
    let p = embassy_rp::init(Default::default());

    // Create a flash array. You can destructure it however you like.
    let [mut boot_counter_flash_block] = FlashArray::<1>::new(p.FLASH)?;

    // Read boot counter from flash then increment.
    // FlashArray includes a runtime type hash so values are only loaded
    // if the stored type matches the requested type; mismatches yield `None`.
    let boot_counter = boot_counter_flash_block
        .load()?
        .unwrap_or(BootCounter::new(0)) // Default to 0 type not present
        .increment();

    // Write incremented counter back to flash.
    // This example writes once per power-up (fine for a demo; don't write in a tight loop).
    // Flash is typically good for ~100K erase cycles per block.
    boot_counter_flash_block.save(&boot_counter)?;

    info!("Boot counter: {}", boot_counter.0);
    future::pending().await // Keep running
}

Implementations

impl<const N: usize> FlashArray<N>

pub fn new(peripheral: Peri<'static, FLASH>) -> Result<[FlashBlock; N]>

Reserve N contiguous blocks and return them as an array that you can destructure however you like.

See FlashArray for usage examples.

Examples found in repository

examples/wifiauto2.rs (line 30)

async fn inner_main(spawner: embassy_executor::Spawner) -> Result<Infallible> {
    let p = embassy_rp::init(Default::default());

    let [wifi_flash] = FlashArray::<1>::new(p.FLASH)?;

    let wifi_auto = WifiAuto::new(
        p.PIN_23,  // CYW43 power
        p.PIN_24,  // CYW43 clock
        p.PIN_25,  // CYW43 chip select
        p.PIN_29,  // CYW43 data
        p.PIO0,    // WiFi PIO
        p.DMA_CH0, // WiFi DMA
        wifi_flash,
        p.PIN_13, // Button for reconfiguration
        PressedTo::Ground,
        "PicoAccess", // Captive-portal SSID
        [],           // Any extra fields
        spawner,
    )?;

    let (_stack, _button) = wifi_auto.connect(|_event| async move { Ok(()) }).await?;

    future::pending().await // run forever
}

examples/wifiauto1.rs (line 31)

async fn inner_main(spawner: embassy_executor::Spawner) -> Result<Infallible> {
    let p = embassy_rp::init(Default::default());

    let [wifi_flash] = FlashArray::<1>::new(p.FLASH)?;

    let wifi_auto = WifiAuto::new(
        p.PIN_23,  // CYW43 power
        p.PIN_24,  // CYW43 clock
        p.PIN_25,  // CYW43 chip select
        p.PIN_29,  // CYW43 data
        p.PIO0,    // WiFi PIO
        p.DMA_CH0, // WiFi DMA
        wifi_flash,
        p.PIN_13, // Button for reconfiguration
        PressedTo::Ground,
        "PicoAccess", // Captive-portal SSID
        [],           // Any extra fields
        spawner,
    )?;

    let (stack, _button) = wifi_auto
        .connect(|event| async move {
            match event {
                WifiAutoEvent::CaptivePortalReady => {
                    defmt::info!("Captive portal ready");
                }
                WifiAutoEvent::Connecting { .. } => {
                    defmt::info!("Connecting to WiFi");
                }
                WifiAutoEvent::ConnectionFailed => {
                    defmt::info!("WiFi connection failed");
                }
            }
            Ok(())
        })
        .await?;

    // The stack is ready for network operations (for example, NTP or HTTP).
    defmt::info!("WiFi connected");

    loop {
        if let Ok(addresses) = stack.dns_query("google.com", DnsQueryType::A).await {
            defmt::info!("google.com: {:?}", addresses);
        } else {
            defmt::info!("google.com: lookup failed");
        }
        Timer::after(Duration::from_secs(15)).await;
    }
}

examples/flash.rs (line 47)

async fn inner_main(_spawner: Spawner) -> Result<()> {
    info!("Flash Storage Example");

    // Initialize hardware
    let p = embassy_rp::init(Default::default());

    // Initialize Flash device
    let [_, _, _, mut string_block, mut config_block] = FlashArray::<5>::new(p.FLASH)?;

    info!("Part 1: Storing data to flash");
    string_block.save(&String::<64>::try_from("Hello, Flash Storage!")?)?;
    config_block.save(&SensorConfig {
        name: String::<32>::try_from("Temperature")?,
        sample_rate_hz: 1000,
        enabled: true,
    })?;

    info!("Part 2: Reading data from flash");
    let string: Option<String<64>> = string_block.load()?;
    assert!(string.as_deref() == Some("Hello, Flash Storage!"));
    let config: Option<SensorConfig> = config_block.load()?;
    assert!(
        config
            == Some(SensorConfig {
                name: String::<32>::try_from("Temperature")?,
                sample_rate_hz: 1000,
                enabled: true,
            })
    );

    info!("Part 3: Reading a different type counts as empty");
    // Try to read the string block as a SensorConfig
    let wrong_type_result: Option<SensorConfig> = string_block.load()?;
    assert!(wrong_type_result.is_none());

    info!("Part 4: Clearing flash blocks");
    string_block.clear()?;
    config_block.clear()?;

    info!("Part 5: Verifying cleared blocks");
    let string: Option<String<64>> = string_block.load()?;
    assert!(string.is_none());
    let config: Option<SensorConfig> = config_block.load()?;
    assert!(config.is_none());

    info!("Flash Storage Example Complete!");
    loop {
        embassy_time::Timer::after_secs(1).await;
    }
}

examples/wifiauto3.rs (line 29)

async fn inner_main(spawner: embassy_executor::Spawner) -> Result<core::convert::Infallible> {
    let p = embassy_rp::init(Default::default());

    let [wifi_flash, website_flash, timezone_flash] = FlashArray::<3>::new(p.FLASH)?;

    static WEBSITE_STATIC: TextFieldStatic<32> = TextField::new_static();
    let website_field = TextField::new(
        &WEBSITE_STATIC,
        website_flash,
        "website",
        "Website",
        "google.com",
    );

    // Create timezone field
    static TIMEZONE_STATIC: TimezoneFieldStatic = TimezoneField::new_static();
    let timezone_field = TimezoneField::new(&TIMEZONE_STATIC, timezone_flash);

    let wifi_auto = WifiAuto::new(
        p.PIN_23,  // CYW43 power
        p.PIN_24,  // CYW43 clock
        p.PIN_25,  // CYW43 chip select
        p.PIN_29,  // CYW43 data
        p.PIO0,    // WiFi PIO
        p.DMA_CH0, // WiFi DMA
        wifi_flash,
        p.PIN_13, // Button for reconfiguration
        PressedTo::Ground,
        "PicoAccess",                    // Captive-portal SSID
        [website_field, timezone_field], // Custom fields
        spawner,
    )?;

    let (stack, _button) = wifi_auto
        .connect(|event| async move {
            match event {
                WifiAutoEvent::CaptivePortalReady => {
                    defmt::info!("Captive portal ready");
                }
                WifiAutoEvent::Connecting {
                    try_index,
                    try_count,
                } => {
                    defmt::info!(
                        "Connecting to WiFi (attempt {} of {})...",
                        try_index + 1,
                        try_count
                    );
                }
                WifiAutoEvent::ConnectionFailed => {
                    defmt::info!("WiFi connection failed");
                }
            }
            Ok(())
        })
        .await?;

    let website = website_field.text()?.unwrap_or_default();
    let offset_minutes = timezone_field
        .offset_minutes()?
        .ok_or(Error::MissingCustomWifiAutoField)?;
    defmt::info!("Timezone offset minutes: {}", offset_minutes);

    loop {
        let query_name = website.as_str();
        if let Ok(addresses) = stack
            .dns_query(query_name, embassy_net::dns::DnsQueryType::A)
            .await
        {
            defmt::info!("{}: {:?}", query_name, addresses);
        } else {
            defmt::info!("{}: lookup failed", query_name);
        }

        embassy_time::Timer::after(embassy_time::Duration::from_secs(15)).await;
    }
}

examples/clock_console.rs (line 39)

async fn inner_main(spawner: Spawner) -> Result<Infallible> {
    info!("Starting Console Clock with WiFi");

    // Initialize RP2040 peripherals
    let p = embassy_rp::init(Default::default());

    // Use two blocks of flash storage: Wi-Fi credentials + timezone
    let [wifi_credentials_flash_block, timezone_flash_block] = FlashArray::<2>::new(p.FLASH)?;

    // Define timezone field for captive portal
    static TIMEZONE_FIELD_STATIC: TimezoneFieldStatic = TimezoneField::new_static();
    let timezone_field = TimezoneField::new(&TIMEZONE_FIELD_STATIC, timezone_flash_block);

    // Set up WiFi via captive portal
    let wifi_auto = WifiAuto::new(
        p.PIN_23,  // CYW43 power
        p.PIN_24,  // CYW43 clock
        p.PIN_25,  // CYW43 chip select
        p.PIN_29,  // CYW43 data pin
        p.PIO0,    // CYW43 PIO interface
        p.DMA_CH0, // CYW43 DMA channel
        wifi_credentials_flash_block,
        p.PIN_13, // Reset button pin
        PressedTo::Ground,
        "www.picoclock.net",
        [timezone_field],
        spawner,
    )?;

    // Connect to WiFi
    let (stack, _button) = wifi_auto
        .connect(|event| async move {
            match event {
                WifiAutoEvent::CaptivePortalReady => {
                    info!("Captive portal ready - connect to WiFi network");
                }
                WifiAutoEvent::Connecting {
                    try_index,
                    try_count,
                } => {
                    info!(
                        "Connecting to WiFi (attempt {} of {})...",
                        try_index + 1,
                        try_count
                    );
                }
                WifiAutoEvent::ConnectionFailed => {
                    info!("WiFi connection failed!");
                }
            }
            Ok(())
        })
        .await?;

    info!("WiFi connected successfully!");

    // Create ClockSync device with timezone from WiFi portal
    let timezone_offset_minutes = timezone_field
        .offset_minutes()?
        .ok_or(Error::MissingCustomWifiAutoField)?;
    static CLOCK_SYNC_STATIC: ClockSyncStatic = ClockSync::new_static();
    let clock_sync = ClockSync::new(
        &CLOCK_SYNC_STATIC,
        stack,
        timezone_offset_minutes,
        Some(ONE_SECOND),
        spawner,
    );

    info!("WiFi connected, entering event loop");

    // Main event loop - log time on every tick
    loop {
        let tick = clock_sync.wait_for_tick().await;
        let time_info = tick.local_time;
        info!(
            "Current time: {:04}-{:02}-{:02} {:02}:{:02}:{:02}",
            time_info.year(),
            u8::from(time_info.month()),
            time_info.day(),
            time_info.hour(),
            time_info.minute(),
            time_info.second(),
        );
    }
}

examples/clock_lcd.rs (line 45)

async fn inner_main(spawner: Spawner) -> Result<Infallible> {
    info!("Starting LCD Clock with WiFi");

    // Initialize RP2040 peripherals
    let p = embassy_rp::init(Default::default());

    // Initialize CharLcd
    static CHAR_LCD_STATIC: CharLcdStatic = CharLcd::new_static();
    let char_lcd = CharLcd::new(&CHAR_LCD_STATIC, p.I2C0, p.PIN_5, p.PIN_4, spawner)?;

    // Use two blocks of flash storage: Wi-Fi credentials + timezone
    let [wifi_credentials_flash_block, timezone_flash_block] = FlashArray::<2>::new(p.FLASH)?;

    // Define timezone field for captive portal
    static TIMEZONE_FIELD_STATIC: TimezoneFieldStatic = TimezoneField::new_static();
    let timezone_field = TimezoneField::new(&TIMEZONE_FIELD_STATIC, timezone_flash_block);

    // Set up WiFi via captive portal
    let wifi_auto = WifiAuto::new(
        p.PIN_23,  // CYW43 power
        p.PIN_24,  // CYW43 clock
        p.PIN_25,  // CYW43 chip select
        p.PIN_29,  // CYW43 data pin
        p.PIO0,    // CYW43 PIO interface
        p.DMA_CH0, // CYW43 DMA channel
        wifi_credentials_flash_block,
        p.PIN_13, // Reset button pin
        PressedTo::Ground,
        "www.picoclock.net",
        [timezone_field],
        spawner,
    )?;

    // Connect to WiFi
    let (stack, _button) = wifi_auto.connect(|_event| async move { Ok(()) }).await?;

    // Create ClockSync device with timezone from WiFi portal
    let timezone_offset_minutes = timezone_field
        .offset_minutes()?
        .ok_or(Error::MissingCustomWifiAutoField)?;
    static CLOCK_SYNC_STATIC: ClockSyncStatic = ClockSync::new_static();
    let clock_sync = ClockSync::new(
        &CLOCK_SYNC_STATIC,
        stack,
        timezone_offset_minutes,
        Some(ONE_SECOND),
        spawner,
    );

    info!("Entering main event loop");

    // Main orchestrator loop - owns LCD and displays the clock
    loop {
        let tick = clock_sync.wait_for_tick().await;
        let time_info = tick.local_time;
        let mut text = String::<64>::new();
        let (hour12, am_pm) = if time_info.hour() == 0 {
            (12, "AM")
        } else if time_info.hour() < 12 {
            (time_info.hour(), "AM")
        } else if time_info.hour() == 12 {
            (12, "PM")
        } else {
            #[expect(clippy::arithmetic_side_effects, reason = "hour guaranteed 13-23")]
            {
                (time_info.hour() - 12, "PM")
            }
        };
        fmt::Write::write_fmt(
            &mut text,
            format_args!(
                "{:2}:{:02}:{:02} {}\n{:04}-{:02}-{:02}",
                hour12,
                time_info.minute(),
                time_info.second(),
                am_pm,
                time_info.year(),
                u8::from(time_info.month()),
                time_info.day()
            ),
        )
        .map_err(|_| Error::FormatError)?;
        char_lcd.write_text(text, 0).await;
    }
}

Additional examples can be found in:

• examples/wifiauto_custom.rs
• examples/clock_servos.rs
• examples/clock_led8x12.rs
• examples/clock_led12x4.rs
• examples/clock_led4.rs
• examples/wifi_auto.rs