企业官网建设流程全解析

• 嵌入式
• 开发工具

本文以 cantools 官方文档（docs/index.rst，内嵌完整README.rst）为骨架，结合仓库源码展开，系统讲解这个 Python 3 CAN 总线工具集从数据库解析（DBC/KCD/SYM/ARXML/CDD）、消息编码解码、诊断 DID、CLI 命令行工具（decode/plot/dump/list/generate_c_source/monitor/convert）到 C 源码生成与 Ubuntu 虚拟 CAN 接口（vcan）实战的完整技术栈。阅读本文后，你将能够直接用 cantools 加载车载网络数据库、在脚本或candump管道中实时解码 CAN 报文、可视化信号曲线、生成可落地的 C 代码，并理解其 API 设计与编码规范。

项目概览：cantools 能做什么

cantools 是使用 Python 3 编写的 CAN 总线工具集（CAN BUS tools in Python 3.），官方文档将其核心能力总结为：

• 多格式数据库解析：支持DBC、KCD、SYM、ARXML 3&4 与 CDD 文件的读取与写入。
• CAN 消息编码与解码：根据信号定义（位序、缩放因子、偏移量、符号性）将物理量编码为字节串、或将原始字节解码为物理量。
• 简单与扩展的信号多路复用（signal multiplexing）：支持一个多路复用信号按取值切换不同的信号子集。
• 诊断 DID 编码与解码：面向 UDS 等诊断服务的数据（DID/Data）编解码。
• candump输出解码：直接消费 Linuxcandump程序抓取的日志流。
• 节点 Tester 工具：cantools.tester.Tester提供基于 CAN 数据库的测试辅助。
• C 源代码生成器：从数据库生成 C 语言的struct、pack/unpack与信号encode/decode函数。
• CAN 总线监控器：文本界面实时监控总线流量。
• 信号图形化绘图：基于 matplotlib 可视化信号随时间的变化曲线。

上述能力的模块组织可从源码结构印证：src/cantools/database/下是 CAN 与诊断数据库的加载/序列化逻辑（can/formats/含dbc/、kcd.py、sym.py、arxml/，diagnostics/formats/cdd.py负责 CDD）；src/cantools/subparsers/下是各 CLI 子命令（decode.py、plot.py、monitor.py、generate_c_source.py、convert.py、list.py、dump/）；src/cantools/c_source.py与tester.py分别对应 C 代码生成与节点测试。

安装

项目使用标准pip方式安装：

python3 -m pip install cantools

注意：默认安装不包含 matplotlib，因此plot绘图子命令需要额外安装可选依赖：

python3 -m pip install cantools[plot]

同理，数据库加载缓存（见下文cache_dir参数）依赖可选的diskcache包，可通过pip install cantools[cache]启用。

脚本化使用：加载数据库、编码与解码

官方文档以tests/files/dbc/motohawk.dbc这个小型 DBC 文件为贯穿示例。第一步是解析数据库并打印消息与信号：

>>> import cantools >>> from pprint import pprint >>> db = cantools.database.load_file('tests/files/dbc/motohawk.dbc') >>> db.messages [message('ExampleMessage', 0x1f0, False, 8, 'Example message used as template in MotoHawk models.')] >>> example_message = db.get_message_by_name('ExampleMessage') >>> pprint(example_message.signals) [signal('Enable', 7, 1, 'big_endian', False, 1.0, 0, 0.0, 0.0, '-', False, None, {0: 'Disabled', 1: 'Enabled'}, None), signal('AverageRadius', 6, 6, 'big_endian', False, 0.1, 0, 0.0, 5.0, 'm', False, None, None, ''), signal('Temperature', 0, 12, 'big_endian', True, 0.01, 250, 229.53, 270.47, 'degK', False, None, None, None)]

从输出可见Message与Signal的 repr 字段对应其构造参数：Enable（起始位 7，长度 1 位，大端，缩放 1.0，偏移 0，枚举值{0: 'Disabled', 1: 'Enabled'}）、AverageRadius（缩放 0.1，单位 m）、Temperature（有符号，缩放 0.01，偏移 250，范围 229.53~270.47，单位 degK）。

编码并发送到总线

配合python-can包，可把信号字典编码为字节串并发送到虚拟 CAN 总线：

>>> import can >>> can_bus = can.interface.Bus('vcan0', bustype='socketcan') >>> data = example_message.encode({'Temperature': 250.1, 'AverageRadius': 3.2, 'Enable': 1}) >>> message = can.Message(arbitration_id=example_message.frame_id, is_extended_id=example_message.is_extended_frame, data=data) >>> can_bus.send(message)

