AM263Px MCU+ SDK: Enet CPSW Ether-Ring CAN Example

| AM263Px MCU+ SDK 26.00.00 |

Enet CPSW Ether-Ring CAN Example

# Introduction

Modern vehicle architectures are increasingly adopting a distributed control approach, moving away from centralized Electronic Control Units (ECUs) towards a network of interconnected zonal controllers. Ether-Ring Architecture reduces wiring and improves reliability by adding redundancy.

## Zonal Controllers: Localized Intelligence

Zonal controllers are essentially powerful, localized ECUs responsible for managing a specific zone or region within the vehicle (e.g., the driver’s door, the front-left wheel well). They directly interface with sensors and actuators within their zone, processing data locally and reducing the load on the central vehicle computer. This localized intelligence leads to faster reaction times for critical functions and reduces the impact of network congestion.

## The Role of CAN Communication within a Zone

Within each zone, the primary communication protocol is typically Controller Area Network (CAN). CAN provides a robust and reliable method for short-range, real-time communication between sensors, actuators, and the zonal controller itself. Critical data such as sensor readings (temperature, pressure, position) and control commands (motor speeds, valve positions) are exchanged over the CAN bus. The inherent deterministic nature of CAN is crucial for safety-critical applications.

## Bridging the Gap: CAN to Ethernet Communication

While CAN is ideal for in-zone communication, it lacks the bandwidth and range required for communication between zones or with higher-level systems (e.g., a central domain controller or cloud services). This is where Ethernet comes into play. Ethernet provides the high bandwidth and long-distance capabilities necessary for broader vehicle network connectivity. However, CAN and Ethernet are fundamentally different protocols. Direct communication between CAN and Ethernet networks is not possible. This necessitates a bridging mechanism to translate and forward data between the two domains.

This application focuses on sending/receiving the CAN vehicle data within Ether-Ring Architecture. CAN-Ethernet Gateway is also implemented to encapsulate/decapsulate the CAN packets. Few CAN Traffic generator configuration parameters are left to customer to modify it based on usecase.

# Ether-Ring overview

Please refer here for Ether-Ring overview

# Ether-Ring CAN Software Architecture

Software Arch

# Application Functionality

Packet Flow

Application contains following three major functionaties

## CAN Traffic Generator

The CAN Traffic Generator is a key functionality of the application, responsible for generating periodic CAN data that simulates sensor/actuator vehicle data in a vehicle. This feature is highly configurable, allowing users to customize the traffic generation process to suit their specific needs.

### Traffic Generator Configuration

The traffic generator configuration consists of the following parameters:

Packet parameters
Parameter | Description
--- | ---
'CAN_msgId' | The Message ID of the CAN packet generated by the traffic generator.
'payloadSize' | The payload size of the CAN packet generated by the traffic generator.
'periodicity' | The periodicity of the CAN packet, measured in microseconds.
'packetCountPerTick' | The number of CAN packets to be generated for each timer tick.
'maxPacketSend' | The maximum number of CAN packets to be generated. If set to 0, packets are sent periodically and continuously.
'hasAllCanPktsSent' | Flag to check whether the all the packets of that configuration is generated.

Traffic Generator Configuration
Parameter | Description
--- | ---
'timerTickPeriodicityInus' | The periodicity of the hardware timer, measured in microseconds.
'validPktParamsCount' | Valid number of CAN packet configurations to be generated by CAN Traffic Generator
'rxReadyElementQ' | Queue to hold the generated CAN packets. This queue will be used by Ethernet App to dequeue the element and send it via CAN-ETH Gateway.
'pktParams[]' | Array of "Packet parameters"

The traffic generator checks the number of valid packet parameters (validPktParamsCount) at each timer tick. If the timer tick interval matches the scheduled periodicity of a CAN packet parameter, the traffic generator creates a new CAN packet. The generated CAN packet is filled with the configured CAN Message ID, payload, and other parameters. Each packet parameter maintains a packetCounter to track whether the maximum packet count has been reached. CAN packets will be sent periodically forever If "maxPacketSend" is configured as "0" or else only maxPacketSend CAN packets will be generated.

By default, a free queue of size 32 (defined by ENETAPP_MAX_CANPKT_MEMBLOCKS) is created initially, and the traffic generator dequeues a free CAN element, fills it based on the packet configuration, and enqueues it to the rxReadyElementQ for the Tx task to process. The Tx task then encapsulates the CAN packet into an Ethernet packet using the CAN-ETH Gateway.

