Skip to content

icd-template.md

Latest commit

 

History

History
274 lines (193 loc) · 5.71 KB

icd-template.md

File metadata and controls

274 lines (193 loc) · 5.71 KB
Raw

ICD-XXX: [Interface Name]

Document Information

Field Value
Document ID ICD-XXX
Version 0.1
Status Draft
Date YYYY-MM-DD
Owner [Name or working group]
Reviewers [Names]

Change History

Version Date Author Changes
0.1 YYYY-MM-DD [Name] Initial draft

Purpose

[Describe the interface's purpose in the system. What does it enable? What components rely on it?]

Scope

This document specifies:

  • [Aspect 1]
  • [Aspect 2]
  • [Aspect 3]

This document does not cover:

  • [Out of scope item 1]
  • [Out of scope item 2]

Parties

Component Hardware Role
[Component A] [MCU/board] [What it does in this interface]
[Component B] [MCU/board] [What it does in this interface]

Physical Layer

Electrical Specification

Parameter Value Notes
Bus type [e.g., CAN 2.0B, RS-422]
Bit rate [e.g., 1 Mbit/s]
Signaling [e.g., differential]
Voltage levels [e.g., 0-3.3V]

Connector and Pinout

Pin Signal Direction Notes
1 [Signal name] [In/Out/Bidir]
2 [Signal name] [In/Out/Bidir]

Cable Specification

[Wire gauge, shielding, maximum length, termination requirements]

Protocol Specification

General Format

[How are messages structured? What is the byte order? Are there sync words, length fields, checksums?]

Timing Requirements

Parameter Value Notes
[Parameter name] [Value] [Context]

Identifier Assignment

ID Range Owner Purpose
[Range] [Owner] [Use case]

Message Definitions

Message: [Message Name]

Field Value
ID [Identifier]
Direction [A → B or B → A or bidirectional]
Length [Bytes]
Frequency [How often this is sent]
Purpose [What this message conveys]

Payload Structure:

Offset Size Type Field Description
0 4 B uint32 LE [field_name] [description]
4 1 B uint8 [field_name] [description]
5 3 B uint24 reserved Set to 0

Example:

Hex bytes: 0x37 0x05 0x00 0x00 0x01 0x00 0x00 0x00
Decoded: field_name=1335, status=ENABLED

Notes:

[Any clarifications about field semantics, edge cases, valid ranges]

Message: [Next Message Name]

[Repeat structure above for each message]

Error Handling

Corruption Detection

[How is corruption detected? CRC? Length check? Magic word?]

Recovery from Corruption

[What does each party do when a corrupted message is detected?]

Missing Messages

[What if expected messages don't arrive? Timeout values, fallback behaviour]

Out-of-Sequence Messages

[What if messages arrive in unexpected order?]

Constants and Limits

Constant Value Description
[CONSTANT_NAME] [Value] [Meaning]

Test Vectors

Valid Message Example 1

[Hex bytes of a valid message]
Expected interpretation: [What this message means]

Valid Message Example 2

[Another valid example]

Invalid Message Example (Corrupted)

[Hex bytes of an invalid message]
Expected behaviour: [How implementations should respond]

Implementation Notes

[Anything implementers should know that isn't strictly part of the specification]

References

  • Related ADRs: ADR-XXX
  • Related ICDs: ICD-YYY
  • Standards: [Relevant standard reference]
  • Implementation: path/to/code/
  • Datasheet: [Link to component datasheet if applicable]

Glossary

Term Definition
[Term] [Definition]