# modbus-moon 中文教程

欢迎阅读 modbus-moon 项目的中文教程。本教程按照由浅入深的顺序，
逐章讲解整个项目的设计思路与实现细节。每章末尾都给出了**对应
源代码的位置**，方便读者结合代码阅读。

## 项目简介

`modbus-moon` 是一个使用 [MoonBit](https://www.moonbitlang.com/)
语言实现的 [Modbus](https://modbus.org) 工业通信协议库，参考
[tokio-modbus](https://github.com/slowtec/tokio-modbus) 的分层设计，
覆盖 Modbus TCP（网络）和 Modbus RTU（串口）两种传输方式，
同时提供客户端（Client / Context）与服务端（Server / Service）
两类 API。

## 教程目录

### 第一部分：协议基础
1. [Modbus 协议基础](01-modbus-protocol-basics.md) — Modbus
   协议模型、主从通信、PDU/ADU、功能码、异常码
2. [项目架构总览](02-project-architecture.md) — 包结构、各层
   职责、与 tokio-modbus 的对照

### 第二部分：核心协议层（`src/lib`）
3. [核心协议模块](03-lib-core-protocol.md) — `types.mbt`、
   `slave.mbt`、`function_code_ctors.mbt`、`exception_ctors.mbt`
4. [ADU 和 PDU 编解码](04-adu-and-pdu.md) — `adu.mbt`、`pdu.mbt`、
   TCP MBAP 头部与 RTU CRC-16 帧格式
5. [CRC-16 与异常处理](05-crc-and-exceptions.md) — `crc.mbt`、
   `exception.mbt`、`ExceptionResponse`
6. [功能码与 Request/Response](06-function-codes-and-requests.md) —
   `func_codes.mbt`、`request.mbt`、`response.mbt`、
   `coil.mbt` 位打包
7. [从站地址与寻址](07-slave-and-addressing.md) — `slave.mbt`、
   `SlaveContext`、`Slave::broadcast/min_device/max_device/tcp_device`

### 第三部分：客户端（`src/client`）
8. [客户端 Context](08-client-context.md) — `Runtime` trait、
   `Context[R]`、`ClientResult` 双层 Result
9. [Reader / Writer trait](09-client-reader-writer.md) — 高层
   类型化读写 API，方法对照 tokio-modbus
10. [Mock 运行时（端到端测试）](10-client-mock-runtime.md) —
    `MockRuntime`，无网络依赖的完整 Client ⇄ Service 回路
11. [TCP 客户端运行时](11-client-tcp-runtime.md) — `TcpRuntime`、
    同步 façade 与 `async fn` 异步辅助
12. [串口/RTU 运行时](12-client-serial-runtime.md) —
    `SimulatedSerialRuntime`、`SerialRuntime`、`SerialPort` trait、
    `SerialPortHandle`

### 第四部分：服务端（`src/server`）
13. [服务端 Service trait](13-server-service.md) — `Service`、
    `OptionalService`、`Terminated`
14. [MemoryContext 服务实现](14-server-memory-context.md) —
    内存版的线圈/寄存器存储，所有功能码的处理逻辑
15. [TCP 服务端](15-server-tcp-server.md) — `process_request`、
    `encode_response`、从 `SlaveRequest` 到响应

### 第五部分：传输层（`src/transport`）
16. [传输层编解码](16-transport-codecs.md) — `tcp.mbt`、`rtu.mbt`、
    ADU ↔ Request/Response 互转

### 第六部分：测试与示例
17. [测试](17-testing.md) — 黑盒测试、关键用例、覆盖率策略
18. [端到端示例](18-examples.md) — 跑通的完整 demo

### 第七部分：进阶
19. [实现细节与设计取舍](19-internals.md) — MoonBit 跨包 trait
    派发的限制、`with fn` 语法、函数表抽象、Codec 设计哲学

## 阅读建议

- **新接触 Modbus 的读者**：先看第 1 章了解协议背景，再按顺序阅读
  第 3～7 章掌握核心协议层。
- **想快速接入使用的读者**：直接跳到第 8～12 章（客户端）和
  第 13～15 章（服务端）。
- **关心协议实现细节的读者**：重点阅读第 4～7 章与第 16 章。
- **想理解 MoonBit 工程实践的读者**：第 19 章整理了项目里所有
  与语言特性相关的设计取舍。