## CAN-ETH Gateway

The CAN-ETH Gateway is a crucial component of the application, responsible for converting CAN messages to AVTP packets and vice versa. It consists of two primary parts: Gateway Look-up and CAN Encapsulation/Decapsulation.

### Gateway Look-up

Look-up table is maintained to map the CAN MessageID to the Destination Mac address. This is mainly used for CAN Encapsulation to Ethernet packet.The below table shows the default Look-up table configured in Application and user should be able to modify this based on thier usecase.

Look-up Table
CAN Message ID | Destination Mac address
--- | ---
0x2 | 01:00:5E:7F:FF:02
0x1 | 01:00:5E:7F:FF:01
0x3 | 01:00:5E:7F:FF:03
0xFF | FF:FF:FF:FF:FF:FF

To achieve low software latency, the destination Mac address for a given CAN Message ID must be fetched quickly. The brute force method to fetch the element with index/key from array takes O(N2) time complexity. In this application, the Look-up table is sorted with "CAN Message ID" at init and also at every time new element is added to the Look-up table. The assumption is that the Look-up table is static at run-time and it is configured only at init. With the sorted Look-up table, the time complexity to fetch any element is reduced to O(logN). This application uses Merge sort and standard binary search is used to fetch the element.

### CAN Encapsulation/Decapsulation

CAN Encapsulation is the process of converting CAN packets to AVTP packets for transmission over Ethernet. In this application, CAN packets are encapsulated and decapsulated using the IEEE 1722 CAN/CAN FD ACF packet format. For encapsulation, the Gateway checks the Message ID of the CAN packet and fetches the Destination Mac address from the look-up table. The Ethernet packet is then formed using the Destination Mac and CAN packet content. For decapsulation, the Gateway forms the CAN packet from the Ethernet packet, and the look-up table is not involved in this process. The idea behind decapsulation is to send the CAN packet to all available CAN interfaces in the Zonal controller, as Ethernet is only used for transportation.

CAN Encap/Decap

IEEE 1722 CAN ACF Packet Format is shown below

IEEE 1722 CAN ACF Packet Format

## Ethernet Transmit App

The CAN Transmit App is responsible for transmitting CAN packets over the Ethernet network using the IEEE 1722 ACF packet format. The transmission process is triggered by a periodic timer, which creates and enqueues CAN packets into the rxReadyElementQ. The Tx Task then dequeues the CAN packet from the queue and uses the Gateway to encapsulate it into a IEEE 1722 ACF packet. The packet is then submitted to the CPDMA for transmission over both Mac ports to other zonal controllers in the EtherRing.

Currently, the Traffic Generator pushes the CAN packet into the rxReadyElementQ. However, users are free to modify this and use actual CAN packets from the MCAN driver, which can be pushed into the same queue for encapsulation.

Packet Flow

## Ethernet Receive App

The CAN Receive App is responsible for receiving CAN packets over the Ethernet network using the IEEE 1722 ACF packet format. The reception process is triggered by a CPDMA Rx interrupt, which releases a semaphore for the Rx Task. The Rx Task then retrieves the Ethernet packet and checks if it is in the IEEE 1722 ACF CAN format. If it is, the packet is sent via the Gateway to decapsulate the CAN packet. Once the CAN packet is retrieved, it is not currently consumed by the application. However, users are free to modify this and send the CAN packet to an actual CAN interface.

Packet Flow

## MCAN Transmit App

The MCAN Transmit Application utilizes the MCAN Low-Level Driver (LLD) to transmit and receive CAN packets via the on-board MCAN transceiver. During initialization, the MCAN driver is configured with standard ID filter elements, and CAN packet Interrupt Service Routines (ISRs) are registered. The application operates in buffer mode for both transmission and reception.

The CAN packets received from the "Ethernet Receive Application" are transmitted to the CAN bus without modification. The MCAN transmit completion and error statistics are updated accordingly to ensure accurate tracking of transmission performance.

## MCAN Receive App

Upon receipt of the MCAN Receive ISR, the buffer number is calculated based on the MCAN0 status bit. The CAN message is then read from the Message RAM using the calculated buffer number. It is essential to configure the filter to receive specific "message IDs" and "buffer numbers" during the initialization process to ensure proper reception of CAN messages.

Note: The configuration of the filter is a critical step in the initialization process, as it determines which CAN messages are received and processed by the application.

