产品特色

LM 协议的三种用法

工作形态

机器人本体通信与调试

多平台上位机

应用场景

规格摘要

从开发到交付

目录与阅读路径

本手册面向需要把 UCAN-Mini 接入工程系统的用户。UCAN-Mini 运行 LM 协议；LM 协议既可以通过 Linux 内核驱动呈现为 SocketCAN 接口，也可以通过 Python 脚本直接访问 USB TLV 协议。

基础收发流程

按任务阅读

1. 产品定位

UCAN-Mini 是一款 USB 转双通道 CAN/CAN FD 接口设备。设备运行 LM 协议，面向以下工程需求：

2. 核心特性

3. 接入路径选择

4. USB 枚举与端点

4.1 LM 模式

5. LM TLV 协议概览

5.1 TLV Header

所有 LM 消息均以 8 字节 TLV Header 开头，后跟可变长度载荷，总长度 4 字节对齐。

offset  size  field      description
0x00    2     type       消息类型
0x02    2     size       整条消息总长度，含头部，4B 对齐
0x04    1     channel    CAN 通道号，0xFF 表示设备级/广播
0x05    1     flags      消息级标志
0x06    2     reserved   保留，置 0
0x08    ...   payload    可变长度载荷

Wire 格式为 little-endian：<HHBBH。

5.2 常用消息类型

5.3 能力位重点

6. Linux 内核驱动

UCAN-Mini 的 LM 模式提供 out-of-tree Linux SocketCAN 驱动，发布包目录为：

kernel_driver

驱动文件：

6.1 环境准备

Debian / Ubuntu 示例：

sudo apt update
sudo apt install -y build-essential linux-headers-$(uname -r) can-utils

如果系统没有 ip 或 CAN 工具，补充安装：

sudo apt install -y iproute2 can-utils

6.2 手动编译安装

cd kernel_driver
make
sudo make install
sudo depmod -a
sudo modprobe ucan_lm

确认模块加载：

lsmod | grep ucan_lm
modinfo ucan_lm

插入 UCAN-Mini 后查看内核日志：

dmesg | tail -80
ip link

正常情况下，每个 CAN 通道会注册为一个 SocketCAN 网络接口，例如 can0、can1。

6.3 DKMS 安装

DKMS 适合随内核升级自动重建模块：

sudo mkdir -p /usr/src/ucan-lm-0.1.0
sudo cp -a kernel_driver/. /usr/src/ucan-lm-0.1.0/
sudo dkms add -m ucan-lm -v 0.1.0
sudo dkms build -m ucan-lm -v 0.1.0
sudo dkms install -m ucan-lm -v 0.1.0
sudo modprobe ucan_lm

查看 DKMS 状态：

dkms status ucan-lm

卸载：

sudo dkms remove -m ucan-lm -v 0.1.0 --all
sudo modprobe -r ucan_lm

6.4 模块参数

临时加载示例：

sudo modprobe ucan_lm tx_window=8 rx_hwts=1 time_sync_interval_ms=500

需要把参数持久化时，可创建 /etc/modprobe.d/ucan_lm.conf：

options ucan_lm tx_window=8 rx_hwts=1 time_sync_interval_ms=500

注意：rx_hwts=1 时，驱动会绑定 MGMT 接口用于时间同步。此时用户态 Python 管理工具可能无法同时打开 MGMT 接口。Linux 内核驱动不提供固件更新功能。

6.5 SocketCAN 使用

Classic CAN：

sudo ip link set can0 down 2>/dev/null || true
sudo ip link set can0 up type can bitrate 500000
candump can0
cansend can0 123#11223344

CAN FD：

sudo ip link set can0 down 2>/dev/null || true
sudo ip link set can0 up type can bitrate 1000000 dbitrate 5000000 fd on
candump can0
cansend can0 123##100112233445566778899AABBCCDDEEFF

双通道：

sudo ip link set can0 up type can bitrate 1000000 dbitrate 5000000 fd on
sudo ip link set can1 up type can bitrate 1000000 dbitrate 5000000 fd on
candump can0 can1

6.6 时间戳与 TX 窗口