也可以绕过Message.encode()，直接调用数据库级的encode_message()（源码见 database.py，它同时接受 frame_id（int）或消息名（str），内部走_frame_id_to_message/_name_to_message查表）：

>>> db.encode_message(158, {'Bar': 1, 'Fum': 5.0}) b'\x01\x45\x23\x00\x11' >>> db.encode_message('Foo', {'Bar': 1, 'Fum': 5.0}) b'\x01\x45\x23\x00\x11'

encode()方法（message.py）的三个可选参数含义：

• scaling=True：默认对信号应用缩放（物理量 = raw × factor + offset）；设为False则不缩放。
• padding=False：默认未使用的位编码为 0；设为True则按unused_bit_pattern（默认0x00）填充为 1。
• strict=True：严格模式会先调用assert_signals_encodable()校验信号值是否在允许范围内、信号是否齐全，否则抛出EncodeError。

接收并解码

接收一帧并解码得到信号名到物理值的字典：

>>> message = can_bus.recv() >>> db.decode_message(message.arbitration_id, message.data) {'AverageRadius': 3.2, 'Enable': 'Enabled', 'Temperature': 250.09}

注意Enable被解码为枚举字符串'Enabled'而非整数1——这是decode_choices默认开启的效果。decode_message()（database.py）关键参数：

• decode_choices=True：将缩放后的值映射为choices中的字符串；设为False则返回数值。
• scaling=True：默认缩放；False返回原始 raw 值。
• allow_truncated=False：数据不足时是否允许截断解码。
• decode_containers=False：容器帧（container frame）的解码需显式开启，否则抛出DecodeError；因为容器帧返回的是(Message, SignalsDict)元组列表，会破坏普通调用方的预期。

更多综合示例见仓库 examples 目录（如 hello_world.py、dbc_io/main.py、motor_tester）。

核心 API 参考（Functions and classes）

docs/index.rst通过 Sphinx 的autofunction/autoclass/autodata指令，把以下对象直接纳入文档索引，构成完整的公开 API 面：

顶层加载/转储函数

• cantools.database.load_file()：打开并解析文件，返回can.Database或diagnostics.Database。
• cantools.database.dump_file()：将数据库写回文件。
• cantools.database.load_string()：解析字符串内容。
• cantools.database.load()：解析文件对象（file-like object，读取其.read()内容）。

load_file 的格式与编码推断

load_file()（database/init.py）在database_format与encoding均为None时，按扩展名自动推断格式、按格式推断默认编码（扩展名大小写不敏感）：

（'dbc'与'sym'默认使用cp1252编码，是因为这两种格式在历史工具链中常含 Latin-1 字符，源码_resolve_database_format_and_encoding()中明确映射了这一点。）

其他重要参数：

• frame_id_mask：对消息 frame id 做掩码后建索引，用于复用同一 id 空间的场景。
• prune_choices：默认开启，把枚举取值名中共有的、以_结尾的前缀去掉以缩短名称；需要原名时传False。
• strict=True：信号重叠或超出消息长度时抛异常。
• sort_signals：默认sort_signals_by_start_bit（按起始位排序）；传None不排序，也可传自定义函数如lambda signals: list(sorted(signals, key=lambda sig: sig.name))。
• cache_dir：启用磁盘缓存（依赖diskcache），缓存键包含文件路径 + 修改时间 + 全部影响结果的参数；可通过环境变量CANTOOLS_CACHE_DIR开启，删除cache_dir目录即可清缓存。未安装diskcache时会发出警告并自动禁用缓存。
• 解析失败会抛出UnsupportedDatabaseFormatError；load_string()在database_format=None时按arxml → dbc → kcd → sym → cdd顺序逐一尝试解析（源码见 database/init.py）。

dump_file 的写回规则

dump_file()（database/init.py）只支持写出'dbc'、'kcd'、'sym'三种格式（其余抛Unsupported output database format）。规则：

• 'dbc'文件总是使用 Windows 风格行尾（\r\n），其他格式跟随操作系统；这与源码中newline=''（\r\n的显式声明）一致。
• DBC 默认按信号起始位降序排序输出，KCD 默认不排序；可通过sort_signals=None关闭排序。若要让 foo.dbc 与 bar.dbc 差异最小，加载时传sort_signals=None, prune_choices=False。
• load_file(..., sort_signals=None)后再dump_file()会继承“不排序”的设定（as_dbc_string()中若加载时未排序则默认也传None）。