Note
  In this application, only 'Node0' acts as CAN traffic generator(Tx Task) and all the nodes has Rx Task. By default, Node0 sends CAN packets only to Node2.

# Round Trip Latency Measurement

Round Trip Latency Measurement

The Round Trip Latency is measured by recording the time it takes for a CAN packet to travel from the source node (Node 0) to the destination node (Node 2) and back. The process involves the following steps:

Timestamp Generation: When a CAN packet is generated by the traffic generator, the current CPTS (Clock Precision Time Synchronization) timestamp is stored and pushed into the timeStampReadyQueue. Packet Transmission: The CAN packet is encapsulated and transmitted to the destination node (Node 2) via the Ether-Ring network. Packet Decapsulation and Response: At the destination node, the CAN packet is decapsulated from the Ethernet packet and sent back to the source node (Node 0) using the on-board MCAN transceiver. Round Trip Latency Calculation: When the packet returns to the source node, a new CPTS timestamp is generated. The difference between this new timestamp and the original timestamp dequeued from the timeStampReadyQueue is calculated, resulting in the Round Trip Latency.

Please refer here for Ether-Ring performance

# Ether-Ring CAN Application Sequence Diagram

Application Flow

## ALE Configuration

- Each Node adds Multicast entry with mac address "01:00:5E:7F:FF:<node_id>" and port mask "0x1"(Only Host Port).

## Ether-Ring Start Menu

The following helper options are also provided in the application's start menu to configure the each node uniquely in Etherring:

0 - Central Compute Node
1 - Zone Left Node
2 - Zone Right Node
3 - Zone Tail Node
Enter the nodeId :

# Supported Combinations

Parameter | Value
--- | ---
CPU + OS | r5fss0-0_freertos
Toolchain | ti-arm-clang
Boards | am263px-lp
Example folder | source/networking/enet/core/examples/etherring_can

# Packet pool configuration

To change packet pool configuration from syscfg, please refer to Ethernet Packet Pool Allocation Guidelines

# Steps to Run the Example

## Build the example

- When using CCS projects to build, import the CCS project for the required combination and build it using the CCS project menu (see Using SDK with CCS Projects).
- When using makefiles to build, note the required combination and build using make command (see Using SDK with Makefiles)

## HW Setup

Make sure you have setup the EVM with cable connections as shown in below Diagram. In addition, follow the steps in the next section.

Ether-Ring EVM Connections

Note
  Ethernet cable must be connected to both the ports in loop for the example application to run with expected results.

## Run the example

### Basic Test

The simplest test that one can run with the ETHERRING example consists of:

- Configuring the each node uniquely in the Ether-ring Network
- Configures CAN Traffic generator to similate the vehicle data and CAN-ETH Gateway for encapsulation/decapsulation

The steps to run this test are:

- Connect the MAC port as described in HW Setup section and configure the Nodes using UART Terminal.
- Launch a CCS debug session and run the example executable, see CCS Launch, Load and Run.
- Application logs such as CAN and Ethernet Tx, Rx Packet count on both source node(node0) and destination node(node2) will be printed. "ETHERRING_MCAN_ENABLE_PROFILING" Macro needs to be commented to see the Packet count logs. By default, only average and Maximum round trip latency is printed on terminal. Sample logs are shown in the next section.
- Using a UART terminal, configure each node according to the instructions in the Ether-Ring Start Menu section. Initially, set up Node1, Node2, and Node3, and put them in a waiting state for link establishment. Once these nodes are configured, proceed to configure Node0 (the traffic generator) to initiate the transmission of CAN traffic. Here Node1 and Node3 just act as switch which forwards the ethernet packets.

## Sample output with "ETHERRING_MCAN_ENABLE_PROFILING" Enabled

### Source Node(Node0)

==========================
EtherRing CAN App
==========================
0 - Central Compute Node
1 - Zone Left Node
2 - Zone Right Node
3 - Zone Tail Node
Enter the nodeId :
0
start to open driver.
Init all configs
----------------------------------------------
init config
Open MAC port 1
EnetPhy_bindDriver: PHY 3: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
Open MAC port 2
EnetPhy_bindDriver: PHY 12: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
PHY 3 is alive
PHY 12 is alive
initQs() txFreePktInfoQ initialized with 16 pkts
MAC port addr: 34:08:e1:84:dd:31
[MCAN App] Mcan Driver Configured
Waiting for link up...
Cpsw_handleLinkUp: Port 2: Link up: 1-Gbps Full-Duplex
MAC Port 2: link up
Cpsw_handleLinkUp: Port 1: Link up: 1-Gbps Full-Duplex
MAC Port 1: link up
Ethernet RX Task created
Ethernet TX Task created
Generating CAN Traffic
[MCAN Rx App] Avg Round Trip Time:561 us
[MCAN Rx App] Max Round Trip Time:569 us
EtherRing CAN Test Passed

