# UARTPeriodicTx 硬件定时发送

`UARTPeriodicTx` 用硬件定时器周期性发送已经准备好的 UART 帧。它适合周期状态帧、控制帧等发送任务：Python 代码负责准备并更新数据，硬件定时器负责按周期触发原生发送路径。

本教程对应源码示例 `resources/examples/03-Machine/uart_periodic_tx.py`。示例以 50 ms 周期发送 8 字节帧，并使用 UART3 本地回环验证收发结果。

## 编译配置

该模块默认未编入固件。编译前执行：

```bash
# 使用 k230-builder 时
k230 make menuconfig

# 直接本机编译时
make menuconfig
```

在以下菜单打开 `Enable UART periodic TX module`，然后重新编译并烧录固件：

```text
CanMV Micropython Components Configurations
    Enable UART periodic TX module
```

## 接线

示例使用 UART3：

```text
IO50 (UART3_TXD) ---- IO51 (UART3_RXD)
```

运行前断电完成回环接线，并确认该板的 IO50 和 IO51 电平及引脚复用与示例一致。UART 电平必须匹配，不能接入 5 V UART 信号；详细要求见 [串口电平与转接模块安全](./uart.md)。也可以在 IO50 上连接逻辑分析仪测量发送周期。

```{warning}
示例中的 UART3、IO50 和 IO51 是当前示例的板级映射。实际应用应根据开发板原理图、REPL 配置及其他已使用外设选择 UART 和 FPIOA 引脚。
```

## 示例工作方式

示例首先将 IO50/IO51 映射为 UART3 TX/RX：

```python
from machine import FPIOA, UART

fpioa = FPIOA()
fpioa.set_function(50, FPIOA.UART3_TXD)
fpioa.set_function(51, FPIOA.UART3_RXD)
```

然后创建并启动发送器：

```python
from uart_periodic_tx import UARTPeriodicTx

transmitter = UARTPeriodicTx(
    UART.UART3,
    0,
    50,
    max_len=8,
    baudrate=115200,
    bits=UART.EIGHTBITS,
    parity=UART.PARITY_NONE,
    stop=UART.STOPBITS_ONE,
    repeat_last=True,
)

transmitter.update(b"\xA5\x5A\x00\xFF\x3C\xC3\xFF\x0D")
transmitter.start()
```

示例使用 `machine.UART` 只读取回环到 UART3 RX 的数据，以便检查帧内容。业务代码中，运行中的 `UARTPeriodicTx` 已拥有同一 UART 的发送路径，不要再对它调用 `machine.UART.write()`、`init()` 或 `deinit()`。

`repeat_last` 控制未更新数据时的行为：

- `repeat_last=True`（默认）：每次硬件定时器触发都发送最近一次 `update()` 的帧。
- `repeat_last=False`：每次 `update()` 的非空帧只发送一次；没有新数据的触发不发送，并计入 `skipped`。

示例每隔 `UPDATE_PERIOD_MS` 调用一次 `update()`，把序号写入发送帧。帧格式如下：

```text
A5 5A <sequence> <sequence ^ FF> 3C C3 <checksum> 0D
```

例如序号为 `0x0F` 时，帧内容为：

```text
A5 5A 0F F0 3C C3 FF 0D
```

当 `repeat_last=True` 时，硬件定时器会重复发送最近一次成功发布的帧，不会自行生成序号。因此在逻辑分析仪中看到连续相同的帧，表示捕获期间尚未有新的 `update()` 生效，或新帧在本次硬件触发之后才发布。`repeat_last=False` 时，序号帧只会在新的 `update()` 后出现一次。应捕获足够长的时间窗口，并确认脚本仍在运行、`UPDATE_PERIOD_MS` 已到期且 `update()` 没有报错。

## 运行与结果

将示例复制到设备后运行 `uart_periodic_tx.py`。默认配置为：

| 项目 | 值 |
| --- | --- |
| UART | UART3 |
| 波特率 | 115200，8N1 |
| 硬件定时器 | 0 |
| 发送周期 | 50 ms |
| 测试时长 | 5000 ms |
| 帧长度 | 8 字节 |

输出会给出发送、接收和错误统计，例如：

```text
UARTPeriodicTx loopback test: period=50 ms, duration=5000 ms, repeat_last=True
frames: sent=100, received=100, invalid=0
tx stats: short_write=0, errors=0, skipped=0
PASS
```

接收时间戳仅用于软件回环健全性检查。若需要测量真实线上的周期和抖动，应使用 IO50 上的逻辑分析仪，并按 `115200`、8 数据位、无校验、1 停止位解码。

## 常见问题

| 现象 | 排查方式 |
| --- | --- |
| `ImportError: no module named 'uart_periodic_tx'` | 在 `menuconfig` 打开 `Enable UART periodic TX module` 后重新编译固件。 |
| `OSError: [Errno 16] EBUSY` | 检查 `timer_id` 是否已被 `machine.Timer` 或另一个 `UARTPeriodicTx` 使用；同一 UART 的多个周期发送器还必须使用相同配置。 |
| 逻辑分析仪始终显示同一序号 | 确认捕获时长覆盖多个 `UPDATE_PERIOD_MS`，并检查应用是否持续调用 `update()`。定时器在两次更新之间重复上一帧是预期行为。 |
| 收不到回环数据或显示 `FAIL` | 检查 IO50 到 IO51 的连接、FPIOA 映射、UART3 是否被其他功能占用，以及两端是否均为 115200 8N1。 |
| `short_write` 或 `errors` 不为零 | 降低帧长度或提高波特率、增大发送周期，并确保一个 UART 没有多个重叠发送任务。 |
| `skipped` 不为零 | 在 `repeat_last=False` 模式下，未更新数据时的 `skipped` 是预期行为；其他情况检查 UART 忙、定时器资源和帧长度。 |

结束时应释放资源：

```python
try:
    transmitter.start()
    # 业务代码中按需调用 transmitter.update(...)
finally:
    transmitter.deinit()
```

更多 API 参数和资源约束见 [`uart_periodic_tx` 模块 API 手册](../../api/machine/k230_canmv_uart_periodic_tx_api_manual.md)。