Blocking driver cannot return to continuous mode; README documents a workaround that cannot be written

未关闭
  • 哪里不对？
#81 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
3/5
预计耗时
1-2 天
新手友好度
74/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
活跃
技术栈
rust
领域
documentation, embedded-iot, testing

调研方向

Start with the blocking Tmp108 implementation at src/lib.rs:1847 and compare its mode handling with AsyncTmp108::continuous at src/lib.rs:3016-3033. Review the blocking tests, the async doctest, and the README.md and AGENTS.md references named in the issue. Done means the blocking API, cleanup and error cases, crate-level documentation, and misleading workaround text are covered by tests and docs.

由索引模型根据 Issue 内容生成。

描述

audit:SBOS663A bug enhancement impact:documentation

The blocking driver can leave continuous conversion but cannot return to
it. README.md:185-187 says otherwise.

The gap

set_m(Mode::Continuous) appears exactly once in the crate:

src/lib.rs:3022   .modify_async(|r| r.set_m(Mode::Continuous))

That line is inside impl<I2C: AsyncI2c> AsyncTmp108<I2C> (block opens at
src/lib.rs:2474). The blocking block, impl<I2C: I2c> Tmp108<I2C> at
src/lib.rs:1847, writes only:

src/lib.rs:2224   .modify(|r| r.set_m(Mode::Shutdown))     // one_shot preparation
src/lib.rs:2234   .modify(|r| r.set_m(Mode::OneShot))      // one_shot trigger
src/lib.rs:2278   .modify(|r| r.set_m(Mode::Shutdown))     // shutdown

Config carries thermostat_mode, alert_polarity, conversion_rate
and hysteresis — no mode field — and apply_config preserves M. So
a default-features user who calls shutdown(), or one_shot() (which
self-clears to shutdown per SBOS663A §7.4.2), has no way back to
continuous conversion through this crate.

The README is wrong about the workaround

README.md:185-187:

  • AsyncTmp108::continuous is async-only. For blocking continuous-mode
    use, call Tmp108::configure(...) to set Mode::Continuous manually,

configure takes a Config, and Config has no mode field. This
workaround cannot be written. AGENTS.md:28 and AGENTS.md:112 repeat
the "no blocking equivalent" framing without proposing the impossible
remedy, so the README line is the only actively misleading one.

Datasheet context

Continuous conversion is the power-on default — the configuration reset
value is 0x1022, M = 0b10 (SBOS663A Table 8,
sources/datasheet.txt:883-889). The only documented way to restore
power-up register values without software setting M is the general call
reset command:

the TMP108 internal registers are reset to power-up values. The TMP108 does not support the general address

SBOS663A §7.3.7, sources/datasheet.txt:717

That is a broadcast to address 0x00, which resets every general-call
capable device on the bus, so it is arguably not a per-device driver's to
offer. Which leaves the blocking driver with no in-crate escape at all.

Proposed fix

Mirror the async method. The async body is four statements
(src/lib.rs:3016-3033); the blocking one is the same without .await,
and is simpler, because FnOnce avoids the AsyncFnOnce closure-syntax
trap documented in AGENTS.md gotcha #4:

pub fn continuous<F>(&mut self, f: F) -> Result<(), I2C::Error>
where
    F: FnOnce(&mut Self) -> Result<(), I2C::Error>,
{
    self.inner
        .configuration()
        .modify(|r| r.set_m(Mode::Continuous))?;

    let user_result = f(self);
    let cleanup_result = self.shutdown();
    user_result.and(cleanup_result)
}

Purely additive, and ungated — unlike the async one it needs no feature.

Cost
Item Size
Production code ~8 lines in the Tmp108 impl block
Doctest required by AGENTS.md; mirror src/lib.rs:2993-3015 minus the block_on wrapper
Rustdoc needs the # Interrupt-mode acknowledgement section — it is a read-modify-write — plus the qualified cleanup wording #77 just landed on the async one
Crate-level table add a Tmp108::continuous row at src/lib.rs:51-60; today only AsyncTmp108::continuous is listed
Unit tests mirror the async entry-failure / cleanup-error / dropped-error cases in mod tests::blocking
README.md rewrite the gotcha at 185-187; update the feature table at 108
AGENTS.md update lines 28, 101, 112 and gotcha #4's framing
tests/reexports.rs optional use-site pin
Semver additive → minor bump; feat: subject, release-plz handles it
Examples optional: examples/continuous.rs could gain a blocking arm like oneshot.rs and sensor_trait.rs already have. If it does, the CI example matrix and scripts/check-readme-snippets.sh need the extra combination.

The snippet script is unaffected as long as examples/continuous.rs
stays async-only.

Alternative considered

An additive start_continuous() that just writes M without the scoped
cleanup. Rejected: it reintroduces the "who turns it off" problem that
continuous()'s closure shape exists to solve, and the blocking port is
cheap enough that there is no reason to offer the weaker API.

Provenance

Raised by the datasheet compliance audit of PR #77. Two audit agents
reached it from opposite ends — one looking for documented recovery paths,
one for facts absent from the types.

主要语言
Rust
星标
2
派生
7
30 天内没有已合并 PR

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

OpenDevicePartnership/tmp108 的其他 Issue

查看 OpenDevicePartnership/tmp108 的全部 Issue

相似的 Issue

更多 Rust Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。