Struct Connection 

pub struct Connection { /* private fields */ }

Active connection to a PICOBOOT device

This object is used to send commands to a connected PICOBOOT capable device.

Example

    let mut picoboot = Picoboot::from_first(None).await?;
    let conn = picoboot.connect().await?;
    conn.flash_erase_start(4096).await?;
    conn.flash_write_start(&[0u8; 4096]).await?;
    let data = conn.flash_read_start(4096).await?;

Implementations

impl Connection

pub async fn reset_interface(&mut self) -> Result<(), Error>

Resets PICOBOOT USB interface.

This may be called after opening a brand new connection to ensure a consistent starting state, or to reset a stalled connection.

Note that this resets any exclusive access, re-enabling the USB mass storage device if it was ejects due to exclusivity.

Returns:

• Ok(()) - If interface is successfully reset.

pub async fn send_cmd( &mut self, cmd: PicobootCmd, buf: Option<&[u8]>, ) -> Result<Vec<u8>, Error>

Sends a low-level command to the PICOBOOT device.

Depending on the command, the buffer argument may be used to send data to the device.

Depending on the command, the returned Vec may contain data from the device.

Returns:

• Ok(Vec<u8>) - Data returned from the device, if any.

pub async fn set_exclusive_access( &mut self, access: Access, ) -> Result<(), Error>

Requests an exclusive access mode with the device.

Returns:

• Ok(()) - If the exclusive access mode is successfully set.

pub async fn reboot(&mut self, delay: Duration) -> Result<(), Error>

Performs a simple reboot of the device.

Args:

• delay - Time to start the device after. Must fit into a u32 milliseconds.

For a target Target::Custom this command is not supported - use Self::reboot_rp2040 or Self::reboot_rp2350 instead.

Returns:

• Ok(()) - If reboot command is successfully sent.

pub async fn reboot_rp2040( &mut self, program_counter: u32, stack_pointer: u32, delay: Duration, ) -> Result<(), Error>

Reboots the device with a specified program counter, stack pointer, and delay.

Note, reboot is not supported on the RP2350.

• program_counter - Program counter to start the device with. Use 0 for a standard flash boot, or a RAM address to start executing at.
• stack_pointer - Stack pointer to start the device with. Unused if program_counter is 0.
• delay - Time to start the device after. Must fit into a u32 milliseconds.

Returns:

• Ok(()) - If reboot command is successfully sent.

pub async fn reboot_rp2350( &mut self, flags: u32, p0: u32, p1: u32, delay: Duration, ) -> Result<(), Error>

Reboots the device out of BOOTSEL mode into normal operation

Note, not supported on the RP2040.

Args:

• flags - Reboot flags to use.
• p0 - Reboot parameter 0.
• p1 - Reboot parameter 1.
• delay - Time to start the device after. Must fit into a u32 milliseconds.

See the RP2350 datasheet, section 5.4.8.24. reboot for details on the flags and parameters. For a standard boot, set them all to 0.

Returns:

• Ok(()) - If reboot command is successfully sent.

pub async fn flash_erase_start(&mut self, size: usize) -> Result<(), Error>

Erases the flash memory of the device from the start

Args:

• size - Number of bytes to erase. Will be rounded up to the nearest multiple of Target::flash_sector_size.

Returns:

• Ok(()) - If erase command is successfully sent.

pub async fn flash_erase(&mut self, addr: u32, size: u32) -> Result<(), Error>

Erases the flash memory of the device.

• addr - Address to start the erase. Must be on a multiple of Target::flash_sector_size.
• size - Number of bytes to erase. Must be a multiple of Target::flash_sector_size.

Returns:

• Ok(()) - If erase command is successfully sent.

pub async fn flash_write_start(&mut self, buf: &[u8]) -> Result<(), Error>

Writes a buffer to the start of the flash memory of the device.

Args:

• buf - Buffer of data to write to flash. Should be a multiple of Target::flash_page_size. If not, the remainder of the final page is zero-filled.

Returns:

• Ok(()) - If write command is successfully sent.

pub async fn flash_write(&mut self, addr: u32, buf: &[u8]) -> Result<(), Error>

Writes a buffer to the flash memory of the device.

• addr - Address to start the write. Must be on a multiple of Target::flash_page_size.
• buf - Buffer of data to write to memory. Should be a multiple of Target::flash_page_size. If not, the remainder of the final page is zero-filled.

Returns:

• Ok(()) - If write command is successfully sent.

pub async fn write(&mut self, addr: u32, buf: &[u8]) -> Result<(), Error>

Writes a buffer to the (RAM) memory of the device.

For flash, use flash_write() as that polices valid flash write addresses and sizes.

• addr - Address to start the write.
• buf - Buffer of data to write to memory.

pub async fn flash_read_start(&mut self, size: u32) -> Result<Vec<u8>, Error>

Reads from the start of flash memory of the device.

• addr - Address to start the read.
• size - Number of bytes to read.

Returns:

• Ok(Vec<u8>) - Buffer of data read from flash.

pub async fn flash_read( &mut self, addr: u32, size: u32, ) -> Result<Vec<u8>, Error>

Reads from the flash memory of the device.

• addr - Address to start the write. Must be on a multiple of Target::flash_page_size.
• size - Amount of read. Should be a multiple of Target::flash_page_size. If not, it will be rejected.

pub async fn read(&mut self, addr: u32, size: u32) -> Result<Vec<u8>, Error>

Reads from memory of the device.

For flash reads, use flash_read() or flash_read_start() as that polices valid flash read addresses and sizes.

pub async fn enter_xip(&mut self) -> Result<(), Error>

Enter Flash XIP (execute-in-place) mode.

Only functional on RP2040 devices - is a no-op on RP2350.

Returns:

• Ok(()) - If enter XIP command is successfully sent.

pub async fn exit_xip(&mut self) -> Result<(), Error>

Exits Flash XIP (execute-in-place) mode.

Only functional on RP2040 devices - is a no-op on RP2350.

Returns:

• Ok(()) - If exit XIP command is successfully sent.

pub fn target(&mut self) -> &Target

Returns the target type of the connected PICOBOOT device

pub async fn get_command_status(&mut self) -> Result<PicobootStatusCmd, Error>

Issues a GET_COMMAND_STATUS control request to the device and returns the result.

pub async fn send_picobootx_cmd( &mut self, cmd: PicobootXCmd, buf: Option<&[u8]>, ) -> Result<Vec<u8>, Error>

Sends a custom picobootx protocol extension command to the device.

Follows identical protocol mechanics to send_cmd but accepts an arbitrary magic value. The caller is responsible for constructing valid args for their extension protocol using the PicobootXCmd struct.

Trait Implementations

impl Clone for Connection

fn clone(&self) -> Connection

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.