Chanchaldhiman/CANviz

# CANviz 工具 **基于浏览器的CAN总线分析工具。即插即用。一条命令。即可分析。** [](https://github.com/Chanchaldhiman/CANviz/actions) [](https://pypi.org/project/canviz/) [](https://pepy.tech/project/canviz) [](https://pepy.tech/project/canviz) [](https://pypi.org/project/canviz/) [](LICENSE)  ``` pip install canviz canviz # 浏览器打开 http://localhost:8080 ```  无需安装图形界面。无需配置驱动。无需注册账户。无需网络连接。无论您是在 调试ECU、调试伺服驱动器、分析J1939卡车流量，还是通过CANopen控制机械臂， CANviz都能将每一帧、每个信号和协议事件立即呈现在您面前。 ## 安装与运行 ``` pip install canviz canviz ``` 就这么简单。CANviz 会自动检测已连接的适配器并打开浏览器。 ## 功能特性 完整版本历史请参阅 [CHANGELOG.md](docs/CHANGELOG.md)。 ### 实时消息表 实时显示总线上的每一帧。ID、DLC、原始字节、帧计数、速率和 最后可见时间戳。虚拟滚动可处理数千行数据且无帧丢失。 在持续2,000帧/秒的条件下测试，零丢包。 ### DBC 信号解码 上传一个 `.dbc` 文件，原始十六进制字节将转换为命名的信号值，并在消息表中内联显示。 可随时在原始视图和解码视图之间切换。 ### 信号时序图绘制 将任何解码后的信号绘制为实时时间序列图。共享时间轴上最多可绘制8个信号， 每个信号可缓冲36,000个数据点，采用LTTB降采样算法，渲染速率为10 Hz（与总线速度无关）。 拖拽可缩放，双击可恢复实时滚动，为每个信号设置阈值线和违规警报。 支持一键导出为PNG。 ### 使用定时器进行多帧传输 构建帧列表，每帧拥有独立的传输间隔。可以同时以20 Hz发送心跳包和以10 Hz发送速度信号。 状态在标签页切换后仍然保留。 ### 记录与回放 记录为行业标准的 `.asc` 和 `.csv` 格式。可调整回放速度（0.5倍至10倍）回放任何日志文件。 ### 总线健康统计 始终可见的状态栏：接收/发送帧数、总线负载%、错误帧计数、总线关闭事件、吞吐量。 错误帧的可见性取决于硬件——slcan 固件通常静默丢弃错误帧；当使用 slcan 接口时，会有提示说明此情况。 ### CLI 与无头模式 `canviz monitor` 命令可通过SSH、CI流水线或在无头的树莓派上渲染终端实时彩色编码表。 详见 [CLI 参考手册](#cli-reference)。 ## 协议解码器 CANviz 内置 J1939 和 CANopen 的被动解码器。它们完全基于捕获的流量运行—— 无需额外硬件、无需轮询、无需配置，只需在UI中启用解码器即可。 两个解码器都显示在右侧协议面板中，该面板与消息表并列，并可调整大小。 ### J1939 协议 J1939 是卡车、农业、船舶和建筑设备中的主导协议。 - **自动检测**：250 kbps，29位扩展ID - **CAN ID 分解**：每一帧都显示优先级、PGN、源地址、目标地址 - **54个内置PGN名称**：EEC1、CCVS、DM1、ET1、AMB、VEP1、传输协议等 - **99个源地址名称**：“Engine #1”、“Brakes - System Controller”、“Diesel Particulate Filter Controller” - **BAM 传输重组**：多包消息（VIN、软件ID、长DM负载）完整显示 - **DM1 活跃故障解码**：SPN编号、组件名称、故障模式指示器、发生次数、灯状态 完整文档和基于DBC的信号解码，请参阅 [J1939 指南](docs/j1939.md)。 ### CANopen 协议 (CiA 301 + CiA 402) CANopen 是机器人、工业自动化和运动控制中的主导协议。 CiA 402 覆盖了几乎所有的伺服驱动器和电机控制器。 - **自动检测**：基于COB-ID结构——无需假设比特率 - **节点表**：NMT状态、心跳间隔、每个节点的帧计数 - **CiA 402 驱动器状态**：将状态字解码为命名状态（运行使能、故障、快速停止等），在每个节点旁内联显示 - **CiA 402 驱动器控制**：快捷按钮：使能、上电、关机、快速停止、禁用、故障复位。包含一次性安全提示。 - **EMCY 解码**：错误代码、错误类名称、错误寄存器标志、厂商数据 - **SDO 日志**：从总线流量中自动配对请求/响应，并使用内置的180条CiA 301/402字典条目显示对象名称 - **SDO 读/写**：从面板向任何在线节点发送快速读写请求 - **NMT 命令**：运行、预运行、停止、复位节点、复位通信（带节点选择器） - **对象字典浏览器**：按名称或索引搜索180个标准对象 - **PDO 信号绘图**：上传设备EDS文件，将TPDO负载解码为命名信号，并馈送到绘图标签页 - **读取所有节点对象**：一键从所有已发现节点读取15个标准 CiA 301/402 对象 完整文档、EDS要求、驱动器控制安全注意事项和REST API参考，请参阅 [CANopen 指南](docs/canopen.md)。 ## 硬件 任何运行 **Candlelight 固件** 的适配器在Windows上都支持即插即用，无需安装驱动： | 硬件 | 价格 | 备注 | |----------|-------|-------| | FYSETC UCAN (STM32F072) | ~$8 | 经验证的参考硬件 | | CANable 1.0 (Candlelight) | ~$15 | 广泛可用 | | DSD TECH SH-C31A | ~$20 | gs_usb / slcan 均已测试 | | GY / Seeed Studio USB-CAN | ~$15 | 选择 `USB-CAN Analyzer (GY/Seeed)` | | 任何 gs_usb / WinUSB 设备 | 价格不等 | 应该可以工作 | **通过 python-can 配置也支持以下设备：** - **slcan** -- 运行 slcan 固件的设备（Windows上为COM端口） - **SocketCAN** -- Linux、树莓派、WSL2 - **PEAK PCAN-USB** -- 需要安装PEAK驱动 - **Kvaser** -- 配置中支持，详见 [已知限制](#known-limitations) - **虚拟总线** -- 软件回环，无需硬件 ## 安全模型 ``` Browser (your local browser tab) | HTTP + WebSocket -- localhost only, never leaves your machine Python backend (127.0.0.1:8080) | python-can USB CAN adapter | CAN Bus ``` 浏览器仅与本地 `127.0.0.1:8080` 上的Python进程通信。数据不会离开您的机器。无云服务。无遥测数据。无任何外部连接。所有USB通信都在Python后端内部完成——浏览器永远不会直接访问您的USB设备或CAN总线。 其安全模型与运行任何本地安装的Python工具相同：您信任通过pip安装的代码。如果您对安全性有顾虑，请在安装前审查GitHub上的源代码。 **远程部署：** 使用默认的 `--host 127.0.0.1` 绑定，并通过SSH端口转发访问。不要在没有反向代理（带身份验证）的情况下将端口8080暴露给不受信任的网络。 ## CLI 参考手册 ``` canviz [OPTIONS] --interface gs_usb | slcan | socketcan | virtual (default: gs_usb) --channel COM port or SocketCAN channel (e.g. COM3, can0) --bitrate CAN bitrate in bps (default: 500000) --host Host to bind to (default: 127.0.0.1) --port Port to bind to (default: 8080) --headless Start without opening a browser ``` **子命令：** ``` # 实时终端监控器 -- 支持通过 SSH 工作 canviz monitor --interface socketcan --channel can0 --dbc vehicle.dbc # 捕获帧到文件 canviz capture --output trace.json --duration 60 # 解码捕获的日志 canviz decode --input trace.json --dbc vehicle.dbc --output decoded.csv # 纯 API 服务器（无浏览器） canviz serve --headless --port 8080 ``` 完整的SSH工作流文档，请参阅 [CLI 指南](docs/cli.md)。 ## REST API 与 WebSocket 运行时，完整交互式文档位于 `http://localhost:8080/docs`。 | 方法 | 路径 | 描述 | |--------|------|-------------| | POST | `/connect` | 打开CAN接口 | | POST | `/disconnect` | 关闭接口 | | GET | `/status` | 连接状态和配置 | | GET | `/stats` | 总线统计快照 | | POST | `/send` | 发送一个CAN帧 | | WS | `/ws/frames` | 实时帧和统计流（JSON格式） | | POST | `/dbc/load` | 上传一个DBC文件 | | GET | `/dbc/messages` | 列出已解码的消息定义 | | DELETE | `/dbc` | 卸载DBC | | POST | `/log/start` | 开始记录 | | POST | `/log/stop` | 停止并完成日志 | | GET | `/log/download/{file}` | 下载 `.asc` 或 `.csv` | | POST | `/replay/start` | 开始回放日志文件 | | POST | `/replay/stop` | 停止回放 | | GET | `/canopen/status` | CANopen解码器状态、节点、SDO日志 | | POST | `/canopen/sdo/read` | 向节点发送SDO上传请求 | | POST | `/canopen/sdo/write` | 向节点发送SDO下载请求 | | POST | `/canopen/nmt` | 发送NMT命令 | | GET | `/canopen/objects` | 搜索内置CiA 301/402对象字典 | ## 架构 ``` [CAN Bus] | [USB CAN Module] ~$8-$65 depending on capability | [Python Backend] FastAPI python-can cantools aiofiles typer rich | HTTP + WebSocket (localhost only) [Browser UI] React 18 TanStack Table TanStack Virtual Zustand uPlot | http://localhost:8080 ``` ## 已知限制 - **USB时间戳抖动约1毫秒** -- 这是USB连接的CAN适配器的硬件限制。不适用于亚毫秒级的定时分析。 - **高于2,000帧/秒的高总线负载** -- 未经测试。已内置服务器端节流钩子，可在需要时启用。 - **CAN FD** -- 负载大于8字节的帧显示为原始十六进制。完整的CAN FD UI已列入计划。 - **slcan错误帧** -- slcan固件在转发前会静默丢弃错误帧。即使在总线状态不佳时，slcan接口的总线错误统计也可能显示为0%。使用gs_usb可获得准确的错误可见性。 - **Windows上的Kvaser** -- CANviz有完整的UI支持。连接失败是由于python-can 4.6.1中的一个bug（`canIoCtlInit` 返回 `canERR_PARAM`）。跟踪请见 [python-can #2051](https://github.com/hardbyte/python-can/issues/2051)。问题解决后升级python-can，Kvaser无需任何CANviz更改即可工作。 - **CANopen PDO解码** -- 需要设备的EDS文件。没有EDS时，TPDO1的字节0-1默认假设解码为状态字；其他PDO字节显示为原始十六进制。 - **CANopen SDO分段/块传输** -- 仅解码快速SDO（1-4字节负载）。分段响应显示为原始数据。 - **J1939 PGN数据库** -- SAE J1939数字附录受版权保护，无法重新分发。内置的54个PGN表涵盖了常见的发动机和车辆信号。加载您自己的DBC以获得完整覆盖。 - **回放时序** -- 取决于Python asyncio调度器，而非硬件时钟。 - **浏览器支持** -- 已在Chrome上测试。Firefox和Edge为尽力支持。 - **移动设备布局** -- 非目标设备。针对1080p及以上分辨率优化。 ## 故障排除 **在Ubuntu / Linux上出现 `No matching distribution found for canviz`** - 使用 `pip3 install canviz` 或 `python3 -m pip install canviz`。CANviz需要Python 3.10+。Ubuntu 20.04自带Python 3.8——请升级到22.04+或单独安装Python 3.10。 - 如果仍不工作，尝试使用pipx安装： `sudo apt install pipx` `pipx ensurepath`， 然后尝试 `pipx install canviz` **设备在Windows上显示为COM端口** 您的适配器运行的是slcan固件，而不是Candlelight。 使用：`canviz --interface slcan --channel COM3` **PEAK PCAN-USB 连接失败** 确保已安装 [PEAK驱动](https://www.peak-system.com/Drivers.523.0.html)。 设备管理器中，设备必须显示在 **CAN-Hardware** 下，而不是作为未知设备。 **Kvaser 连接失败 (`canIoCtl failed -- Error in parameter`)** 这是python-can 4.6.1中的已知bug。详见 [已知限制](#known-limitations)。 **CANopen节点未出现** 启用解码器，然后等待一个心跳周期（通常为250-1000毫秒）。如果节点禁用了心跳（0x1017 = 0），请先发送一个NMT运行广播。 **CANopen SDO读取返回ABORT** 节点拒绝了请求。常见原因：对象不存在于该节点的对象字典中（0x06020000），或对象是只写的（0x06010001）。请检查SDO日志中的中止代码以获取确切原因。 ## 路线图 - [x] 实时帧表、DBC解码、过滤、发送、记录、回放、pip安装 - [x] 信号绘图、多信号叠加、阈值警报、CLI模式、总线健康统计、多帧传输 - [x] J1939被动解码器 -- PGN/SA解码、BAM重组、DM1故障解码 - [x] CANopen CiA 301 + CiA 402 -- NMT、EMCY、SDO、PDO、心跳、驱动器控制 - [ ] CAN FD 显式UI支持（>8字节负载、FDF/BRS/ESI标志） - [ ] 基于原始CAN的OBD-II -- ISO 15765-4，无需ELM327 - [ ] UDS诊断面板 -- ReadDataByIdentifier、ReadDTCInformation、ClearDTC - [ ] 逆向工程工具包 -- 位翻转率热图、陷波滤波器嗅探器、自动DBC生成 - [ ] 插件API -- 可pip安装的社区解码器和导出器 ## 贡献 CANviz正在积极开发中。目前最有价值的贡献是测试我们尚未尝试过的硬件——例如CANable 2.0、任何macOS设备、任何通过COM端口连接的设备。无需编写代码。只需提交一个issue，告诉我们发生了什么。 欢迎提交错误报告、解码不正确的DBC文件以及代码贡献。 如何设置开发环境，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 致谢 CANviz建立在卓越的开源工作之上。没有这些，一切都不会存在： - **[python-can](https://github.com/hardbyte/python-can)** -- 硬件抽象层，使得每个CAN适配器都能通过相同的三行Python代码工作。技术栈中最重要的依赖。 - **[cantools](https://github.com/eerimoq/cantools)** -- DBC解析和信号解码。坚实可靠，维护良好，处理了我们遇到的每一种DBC方言。 - **[canopen](https://github.com/christiansandberg/canopen)** -- CiA 301对象字典解析和EDS支持。驱动了CANopen PDO解码流水线。 - **[FastAPI](https://github.com/tiangolo/fastapi)** -- 后端API框架。异步WebSocket支持和自动OpenAPI文档确实非常出色。 - **[uPlot](https://github.com/leeoniya/uPlot)** -- 一个快得离谱的时间序列绘图库。在10 Hz下每个信号处理36,000个数据点且不卡顿，这需要真正的工程技巧，而Leon Sorokin做到了。 - **[TanStack Table](https://github.com/TanStack/table)** 和 **[TanStack Virtual](https://github.com/TanStack/virtual)** -- 虚拟滚动数千个CAN帧而不丢失一行数据并非易事。这些库使其变得简单直接。 - **[Zustand](https://github.com/pmndrs/zustand)** -- 最小化、快速且不碍事。状态管理名副其实。 - **[Typer](https://github.com/fastapi/typer)** 和 **[Rich](https://github.com/Textualize/rich)** -- CLI终端输出看起来很好看要归功于这两个库。 - **[pretty_j1939](https://github.com/nmfta-repo/pretty_j1939)** -- 开放的J1939 PGN和SPN定义，驱动了J1939解码器的内置名称表。 感谢所有提交问题、测试硬件和发送DBC文件的每一位。每一条反馈都让工具变得更好。 ## 支持 CANviz是免费且开源的。如果它为您节省了时间或对您的项目有所帮助，可以考虑 [在GitHub上赞助开发](https://github.com/sponsors/Chanchaldhiman)。每一份赞助都直接用于购买测试新适配器和协议的硬件。 ## 许可证 MIT -- 详见 [LICENSE](LICENSE)。

标签：CAN分析器, CAN总线, DBC文件, DNS解析, Python, 低功耗硬件, 信号解码, 嵌入式系统, 嵌入式调试, 工业自动化, 开源CAN工具, 开源项目, 总线分析工具, 数据解析, 无后门, 时间序列分析, 汽车电子, 浏览器, 浏览器CAN分析, 绘图, 自动化攻击, 诊断工具, 逆向工具