【注意】我发现将用ValueRegister编写的成员放入ValueRegisterBitfield中有点误导。所以这可能在将来改变，但我目前想不出另一种像我们现在所拥有的那样简单易用的设计。问题是我们需要一个结构体用于打包数据，另一个用于解包数据。由于我们通常处理打包数据，并且希望为了性能允许直接对打包数据进行读写操作，名称很快就变得混淆。

访问寄存器

在定义寄存器之后，我们可能可以通过MyDevice来访问它。

// Imagine we already have constructed a device:
let mut dev = MyDevice::new_i2c(i2c_bus /* the i2c bus from your controller */, 0x12 /* address */);
// We can now retrieve the register
let mut reg = dev.read_register::<ValueRegister>().await?;

// Unpack a specific field from the register and print it
println!("{}", reg.read_width());
// If you need all fields (or are not bound to tight resource constraints),
// you can also unpack all fields and access them more conveniently
let data = reg.read_all();
// All bitfields implement Debug and defmt::Format, so you can conveniently
// print the contents
println!("{:?}", data);

// We can also change a single value
reg.write_height(190);
// Or pack a bitfield and replace everything
reg.write_all(data); // same as reg = ValueRegister::new(data);

// Which we can now write back to the device, given that the register is writable.
dev.write_register(reg).await?;

更复杂的寄存器

一个更复杂的寄存器可能包含不仅仅是简单的值。通常会有枚举或位标志，幸运的是，我们也可以用bondrewd来表示。使用bondrewd的属性宏，我们可以指定哪个位对应哪个字段。

#[allow(non_camel_case_types)]
#[derive(BitfieldEnum, Copy, Clone, Default, PartialEq, Eq, Debug, defmt::Format)]
#[bondrewd_enum(u8)]
pub enum TemperatureResolution {
    Deg_0_5C = 0b00,
    Deg_0_25C = 0b01,
    Deg_0_125C = 0b10,
    #[default]
    Deg_0_0625C = 0b11,
}

#[device_register(MyDevice)]
#[register(address = 0x44, mode = "rw")]
#[bondrewd(read_from = "msb0", default_endianness = "be", enforce_bytes = 1)]
pub struct ComplexRegister {
    #[bondrewd(bit_length = 6, reserve)]
    #[allow(dead_code)]
    pub reserved: u8,

    #[bondrewd(enum_primitive = "u8", bit_length = 2)]
    pub temperature_resolution: TemperatureResolution,
}

【注意】实际上，我们可能会将所有寄存器都放在一个方便的registers模块中，而不是命名所有寄存器为*Register，以简化操作并删除后缀。

定义设备

现在我们还需要定义我们的设备，这样我们才能实际使用寄存器。想象一下，我们的简单设备只会通过I2C进行通信。

首先，我们可以通过使用#[device]宏来定义一个结构体。这个结构体存储了我们设备所需的运行时状态，例如通信接口。这个宏只是定义了一个标记特质，我们稍后会需要它来定义寄存器，你现在可以忽略它。

/// Insert description from datasheet.
#[device]
pub struct MyDevice<I: RegisterInterface> {
    /// The interface to communicate with the device
    interface: I,
}

寄存器接口是来自embedded-registers的一个特质，它是一个暴露了特定read_register和write_register函数的对象。内部这将是我们稍后可以调用的函数，用于读取或写入特定寄存器。

但在此之前，我们需要为我们的设备添加一个构造函数，以便我们可以从真实的I2C总线和地址创建一个新的设备。《code>embedded-registers存储库还提供了一个名为I2cDevice的结构体，它实现了I2C的RegisterInterface，所以我们只需将其用作我们的接口。

对于不需要额外字段的非常简单的设备，有一个方便的宏simple_device::i2c!，它会为您定义必要的设备。

simple_device::i2c!(MyDevice, MyAddress, SevenBitAddress, OneByteRegAddrCodec);

地址枚举MyAddress应包含设备的所有有效地址，以及一个变体，以便允许指定任意地址，以防用户使用地址转换单元。地址可以是任何可以转换为总线底层（7位或10位寻址）的embedded_hal::i2c::AddressMode的类型。对于真实示例，请参阅mcp9808::Address。