tx_window 限制每个通道同时等待 TX echo 的发送槽数量。控制类业务建议保持较小窗口，减少旧命令排队；吞吐类测试可适当增大。

rx_hwts=1 时，驱动使用 MGMT 命令端点做设备/主机时间同步，并将设备 RX 时间戳换算到 Linux skb 硬件时间戳路径。若现场只需要普通 SocketCAN 收发，可用 rx_hwts=0 简化接口占用。

7. Python LM 协议脚本

Python 脚本发布包目录为：

private_proto

7.1 安装依赖

cd private_proto
python -m pip install pyusb

Linux 需要 libusb：

sudo apt install -y libusb-1.0-0-dev

Windows 下需要给 LM 接口安装 WinUSB / libusb 驱动，例如使用 Zadig。若同一台电脑上还有内核驱动或其他工具占用设备，先关闭占用进程。

7.2 基础命令

python ucan_mini_cli.py list
python ucan_mini_cli.py info
python ucan_mini_cli.py status --ch 0
python ucan_mini_cli.py identify

info 走 EP0 vendor request，可用于确认设备在线、通道数量、固件版本和能力信息。

7.3 通道配置

设置 Classic CAN 仲裁段位时序：

python ucan_mini_cli.py set-bittiming --ch 0 --brp 10 --tseg1 13 --tseg2 2 --sjw 1
python ucan_mini_cli.py start --ch 0

CAN FD + BRS：

python ucan_mini_cli.py set-bittiming --ch 0 --brp 10 --tseg1 13 --tseg2 2 --sjw 1
python ucan_mini_cli.py set-data-bittiming --ch 0 --brp 2 --tseg1 13 --tseg2 2 --sjw 1
python ucan_mini_cli.py start --ch 0 --mode fd fd_brs tx_echo

终端电阻：

python ucan_mini_cli.py set-termination --ch 0 --enable 1
python ucan_mini_cli.py set-termination --ch 1 --enable 1

停止通道：

python ucan_mini_cli.py stop --ch 0

7.4 立即发送与接收

发送标准帧：

python ucan_mini_cli.py send --ch 0 --id 0x123 --data "01 02 03 04"

发送扩展帧：

python ucan_mini_cli.py send --ch 0 --id 0x12345678 --ext 1 --data "AA BB"

发送 CAN FD + BRS：

python ucan_mini_cli.py send --ch 0 --id 0x100 --fd 1 --brs 1 --data "01 02 03 04 05 06 07 08 09 0A"

批量发送：

python ucan_mini_cli.py send --ch 0 --id 0x200 --data "FF" --count 100 --interval-ms 10

接收：

python ucan_mini_cli.py receive --ch 0
python ucan_mini_cli.py receive --ch 0 --count 10 --rx-timeout-ms 1000

7.5 过滤、选项与状态

过滤器：

python ucan_mini_cli.py set-filter --ch 0 --type range --index 0 --id1 0x100 --id2 0x1FF
python ucan_mini_cli.py set-filter --ch 0 --type exact --index 0 --id1 0x123
python ucan_mini_cli.py set-filter --ch 0 --type mask --index 0 --id1 0x7F0 --id2 0x100
python ucan_mini_cli.py clear-filter --ch 0

运行时选项：

python ucan_mini_cli.py set-option --ch 0 --options tx_echo error_report bus_load
python ucan_mini_cli.py clear-option --ch 0 --options bus_load
python ucan_mini_cli.py set-auto-recover --ch 0 --enable 1
python ucan_mini_cli.py set-iso-mode --ch 0 --iso 1

状态查询：

python ucan_mini_cli.py status --ch 0

返回信息中重点关注 state_name、started、termination、tx_count、rx_count、tx_err_count、rx_err_count、overrun_count 和 busload。

7.6 Python API

CanClient 适合需要设备级管理命令的脚本：

from ucan_mini_proto import CanClient, MODE_FD, MODE_FD_BRS, MODE_TX_ECHO

cli = CanClient()
info = cli.get_device_info()
print(info)

