Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

proposal: rework timeouts, StreamDevices and DatagramDevices

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

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
8/100
Issue 类型
重构
描述清晰度
需要澄清
活跃度
停滞
领域
embedded-iot

调研方向

This is a design proposal, not a patch: it asks whether the StreamDevice and DatagramDevices interfaces should be merged, with read/write treating timeouts as non-errors and read_all/write_all treating them as errors. Start by reading the three comments to see whether maintainers reached a decision, and check the interface definitions the issue refers to. Done means a maintainer-agreed interface design, which should come before any code.

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

描述

driver framework

Summary:

  • Change the default timeout behavior in protocols that behave like streams

  • Analyze ambiguity between the current Datagram and StreamDevices interfaces

  • Extra case: Analyze the use case of drivers exposing generic interfaces

How a timeout can turn a stream into a datagram

A stream represents a communication channel with no predefined size.
Because of this, a timeout should not be treated as an error by default — it’s expected that a device might not send an entire buffer at once, or that a receiver might not always have enough incoming data to fill its read buffer.

However, the way we currently handle timeouts in most UART HALs treats a timeout as a failed transmission of a fixed-size buffer in single transaction, effectively turning the stream into a datagram-like operation.

This raises an interesting question:

Is UART really a StreamDevice?

Streams often use UART as their canonical example, since UART is a very common way to perform raw communication between two controllers.
But thinking more deeply — what prevents a fixed-size protocol from using UART?
Nothing. It’s perfectly valid (even if less common in some designs) to implement length-defined packet protocols over UART.

That means StreamDevice has an edge case where it behaves like a datagram.
But then, what are the edge cases for Datagram?

Is a datagram also a kind of stream?

By analogy, datagram interfaces are typically represented by I2C or SPI, which are usually used for fixed-size packet transfers.
And that’s true — to some extent.

These buses are very common in simple modules where communication rules are rigidly defined, and a write timeout or failed full transfer is indeed an error.

But both I2C and SPI can also be used in a stream-like context, especially SPI, which is often used for raw controller-to-controller communication (similar to USART).

I2C as a special case:

In a host → device transaction, the device can send a NACK to indicate it no longer wants to receive data — this is valid behavior.

In a device → host transaction, the specification requires the device to send 0xFF if it has no more data to transmit; This means that a reader with an arbitrary buffer length does not generate an error, which is problematic for streams: here, 0xFF is ambiguous, as it could be either valid data or a placeholder.

Despite this, REPEATED START, makes it much closer to stream-like behavior over a datagram, And there are also cases of
some I2C modules — especially those that also support SPI — to typically provide a burst read/write function, allowing the host to read or write N bytes sequentially (as long as a certain limit is not exceeded), edge-case of stream-like behavior on I2C.

So, even protocols usually treated as datagram-based have situations where they behave like streams.

In other words:

Anything that can be a stream can also behave like a datagram —
but not everything that’s a datagram can behave like a stream.

Why separate them, then?

If the distinction between stream and datagram depends mostly on how timeouts and buffer sizes are handled, we might not need two separate interfaces at all.

By defining methods like read_all and write_all, we can express both behaviors cleanly:

  • write/read — Timeout, NACK or any EOF is not an error → behaves like a stream
  • write_all/read_all — Timeout, NACK or any early EOF is an error → behaves like a datagram
主要语言
Zig
星标
2.3k
派生
198
平均合并
1 天 8 小时
30 天内合并 PR
37

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

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

ZigEmbeddedGroup/microzig 的其他 Issue

查看 ZigEmbeddedGroup/microzig 的全部 Issue

相似的 Issue

更多 Embedded & IoT Issue

把新 issue 发到你的邮箱

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