CAN 数据库对象：Database / Message / Signal / Node / Bus / SignalGroup

• cantools.database.can.Database：整个 CAN 网络的容器。公开属性/方法包括messages、nodes、buses、version、dbc（DBC 特有属性对象）、autosar（AUTOSAR 特有属性对象）、get_message_by_name()、get_message_by_frame_id()（frame id 大于0x7FF自动按扩展帧处理）、get_node_by_name()、get_bus_by_name()、encode_message()、decode_message()、add_dbc_string()/add_dbc_file()/add_arxml_string()/add_arxml_file()/add_kcd_string()/add_kcd_file()/add_sym_string()/add_sym_file()、as_dbc_string()/as_kcd_string()/as_sym_string()、is_similar()（容差比较，忽略舍入等微小差异）、refresh()（修改消息后重建查找表）。构造参数中的strict与sort_signals语义与load_*一致，frame_id_mask默认0xffffffff。
• cantools.database.can.Message：单条 CAN 消息。属性包括frame_id、name、length、signals、is_extended_frame、is_fd、senders、receivers、comment/comments、send_type、cycle_time、dbc、autosar、signal_groups、signal_tree、is_container、contained_messages、header_id、unused_bit_pattern等。方法包括encode()、decode()、decode_simple()、decode_container()、unpack_container()、get_signal_by_name()、is_multiplexed()、refresh()。构造时对 frame id 有位数校验：标准帧超过 11 位、扩展帧超过 29 位都会抛Error（见 message.py）。
• cantools.database.can.Signal：单个信号。属性包括name、start、length、byte_order（little_endian/big_endian）、is_signed、raw_initial、raw_invalid、conversion、minimum、maximum、unit、comment/comments、receivers、is_multiplexer、multiplexer_ids、multiplexer_signal、spn、choices等；方法包括raw_to_scaled()、scaled_to_raw()、choice_to_number()、is_float()。
• cantools.database.can.Node：网络节点，属性name、comment/comments、dbc、autosar。
• cantools.database.can.Bus：总线，属性name、comment/comments、baudrate、fd_baudrate、autosar。
• cantools.database.can.signal_group.SignalGroup：信号组，属性name、repetitions、signal_names。

DBC 特有对象

• DbcAttributeDefinition：DBC 属性定义，属性name、default_value、kind、type_name、minimum、maximum、choices。
• DbcAttributeValueTypeVar：属性值类型联合（autodata指令导出）。
• DbcAttribute：一次具体属性赋值，属性name、value、definition，方法formatted_value()。
• DbcEnvironmentVariable：DBC 环境变量，属性name、env_type、minimum、maximum、unit、initial_value、env_id、access_type、access_nodes、data_size、comment、dbc。
• DbcSpecifics：挂在 Database/Message/Node/Signal 上的 DBC 专属信息，属性attributes、attribute_definitions、value_tables、environment_variables、relation_attributes、relation_attribute_definitions。这些类型定义位于 formats/dbc 下，如dbc_attribute_definition.py、dbc_attribute.py、dbc_environment_variable.py、dbc_specifics.py。

AUTOSAR 特有对象

• AutosarDatabaseSpecifics：数据库级 AUTOSAR 信息（如arxml_version）。
• AutosarMessageSpecifics：消息级信息，属性pdu_paths、is_nm、is_general_purpose、is_secured、secoc（SecOC 安全属性）、e2e（E2E 端到端保护属性）。
• AutosarNodeSpecifics：节点级 AUTOSAR 信息。
• AutosarSecOCProperties：SecOC 属性，含auth_algorithm_name、freshness_algorithm_name、payload_length、data_id、auth_tx_bit_length、freshness_bit_length、freshness_tx_bit_length。
• AutosarEnd2EndProperties：E2E 属性，含category、data_ids、payload_length。
• AutosarBusSpecifics：总线级 AUTOSAR 信息。

这些类型位于 formats/arxml（database_specifics.py、message_specifics.py、node_specifics.py、secoc_properties.py、end_to_end_properties.py、bus_specifics.py），由SystemLoader（system_loader.py）与EcuExtractLoader（ecu_extract_loader.py）两类加载器解析 AUTOSAR System Extract 与 ECU Extract 文件（ecu-extract-4.2.arxml、system-4.2.arxml 等测试样例）。

数值表示与转换

