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

Abierto
  • ¿Algo no está bien?
#81 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
74/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
rust
Área
documentation, embedded-iot, testing

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Rust
Estrellas
2
Forks
7
Sin PR fusionados en 30 d

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de OpenDevicePartnership/tmp108

Todos los issues de OpenDevicePartnership/tmp108

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.