Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Edited pacmod user CAN protocol standard for spelling/grammar #56

Open
wants to merge 4 commits into
base: v3
Choose a base branch
from
Open

Edited pacmod user CAN protocol standard for spelling/grammar #56

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b59cc9c
Update user_can_protocol.md
g-likes Dec 11, 2023
6903ee5
Update user_can_protocol.md
g-likes Dec 11, 2023
fc3da10
Update user_can_protocol.md
g-likes Dec 13, 2023
167be0e
Update user_can_protocol.md
g-likes Dec 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 21 additions & 24 deletions doc/user_can_protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,31 @@
# User CAN Protocol Standard 3.0

This document the authoritative definition of the User CAN Protocol, commonly called the CAN API. It is the interface to the PACMod System and resides on the User CAN data bus.
This document is the authoritative definition of the User CAN Protocol, commonly called the CAN API. It is the interface to the PACMod System and resides on the User CAN data bus.

## Document References
This document is the authoritative defintion of the User CAN Protocol. The following documents are supplimental to this document. They all reside in GitHub (https://github.com/astuff/pacmod_dbc).
This document is the authoritative defintion of the User CAN Protocol. The following documents are supplemental to this document. They all reside in GitHub (https://github.com/astuff/pacmod_dbc).

- as_pacmod.dbc - The file contains the CAN Message definitions in Vector proprietary DBC file format.
- vehicle_associations.xml - The file contains the availability of each message on each of the different vehicle platforms.
- dbc_description.html - This file is derived from as_pacmod.dbc and vehicle_associations.xml. It is a human readble version of the same.
- dbc_description.html - This file is derived from as_pacmod.dbc and vehicle_associations.xml. It is a human readable version of the same file.

## Definitions

- Amber Warning Lamp: Warning lamp that indicates faults that do not require the vehicle to stop immediately.
- Red Warning Lamp: Warning lamp that indicates faults that require the vehicle to stop immediately.
- CAN ID: A CAN ID is the value in the CAN arbitration field that identifies the data in the CAN data field.
- CAN Message: A CAN message is a CAN frame with a specific value in its CAN arbitration field.
- Component: An individual electronic part of the PACMod System that communicates on the User CAN.
- DBC: The as_pacmod.dbc file.
- PACMod System: The PACMod System is the PACMod System.
- Red Warning Lamp: warning lamp that indicates faults that do require the vehicle to stop immediately.
- System: A vehicle system that is under by-wire control.
- User CAN: The CAN bus that interfaces to the PACMod System.
- User PC: Any device the customer uses to communicate with the PACMod System.
- Vehicle: A vehicle with under the control of the PACMod System.
- Vehicle: Any vehicle under the control of the PACMod System.
- Vehicle Platform: A particular manufacturer make and model compatible with the PACMod System.

## User CAN
User CAN is the CAN bus interface to the PACMod System. It refers to both the User CAN bus and to the User CAN protocol that describes the messages on the CAN bus.
User CAN is the CAN bus interface to the PACMod System. It refers to both the User CAN bus and the User CAN protocol that describes the messages on the CAN bus.

## Restrictions
User CAN has the following restrictions:
Expand All @@ -34,15 +34,15 @@ User CAN has the following restrictions:
3. Messaging beyond the interface to the PACMod system is prohibited.

## Types of CAN Messages
Each stock vehicle system under by-wire control has an associated by-wire system command message and a by-wire system report message. A command message is a CAN message from the User PC to command the PACMod System commanding the by-wire system to perform some action. A command message is identified by a "CMD" in its name. A report message from the PACMod System provides feedback to the User PC. A report message is indicated by a "RPT" in its name.
Each stock vehicle system under by-wire control has an associated by-wire system command message and a by-wire system report message. A command message is a CAN message from the User PC to the PACMod System commanding the by-wire system to perform an action. A command message is identified by a "CMD" in its name. A report message from the PACMod System provides feedback to the User PC. A report message is indicated by a "RPT" in its name.

Each system command and report message pair is of one of the following types:
1. Boolean: The data type carried by the command or report message is a boolean and is 8 bits long.
1. Enumeration: The data type carried by the command or report message is an enumeration and is of 8 or 16 bits.
1. Multi Enumeration: The data type carried by the command or report message is a set of enumerations. They of varying number and sizes limited by how they fit into 8 or 16 bits.
1. Enumeration: The data type carried by the command or report message is an enumeration and is 8 or 16 bits long.
1. Multi Enumeration: The data type carried by the command or report message is a set of enumerations. The enumerations are of varying number and sizes limited by how they fit into 8 or 16 bits.
1. Float: The data type carried by the command or report message is 8 or 16 bit integer.

A single command and report message pair communicates data related to the by-wire control established at the corresponding operator control for a single stock vehicle parameter. Each report message includes the following fields.
A single command and report message pair communicates data related to the by-wire control established at the corresponding operator control for a single stock vehicle parameter. Each report message includes the following fields:

1. MANUAL_INPUT - measurement from operator control for monitoring operator intent.
1. COMMANDED_VALUE - copy of the command received for diagnostic of User CAN.
Expand All @@ -55,9 +55,9 @@ The availability of feedback data for the OUTPUT_VALUE varies between stock vehi
1. COMMANDED_VALUE in by-wire mode and MANUAL_INPUT in manual mode.
1. Zero in both modes.

The global messages affect the PACMod System as a whole (all its systems and/or components). It is made up of the global command and the global report. The global command affects the PACMod System as a whole. The global report reflects the status of the PACMod System as a whole. Global messages are identified with "GLOBAL" in its name.
The global messages affect the PACMod System as a whole (all systems and/or components). It is made up of the global command and the global report. The global command affects the PACMod System as a whole. The global report reflects the status of the PACMod System as a whole. Global messages are identified with "GLOBAL" in its name.

System messages are made up of command messages and report messages and have a fixed association to a single vehicle system under by-wire control. The system command message contains the command specific to its system. The system report contains an echo of the command, the operator command to the corresponding system, as well as the vehicle response to the command (if available). It also contains status information. System auxiliary reports contain additional information related to its system. Each data field in a system auxiliary report has a corresponding data field that indicates the availability of the data for vehicle. System messages begin with the name of a system. Auxiliary messages are identified with "AUX" in its name.
System messages are made up of command messages, report messages, and have a fixed association to a single vehicle system under by-wire control. The system command message contains the command specific to its system. The system report contains an echo of the command, the operator command to the corresponding system, as well as the vehicle response to the command (if available). It also contains status information. System auxiliary reports contain additional information related to its system. Each data field in a system auxiliary report has a corresponding data field that indicates the availability of the data for vehicle. System messages begin with the name of a system. Auxiliary messages are identified with "AUX" in its name.

Component reports have a fixed association to a single component. It contains data fields that indicate the type of its component, the systems available on its component, and the status of its component.

Expand All @@ -73,15 +73,14 @@ All signals that can possess one or more of these statuses shall reserve the lar
(N = the largest positive value for the given value space. For non-integers, consider the value space as an integer.)

## Single Bit Data

Reserve 2-bits for data and statuses, defined as follows.
Reserve 2-bits for data and statuses, defined as follows:
0=FALSE_STATE, 1=TRUE_STATE, 2=ERROR, 3=NOT_AVAIL
## 2-7 Bit Data

## 2-7 Bit Data
Reserve two largest positive values for statuses, defined as follows.
N-1=ERROR, N=NOT_AVAIL
## 8 Bit Data and Larger

## 8 Bit Data and Larger
Reserve five largest positive values for statuses, defined as follows.
N-5, N-4, and N-3=RESERVED, N-1=ERROR, N=NOT_AVAIL
RESERVED values are for later use.
Expand All @@ -92,7 +91,6 @@ If one of the enumeration values do not apply to a given signal - NOT_USED may b
User CAN Protocol datalink layer is CAN 2.0 at 500kbps.

## CAN IDs

The list below constrains the assignment of CAN IDs to specific messages. Its purpose is to give increasing priority to the increasing time-criticality of associated data.

1. 0x000-0x03F (0-63) - System-wide reports (global and component reports meant to be received by all components)
Expand All @@ -109,7 +107,6 @@ The list below constrains the assignment of CAN IDs to specific messages. Its pu
1. 0x700-0x7FF (1792-2047) - Unused

## Rules for Transmitting CAN Messages

All system messages transmit at 30Hz. Other messages transmit at 30Hz or less. Transmission of successive messages shall not be back-to-back but must have a minimum separation of 500 microseconds. See the figure below. Faster data transmission may prevent PACMod from processing all data and result in inconsistent behavior.

The figure below is an example of the minimum separation between the transmission of the BRAKE_CMD, STEERING_CMD, and the ACCEL_CMD messages by the User PC. The User PC transmits the complete set of messages, each separated by 500us. The user then transmits the same set of messages again on 30Hz cycle (33.3ms) later. Each message is again separated by 500us.
Expand All @@ -118,7 +115,7 @@ The figure below is an example of the minimum separation between the transmissio

## CAN Signals

The byte order of all CAN signals is Motorola/Big-Endian. All negative numbers are represented as two’s compliment.
The byte order of all CAN signals is Motorola/Big-Endian. All negative numbers are represented as two’s complement.

## CAN Message Availability

Expand Down Expand Up @@ -230,7 +227,7 @@ The SYSTEM_READY signal in the GLOBAL_RPT_2 message shall be READY when all the
Otherwise the SYSTEM_READY signal in the GLOBAL_RPT_2 message shall be NOT_READY.

## User Notification Command Priorities
The buzzer and LED controls have a priority list as follows.
The buzzer and LED controls have a priority list as follows:
BUZZER_MUTE (highest), BUZZER_ON, and internal PACMod (lowest) are the buzzer control priorities.
LIGHT_COMMAND::OFF (highest), LED_BRIGHTNESS, INTERIOR_LIGHTS_RPT::AMBIENT_LIGHT_SENSOR, INTERIOR_LIGHTS_RPT::DIM_LEVEL, MAX_BRIGHTNESS (lowest) are the light control priorities, as available.

Expand All @@ -257,9 +254,9 @@ Bool signal type names shall be suffixed with a direct reference to their affirm

Enumeration signal type names that require additional specificity shall be suffixed with a reference to their corresponding physical signal type. When the signal represents logical information instead of physical, one of the following suffixes shall be used:

1. MODE - shall represent a signal that is read/write and indicates differing behaviors with a given set of hardware or I/O.
1. STATE - shall represent a signal that is read/write and indicates a physical or logical condition.
1. STATUS - shall represent a signal that is read only and indicates a physical or logical condition.
1. MODE - Represents a signal that is read/write and indicates differing behaviors with a given set of hardware or I/O.
1. STATE - Represents a signal that is read/write and indicates a physical or logical condition.
1. STATUS - Represents a signal that is read only and indicates a physical or logical condition.

## Signal Value Name Rules

Expand Down Expand Up @@ -328,4 +325,4 @@ Abbreviations are only required when the name is over 32 characters.
- VEL: Velocity
- VOL: Volume
- XBR: External Braking Request
- XMSN: Transmission
- XMSN: Transmission