pub const SPECIFICATION: &str = "# DBC File Format Specification\n\n---\n\n## Table of Contents\n\n1. [Introduction](#introduction)\n2. [General Definitions](#general-definitions)\n3. [File Structure](#file-structure)\n4. [Version and New Symbols](#version-and-new-symbols)\n5. [Bit Timing Definition](#bit-timing-definition)\n6. [Node Definitions](#node-definitions)\n7. [Value Table Definitions](#value-table-definitions)\n8. [Message Definitions](#message-definitions)\n9. [Signal Definitions](#signal-definitions)\n10. [Bit Manipulation and Byte Ordering](#bit-manipulation-and-byte-ordering)\n11. [Message Transmitters](#message-transmitters)\n12. [Environment Variables](#environment-variables)\n13. [Signal Types and Groups](#signal-types-and-groups)\n14. [Comments](#comments)\n15. [User-Defined Attributes](#user-defined-attributes)\n16. [Extended Multiplexing](#extended-multiplexing)\n17. [Common Attributes](#common-attributes)\n18. [Examples](#examples)\n19. [Validation and Error Checking](#validation-and-error-checking)\n20. [Best Practices](#best-practices)\n21. [Common Pitfalls](#common-pitfalls)\n22. [Tools and Parsers](#tools-and-parsers)\n23. [Glossary](#glossary)\n24. [References](#references)\n\n---\n\n## 1. Introduction\n\nA DBC (Database Container) file describes the communication protocol for a single Controller Area Network (CAN). The information contained within enables:\n\n- **Network monitoring** - Real-time observation of CAN traffic\n- **Traffic analysis** - Decoding raw CAN data to human-readable values\n- **ECU simulation** - \"Remaining bus simulation\" for ECUs not physically present\n- **Communication software development** - Foundation for ECU software that participates in the network\n\n**Important Limitations:**\n- DBC files describe **only the communication layer**\n- They do **not** specify internal functional behavior or application logic of ECUs\n- They represent the **passive/reading** part of CAN communication, not transmission logic\n\n---\n\n## 2. General Definitions\n\nThe following general elements are used throughout this specification:\n\n| Element | Description | Example |\n|---------|-------------|---------|\n| `unsigned_integer` | An unsigned integer | `100`, `255`, `0` |\n| `signed_integer` | A signed integer | `-50`, `0`, `100` |\n| `double` | A double precision floating point number | `0.25`, `-40.5`, `1.0` |\n| `Printable character` | ASCII characters 0x20 - 0x7E (including space) | `A`, `9`, `_`, ` ` |\n| `char_string` | String of printable characters (no `\"` or `\\`) | `\"Engine Speed\"`, `\"km/h\"` |\n| `C_identifier` | Valid C identifier: starts with letter/underscore, contains alphanumeric/underscores | `EngSpeed`, `_temp`, `signal_1` |\n| `DBC_identifier` | A `C_identifier` that is not a DBC keyword | `EngineData`, `RPM` |\n\n### DBC Keywords\n\nThe following are reserved keywords and **cannot** be used as identifiers:\n\n```\nVERSION, NS_, NS_DESC_, CM_, BA_DEF_, BA_, VAL_, CAT_DEF_, CAT_, FILTER, \nBA_DEF_DEF_, EV_DATA_, ENVVAR_DATA_, SGTYPE_, SGTYPE_VAL_, BA_DEF_SGTYPE_, \nBA_SGTYPE_, SIG_TYPE_REF_, VAL_TABLE_, SIG_GROUP_, SIG_VALTYPE_, \nSIGTYPE_VALTYPE_, BO_TX_BU_, BA_DEF_REL_, BA_REL_, BA_DEF_DEF_REL_, \nBU_SG_REL_, BU_EV_REL_, BU_BO_REL_, SG_MUL_VAL_, BS_, BU_, BO_, SG_, EV_, \nVECTOR__INDEPENDENT_SIG_MSG, VECTOR__XXX\n```\n\n### Object Type Keywords\n\n| Keyword | Object Type |\n|---------|-------------|\n| `BU_` | Network Node (Bus Unit) |\n| `BO_` | Message (Bus Object) |\n| `SG_` | Signal |\n| `EV_` | Environment Variable |\n| `SIG_GROUP_` | Signal Group |\n| `VAL_TABLE_` | Value Table |\n\n### String and Identifier Limits\n\n- **DBC identifiers:** Maximum 32 characters\n- **Other strings:** Arbitrary length (parser-dependent limits may apply)\n- **Security:** Modern parsers limit string lengths to prevent buffer overflow attacks\n- **dbc-rs note:** For security reasons, dbc-rs limits string lengths depending on the object type\n\n---\n\n## 3. File Structure\n\nThe DBC file format has the following overall structure:\n\n```bnf\nDBC_file =\n version\n new_symbols\n bit_timing (* Required but typically empty *)\n nodes (* Required *)\n value_tables\n messages (* Core section *)\n message_transmitters\n environment_variables\n environment_variables_data\n signal_types (* Rarely used *)\n comments\n attribute_definitions\n sigtype_attr_list (* Rarely used *)\n attribute_defaults\n attribute_values\n value_descriptions\n category_definitions (* Obsolete *)\n categories (* Obsolete *)\n filter (* Obsolete *)\n signal_type_refs (* Rarely used *)\n signal_groups\n signal_extended_value_type_list\n extended_multiplexing ;\n```\n\n### Core Sections (Required for Basic DBC)\n\n1. **bit_timing** - Required keyword but typically empty\n2. **nodes** - Defines network participants\n3. **messages** - Defines CAN messages and their signals\n\n### Optional Sections (Common)\n\n- **comments** - Human-readable descriptions\n- **attribute_definitions** - Custom attributes\n- **attribute_values** - Attribute assignments\n- **value_descriptions** - Text encodings for signal values\n- **signal_extended_value_type_list** - Float/double signal types\n\n### Rarely Used Sections\n\n- **signal_types** - Shared signal properties\n- **sigtype_attr_list** - Signal type attributes\n- **signal_type_refs** - Signal type references\n- **signal_groups** - Signal groupings\n\n### Obsolete Sections\n\n- **category_definitions** - Defined for completeness but rarely used in practice\n- **categories** - Defined for completeness but rarely used in practice\n- **filter** - Defined for completeness but rarely used in practice\n\n---\n\n## 4. Version and New Symbols\n\n### 4.1 Version\n\n```bnf\nversion = [\'VERSION\' \'\"\' char_string \'\"\' ] ;\n```\n\n**Examples:**\n```\nVERSION \"\"\nVERSION \"1.0\"\nVERSION \"MyDatabase_v2.5\"\n```\n\n**Notes:**\n- Optional section\n- Empty version (`VERSION \"\"`) is valid and common\n- If omitted, parsers assume empty version\n\n### 4.2 New Symbols\n\n```bnf\nnew_symbols = [ \'NS_\' \':\' \n [\'CM_\'] [\'BA_DEF_\'] [\'BA_\'] [\'VAL_\']\n [\'CAT_DEF_\'] [\'CAT_\'] [\'FILTER\'] [\'BA_DEF_DEF_\'] \n [\'EV_DATA_\'] [\'ENVVAR_DATA_\'] [\'SGTYPE_\'] [\'SGTYPE_VAL_\'] \n [\'BA_DEF_SGTYPE_\'] [\'BA_SGTYPE_\'] [\'SIG_TYPE_REF_\'] \n [\'VAL_TABLE_\'] [\'SIG_GROUP_\'] [\'SIG_VALTYPE_\'] \n [\'SIGTYPE_VALTYPE_\'] [\'BO_TX_BU_\'] [\'BA_DEF_REL_\'] \n [\'BA_REL_\'] [\'BA_DEF_DEF_REL_\'] [\'BU_SG_REL_\']\n [\'BU_EV_REL_\'] [\'BU_BO_REL_\'] [\'SG_MUL_VAL_\'] \n] ;\n```\n\n**Purpose:** Declares which optional sections are present in the file\n\n**Example:**\n```\nNS_ : \n CM_\n BA_DEF_\n BA_\n VAL_\n```\n\n---\n\n## 5. Bit Timing Definition\n\n```bnf\nbit_timing = \'BS_:\' [baudrate \':\' BTR1 \',\' BTR2 ] ;\nbaudrate = unsigned_integer ;\nBTR1 = unsigned_integer ;\nBTR2 = unsigned_integer ;\n```\n\n**Examples:**\n```\nBS_:\nBS_: 500\nBS_: 500 : 12,34\n```\n\n**Important Notes:**\n- **REQUIRED KEYWORD** but section is typically empty\n- **OBSOLETE** - No longer used in modern CAN systems\n- Baudrate and BTR values are not processed by modern parsers (legacy feature)\n- Always include `BS_:` in your DBC files\n\n---\n\n## 6. Node Definitions\n\n```bnf\nnodes = \'BU_:\' {node_name} ;\nnode_name = DBC_identifier ;\n```\n\n**Examples:**\n```\nBU_:\nBU_: Engine Gateway Dashboard\nBU_: ECM TCM BCM ADAS_Controller\n```\n\n**Rules:**\n- **REQUIRED SECTION**\n- Node names separated by whitespace\n- All node names must be **unique** (case-sensitive)\n- Empty node list is valid (`BU_:`)\n- Maximum 32 characters per node name\n\n**Best Practices:**\n- Use descriptive names: `EngineControlModule` not `ECU1`\n- Follow naming convention: CamelCase or underscore_separated\n- Avoid special characters\n\n---\n\n## 7. Value Table Definitions\n\n```bnf\nvalue_tables = {value_table} ;\nvalue_table = \'VAL_TABLE_\' value_table_name {value_description} \';\' ;\nvalue_table_name = DBC_identifier ;\nvalue_description = unsigned_integer char_string ;\n```\n\n**Example:**\n```\nVAL_TABLE_ GearPosition 0 \"Park\" 1 \"Reverse\" 2 \"Neutral\" 3 \"Drive\" 4 \"Sport\" ;\nVAL_TABLE_ OnOff 0 \"Off\" 1 \"On\" ;\n```\n\n**Notes:**\n- Global value tables (rarely used in practice)\n- More common: signal-specific value descriptions (see Value Descriptions section)\n- Maps numeric values to human-readable text\n\n---\n\n## 8. Message Definitions\n\n```bnf\nmessages = {message} ;\nmessage = \'BO_\' message_id message_name \':\' message_size transmitter {signal} ;\nmessage_id = unsigned_integer ;\nmessage_name = DBC_identifier ;\nmessage_size = unsigned_integer ;\ntransmitter = node_name | \'Vector__XXX\' ;\n```\n\n### 8.1 Message ID\n\n**Format:** `unsigned_integer`\n\n**Rules:**\n- Must be **unique** within the DBC file\n- **Standard CAN ID:** 0 to 2047 (0x7FF) - 11-bit identifier\n- **Extended CAN ID:** Set bit 31 (0x80000000) and use bits 0-28\n\n**Extended ID Calculation:**\n```\nExtended ID in DBC = 0x80000000 | actual_extended_id\nExample: 0x80001234 represents extended ID 0x1234\n```\n\n**Examples:**\n```\nBO_ 100 SpeedData : 8 ECM (Standard ID: 100)\nBO_ 2147484148 DiagData : 8 TCM (Extended ID: 0x494, with bit 31 set)\n```\n\n### 8.2 Message Name\n\n**Rules:**\n- Must be unique across all messages\n- Maximum 32 characters\n- Must be valid `DBC_identifier`\n\n### 8.3 Message Size\n\n**Format:** Data Length Code (DLC) in bytes\n\n**Valid Values:**\n- **CAN 2.0:** 0 to 8 bytes\n- **CAN FD:** 0 to 64 bytes (tool-dependent support)\n\n### 8.4 Transmitter\n\n**Options:**\n- **Node name** - Must be defined in `BU_:` section\n- **`Vector__XXX`** - No sender / unknown sender\n\n**Example:**\n```\nBO_ 200 EngineData : 8 Engine\nBO_ 300 UnknownMsg : 4 Vector__XXX\n```\n\n### 8.5 Message Components\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| `message_id` | Unique CAN identifier | `100`, `2147484148` |\n| `message_name` | Unique message name | `EngineData`, `SpeedData` |\n| `message_size` | Data Length Code (DLC) in bytes | `0`, `4`, `8` |\n| `transmitter` | Sending node | `ECM`, `Vector__XXX` |\n\n### 8.6 Pseudo-Message\n\nSpecial message for signals not associated with any CAN message:\n\n```\nBO_ 3221225472 VECTOR__INDEPENDENT_SIG_MSG : 0 Vector__XXX\n```\n\n**Notes:**\n- Message ID: `3221225472` (0xC0000000)\n- Used internally by tools\n- Contains \"orphan\" signals\n\n---\n\n## 9. Signal Definitions\n\n### 9.1 Signal Syntax\n\n```bnf\nsignal = \'SG_\' signal_name multiplexer_indicator \':\' \n start_bit \'|\' signal_size \'@\' byte_order value_type \n \'(\' factor \',\' offset \')\' \n \'[\' minimum \'|\' maximum \']\' \n unit receivers ;\n```\n\n### 9.2 Signal Components\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| `signal_name` | Unique within message | `EngineSpeed` |\n| `start_bit` | Bit position (0 to 8\u{d7}DLC-1) | `0`, `16`, `48` |\n| `signal_size` | Length in bits | `8`, `16`, `32` |\n| `byte_order` | `0` = Big-Endian, `1` = Little-Endian | `@1` |\n| `value_type` | `+` = unsigned, `-` = signed | `+`, `-` |\n| `factor` | Scaling factor (cannot be 0) | `0.25`, `1.0` |\n| `offset` | Offset value | `0`, `-40` |\n| `minimum` | Minimum physical value | `0`, `-273.15` |\n| `maximum` | Maximum physical value | `8000`, `100` |\n| `unit` | Physical unit (string) | `\"rpm\"`, `\"\u{b0}C\"` |\n| `receivers` | Receiving nodes | `Gateway`, `Vector__XXX` |\n\n### 9.3 Complete Example\n\n```\nSG_ EngineSpeed : 0|16@1+ (0.25,0) [0|8000] \"rpm\" Gateway,Dashboard\n```\n\n**Breakdown:**\n- Signal name: `EngineSpeed`\n- Start bit: 0 (LSB for little-endian)\n- Length: 16 bits\n- Byte order: Little-endian (`@1`)\n- Value type: Unsigned (`+`)\n- Factor: 0.25 (raw \u{d7} 0.25 = physical)\n- Offset: 0\n- Range: 0 to 8000 rpm\n- Unit: \"rpm\"\n- Receivers: Gateway and Dashboard nodes\n\n### 9.4 Multiplexer Indicator\n\n```bnf\nmultiplexer_indicator = \' \' | \'M\' | \'m\' multiplexer_switch_value ;\nmultiplexer_switch_value = unsigned_integer ;\n```\n\n**Types:**\n- **Normal signal:** (space character or nothing)\n- **Multiplexer switch:** `M`\n- **Multiplexed signal:** `m0`, `m1`, `m2`, etc.\n\n**Example (Basic Multiplexing):**\n```\nBO_ 400 MultiplexedMsg : 8 ECM\n SG_ MuxSwitch M : 0|8@1+ (1,0) [0|255] \"\" Gateway\n SG_ Signal_0 m0 : 8|16@1+ (0.1,0) [0|1000] \"kPa\" Gateway\n SG_ Signal_1 m1 : 8|16@1+ (0.01,0) [0|100] \"\u{b0}C\" Gateway\n```\n\n**Rules:**\n- When `MuxSwitch` = 0, `Signal_0` is valid\n- When `MuxSwitch` = 1, `Signal_1` is valid\n- Multiplexed signals share the same bit positions\n- For extended multiplexing (multiple multiplexer switches), see Section 16\n\n### 9.5 Receivers\n\n```bnf\nreceiver = node_name | \'Vector__XXX\' ;\nreceivers = receiver {\',\' receiver} ;\n```\n\n**Formats:**\n```\nGateway (Single receiver)\nGateway,Dashboard (Multiple receivers - comma-separated)\nVector__XXX (No specific receiver)\n```\n\n**Note:** The specification BNF defines only comma-separated receivers. Some tools may accept space-separated receivers as an extension, but this is not part of the specification.\n\n---\n\n## 10. Bit Manipulation and Byte Ordering\n\n### 10.1 Sawtooth Bit Numbering\n\nCAN message bytes use sequential bit numbering:\n\n```\nByte 0: bits 0-7 (bit 0 = LSB, bit 7 = MSB of byte)\nByte 1: bits 8-15\nByte 2: bits 16-23\nByte 3: bits 24-31\nByte 4: bits 32-39\nByte 5: bits 40-47\nByte 6: bits 48-55\nByte 7: bits 56-63\n```\n\n**Example:** 8-byte message has bit positions 0-63\n\n### 10.2 Byte Order (CORRECTED)\n\n**\u{26a0}\u{fe0f} CRITICAL CORRECTION:**\n\nThe original Vector documentation had an error regarding byte order encoding. The correct interpretation is:\n\n| Value | Byte Order | Description | Alternative Name |\n|-------|------------|-------------|------------------|\n| `@0` | **Big-Endian** | Most significant byte first | Motorola |\n| `@1` | **Little-Endian** | Least significant byte first | Intel |\n\n**Source:** Vector DBC specification version 1.0.1 (2007-11-19) correction states \"Big endian is stored as \'0\', little endian is stored as \'1\'\"\n\n### 10.3 Little-Endian Signals (`@1`)\n\n**Start bit interpretation:** **Least Significant Bit (LSB)**\n\n**Signal bit range:** `[start_bit, start_bit + length - 1]`\n\n**Example:**\n```\nSignal: SG_ Speed : 0|16@1+ (0.1,0) [0|6553.5] \"km/h\"\nMessage bytes: [0x64, 0x00, ...]\n\nBit layout:\nByte 0 Byte 1\n7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8\n[ 0x64 ] [ 0x00 ]\n\u{2514}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{252c}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2534}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{252c}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2518}\n 16-bit signal (bits 0-15)\n\nRaw value = 0x0064 = 100 decimal\nPhysical = 100 \u{d7} 0.1 = 10.0 km/h\n```\n\n### 10.4 Big-Endian Signals (`@0`)\n\n**Start bit interpretation:** **Most Significant Bit (MSB)**\n\n**More complex:** Signal extends \"backward\" toward lower bit numbers\n\n**Big-Endian Bit Numbering Within Bytes:**\n```\nByte 0: bits 7, 6, 5, 4, 3, 2, 1, 0 (MSB to LSB)\nByte 1: bits 15, 14, 13, 12, 11, 10, 9, 8\nByte 2: bits 23, 22, 21, 20, 19, 18, 17, 16\n```\n\n**Example:**\n```\nSignal: SG_ Pressure : 7|16@0+ (0.01,0) [0|655.35] \"kPa\"\nMessage bytes: [0x03, 0xE8, ...]\n\nBit layout (Big-Endian perspective):\nByte 0 Byte 1\n7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8\n[ 0x03 ] [ 0xE8 ]\n\u{2514}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{252c}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2534}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{252c}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2500}\u{2518}\n 16-bit signal (bits 7 down to -8... wraps to next byte)\n\nRaw value = 0x03E8 = 1000 decimal\nPhysical = 1000 \u{d7} 0.01 = 10.0 kPa\n```\n\n### 10.5 Value Conversion\n\n**Formula:**\n```\nphysical_value = raw_value \u{d7} factor + offset\nraw_value = (physical_value - offset) / factor\n```\n\n**Rules:**\n- Factor **cannot be zero** (division required)\n- Signed signals use two\'s complement representation\n- Range check: `minimum \u{2264} physical_value \u{2264} maximum`\n\n**Example with Offset:**\n```\nSignal: SG_ Temperature : 16|8@1- (1,-40) [-40|87] \"\u{b0}C\"\n\nRaw value = 127 (0x7F)\nPhysical = 127 \u{d7} 1 + (-40) = 87\u{b0}C\n\nRaw value = 0 (0x00)\nPhysical = 0 \u{d7} 1 + (-40) = -40\u{b0}C\n\nPhysical = 20\u{b0}C\nRaw = (20 - (-40)) / 1 = 60\n```\n\n**Note:** For a signed 8-bit signal, the raw value range is -128 to 127. With factor=1 and offset=-40, the physical range is -168 to 87. The example uses a valid range of [-40|87] for clarity.\n\n### 10.6 Signal Extended Value Types\n\nFor floating-point signals:\n\n```bnf\nsignal_extended_value_type_list = {signal_extended_value_type_entry} ;\nsignal_extended_value_type_entry = \'SIG_VALTYPE_\' message_id signal_name signal_extended_value_type \';\' ;\nsignal_extended_value_type = \'0\' | \'1\' | \'2\' ;\n```\n\n**Value Types:**\n- `0` = Signed or unsigned integer (default)\n- `1` = 32-bit IEEE float\n- `2` = 64-bit IEEE double\n\n**Example:**\n```\nSIG_VALTYPE_ 100 FloatSignal 1 ;\nSIG_VALTYPE_ 100 DoubleSignal 2 ;\n```\n\n---\n\n## 11. Message Transmitters\n\nDefines multiple transmitters for a message (higher-layer protocols):\n\n```bnf\nmessage_transmitters = {message_transmitter} ;\nmessage_transmitter = \'BO_TX_BU_\' message_id \':\' {transmitter} \';\' ;\n```\n\n**Example:**\n```\nBO_TX_BU_ 100 : Engine Gateway ;\n```\n\n**Note:** This is **not** for CAN layer-2 communication, but for higher-layer protocol descriptions.\n\n---\n\n## 12. Environment Variables\n\n### 12.1 Environment Variable Definition\n\n```bnf\nenvironment_variable = \'EV_\' env_var_name \':\' env_var_type \n \'[\' minimum \'|\' maximum \']\' unit initial_value ev_id \n access_type access_node {\',\' access_node } \';\' ;\nenv_var_type = \'0\' | \'1\' | \'2\' ; (* 0=integer, 1=float, 2=string *)\naccess_type = \'DUMMY_NODE_VECTOR\' (\'0\'|\'1\'|\'2\'|\'3\'|\'8000\'|\'8001\'|\'8002\'|\'8003\') ;\n```\n\n**Access Types:**\n- `DUMMY_NODE_VECTOR0` = Unrestricted\n- `DUMMY_NODE_VECTOR1` = Read only\n- `DUMMY_NODE_VECTOR2` = Write only\n- `DUMMY_NODE_VECTOR3` = Read/Write\n- `DUMMY_NODE_VECTOR800X` = String type (OR-ed with 0x8000)\n\n**Example:**\n```\nEV_ TestVar : 0 [0|100] \"\" 0 0 DUMMY_NODE_VECTOR0 ECM,TCM ;\n```\n\n### 12.2 Environment Variable Data\n\n```bnf\nenvironment_variable_data = \'ENVVAR_DATA_\' env_var_name \':\' data_size \';\' ;\ndata_size = unsigned_integer ;\n```\n\n**Purpose:** Defines binary data storage with specified byte length\n\n### 12.3 Value Descriptions for Environment Variables\n\n```bnf\nvalue_descriptions_for_env_var = \'VAL_\' env_var_name { value_description } \';\' ;\n```\n\n---\n\n## 13. Signal Types and Groups\n\n### 13.1 Signal Types (Rarely Used)\n\n```bnf\nsignal_types = {signal_type} ;\nsignal_type = \'SGTYPE_\' signal_type_name \':\' signal_size \'@\' byte_order value_type \'(\' factor \',\' offset \')\' \'[\' minimum \'|\' maximum \']\' unit default_value \',\' value_table \';\' ;\nsignal_type_name = DBC_identifier ;\ndefault_value = double ;\nvalue_table = value_table_name ;\nsignal_type_refs = {signal_type_ref} ;\nsignal_type_ref = \'SIG_TYPE_REF_\' message_id signal_name \':\' signal_type_name \';\' ;\n```\n\n**Purpose:** Define reusable signal properties\n\n### 13.2 Signal Type Attributes\n\nSignal type attributes allow defining custom attributes for signal types, similar to regular attributes but specific to signal types.\n\n```bnf\nsigtype_attr_list = {sigtype_attribute_definition} {sigtype_attribute_value} ;\nsigtype_attribute_definition = \'BA_DEF_SGTYPE_\' attribute_name attribute_value_type \';\' ;\nsigtype_attribute_value = \'BA_SGTYPE_\' attribute_name signal_type_name attribute_value \';\' ;\nattribute_name = \'\"\' DBC_identifier \'\"\' ;\nattribute_value_type = \n \'INT\' signed_integer signed_integer |\n \'HEX\' signed_integer signed_integer |\n \'FLOAT\' double double |\n \'STRING\' |\n \'ENUM\' char_string {\',\' char_string} ;\nattribute_value = unsigned_integer | signed_integer | double | char_string ;\nsignal_type_name = DBC_identifier ;\n```\n\n**Purpose:** Extend signal type objects with custom attributes\n\n**Examples:**\n```\nBA_DEF_SGTYPE_ \"SignalTypeCategory\" ENUM \"Temperature\",\"Pressure\",\"Speed\" ;\nBA_SGTYPE_ \"SignalTypeCategory\" TempType \"Temperature\" ;\n```\n\n**Notes:**\n- Similar to `BA_DEF_` and `BA_` but for signal types\n- Rarely used in practice\n- Signal types must be defined with `SGTYPE_` before attributes can be assigned\n\n### 13.3 Signal Groups\n\n```bnf\nsignal_groups = \'SIG_GROUP_\' message_id signal_group_name repetitions { signal_name } \';\' ;\nsignal_group_name = DBC_identifier ;\nrepetitions = unsigned_integer ;\n```\n\n**Example:**\n```\nSIG_GROUP_ 256 EngineGroup 1 RPM Temperature ThrottlePosition;\n```\n\n**Purpose:**\n- Organize related signals\n- UI/tool grouping\n- Atomic update requirements\n- Does **not** affect CAN message structure\n\n---\n\n## 14. Comments\n\n```bnf\ncomments = {comment} ;\ncomment = \'CM_\' (\n char_string | (* General comment *)\n \'BU_\' node_name char_string | (* Node comment *)\n \'BO_\' message_id char_string | (* Message comment *)\n \'SG_\' message_id signal_name char_string | (* Signal comment *)\n \'EV_\' env_var_name char_string (* Env var comment *)\n) \';\' ;\n```\n\n**Examples:**\n```\nCM_ \"CAN communication matrix for powertrain electronics\" ;\nCM_ BU_ Engine \"Engine Control Module - Main powertrain controller\" ;\nCM_ BO_ 100 \"Engine status and diagnostic data\" ;\nCM_ SG_ 100 EngineSpeed \"Actual engine speed calculated over 720\u{b0} crankshaft angle\" ;\n```\n\n**Best Practices:**\n- Describe purpose and context\n- Document special conditions or constraints\n- Reference related specifications\n- Keep concise but informative\n\n---\n\n## 15. User-Defined Attributes\n\n### 15.1 Attribute Definitions\n\n```bnf\nattribute_definition = \'BA_DEF_\' object_type attribute_name attribute_value_type \';\' ;\nobject_type = \'\' | \'BU_\' | \'BO_\' | \'SG_\' | \'EV_\' ;\nattribute_name = \'\"\' DBC_identifier \'\"\' ;\nattribute_value_type = \n \'INT\' signed_integer signed_integer |\n \'HEX\' signed_integer signed_integer |\n \'FLOAT\' double double |\n \'STRING\' |\n \'ENUM\' char_string {\',\' char_string} ;\n```\n\n**Object Types:**\n- Empty `\'\'` = Network/global attribute\n- `BU_` = Node attribute\n- `BO_` = Message attribute\n- `SG_` = Signal attribute\n- `EV_` = Environment variable attribute\n\n**Examples:**\n```\nBA_DEF_ BO_ \"GenMsgCycleTime\" INT 0 10000 ;\nBA_DEF_ SG_ \"GenSigStartValue\" INT 0 255 ;\nBA_DEF_ BO_ \"VFrameFormat\" ENUM \"StandardCAN\",\"ExtendedCAN\",\"J1939PG\" ;\nBA_DEF_ \"BusType\" STRING ;\n```\n\n### 15.2 Attribute Defaults\n\n```bnf\nattribute_default = \'BA_DEF_DEF_\' attribute_name attribute_value \';\' ;\n```\n\n**Examples:**\n```\nBA_DEF_DEF_ \"GenMsgCycleTime\" 0 ;\nBA_DEF_DEF_ \"VFrameFormat\" \"StandardCAN\" ;\nBA_DEF_DEF_ \"BusType\" \"\" ;\n```\n\n### 15.3 Attribute Values\n\n```bnf\nattribute_value_for_object = \'BA_\' attribute_name (\n attribute_value | (* Network/global *)\n \'BU_\' node_name attribute_value | (* Node *)\n \'BO_\' message_id attribute_value | (* Message *)\n \'SG_\' message_id signal_name attribute_value | (* Signal *)\n \'EV_\' env_var_name attribute_value (* Env var *)\n) \';\' ;\n```\n\n**Examples:**\n```\nBA_ \"GenMsgCycleTime\" BO_ 100 10 ;\nBA_ \"GenSigStartValue\" SG_ 100 EngineSpeed 0 ;\nBA_ \"VFrameFormat\" BO_ 2364540158 \"J1939PG\" ;\n```\n\n---\n\n## 16. Extended Multiplexing\n\n### 16.1 Purpose\n\nEnables advanced multiplexing scenarios:\n- Multiple multiplexer switches per message\n- Multiple multiplexer values per signal\n\n### 16.2 Syntax\n\n```bnf\nextended_multiplexing = {multiplexed_signal} ;\nmultiplexed_signal = \'SG_MUL_VAL_\' message_id multiplexed_signal_name \n multiplexor_switch_name multiplexor_value_ranges \';\' ;\nmultiplexor_value_ranges = multiplexor_value_range {\',\' multiplexor_value_range} ;\nmultiplexor_value_range = unsigned_integer \'-\' unsigned_integer ;\n```\n\n### 16.3 Example\n\n```\nBO_ 500 ComplexMux : 8 ECM\n SG_ Mux1 M : 0|8@1+ (1,0) [0|255] \"\" Gateway\n SG_ Mux2 M : 8|8@1+ (1,0) [0|255] \"\" Gateway\n SG_ Signal_A m0 : 16|16@1+ (0.1,0) [0|100] \"\" Gateway\n SG_ Signal_B m1 : 16|16@1+ (0.1,0) [0|100] \"\" Gateway\n\nSG_MUL_VAL_ 500 Signal_A Mux1 0-5,10-15 ;\nSG_MUL_VAL_ 500 Signal_B Mux2 20-25 ;\n```\n\n**Explanation:**\n- `Signal_A` is valid when `Mux1` is 0-5 or 10-15\n- `Signal_B` is valid when `Mux2` is 20-25\n\n---\n\n## 17. Common Attributes\n\n**Note:** The DBC specification does not define any standard attributes. All attributes must be defined using `BA_DEF_` before use. The attributes listed below are commonly used **tool-specific extensions** (primarily from Vector CANdb++) and are not part of the specification itself.\n\n### 17.1 Common Tool-Specific Message Attributes\n\nThese attributes are commonly used in practice but are tool-specific:\n\n| Attribute | Type | Description | Example |\n|-----------|------|-------------|---------|\n| `GenMsgCycleTime` | INT | Message cycle time (ms) | `10`, `100`, `1000` |\n| `GenMsgSendType` | ENUM | Send behavior | `\"cyclic\"`, `\"triggered\"` |\n| `GenMsgStartDelayTime` | INT | Startup delay (ms) | `0`, `100` |\n| `VFrameFormat` | ENUM | Frame format | `\"StandardCAN\"`, `\"ExtendedCAN\"`, `\"J1939PG\"` |\n\n### 17.2 Common Tool-Specific Signal Attributes\n\n| Attribute | Type | Description | Example |\n|-----------|------|-------------|---------|\n| `GenSigStartValue` | INT/FLOAT | Initial value | `0`, `100.5` |\n| `GenSigSendType` | ENUM | Send behavior | `\"cyclic\"`, `\"onWrite\"` |\n\n### 17.3 J1939-Specific Attributes\n\nFor J1939 networks, tools commonly define:\n\n```\nBA_DEF_ BO_ \"VFrameFormat\" ENUM \"StandardCAN\",\"ExtendedCAN\",\"J1939PG\" ;\nBA_DEF_ SG_ \"SPN\" INT 0 524287 ; (* Suspect Parameter Number *)\nBA_DEF_ BO_ \"PGN\" INT 0 262143 ; (* Parameter Group Number *)\n\nBA_ \"VFrameFormat\" BO_ 2364540158 \"J1939PG\" ;\nBA_ \"SPN\" SG_ 2364540158 EngineSpeed 190 ;\nBA_ \"PGN\" BO_ 2364540158 61444 ;\n```\n\n---\n\n## 18. Examples\n\n### 18.1 Minimal DBC File\n\n```\nVERSION \"\"\n\nBS_:\n\nBU_: Engine Gateway Dashboard\n\nBO_ 100 EngineData : 8 Engine\n SG_ EngineSpeed : 0|16@1+ (1,0) [0|8000] \"rpm\" Gateway,Dashboard\n SG_ EngineTemp : 16|8@1- (1,-40) [-40|87] \"\u{b0}C\" Gateway\n SG_ ThrottlePos : 24|8@1+ (0.4,0) [0|100] \"%\" Gateway\n\n```\n\n### 18.2 Complete DBC File with All Sections\n\n```\nVERSION \"1.0\"\n\nNS_ : \n NS_DESC_\n CM_\n BA_DEF_\n BA_\n VAL_\n BA_DEF_DEF_\n SIG_VALTYPE_\n BO_TX_BU_\n\nBS_:\n\nBU_: Engine Gateway Dashboard\n\nVAL_TABLE_ GearPosition 0 \"Park\" 1 \"Reverse\" 2 \"Neutral\" 3 \"Drive\" 4 \"Sport\" ;\n\nBO_ 100 EngineData : 8 Engine\n SG_ EngineSpeed : 0|16@1+ (0.25,0) [0|8000] \"rpm\" Gateway,Dashboard\n SG_ EngineTemp : 16|7@1+ (2,-50) [-50|150] \"\u{b0}C\" Gateway\n SG_ IdleRunning : 23|1@1+ (1,0) [0|1] \"\" Gateway\n SG_ PetrolLevel : 24|8@1+ (1,0) [0|255] \"l\" Gateway\n SG_ EngForce : 32|16@1+ (1,0) [0|65535] \"N\" Gateway\n SG_ EngPower : 48|16@1+ (0.01,0) [0|150] \"kW\" Gateway\n\nBO_ 200 GearboxData : 4 Gateway\n SG_ GearActual : 0|8@1+ (1,0) [0|5] \"\" Dashboard\n\nCM_ \"CAN communication matrix for powertrain electronics\" ;\nCM_ BU_ Engine \"Engine Control Module\" ;\nCM_ BO_ 100 \"Cyclic message with engine parameters\" ;\nCM_ SG_ 100 EngineSpeed \"Actual engine speed calculated over 720\u{b0} crankshaft angle\" ;\n\nBA_DEF_ BO_ \"GenMsgCycleTime\" INT 0 10000 ;\nBA_DEF_ SG_ \"GenSigStartValue\" FLOAT 0 100000 ;\nBA_DEF_ \"BusType\" STRING ;\n\nBA_DEF_DEF_ \"GenMsgCycleTime\" 0 ;\nBA_DEF_DEF_ \"GenSigStartValue\" 0 ;\nBA_DEF_DEF_ \"BusType\" \"CAN\" ;\n\nBA_ \"GenMsgCycleTime\" BO_ 100 10 ;\nBA_ \"GenSigStartValue\" SG_ 100 EngineSpeed 0 ;\nBA_ \"BusType\" \"CAN\" ;\n\nVAL_ 100 IdleRunning 0 \"Running\" 1 \"Idle\" ;\nVAL_ 200 GearActual 0 \"Park\" 1 \"Reverse\" 2 \"Neutral\" 3 \"Drive\" 4 \"Sport\" 5 \"Manual\" ;\n\n```\n\n### 18.3 Multiplexed Message Example\n\n```\nVERSION \"\"\n\nBS_:\n\nBU_: Sensor Gateway\n\nBO_ 300 MultiplexedSensors : 8 Sensor\n SG_ SensorID M : 0|8@1+ (1,0) [0|255] \"\" Gateway\n SG_ Temperature m0 : 8|16@1- (0.1,-40) [-40|125] \"\u{b0}C\" Gateway\n SG_ Pressure m1 : 8|16@1+ (0.01,0) [0|655.35] \"kPa\" Gateway\n SG_ Humidity m2 : 8|8@1+ (0.5,0) [0|100] \"%\" Gateway\n SG_ Voltage m3 : 8|16@1+ (0.001,0) [0|65.535] \"V\" Gateway\n\nCM_ BO_ 300 \"Multiplexed sensor data - SensorID selects active signal\" ;\n\nVAL_ 300 SensorID 0 \"Temperature Sensor\" 1 \"Pressure Sensor\" 2 \"Humidity Sensor\" 3 \"Voltage Sensor\" ;\n\n```\n\n### 18.4 Extended Multiplexing Example\n\n```\nVERSION \"\"\n\nBS_:\n\nBU_: ECU Tester\n\nBO_ 400 DiagnosticData : 8 ECU\n SG_ DiagMode M : 0|4@1+ (1,0) [0|15] \"\" Tester\n SG_ SubMode M : 4|4@1+ (1,0) [0|15] \"\" Tester\n SG_ Data_A m0 : 8|32@1+ (1,0) [0|4294967295] \"\" Tester\n SG_ Data_B m1 : 8|32@1- (1,0) [-2147483648|2147483647] \"\" Tester\n SG_ Data_C m2 : 8|32@1+ (0.001,0) [0|4294967.295] \"\" Tester\n\nSG_MUL_VAL_ 400 Data_A DiagMode 0-2 ;\nSG_MUL_VAL_ 400 Data_A SubMode 0-5 ;\nSG_MUL_VAL_ 400 Data_B DiagMode 3-5 ;\nSG_MUL_VAL_ 400 Data_C DiagMode 6-8 ;\nSG_MUL_VAL_ 400 Data_C SubMode 10-15 ;\n\n```\n\n---\n\n## 19. Validation and Error Checking\n\n### 19.1 Required Checks\n\n**File Structure:**\n- \u{2705} `BS_:` keyword must be present\n- \u{2705} `BU_:` section must be present (can be empty)\n- \u{2705} All sections must follow the defined order\n\n**Uniqueness:**\n- \u{2705} All node names must be unique\n- \u{2705} All message IDs must be unique\n- \u{2705} Signal names within a message must be unique\n\n**References:**\n- \u{2705} Message transmitter must exist in `BU_:` or be `Vector__XXX`\n- \u{2705} Signal receivers must exist in `BU_:` or be `Vector__XXX`\n- \u{2705} Multiplexer switch must exist in same message\n- \u{2705} Attribute names must be defined before use\n\n**Value Ranges:**\n- \u{2705} `start_bit` must be < (8 \u{d7} message_size)\n- \u{2705} Signal must fit within message boundaries\n- \u{2705} `factor` cannot be zero\n- \u{2705} `minimum` \u{2264} `maximum`\n- \u{2705} Extended CAN IDs must have bit 31 set\n\n**Signal Overlap:**\n- \u{2705} Non-multiplexed signals must not overlap in bit positions\n- \u{2705} Multiplexed signals can share bits only with different mux values\n\n### 19.2 Common Errors\n\n| Error | Description | Solution |\n|-------|-------------|----------|\n| Missing `BS_:` | Required keyword missing | Add `BS_:` after `NS_` section |\n| Duplicate message ID | Two messages with same ID | Use unique IDs for each message |\n| Invalid start bit | Start bit \u{2265} (8 \u{d7} DLC) | Reduce start bit or increase DLC |\n| Factor is zero | Division by zero in conversion | Use non-zero factor |\n| Unknown transmitter | Node not in `BU_:` list | Add node to `BU_:` or use `Vector__XXX` |\n| Signal overflow | Signal extends beyond message | Reduce size or adjust start bit |\n| Overlapping signals | Signals share bits without mux | Adjust bit positions or use multiplexing |\n\n---\n\n## 20. Best Practices\n\n### 20.1 Naming Conventions\n\n**Nodes:**\n```\n\u{2705} GOOD: EngineControlModule, Gateway_1, ADAS_ECU\n\u{274c} AVOID: ECU1, node, temp\n```\n\n**Messages:**\n```\n\u{2705} GOOD: EngineStatus, WheelSpeedData, BrakePressure\n\u{274c} AVOID: Msg1, data, x\n```\n\n**Signals:**\n```\n\u{2705} GOOD: EngineSpeed_rpm, BrakePress_Front_Left, VehicleSpeed_kph\n\u{274c} AVOID: sig1, s, temp\n```\n\n### 20.2 Message Design\n\n- **Keep DLC minimal** - Only use bytes needed for signals\n- **Align signals to byte boundaries** when possible for efficiency\n- **Group related signals** in same message\n- **Use consistent byte order** throughout the network (prefer little-endian)\n- **Document multiplexing** thoroughly with comments\n\n### 20.3 Signal Scaling\n\n- **Choose appropriate factor** for required precision\n- **Avoid extreme factors** (very large or very small)\n- **Use integer raw values** when possible for efficiency\n- **Set meaningful ranges** for `minimum` and `maximum`\n- **Include units** in signal definition\n\n### 20.4 Documentation\n\n- **Add comments** for all messages and critical signals\n- **Define attributes** for cycle times and send types\n- **Use value descriptions** for enumerated signals\n- **Document special conditions** (e.g., \"valid only when vehicle speed > 0\")\n\n### 20.5 Version Control\n\n- **Include VERSION** statement with meaningful version string\n- **Use timestamps** in version string: `\"v2.3_2024-12-04\"`\n- **Document changes** in file header comment\n- **Track compatibility** with ECU software versions\n\n---\n\n## 21. Common Pitfalls\n\n### 21.1 Byte Order Confusion\n\n**Problem:** Misunderstanding `@0` and `@1`\n\n**Solution:** Remember:\n- `@0` = Big-endian (Motorola) - MSB first\n- `@1` = Little-endian (Intel) - LSB first\n\n**Test:** Always verify with sample data\n\n### 21.2 Sign Extension\n\n**Problem:** Signed signals not properly decoded\n\n**Example:**\n```\nSignal: 8-bit signed, raw value = 0xFF\nIncorrect: 255 (unsigned interpretation)\nCorrect: -1 (signed interpretation)\n```\n\n**Solution:** Check `value_type` (`-` for signed) and apply two\'s complement\n\n### 21.3 Start Bit for Big-Endian\n\n**Problem:** Start bit for big-endian refers to MSB, not LSB\n\n**Example:**\n```\nSignal: SG_ Test : 7|16@0+ ...\nStarts at bit 7 (MSB) and extends backward through bytes\n```\n\n**Solution:** Carefully calculate physical bit ranges for big-endian\n\n### 21.4 Factor Cannot Be Zero\n\n**Problem:** Setting `factor = 0` causes division by zero\n\n**Solution:** Always use non-zero factor (use `1` if no scaling needed)\n\n### 21.5 Receiver Format Variations\n\n**Problem:** Tools may interpret receiver lists differently\n\n**Formats seen in practice:**\n```\nSG_ Signal : ... \"unit\" Node1,Node2 (comma-separated - per spec)\nSG_ Signal : ... \"unit\" Node1 Node2 (space-separated - tool extension)\nSG_ Signal : ... \"unit\" Node1, Node2 (comma+space - tool extension)\n```\n\n**Solution:** The specification defines only comma-separated receivers. Some tools accept space-separated as an extension, but for maximum compatibility, use comma-separated format as defined in the specification.\n\n---\n\n## 22. Tools and Parsers\n\n### 22.1 Common DBC Tools\n\n- **Vector CANdb++** - Original DBC editor\n- **CANalyzer / CANoe** - Analysis and simulation\n- **PCAN-View** - Free CAN bus monitor\n- **Kvaser Database Editor** - DBC creation/editing\n- **Intrepid Control Systems Vehicle Spy** - Analysis tool\n\n### 22.2 Open Source Parsers\n\n- **cantools** (Python) - Full DBC parser and encoder/decoder\n- **python-can** (Python) - CAN library with DBC support\n- **CANdb** (C++) - Fast C++ parser\n- **dbc-rs** (Rust) - Rust DBC parser library\n\n### 22.3 Parser Recommendations\n\nWhen implementing a DBC parser:\n\n1. **Be lenient with whitespace** - Accept both spaces and tabs\n2. **Handle line endings** - Support both Windows (CRLF) and Unix (LF)\n3. **Validate carefully** - Check all references and ranges\n4. **Support comments** - Allow C-style comments `/* */` in some tools\n5. **Warn on violations** - Don\'t silently ignore errors\n6. **Test with real files** - Use automotive industry DBC files for testing\n\n---\n\n## 23. Glossary\n\n| Term | Definition |\n|------|------------|\n| **CAN** | Controller Area Network - automotive bus standard |\n| **DBC** | Database Container - CAN database file format |\n| **ECU** | Electronic Control Unit - network node/device |\n| **DLC** | Data Length Code - message size in bytes |\n| **LSB** | Least Significant Bit |\n| **MSB** | Most Significant Bit |\n| **Big-endian** | Byte order with MSB first (Motorola) |\n| **Little-endian** | Byte order with LSB first (Intel) |\n| **Multiplexing** | Multiple signals sharing bit positions |\n| **Raw value** | Integer value transmitted on bus |\n| **Physical value** | Scaled/offset value in engineering units |\n| **J1939** | SAE standard for heavy-duty vehicle networks |\n| **CAN FD** | CAN with Flexible Data rate - up to 64 bytes |\n\n---\n\n## 24. References\n\n### 24.1 Specifications\n\n- Vector Informatik GmbH DBC File Format Specification (versions 1.0.0 - 1.0.1)\n- ISO 11898: Road vehicles \u{2014} Controller area network (CAN)\n- SAE J1939: Recommended Practice for Serial Control and Communications Heavy Duty Vehicle Network\n\n### 24.2 Related Standards\n\n- **ARXML** - AUTOSAR XML format (successor to DBC for modern vehicles)\n- **KCD** - Kayak CAN Database (XML-based alternative)\n- **LDF** - LIN Description File (for LIN networks)\n\n---\n\n## License and Disclaimer\n\n**Important:** The DBC file format is proprietary to Vector Informatik GmbH. This documentation is provided for educational and interoperability purposes based on publicly available information and reverse engineering.\n\n**No Warranty:** This specification is provided \"as is\" without warranty of any kind. Always verify against actual tool behavior and industry standards.\n\n**Contributions:** Community feedback and corrections are welcome to improve accuracy.\n";Expand description
The DBC file format specification document.
This is the complete specification in Markdown format, useful for documentation and reference purposes.
This constant is only available when the std feature is enabled.