cli.set_bittiming(channel=0, brp=10, tseg1=13, tseg2=2, sjw=1)
cli.set_data_bittiming(channel=0, brp=2, tseg1=13, tseg2=2, sjw=1)
cli.start(channel=0, mode_flags=MODE_FD | MODE_FD_BRS | MODE_TX_ECHO)
cli.send(channel=0, can_id=0x123, data=b"\x01\x02\x03", is_fd=True, brs=True)

frame = cli.receive(channel=0, timeout_ms=1000)
print(frame)

cli.stop(channel=0)
cli.close()

ChannelClient 适合两个独立进程分别占用一个 CAN DATA interface。它只暴露通道级命令；设备信息、设备复位、用户 Flash、设备 ID、timestamp sync 等设备级操作仍通过 CanClient 完成。Python CLI/API 不提供固件更新功能。

from ucan_mini_proto import ChannelClient, MODE_FD, MODE_FD_BRS

can0 = ChannelClient(0)
can0.set_bittiming(brp=10, tseg1=13, tseg2=2, sjw=1)
can0.start(mode_flags=MODE_FD | MODE_FD_BRS)
can0.send(can_id=0x123, data=b"\x01\x02")
can0.close()

8. UCAN-Analyzer 多平台上位机

UCAN-Analyzer 是 UCAN-Mini 的配套桌面分析工具，面向 CAN / CAN FD 设备配置、收发测试、帧监控、过滤、数据追踪、曲线分析和固件更新，适合交互式调试、现场诊断和总线可视化分析。

8.1 支持平台与发布形态

按主机系统选择对应发布包，启动后连接 UCAN-Mini 即可进行通道配置、收发测试、总线分析和固件维护。

8.2 功能模块

8.3 典型调试流程

1. 启动 UCAN-Analyzer
2. 连接 UCAN-Mini
3. 选择 CAN0/CAN1，设置仲裁位率、数据位率、CAN FD、BRS 和终端电阻
4. 启动通道
5. 在接收/追踪窗口观察实时帧
6. 在发送窗口构造单帧、批量帧或周期发送条目
7. 使用过滤、触发、DBC、信号曲线或数据分析定位问题
8. 需要维护时使用 UCAN-Analyzer 的固件更新功能

8.4 机器人本体调试建议

UCAN-Analyzer 适合机器人本体内部 CAN/CAN FD 网络的交互式调试：

9. 预约发送

预约发送用于减少主机调度抖动对发送时刻的影响。主机先同步设备时间，再把待发送帧和目标时间下发到设备；设备按本地 PTPC 时间触发发送。

9.1 能力与限制

9.2 CLI 单次预约

CLI 在未提供 --start-time-us 时会自动执行 timestamp-sync，并使用当前设备时间加 --delay-us。

python ucan_mini_cli.py set-schedule \
  --ch 0 \
  --slot 0 \
  --enable 1 \
  --delay-us 10000 \
  --can-id 0x100 \
  --data "01 02 03"

这表示约 10 ms 后发送一次 ID 0x100。

9.3 CLI CAN FD + BRS 预约

python ucan_mini_cli.py set-schedule \
  --ch 0 \
  --slot 1 \
  --enable 1 \
  --delay-us 20000 \
  --can-id 0x123 \
  --fd 1 \
  --brs 1 \
  --data "00 01 02 03 04 05 06 07 08 09 0A 0B"

清除预约：

python ucan_mini_cli.py clear-schedule --ch 0

9.4 API 预约发送

import time
from ucan_mini_proto import CanClient, TX_FLAG_FD, TX_FLAG_BRS, len_to_dlc

cli = CanClient()
dev_us, _ = cli.timestamp_sync(int(time.time() * 1_000_000))
data = bytes.fromhex("01 02 03 04")

cli.set_schedule(
    channel=0,
    slot_index=0,
    enable=True,
    start_time_us=dev_us + 10_000,
    can_id=0x100,
    dlc=len_to_dlc(len(data)),
    tx_flags=0,
    data=data,
)

9.5 排查建议

10. 通道配置建议

10.1 Classic CAN

10.2 CAN FD