### Destination Node(Node0)

==========================
EtherRing CAN App
==========================
0 - Central Compute Node
1 - Zone Left Node
2 - Zone Right Node
3 - Zone Tail Node
Enter the nodeId :
2
start to open driver.
Init all configs
----------------------------------------------
init config
Open MAC port 1
EnetPhy_bindDriver: PHY 3: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
Open MAC port 2
EnetPhy_bindDriver: PHY 12: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
PHY 3 is alive
PHY 12 is alive
initQs() txFreePktInfoQ initialized with 16 pkts
MAC port addr: 34:08:e1:84:db:cf
[MCAN App] Mcan Driver Configured
Waiting for link up...
Cpsw_handleLinkUp: Port 2: Link up: 1-Gbps Full-Duplex
MAC Port 2: link up
Cpsw_handleLinkUp: Port 1: Link up: 1-Gbps Full-Duplex
MAC Port 1: link up
Ethernet RX Task created

## Sample output with "ETHERRING_MCAN_ENABLE_PROFILING" Disabled

### Source Node(Node0)

==========================
EtherRing CAN App
==========================
0 - Central Compute Node
1 - Zone Left Node
2 - Zone Right Node
3 - Zone Tail Node
Enter the nodeId :
0
start to open driver.
Init all configs
----------------------------------------------
init config
Open MAC port 1
EnetPhy_bindDriver: PHY 3: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
Open MAC port 2
EnetPhy_bindDriver: PHY 12: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
PHY 3 is alive
PHY 12 is alive
initQs() txFreePktInfoQ initialized with 16 pkts
MAC port addr: 34:08:e1:84:dd:31
[MCAN App] Mcan Driver Configured
Waiting for link up...
Cpsw_handleLinkUp: Port 1: Link up: 1-Gbps Full-Duplex
MAC Port 1: link up
Cpsw_handleLinkUp: Port 2: Link up: 1-Gbps Full-Duplex
MAC Port 2: link up
Ethernet RX Task created
Ethernet TX Task created
Generating CAN Traffic
[Traffic Gen] Generated 1000 CAN packet of CAN Message ID: 2
[MCAN Rx App] Received 1000 CAN packets from CAN bus
EtherRing CAN Test Passed

### Destination Node(Node0)

==========================
EtherRing CAN App
==========================
0 - Central Compute Node
1 - Zone Left Node
2 - Zone Right Node
3 - Zone Tail Node
Enter the nodeId :
2
start to open driver.
Init all configs
----------------------------------------------
init config
Open MAC port 1
EnetPhy_bindDriver: PHY 3: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
Open MAC port 2
EnetPhy_bindDriver: PHY 12: OUI:080028 Model:0f Ver:01 <-> 'DP83869' : OK
PHY 3 is alive
PHY 12 is alive
initQs() txFreePktInfoQ initialized with 16 pkts
MAC port addr: 34:08:e1:84:db:cf
[MCAN App] Mcan Driver Configured
Waiting for link up...
Cpsw_handleLinkUp: Port 1: Link up: 1-Gbps Full-Duplex
MAC Port 1: link up
Cpsw_handleLinkUp: Port 2: Link up: 1-Gbps Full-Duplex
MAC Port 2: link up
Ethernet RX Task created
Cpsw_handleLinkDown: Port 1: Link down
Cpsw_handleLinkDown: Port 2: Link down
MAC Port 1: link down
MAC Port 2: link down
Cpsw_handleLinkUp: Port 2: Link up: 1-Gbps Full-Duplex
MAC Port 2: link up
Cpsw_handleLinkUp: Port 1: Link up: 1-Gbps Full-Duplex
MAC Port 1: link up
[Ethernet Rx App] Received 1000 EtherRing CAN packets to Rx Eth task
[MCAN Tx App] Sent 1000 CAN packets to CAN bus

# See Also

Ethernet And Networking