Struct stm32_i2s_v12x::I2s

pub struct I2s<I, MODE> { /* fields omitted */ }

Interface to an SPI peripheral in I2S mode

Basic sequence of operations

• Create an I2s object
• Configure it in the desired mode (master/slave, transmit/receive)
• Enable interrupts and DMA (optional)
• Enable
• Transmit or receive samples
• Disable
• Deconfigure the I2s, allowing it to be configured again differently

Example

fn use_i2s<I>(i2s: I2s<I, InitMode>) where I: Instance {
    let config = MasterConfig::with_division(
        25,
        Data16Frame16,
        FrameFormat::PhilipsI2s,
        Polarity::IdleHigh,
        MasterClock::Disble,
    );
    let mut i2s_configured = i2s.configure_master_receive(config);
    let mut samples: [i16; 64] = [0; 64];
    i2s_configured.enable();
    i2s_configured.receive_blocking(&mut samples);
    i2s_configured.disable();
}

Implementations

impl<I, MODE> I2s<I, MODE> where
    I: Instance, 

pub fn instance(&self) -> &I

Returns a reference to the enclosed peripheral instance

pub fn instance_mut(&mut self) -> &mut I

Returns a mutable reference to the enclosed peripheral instance

impl<I> I2s<I, InitMode> where
    I: Instance, 

pub fn new(instance: I) -> Self

Creates a wrapper around an instance, but does not do any configuration

pub fn configure_master_transmit<F>(
    self,
    config: MasterConfig<F>
) -> I2s<I, TransmitMode<F>> where
    F: DataFormat, 

Configures the SPI peripheral in master transmit mode

pub fn configure_master_receive<F>(
    self,
    config: MasterConfig<F>
) -> I2s<I, ReceiveMode<F>> where
    F: DataFormat, 

Configures the SPI peripheral in master receive mode

pub fn configure_slave_transmit<F>(
    self,
    config: SlaveConfig<F>
) -> I2s<I, TransmitMode<F>> where
    F: DataFormat, 

Configures the SPI peripheral in slave transmit mode

pub fn configure_slave_receive<F>(
    self,
    config: SlaveConfig<F>
) -> I2s<I, ReceiveMode<F>> where
    F: DataFormat, 

Configures the SPI peripheral in slave receive mode

impl<I, F> I2s<I, TransmitMode<F>> where
    I: Instance,
    F: DataFormat, 

Transmit mode

Both master and slave mode use the same functions to transmit. The only difference is where the clock is generated.

Slave transmit

The I2S peripheral must be enabled and the first sample should be written to the transmit register before the master starts sending clock and word select signals.

Master transmit

The first sample should be written to the transmit register just after the I2S peripheral is enabled. Once the I2S peripheral is enabled, the first sample will be transmitted and the next sample should be written to the transmit register.

pub fn ready_to_transmit(&self) -> Option<Channel>

Returns the channel on which the next sample will be transmitted, or None if a previous sample is still in the process of being transmitted

pub fn transmit(&mut self, sample: F::Sample) -> Result<(), Infallible>

Writes a sample into the transmit buffer

The I2S peripheral should normally be enabled before this function is called. However, if the data format contains 16 bits, this function can be called once before enabling the I2S to load the first sample.

If the data format contains 24 or 32 bits, the sample will be split into two write operations. This function will block until the second write has completed.

pub fn transmit_blocking(&mut self, samples: &[F::Sample])

Transmits multiple samples, blocking until all samples have been transmitted

pub fn write_data_register(&mut self, value: u16) -> Result<(), Infallible>

Writes a 16-bit value to the data register

Like transmit, this function returns Err(nb::Error::WouldBlock) if the data register contains a value that has not been transmitted yet.

Unlike transmit, this function never blocks because it performs only one 16-bit write. If the data format contains 24 or 32 bits, the calling code is responsible for dividing each sample into two chunks and calling this function twice. Details about this can be found in the microcontroller reference manual.

pub fn take_error(&mut self) -> Result<(), TransmitError>

Checks for an error and clears the error flag

pub fn set_dma_enabled(&mut self, enabled: bool)

Enables or disables DMA requests for transmission

pub fn enable(&mut self)

Enables the I2S peripheral

In master mode, this will activate the word select and clock outputs and start sending samples, with the left channel first. The first sample should be transmitted immediately after enabling the I2S.

In slave mode, this will cause the I2S peripheral to start responding to word select and clock inputs from the master device. The first sample should be written to the data register before the word select input goes low.

pub fn disable(&mut self) -> Result<(), Infallible>

Disables the I2S peripheral

To avoid stopping a transfer in the middle of a frame, this function returns WouldBlock until the current transfer is finished.

pub fn deconfigure(mut self: Self) -> I2s<I, InitMode>

Returns the I2S to init mode, allowing it to be reconfigured

This function resets all configuration options, including interrupts and DMA setup.

If the I2S peripheral is enabled, this function will block until it has finished the current transmission.

impl<I, F> I2s<I, ReceiveMode<F>> where
    I: Instance,
    F: DataFormat, 

Receive mode

Both master and slave mode use the same functions to receive. The only difference is where the clock is generated.

pub fn enable(&mut self)

Enables the I2S peripheral

In master mode, this will activate the word select and clock outputs and start receiving samples, with the left channel first. The first sample will be available shortly after enabling the I2S.

In slave mode, this will cause the I2S peripheral to start responding to word select and clock inputs from the master device.

pub fn sample_ready(&self) -> Option<Channel>

If a sample has been read in and is ready to receive, this function returns the channel it was received on.

pub fn receive(&mut self) -> Result<(F::Sample, Channel), Infallible>

Receives a sample from the data register, returning the sample and its associated channel

If the data format contains 24 or 32 bits, the sample will be split into two read operations. This function will block until the second read has completed.

pub fn receive_blocking(&mut self, samples: &mut [F::Sample])

Receives multiple samples, blocking until all samples have been received

Samples from the left and right channels will be interleaved.

pub fn read_data_register(&mut self) -> Result<(u16, Channel), Infallible>

Reads a 16-bit value from the data register, returning the value and its associated channel

Like receive, this function returns Err(nb::Error::WouldBlock) if the data register does not contain a value.

Unlike receive, this function never blocks because it performs only one 16-bit read. If the data format contains 24 or 32 bits, the calling code is responsible for calling this function twice and combining the two returned chunks into a sample. Details about this can be found in the microcontroller reference manual.

pub fn take_error(&mut self) -> Result<(), ReceiveError>

Checks if an error has occurred, and clears the overrun error flag

pub fn set_dma_enabled(&mut self, enabled: bool)

Enables or disables DMA requests for reception

pub fn disable(&mut self)

Disables the I2S

In master mode, this stops the clock, word select, and (if enabled) master clock outputs.

Caution: Before disabling the I2S, a specific sequence of operations should be performed so that the I2S peripheral does not stop in the middle of a frame. Refer to the target microcontroller reference manual for more information.

pub fn deconfigure(mut self: Self) -> I2s<I, InitMode>

Returns the I2S to init mode, allowing it to be reconfigured

This function resets all configuration options, including interrupts and DMA setup.

If the I2S peripheral is enabled, this function will disable it.

impl<I, M> I2s<I, M> where
    I: Instance,
    M: ActiveMode, 

Common functions

These interrupt functions can be used for transmission and reception.

pub fn listen(&mut self, event: Event)

Enables the interrupt signal output for an event

pub fn unlisten(&mut self, event: Event)

Disables the interrupt signal output for an event