11. 按键、LED 与固件更新

11.1 按键功能

11.2 LED 指示

11.3 固件更新

固件更新仅在 UCAN-Analyzer 闭源上位机中提供。Linux 内核驱动和 Python CLI/API 不提供固件更新功能。

12. 调试与诊断

12.1 USB 或驱动异常

12.2 CAN 无法通信

优先检查：

• CANH/CANL/GND 和屏蔽连接。
• 总线两端是否各有 120R。
• 两端仲裁段位率、数据段位率、BRS 和 CAN FD 使能是否一致。
• 通道是否已启动，是否处于 Warning、Error Passive 或 Bus-Off。
• 是否把 CAN0/CAN1、端点或 SocketCAN 接口用反。

12.3 预约发送异常

优先检查：

• 设备能力是否包含 SCHEDULE_TX。
• 通道是否已经启动。
• start_time_us 是否基于设备时间，不是主机系统时间。
• 下发时间是否太晚，至少预留 200 us，工程测试建议预留数 ms。
• 是否误用了已移除的周期预约参数。

13. 技术规格

14. 修订历史

Copyright (c) 2026 LanMotion.

UCAN-Analyzer 上位机使用手册

1. 概述

UCAN-Analyzer 是 UCAN-Mini 的多平台图形上位机，用于 CAN / CAN FD 设备配置、报文收发、总线监控、过滤、数据分析、DBC 信号查看、回放、触发测试和维护升级。

软件面向研发调试、现场诊断、产测验证和数据采集场景。典型使用流程是连接 UCAN-Mini，配置 CAN 通道，启动通道后观察实时帧数据，并按需要发送测试帧、加载 DBC、导出记录或执行自动化触发规则。

典型调试流程：

1. 连接 UCAN-Mini 并确认 USB 在线。
2. 配置 CAN / CAN FD 通道参数并启动通道。
3. 在接收、追踪和总线负载窗口观察现场数据。
4. 使用发送、过滤、触发、回放和 Lua 控制台完成验证。
5. 保存项目或导出 CSV / ASC / BLF，形成可复现记录。

2. 安装与启动

2.1 Windows

下载 Windows x86_64 安装包，运行 UCAN-Analyzer-*-windows-x86_64.exe 并按提示安装。安装完成后可从开始菜单或安装目录启动 UCAN-Analyzer.exe。

如果系统提示驱动或 USB 权限异常，请确认 UCAN-Mini 已正确连接，并避免多个上位机实例同时占用同一通道。

2.2 Linux

下载 Linux x86_64 AppImage：

chmod +x UCAN-Analyzer-*-linux-x86_64.AppImage
./UCAN-Analyzer-*-linux-x86_64.AppImage

如普通用户无法访问 USB 设备，请按现场系统策略配置 udev 规则，或使用具备 USB 访问权限的用户运行。

2.3 macOS

下载 .dmg 或 .pkg 安装包。首次运行时如果系统拦截未签名应用，可在系统设置的安全性页面允许打开。

3. 主界面

UCAN-Analyzer 的主界面由菜单栏、工具栏、设备与通道区域、报文区域和分析工具窗口组成。常用入口如下：

3.1 工具栏图标按钮

4. 连接 UCAN-Mini

1. 使用 USB 线连接 UCAN-Mini。
2. 启动 UCAN-Analyzer。
3. 在设备区域刷新设备列表。
4. 选择设备和通道，点击连接。
5. 连接成功后，状态栏会显示在线状态，通道配置、接收、发送和分析窗口开始使用当前设备数据。

如果连接失败，优先检查 USB 线缆、设备供电、系统权限、驱动占用和是否已有其他程序占用 UCAN-Mini。

5. CAN / CAN FD 通道配置

通道配置用于设置 UCAN-Mini 的 CAN 控制器工作参数。常用项目包括：

建议先从项目常用的标准位率开始验证，例如 500 kbit/s、1 Mbit/s、2 Mbit/s 或 5 Mbit/s。需要精确匹配现场网络时，再调整采样点和高级位时序参数。

6. 接收、追踪与过滤

