Camera Media Route Configuration

Overview

The VizionSDK abstracts complex underlying hardware configurations to manage the flow of data from the lens to the application. This abstraction allows developers to focus on application logic rather than low-level driver routing.

When libcamerasrc is available, VizionSDK can automatically handle camera routing via the VIZIONSDK_ENABLE_LIBCAMERASRC_AUTO_LINK environment variable, eliminating the need for manual route configuration.

Understanding the Data Path

The camera data flow passes through multiple hardware stages. For conceptual clarity, we group them into three logical layers:

Sensor Layer:
- Components: Camera sensor (e.g., AR0821, AR1335) and SerDes link (Serializer/Deserializer for GMSL setups).
- Device Examples: max96717 (Serializer), max96724 (Deserializer).
- Device Naming: In YAML configurations, devices appear with their I2C address, such as max96724 1-002e (I2C bus 1 at address 0x2e).
Capture Layer:
- Components: CSI receiver and data formatting.
- Device Examples: csidev-4ad30000.csi, 4ac10000.syscon:formatter@20.
- Key Concept: "Virtual Channels" (VC) separate multiple camera streams coming in on a single physical cable.
Distribution Layer:
- Components: Crossbar routing to ISI processing pipelines.
- Role: Acts as a "Traffic Officer," directing data streams from input ports to the correct ISI output.
- Importance: On complex SoCs like the i.MX95, this is where most configuration errors happen (e.g., collisions).

Data Flow Visualization

The following diagram visualizes how data travels from the physical sensor, through the deserializer (input), across the crossbar (routing), and finally into the SoC's processing pipelines.

libcamerasrc Auto-Link

If libcamerasrc is available and VIZIONSDK_ENABLE_LIBCAMERASRC_AUTO_LINK is enabled, VizionSDK will automatically use libcamerasrc for camera routing. In this case, manual route configuration is not required.

`VIZIONSDK_ENABLE_LIBCAMERASRC_AUTO_LINK`

This environment variable controls whether VizionSDK automatically uses libcamerasrc for routing when it is available.

Value	Behavior
Unset (`null`)	`true` — auto-link enabled
`0`	`false` — auto-link disabled
`1`	`true` — auto-link enabled

To configure this variable:

# Disable libcamerasrc auto-link
export VIZIONSDK_ENABLE_LIBCAMERASRC_AUTO_LINK=0

# Enable libcamerasrc auto-link
export VIZIONSDK_ENABLE_LIBCAMERASRC_AUTO_LINK=1

# Restore default (auto-link enabled)
unset VIZIONSDK_ENABLE_LIBCAMERASRC_AUTO_LINK

info

When libcamerasrc auto-link is enabled, VizionSDK handles routing internally. You only need to manually configure routes (via YAML files or API calls) when auto-link is disabled or libcamerasrc is unavailable.

Hardware Platform Guide

Please refer to the specific configuration guide for your hardware platform:

i.MX95 Configuration (Advanced) - For advanced routing with Crossbar.
i.MX93 Configuration - For direct connections.

Configuration Cookbook

Use this "Quick Reference" to find the exact file you need. You can access and download these example configuration files directly from our GitHub Repository.

Hardware Setup	Platform	Recommended YAML File	Notes
8-Cam (CSI1+CSI2)	i.MX95	`VxRoute_iMX95_GMSL_CSI1_CSI2.yaml`	Uses CSI1+CSI2. CSI1->Pipe A, CSI2->Pipe B.
4-Cam (CSI1)	i.MX95	`VxRoute_iMX95_GMSL_CSI1.yaml`	Dedicated to CSI1 only.
4-Cam (CSI2)	i.MX95	`VxRoute_iMX95_GMSL_CSI2.yaml`	Dedicated to CSI2 only.
2-Camera Kit	i.MX95	`VxRoute_iMX95_GMSL_2CAM_CSI1.yaml`	Connects to CSI1. Routes to Pipeline A.
Single Camera	i.MX93	`VxRoute_iMX93_CSI1.yaml`	Single CSI port, supports one camera.
Single/Dual Cam	RPi 5	`VxRoute_RaspberryPi5.yaml`	Auto-detects connected cameras.

Advanced: Merging Configurations

If you have a custom setup (e.g., 2 cameras on Port 1 and 2 cameras on Port 2), you can create a custom YAML file by copying the Routes section from the "Port 1" file and the Routes section from the "Port 2" file into a single document. Ensure the enable bit is set to 1 for all active paths.

YAML Reference

For advanced users who need to customize the files, here is a brief explanation of the syntax.

Routes:
  - device: "crossbar"
    links:
      - {src: "2/0", dst: "5/0", enable: 1}

device: The specific media entity you are configuring (e.g., "crossbar", "max96724 1-002e").
src: The source pad index (input to the entity).
dst: The destination pad index (output of the entity).
enable: Set to 1 to activate the link, or 0 to disconnect it.

Activate the Media Routes

After setting the routes in YAML file, you can activate these routes by VizionSDK API or run the command from vizion-ctl directly.

Using VizionSDK API to load and activate the YAML file

C++
Python
C#
C

std::string yamlPath = "routes.yaml";
std::shared_ptr<VxRoute> yamlRoutes = VxLoadRouteYaml(yamlPath);
if(yamlRoutes != nullptr) {
    VxActivateYamlRoutes(yamlRoutes);
}

yamlPath = "routes.yaml"
routesYaml = pyvizionsdk.VxLoadRouteYaml(yamlPath)
if routesYaml:
    pyvizionsdk.VxActivateYamlRoutes(routesYaml)

string yamlPath = "routes.yaml";
VxRoute yamlRoutes = CSVizionSDK.VxLoadRouteYaml(yamlPath);
if(yamlRoutes != null) {
    CSVizionSDK.VxActivateYamlRoutes(yamlRoutes);
}

char* yaml_path = "route.yaml";
vx_route yaml_route = vx_load_route_yaml(yaml_path);
if(yaml_route != NULL){
    vx_activate_yaml_routes(yaml_route);
}
// Note: Only C requires explicit cleanup. Other languages use shared pointers.
vx_release_yaml_route(yaml_route);

Using vizion-ctl to activate the route
```
vizion-ctl --setroute <YAML_FILE_PATH>
```

caution

If the route fails to set successfully, verify that the YAML file is correctly formatted. You can also use the VxResetActiveRoutes or vizion-ctl --reset-route to clear all active routes and then reapply the desired routes.

Troubleshooting

libcamerasrc Cannot Find Pipeline Handler

If libcamerasrc fails to find a matching pipeline handler for your device, use the LIBCAMERA_PIPELINES_MATCH_LIST environment variable to explicitly specify which pipeline handlers to use.

LIBCAMERA_PIPELINES_MATCH_LIST defines an ordered list of pipeline handler names to match against the media devices in the system. The names correspond to those registered via the REGISTER_PIPELINE_HANDLER() macro in the libcamera source code.
```
export LIBCAMERA_PIPELINES_MATCH_LIST='nxp/neo,imx8-isi'
```

Overview​

Understanding the Data Path​

Data Flow Visualization​

libcamerasrc Auto-Link​

VIZIONSDK_ENABLE_LIBCAMERASRC_AUTO_LINK​

Hardware Platform Guide​

Configuration Cookbook​

Advanced: Merging Configurations​

YAML Reference​

Activate the Media Routes​

Troubleshooting​