第三个参数是SevenBitAddress或TenBitAddress，取决于设备的寻址模式。在大多数情况下，设备使用7位地址。

最后一个参数指定用于通过I2C读取或写入寄存器的编解码器。这通常是只是一个简单的前缀寄存器地址的编解码器，但在设备的情况下可能会更复杂。这将是你调整所需协议的位置。

最后，这个宏实际上只是为我们的设备定义了一个构造函数，相当于下面这个 impl 块。我们稍后将会看到为什么我们需要 #[maybe_async_cfg]。

#[maybe_async_cfg::maybe(
    idents(hal(sync = "embedded_hal", async = "embedded_hal_async")),
    sync(not(feature = "async")),
    async(feature = "async"),
    keep_self
)]
impl<I> MyDevice<I2cDevice<I, hal::i2c::SevenBitAddress, OneByteRegAddrCodec>>
where
    I: hal::i2c::I2c<hal::i2c::SevenBitAddress> + hal::i2c::ErrorType,
{
    /// Initializes a new device with the given address on the specified bus.
    /// This consumes the I2C bus `I`.
    #[inline]
    pub fn new_i2c(interface: I, address: MyAddress) -> Self {
        Self {
            interface: I2cDevice::new(interface, address.into(), OneByteRegAddrCodec::default()),
        }
    }
}

现在我们有了设备，我们需要能够读写寄存器，并且也可以实现使用这些寄存器的高级功能。最简单的实现就是一个带有 #[device_impl] 属性宏的空块。

#[device_impl]
impl<I: RegisterInterface> MyDevice<I> {
}

还记得一开始创建的标记特质吗？它是通过 #[device] 创建的？现在它派上用场了；我们将存储为接口的 I2cDevice 非常通用，允许我们读取任何我们想要的合法寄存器定义。但由于这个crate中有多个具有合法寄存器的驱动程序，我们希望防止寄存器与无关设备一起使用。

因此，#[device_impl] 宏定义了两个函数 read_register 和 write_register，这些函数内部只是调用类似名称的函数 self.interface，但还需要传递的寄存器类型实现我们的标记特质。寄存器通过 #[device_register] 标注标记特质，因此传递无关寄存器现在会导致编译错误。

用户现在已经能够以基本安全的方式与设备寄存器进行接口交互，当然，不包括我们的类型寄存器表示的事物（如隐式设备状态）。最后一步是公开我们的设备的便利函数。经典的有如 init、reset、measure、configure 或其他，但原则上你可以写任何东西。

最后，在编写设备函数时，我们总是编写异步代码。maybe_async_cfg 宏将自动从我们的定义中派生出同步代码，并用从 hal 的引用替换为 embedded_hal 或 embedded_hal_async。这是必要的，以便我们可以支持异步和同步crate消费者。例如，下面是 init 的一个例子。

#[device_impl]
impl<I: RegisterInterface> MyDevice<I> {
    /// Initialize the sensor by verifying its device id and manufacturer id.
    /// Not mandatory, but recommended.
    pub async fn init(&mut self) -> Result<(), InitError<I::Error>> {
        use self::registers::DeviceIdRevision;
        use self::registers::ManufacturerId;

        let device_id = self.read_register::<DeviceIdRevision>().await.map_err(InitError::Bus)?;
        if device_id.read_device_id() != self::registers::DEVICE_ID_VALID {
            return Err(InitError::InvalidDeviceId);
        }

        let manufacturer_id = self.read_register::<ManufacturerId>().await.map_err(InitError::Bus)?;
        if manufacturer_id.read_manufacturer_id() != self::registers::MANUFACTURER_ID_VALID {
            return Err(InitError::InvalidManufacturerId);
        }

        Ok(())
    }
}

贡献

如果您有任何改进当前架构的建议或想法，请鼓励您通过 Matrix 打开问题或联系。

贡献受到热烈欢迎！请随时建议新功能、实现设备驱动程序或提出一般性的改进建议。

许可证

许可如下

• Apache License，版本 2.0，(LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 https://opensource.org/licenses/MIT)

根据您的选择。除非您明确表示否则，您根据Apache-2.0许可证定义的任何有意提交以包含在本软件包中的贡献，应按上述方式双重授权，无需任何额外条款或条件。