• cantools.database.namedsignalvalue.NamedSignalValue：信号命名值（如带名称的枚举物理量），其__repr__/__eq__使{'Enable': 'Enabled'}这样的字典可直接比较与打印。
• cantools.database.conversion.BaseConversion：缩放转换基类，Signal.scale/offset即其实现。

诊断数据库（UDS DID）

• cantools.database.diagnostics.Database：诊断数据库。
• cantools.database.diagnostics.Did：诊断标识符（DID）。
• cantools.database.diagnostics.Data：DID 承载的数据对象。

CDD 格式由 diagnostics/formats/cdd.py 实现，测试样例见 tests/files/cdd（如 example.cdd、example-diddatarefs.cdd），示例脚本见 examples/diagnostics/did.py。

异常与测试辅助

• cantools.database.UnsupportedDatabaseFormatError：无法识别数据库格式时抛出（errors.py 中与DecodeError、EncodeError并列定义）。
• cantools.tester.Tester：基于 CAN 数据库的节点测试类。
• cantools.tester.DecodedMessage：解码后的消息容器，含name（消息名）与signals（消息信号）两个数据字段。
• cantools.typechecking.Codec：内部编解码器类型别名，Message._codecs即该类型，用于描述一条消息全部信号的解码格式与多路复用结构。

命令行工具（CLI）

CLI 入口为python3 -m cantools（main.py 调用init.py 中的_main()）。顶层参数有-d/--debug（开启 DEBUG 日志）与--version。所有子命令定义在src/cantools/subparsers/目录，每个模块提供add_subparser()向 argparse 注册，因此新子命令是自动发现、按文件加载的（加载失败不影响其他命令）。可用子命令包括decode、plot、dump、list、generate_c_source、monitor、convert等。

decode：解码 candump 输出

从标准输入读取 Linuxcandump抓取的帧，按数据库解码为可读文本：

$ candump vcan0 | python3 -m cantools decode tests/files/dbc/motohawk.dbc vcan0 1F0 [8] 80 4A 0F 00 00 00 00 00 :: ExampleMessage( Enable: 'Enabled' -, AverageRadius: 0.0 m, Temperature: 255.92 degK )

使用--single-line把每条消息压缩到一行，便于脚本或日志聚合：

$ candump vcan0 | python3 -m cantools decode --single-line tests/files/dbc/motohawk.dbc vcan0 1F0 [8] 80 4A 0F 00 00 00 00 00 :: ExampleMessage(Enable: 'Enabled' -, AverageRadius: 0.0 m, Temperature: 255.92 degK)

plot：信号可视化

plot与decode类似，但输出 matplotlib 图形而非文本。先抓取日志再绘图：

$ candump -l vcan0 $ cat candump-2021-01-04_180521.log (1609779922.655421) vcan0 00000343#B204B9049C049C04 (1609779922.655735) vcan0 0000024A#120527052E051905 ... $ cat candump-2021-01-04_180521.log | python3 -m cantools plot tests/files/dbc/abs.dbc

信号选择语法支持通配符与布局控制：

• *匹配任意数量任意字符，?匹配恰好一个任意字符；
• 用-分隔的信号显示在不同子图；
• 信号后可用冒号指定可选格式（如:-<、:>、:3、:4等线型/样式标记）。

例如左侧轮速与右侧轮速分两个子图显示：

$ cat candump-2021-01-04_180521.log | python3 -m cantools plot tests/files/dbc/abs.dbc '*33.*fl:-<' '*33.*fr:->' - '*33.*rl:-<' '*33.*rr:->'

取值范围差异大的信号可以在同一子图内使用不同纵轴：用逗号分隔信号组，配合--auto-color自动着色，并用--ylabel分别标注：

$ cat candump-2021-01-04_180521.log | cantools plot --auto-color tests/files/dbc/abs.dbc -- \ --ylabel 'Bremse 33' '*_33.*fl*:-<' '*_33.*fr*:>' '*_33.*rl*:3' '*_33.*rr*:4' , \ --ylabel 'Bremse 2' '*_2.*fl*:-<' '*_2.*fr*:>' '*_2.*rl*:3' '*_2.*rr*:4'

matplotlib 预装多种绘图风格，可直接套用：

$ cat candump-2021-01-04_180521.log | cantools plot tests/files/dbc/abs.dbc --style seaborn

遍历所有可用风格逐个预览：

$ cantools plot --list-styles . | sed -n '/^- /s/^- //p' | while IFS= read -r style; do cat candump-2021-01-04_180521.log | cantools plot tests/files/dbc/abs.dbc --style "$style" --title "--style '$style'" done

