Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the I2C documentation to use "controller/target" instead of "master/slave" #626

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update the I2C documentation to use "controller/target" instead of "master/slave" #626

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions embedded-hal-async/src/i2c.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,44 +23,44 @@ pub use embedded_hal::i2c::{

/// Async I2c.
pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// Reads enough bytes from slave with `address` to fill `buffer`.
/// Reads enough bytes from target with `address` to fill `buffer`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+R MAK MAK ... NMAK SP
/// Slave: SAK B0 B1 ... BN
/// Controller: ST TAD+R CAK CAK ... NCAK SP
/// Target: TAK B0 B1 ... BN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `SAK` = slave acknowledge
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
async fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
self.transaction(address, &mut [Operation::Read(read)])
.await
}

/// Writes bytes to slave with address `address`.
/// Writes bytes to target with address `address`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W B0 B1 ... BN SP
/// Slave: SAK SAK SAK ... SAK
/// Controller: ST TAD+W B0 B1 ... BN SP
/// Target: TAK TAK TAK ... TAK
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `SP` = stop condition
#[inline]
Expand All @@ -69,27 +69,27 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
.await
}

/// Writes bytes to slave with address `address` and then reads enough bytes to fill `read` *in a
/// Writes bytes to target with address `address` and then reads enough bytes to fill `read` *in a
/// single transaction*.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W O0 O1 ... OM SR SAD+R MAK MAK ... NMAK SP
/// Slave: SAK SAK SAK ... SAK SAK I0 I1 ... IN
/// Controller: ST TAD+W O0 O1 ... OM SR TAD+R CAK CAK ... NCAK SP
/// Target: TAK TAK TAK ... TAK TAK I0 I1 ... IN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Oi` = ith outgoing byte of data
/// - `SR` = repeated start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `Ii` = ith incoming byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
async fn write_read(
Expand All @@ -108,14 +108,14 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// Execute the provided operations on the I2C bus as a single transaction.
///
/// Transaction contract:
/// - Before executing the first operation an ST is sent automatically. This is followed by SAD+R/W as appropriate.
/// - Before executing the first operation an ST is sent automatically. This is followed by TAD+R/W as appropriate.
/// - Data from adjacent operations of the same type are sent after each other without an SP or SR.
/// - Between adjacent operations of a different type an SR and SAD+R/W is sent.
/// - Between adjacent operations of a different type an SR and TAD+R/W is sent.
/// - After executing the last operation an SP is sent automatically.
/// - At the end of each read operation (before SP or SR), the master does not send an acknowledge for the last byte.
/// - At the end of each read operation (before SP or SR), the controller does not send an acknowledge for the last byte.
///
/// - `ST` = start condition
/// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
/// - `TAD+R/W` = target address followed by bit 1 to indicate reading or 0 to indicate writing
/// - `SR` = repeated start condition
/// - `SP` = stop condition
async fn transaction(
Expand Down
48 changes: 24 additions & 24 deletions embedded-hal/src/i2c.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,71 +311,71 @@ pub enum Operation<'a> {

/// Blocking I2C.
pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// Reads enough bytes from slave with `address` to fill `read`.
/// Reads enough bytes from target with `address` to fill `read`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+R MAK MAK ... NMAK SP
/// Slave: SAK B0 B1 ... BN
/// Controller: ST TAD+R CAK CAK ... NCAK SP
/// Target: TAK B0 B1 ... BN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `SAK` = slave acknowledge
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
self.transaction(address, &mut [Operation::Read(read)])
}

/// Writes bytes to slave with address `address`.
/// Writes bytes to target with address `address`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W B0 B1 ... BN SP
/// Slave: SAK SAK SAK ... SAK
/// Controller: ST TAD+W B0 B1 ... BN SP
/// Target: TAK TAK TAK ... TAK
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `SP` = stop condition
#[inline]
fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
self.transaction(address, &mut [Operation::Write(write)])
}

/// Writes bytes to slave with address `address` and then reads enough bytes to fill `read` *in a
/// Writes bytes to target with address `address` and then reads enough bytes to fill `read` *in a
/// single transaction*.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W O0 O1 ... OM SR SAD+R MAK MAK ... NMAK SP
/// Slave: SAK SAK SAK ... SAK SAK I0 I1 ... IN
/// Controller: ST TAD+W O0 O1 ... OM SR TAD+R CAK CAK ... NCAK SP
/// Target: TAK TAK TAK ... TAK TAK I0 I1 ... IN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Oi` = ith outgoing byte of data
/// - `SR` = repeated start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `Ii` = ith incoming byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
fn write_read(&mut self, address: A, write: &[u8], read: &mut [u8]) -> Result<(), Self::Error> {
Expand All @@ -388,14 +388,14 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// Execute the provided operations on the I2C bus.
///
/// Transaction contract:
/// - Before executing the first operation an ST is sent automatically. This is followed by SAD+R/W as appropriate.
/// - Before executing the first operation an ST is sent automatically. This is followed by TAD+R/W as appropriate.
/// - Data from adjacent operations of the same type are sent after each other without an SP or SR.
/// - Between adjacent operations of a different type an SR and SAD+R/W is sent.
/// - Between adjacent operations of a different type an SR and TAD+R/W is sent.
/// - After executing the last operation an SP is sent automatically.
/// - At the end of each read operation (before SP or SR), the master does not send an acknowledge for the last byte.
/// - At the end of each read operation (before SP or SR), the controller does not send an acknowledge for the last byte.
///
/// - `ST` = start condition
/// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
/// - `TAD+R/W` = target address followed by bit 1 to indicate reading or 0 to indicate writing
/// - `SR` = repeated start condition
/// - `SP` = stop condition
fn transaction(
Expand Down