接收和追踪窗口用于查看实时 CAN / CAN FD 帧。表格通常包含时间戳、方向、通道、CAN ID、DLC、数据字节和解析结果。

追踪窗口支持表达式过滤，常用字段如下：

示例：

id==0x100 && ch==0
id==0x18FF50E5 && dlc>7
dev==0 && ch==1

过滤表达式适合快速定位目标帧；设备端过滤适合降低高负载网络下的主机侧数据压力。

7. 报文发送与周期发送

发送窗口用于创建、编辑和执行发送条目。每个条目通常包含通道、CAN ID、帧格式、DLC、数据字节、是否启用和周期参数。

常见操作：

1. 添加发送条目。
2. 设置通道、CAN ID 和数据内容。
3. 点击立即发送验证单帧。
4. 勾选循环发送并设置周期，用于持续激励被测设备。
5. 保存发送预设，便于下次调试复用。

周期发送前建议确认总线负载和被测设备状态，避免过高发送频率影响现场网络。

8. DBC、信号与曲线

UCAN-Analyzer 支持加载 DBC 文件并对报文进行信号解析。加载 DBC 后，可使用以下窗口：

如果没有 DBC，也可以在数据分析窗口手工建立数据项，用于临时观察传感器值、计数器、状态位或控制量。

数据从接收通道进入帧存储后，可同时进入追踪表格、DBC 信号解析、曲线显示、协议辅助和导出流程。需要复现实验时，可通过导入帧数据或回放窗口重新查看同一批记录。

9. 总线负载、错误与诊断

总线负载窗口显示当前、平均和峰值负载，适合观察发送频率、网络拥塞和测试脚本对总线的影响。

错误窗口用于查看通道错误计数、状态变化和告警信息。出现异常时，可按以下顺序排查：

1. 确认位率和采样点与现场网络一致。
2. 确认终端电阻和线缆连接正确。
3. 确认 CAN_H / CAN_L 未接反。
4. 降低发送频率或暂停周期发送。
5. 停止并重新启动通道。

10. 回放、导入与导出

软件支持将采集到的帧导出为常用格式，也可以导入历史帧用于查看或回放。

回放到真实总线前，请确认目标网络允许测试帧注入，并避免在生产环境误发送控制报文。

11. 触发规则与自动化

触发窗口可根据通道、CAN ID、DLC 或数据字段建立规则。规则匹配后可执行记录、提示、停止采集或发送预设帧等动作。

Lua 控制台用于更灵活的自动化调试和测试辅助。建议先在离线数据或低风险网络中验证规则，再应用到现场设备。

12. 更新与维护

帮助菜单中的更新入口用于检查软件发布包。软件发布资料通过官网或项目发布页提供，安装前建议确认版本号、目标系统和包类型。

如果安装包包含 UCAN-Mini 固件资源，可在维护流程中使用配套升级功能。升级前应确认：

• 设备连接稳定。
• 不要在升级过程中断开 USB。
• 使用与设备型号匹配的固件包。
• 升级后重新连接设备并验证通道状态。

维护建议按“检查软件版本、确认设备连接、执行升级、重新连接设备、验证通道状态”的顺序进行。现场设备升级前应保留当前项目文件和必要的报文记录。

13. 常见问题

13.1 设备列表为空

检查 USB 连接、设备供电、系统权限和驱动绑定。Linux 下重点检查 udev 权限，Windows 下检查是否被其他软件占用。

13.2 通道启动后收不到帧

确认现场总线有数据，位率与采样点匹配，终端电阻正确，并检查是否设置了过窄的过滤条件。

13.3 出现大量错误帧或错误计数快速增加

优先检查位率、线缆、终端电阻、接地和 CAN_H / CAN_L 极性。必要时先使用监听模式观察网络。

13.4 DBC 信号没有解析结果

确认 CAN ID 类型、扩展帧标志、字节序、缩放系数和信号定义是否与实际报文一致。

13.5 软件更新入口无法获取新版本

检查网络连接、当前系统时间和代理设置。也可以从官网或项目发布页手动下载对应系统的安装包后更新。

14. 版本记录