全部参数以python3 -m cantools plot --help为准。相关单测见 test_plot.py 与 test_plot_unittests.py。

dump：人类可读转储

以美观的排版打印数据库全部内容，包括位布局图、信号树与枚举值：

$ python3 -m cantools dump tests/files/dbc/motohawk.dbc ================================= Messages ================================= ------------------------------------------------------------------------ Name: ExampleMessage Id: 0x1f0 Length: 8 bytes Cycle time: - ms Senders: PCM1 Layout: Bit 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ 0 |<-x|<---------------------x|<--| +---+---+---+---+---+---+---+---+ | +-- AverageRadius +-- Enable +---+---+---+---+---+---+---+---+ 1 |-------------------------------| +---+---+---+---+---+---+---+---+ 2 |----------x| | | | | | B +---+---+---+---+---+---+---+---+ y +-- Temperature t +---+---+---+---+---+---+---+---+ e 3 | | | | | | | | | +---+---+---+---+---+---+---+---+ 4 | | | | | | | | | +---+---+---+---+---+---+---+---+ 5 | | | | | | | | | +---+---+---+---+---+---+---+---+ 6 | | | | | | | | | +---+---+---+---+---+---+---+---+ 7 | | | | | | | | | +---+---+---+---+---+---+---+---+ Signal tree: -- {root} +-- Enable +-- AverageRadius +-- Temperature Signal choices: Enable 0 Disabled 1 Enabled

该子命令实现于 subparsers/dump，格式化逻辑在 formatting.py。

list：脚本友好输出

与dump类似，但输出“没那么漂亮、更全面、更适合 shell 脚本解析”：

$ python3 -m cantools list -a tests/files/dbc/motohawk.dbc ExampleMessage: Comment[None]: Example message used as template in MotoHawk models. Frame ID: 0x1f0 (496) Size: 8 bytes Is extended frame: False Signals: Enable: Type: Integer Start bit: 7 Length: 1 bits Unit: - Is signed: False Named values: 0: Disabled

-a/--all等选项说明可用python3 -m cantools list --help查询（实现见 subparsers/list.py）。

generate_c_source：生成 C 代码

从数据库生成 C 源码，生成物包含：

• 消息struct（motohawk.h 中对应#define MOTORA ...与结构体定义区域）；
• 消息pack/unpack函数；
• 信号encode/decode函数；
• frame id、长度、类型、周期时间与信号枚举的#define宏（如MOTORA_EXAMPLE_MESSAGE_FRAME_ID、MOTORA_EXAMPLE_MESSAGE_LENGTH等）。

已知限制：信号最大 64 位（实践中几乎不会超过）。

$ python3 -m cantools generate_c_source tests/files/dbc/motohawk.dbc Successfully generated motohawk.h and motohawk.c.

生成的完整内容可对照 motohawk.h 与 motohawk.c 查看。

--use-float：浮点信号使用单精度float而非double：

$ python3 -m cantools generate_c_source --use-float tests/files/dbc/motohawk.dbc Successfully generated motohawk.h and motohawk.c.

--database-name：自定义生成类型、宏与函数的命名空间前缀，同时改变输出文件名：

$ python3 -m cantools generate_c_source --database-name my_database_name tests/files/dbc/motohawk.dbc Successfully generated my_database_name.h and my_database_name.c.

见 my_database_name.h 与 my_database_name.c。

--no-floating-point-numbers：生成不含float/double的定点代码：

$ python3 -m cantools generate_c_source --no-floating-point-numbers tests/files/dbc/motohawk.dbc Successfully generated motohawk.h and motohawk.c.

见 motohawk_no_floating_point_numbers.h 与 motohawk_no_floating_point_numbers.c。

--node：只生成指定节点发送消息的pack函数、以及信号接收者属于该节点的unpack函数：

$ cantools generate_c_source tests/files/dbc/motohawk.dbc --node PCM1 Successfully generated motohawk.h and motohawk.c.

见 motohawk_sender_node.h 与 motohawk_sender_node.c。

C 生成器核心实现位于 src/cantools/database/can/c_source.py，对应测试样例覆盖了位域（*_bit_fields.*）、浮点（floating_point.*）、多路复用（multiplex.*）、轮询舍入（motohawk_use_round.*）等多种形态，见 tests/files/c_source。

monitor：文本界面总线监控

以 TUI（文本用户界面）实时监控总线流量：

$ python3 -m cantools monitor tests/files/dbc/motohawk.dbc

底部菜单提供以下操作：

