Struct DedicatedGpioOutputBundle 

pub struct DedicatedGpioOutputBundle<'lt> { /* private fields */ }

A bundle of dedicated GPIO output drivers.

An output bundle precomputes a channel mask from one or more DedicatedGpioOutput drivers. This lets you update multiple dedicated output channels with a single low-level write.

Attaching a driver does not change any output state. Dropping the output drivers still controls when the underlying GPIO pins are released back to normal GPIO mode.

Relationship to pins

Dedicated output channels can be connected to multiple GPIO pins via DedicatedGpioOutput::with_pin. The bundle operates on channels, not individual pins: writing channel bits affects every pin connected to that channel.

Examples

use esp_hal::gpio::{
    Level,
    Output,
    OutputConfig,
    dedicated::{DedicatedGpio, DedicatedGpioOutput, DedicatedGpioOutputBundle},
};

// Create channels:
let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);

// Create output drivers for three channels:
let out0 = DedicatedGpioOutput::new(channels.channel0);
let out1 = DedicatedGpioOutput::new(channels.channel1);
let out2 = DedicatedGpioOutput::new(channels.channel2);

// Attach GPIO pins to the dedicated outputs (any number of pins per channel):
let p0 = Output::new(peripherals.GPIO0, Level::Low, OutputConfig::default());
let p1 = Output::new(peripherals.GPIO1, Level::Low, OutputConfig::default());
let p2 = Output::new(peripherals.GPIO2, Level::Low, OutputConfig::default());

let out0 = out0.with_pin(p0);
let out1 = out1.with_pin(p1);
let out2 = out2.with_pin(p2);

// Build a bundle that controls channels 0..=2:
let mut bundle = DedicatedGpioOutputBundle::new();
bundle
    .enable_output(&out0)
    .enable_output(&out1)
    .enable_output(&out2);

// Set channel 0 and 2 high, keep channel 1 unchanged:
bundle.set_high(0b101);

// Now drive all channels in the bundle at once:
// - ch0 = 0
// - ch1 = 1
// - ch2 = 0
bundle.write_bits(0b010);

Implementations

impl<'lt> DedicatedGpioOutputBundle<'lt>

pub fn new() -> Self

Creates a new, empty dedicated GPIO output bundle.

A bundle is a logical grouping of one or more DedicatedGpioOutput drivers. Internally, it stores a precomputed channel mask (see Self::mask) which allows writing multiple dedicated GPIO channels efficiently.

The returned bundle initially contains no channels. Add outputs using Self::enable_output.

Notes

• Creating a bundle does not configure any hardware by itself.

pub fn mask(&self) -> u32

Returns the channel mask of this bundle.

Each bit corresponds to one dedicated GPIO channel:

• bit 0 -> channel 0
• bit 1 -> channel 1
• …

A bit is set to 1 if that channel is currently included in the bundle.

Example

use esp_hal::gpio::{
    Level,
    Output,
    OutputConfig,
    dedicated::{DedicatedGpio, DedicatedGpioOutput, DedicatedGpioOutputBundle},
};

let channels = DedicatedGpio::new(peripherals.GPIO_DEDICATED);
let out0 = DedicatedGpioOutput::new(channels.channel0).with_pin(Output::new(
    peripherals.GPIO0,
    Level::Low,
    OutputConfig::default(),
));
let out2 = DedicatedGpioOutput::new(channels.channel2).with_pin(Output::new(
    peripherals.GPIO2,
    Level::Low,
    OutputConfig::default(),
));
let mut bundle = DedicatedGpioOutputBundle::new();
bundle.enable_output(&out0).enable_output(&out2);

let mask = bundle.mask(); // bit 0 -> ch0, bit 2 -> ch2, ...
// For this bundle: mask == 0b0000_0101 (channels 0 and 2).

pub fn enable_output<'d>( &mut self, out: &'lt DedicatedGpioOutput<'d>, ) -> &mut Self

Attaches (enables) a dedicated output driver in this bundle. After enabling, you will be able to control the output channels of out via this bundle.

This method logically borrows the provided DedicatedGpioOutput for the lifetime 'lt. Multiple bundles may borrow the same output driver at the same time. Check examples in the module-level documentation for more.

Notes

• This function does not change any GPIO output state.

pub fn disable_output<'d>( &mut self, out: &'lt DedicatedGpioOutput<'d>, ) -> &mut Self

Disables a dedicated output driver in this bundle.

This updates the internal mask by clearing the channel bit(s) of out. After disabling, future bundle operations will no longer touch those channels.

Notes

• This does not affect out itself. It only changes which channels future bundle operations will touch.
• This does not end the lifetime-based borrow of out. Even after disabling, out still cannot be moved or dropped while this bundle exists.
• You can re-enable it later via Self::enable_output.

pub fn set_high(&mut self, bits: u32)

Sets selected channels high.

For every bit set to 1 in bits, the corresponding dedicated output channel is driven high. Bits set to 0 are left unchanged.

Example

bundle.set_high(0b1011_0001) sets channels 0, 4, 5, and 7 high.

The caller must ensure that bits only contains channels included in this bundle, i.e. bits & !self.mask() == 0.

For example, if the bundle mask is 0b0000_1011 (channels 0, 1, and 3), then bits must not set bit 2 (e.g. 0b0000_0100), or you would modify channel 2 outside the bundle.

When compiled with debug-assertions, this condition is checked at runtime.

pub fn set_low(&mut self, bits: u32)

Sets selected channels low.

For every bit set to 1 in bits, the corresponding dedicated output channel is driven low. Bits set to 0 are left unchanged.

Example

bundle.set_low(0b1011_0001) sets channels 0, 4, 5, and 7 low.

The caller must ensure that bits only contains channels included in this bundle, i.e. bits & !self.mask() == 0.

For example, if the bundle mask is 0b0000_1011 (channels 0, 1, and 3), then bits must not set bit 7 (e.g. 0b1000_0000), or you would clear channel 7 outside the bundle.

When compiled with debug-assertions, this condition is checked at runtime.

pub fn write_bits(&mut self, bits: u32)

Writes output levels for all channels included by this bundle.

This method updates the output state of every channel whose bit is set in Self::mask. Channels not included in the bundle are not modified.

bits provides the level for each channel in the bundle:

• bit = 0 -> low
• bit = 1 -> high

Example

If self.mask() is 0b1111_0000 (bundle contains channels 4..=7), then bundle.write_bits(0b0001_0000) sets channel 4 high and channels 5..=7 low, while leaving channels 0..=3 unchanged.

This function only writes channels selected by Self::mask. It will not change channels outside the mask, even if bits contains 1s there.

Make sure this “masked write” behavior matches what you intend.

pub fn output_levels(&self) -> u32

Returns the current output levels of the channels included by this bundle.

For channels outside the bundle mask, the corresponding bits are always 0.

Example

If the bundle mask is 0b0000_1011 (channels 0, 1, and 3), then output_levels() will only contain bits 0, 1, and 3, regardless of the output state of other channels.

Trait Implementations

impl<'lt> Default for DedicatedGpioOutputBundle<'lt>

Available on crate feature unstable only.

fn default() -> Self

Returns the “default value” for a type.