• Quit：退出监控器（也可用Ctrl-C）。
• Filter：只显示匹配给定正则表达式的消息或信号；输入行按<Enter>返回菜单。
• Play/Pause：在播放与暂停（运行与冻结）之间切换。
• Reset：将监控器重置到初始状态。

实现见 subparsers/monitor.py，相关单测见 test_monitor.py。

convert：数据库格式互转

convert子命令把数据库从一种格式转换为另一种（实现见 subparsers/convert.py），对应测试见 test_convert.py 与 test_conversion.py。DBC 互转的正确性由tests/files/dbc/下的“原文件 +*_dumped文件”配对验证（如 multiplex_2.dbc 与 multiplex_2_dumped.dbc）。

Coding style：编码规范

文档以“基于作者个人偏好”的方式定义了本包源码的编码风格，对贡献者而言是必须遵守的规则：

1. 语句（if、while、return等）前后要有空行；除非位于其他语句或文件的开头/结尾。
2. 文件级定义之间留两个空行。
3. 运算符前后留空格；关键字参数（keyword arguments）两侧不允许空格。
4. 每行只导入一个模块/对象。
5. 注释与 docstring 以大写字母开头、以句号结尾（像句子一样）。
6. docstring 之后留一个空行。
7. 单行最大 90 字符，目标是不超过 80 字符。
8. 函数参数要么全部写在一行，要么每行一个。
9. 类名用CamelCase，不允许下划线。
10. 函数名与变量名用小写 + 下划线分隔（snake_case）。

规范的示例代码（数字标注对应上述规则）：

import sys from os import path # (5) from os import getcwd # (5) # (2) # (2) def foo(bars, fum=None): # (4) """This is a doc string. # (6) """ # (7) fies = [] # (3) kam = path.join(getcwd(), '..') # (1) for bar in bars: if len(bar) == 1): # (8) fies.append(ham + 2 * bar) # (3) # (1) # This is a comment. # (6) if fum in None: fum = 5 # (3) else: fum += 1 # (3) # (1) fies *= fum # (3) # (1) return fies # (2) # (2) def goo(): return True

（示例中if len(bar) == 1):与if fum in None是文档原样保留的演示代码，并非真实语法。）

Tips and tricks：Ubuntu 虚拟 CAN 接口

在无硬件的情况下调试 CAN 应用，可在 Ubuntu 上创建虚拟 CAN 接口。官方文档给出的完整三步设置：

sudo modprobe vcan sudo ip link add dev vcan0 type vcan sudo ip link set vcan0 mtu 72 # For CAN-FD sudo ip link set up vcan0

• 第一条加载vcan内核模块；
• 第二条创建名为vcan0的虚拟 CAN 设备；
• 第三条（可选）把 MTU 设为 72，以支持 CAN-FD（经典 CAN 的 MTU 为 16，CAN-FD 需要 72）；
• 第四条把接口置为up状态。

设置完成后，即可配合python-can的socketcan后端（can.interface.Bus('vcan0', bustype='socketcan')）以及candump/can send等工具进行收发测试。仓库中decode、plot、monitor各子命令的文档示例均基于此环境。

贡献指南（Contributing）

文档同时给出了向本仓库提交贡献的标准流程：

1. Fork 仓库。
2. 安装开发依赖（使用tox可跳过此步）：python3 -m pip install -e .[dev]。
3. 实现新功能或修复 bug。
4. 编写测试用例，防止未来改动破坏既有行为。
5. 运行 linter：ruff check src、mypy src（或tox -e ruff、tox -e mypy）。
6. 运行测试：tox -e py。
7. 检查测试覆盖率：tox -e cov，然后用firefox htmlcov/index.html查看报告。
8. 创建 Pull Request。

配置集中在 pyproject.toml 与 tox.ini，完整的测试套件位于 tests 目录（test_database.py、test_command_line.py、test_autosar.py 等），C 生成代码的交叉验证由 tests/test_c_code 下的 C 测试工程完成。

总结

作为docs/index.rst的完整导读，本文覆盖了 cantools 文档的全部四大板块：README 中的功能矩阵、安装与脚本/CLI 全流程示例；Sphinx 自动生成的 Functions and classes API 索引（含 CAN 数据库、DBC/AUTOSAR 特有对象、诊断数据库与 Tester）；作者定义的 Coding style 规范；以及 Ubuntu vcan 虚拟接口搭建技巧。配合仓库中 examples、tests/files 与 src/cantools 源码，读者可以完整掌握这一 CAN 工具链的实战用法与内部机制。

• 嵌入式
• 开发工具