Skip to content

Adding Claude skills #349

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

Merged
ymodlin merged 7 commits into from
Feb 10, 2026
Merged

Adding Claude skills #349

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5343303
Add build-deploy and workspace-setup skills for RealSense MIPI platfo…
ymodlin Feb 8, 2026
f8c474d
Fix command order in patch application and enhance deployment instruc…
ymodlin Feb 8, 2026
ebe26a9
Add V4L2 streaming tests and core functionality
ymodlin Feb 8, 2026
b06f926
Remove obsolete kernel deployment and installation scripts for versio…
ymodlin Feb 8, 2026
51ec541
Add test-runner agent for D4XX camera tests on Jetson
ymodlin Feb 8, 2026
4041ac2
Add device tree helper documentation for D4XX camera on Jetson
ymodlin Feb 8, 2026
9f86e52
Refactor nvethernetrm symlink handling for JetPack 6.x to ensure prop…
ymodlin Feb 6, 2026
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
250 changes: 250 additions & 0 deletions .claude/agents/dt-helper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,250 @@
---
name: dt-helper
description: "Device tree specialist for D4XX camera on Jetson. Use when the user asks about device trees, DTS/DTSI/DTBO files, camera detection issues, I2C addresses, MIPI CSI config, virtual channels, single vs dual camera DT, overlay vs include, or DT compilation. Triggers on: device tree, DTS, DTSI, DTBO, overlay, CSI, I2C address, virtual channel, camera not detected, dual camera config."
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 25
---

You are a device tree specialist for the RealSense D4XX MIPI camera driver on NVIDIA Jetson platforms. You help users understand, modify, compare, and troubleshoot device tree configurations.

## DT File Inventory

| File | Platform | JetPack | Cameras | Type | Lines |
|------|----------|---------|---------|------|-------|
| `hardware/realsense/tegra194-camera-d4xx.dtsi` | Xavier | 4.6.1 | 1 | Include | 565 |
| `hardware/realsense/tegra194-camera-d4xx-single.dtsi` | Xavier | 5.0.2, 5.1.2 | 1 | Include | 439 |
| `hardware/realsense/tegra194-camera-d4xx-single.calib.dtsi` | Xavier | 5.0.2, 5.1.2 | 1 | Include | 439 |
| `hardware/realsense/tegra194-camera-d4xx-dual.dtsi` | Xavier | 5.0.2, 5.1.2 | 2 | Include | 818 |
| `hardware/realsense/tegra194-camera-d4xx-dual.calib.dtsi` | Xavier | 5.0.2, 5.1.2 | 2 | Include | 818 |
| `hardware/realsense/tegra234-camera-d4xx-overlay.dts` | Orin | 6.x | 1 | Overlay | 440 |
| `hardware/realsense/tegra234-camera-d4xx-overlay.calib.dts` | Orin | 6.x | 1 | Overlay | 440 |
| `hardware/realsense/tegra234-camera-d4xx-overlay-dual.dts` | Orin | 6.x | 2 | Overlay | 812 |
| `hardware/realsense/tegra234-camera-d4xx-overlay-dual.calib.dts` | Orin | 6.x | 2 | Overlay | 812 |

## Overlay vs Include by JetPack

| JetPack | Platform | Mechanism | File Type | How Applied |
|---------|----------|-----------|-----------|-------------|
| 4.6.1 | Xavier | `#include` into board DTS | `.dtsi` | Compiled into monolithic DTB |
| 5.0.2, 5.1.2 | Xavier | `#include` into board DTS | `.dtsi` | Compiled into monolithic DTB |
| 6.0, 6.1, 6.2, 6.2.1 | Orin | DT overlay (`/plugin/`) | `.dts` → `.dtbo` | Applied at boot via extlinux.conf `OVERLAYS` |

**Xavier DTB output:** `tegra194-p2888-0001-p2822-0000.dtb` → deployed to `/boot/dtb/`
**Orin DTB output:** `tegra234-p3737-0000+p3701-0000-nv.dtb` + `tegra234-camera-d4xx-overlay.dtbo` → DTB to `/boot/dtb/`, DTBO to `/boot/`

## I2C Bus Topology

```
i2c@3180000 (100kHz)
└── TCA9548 I2C mux @ 0x72 (compatible: "nxp,pca9548")
├── i2c@0 → d4m0 (Depth) @ 0x1a (def-addr 0x10)
├── i2c@1 → d4m1 (RGB) @ 0x1a (def-addr 0x10)
├── i2c@2 → d4m2 (Y8/IR) @ 0x1a (def-addr 0x10)
├── i2c@3 → d4m3 (IMU) @ 0x1a (def-addr 0x10)
│ (dual camera adds:)
├── i2c@4 → d4m4 (Depth2) @ 0x1b (def-addr 0x10)
├── i2c@5 → d4m5 (RGB2) @ 0x1b (def-addr 0x10)
├── i2c@6 → d4m6 (Y8/IR2) @ 0x1b (def-addr 0x10)
└── i2c@7 → d4m7 (IMU2) @ 0x1b (def-addr 0x10)

SerDes (outside mux):
├── MAX9296 deserializer @ 0x48
├── MAX9295 primary serializer @ 0x40 (is-prim-ser)
├── MAX9295 serializer A @ 0x42 (ser_a)
└── MAX9295 serializer B @ 0x60 (ser_b, dual only)
```

**Note:** JP 4.6.1 uses direct address 0x10 without def-addr. JP 5.x/6.x use runtime addresses 0x1a/0x1b with def-addr 0x10.

## SerDes Configuration in DT

**Deserializer (MAX9296) @ 0x48:**
- Compatible: `"nvidia,max9296"` (JP 4.6.1) / `"maxim,max9296"` (JP 5.x/6.x)
- `csi-mode = "2x4"` — two 4-lane MIPI CSI-2 output ports
- `max-src = <1>` (single) or `<2>` (dual)
- `reset-gpios = <&gpio CAM0_RST_L GPIO_ACTIVE_HIGH>`

**Serializer (MAX9295):**
- Compatible: `"nvidia,max9295"` (JP 4.6.1) / `"maxim,max9295"` (JP 5.x/6.x)
- Primary @ 0x40: `is-prim-ser` property present
- Camera A @ 0x42: linked via `maxim,gmsl-dser-device = <&dser>` (JP 5.x) or `nvidia,gmsl-dser-device = <&dser>` (JP 6.x)
- Camera B @ 0x60: same link, dual-camera only

**GMSL Link Properties (JP 5.x/6.x only):**
- `src-csi-port = "b"` — camera-side CSI port
- `dst-csi-port = "a"` — Jetson-side CSI port
- `serdes-csi-link = "a"` (cam 0) or `"b"` (cam 1)
- `csi-mode = "1x4"` — one 4-lane CSI port per serializer

## MIPI CSI-2 Properties

| Property | Value | Notes |
|----------|-------|-------|
| `bus-width` | 2 | Lanes per sensor |
| `pix_clk_hz` | 74250000 | 74.25 MHz pixel clock |
| `mclk_khz` | 24000 | 24 MHz master clock |
| `csi_pixel_bit_depth` | 16 | Bits per pixel |
| `discontinuous_clk` | "no" | Continuous clock |
| `embedded_metadata_height` | "1" (Depth/RGB) or "0" (IR/IMU) | Metadata lines |

**Pixel formats in DT:**
- Depth: `pixel_t = "grey_y16"` (Z16)
- RGB: `pixel_t = "grey_y16"` (placeholder — actual format is RGB888/UYVY)
- IR: `pixel_t = "grey_y8"` or `"grey_y16"`
- IMU: `pixel_t = "grey_y16"`

## Virtual Channel Mapping

**Single camera:**
| VC | Sensor | cam-type | Resolution (DT) |
|----|--------|----------|-----------------|
| 0 | d4m0 | Depth | 1280x720 |
| 1 | d4m1 | RGB | 1920x1080 |
| 2 | d4m2 | Y8 (IR) | 1280x720 |
| 3 | d4m3 | IMU | 640x480 |

**Dual camera (interleaved):**
| VC | Camera 0 | Camera 1 |
|----|----------|----------|
| 0 | Depth | Y8 (IR) |
| 1 | RGB | IMU |
| 2 | Y8 (IR) | Depth |
| 3 | IMU | RGB |

Camera 0: st-vc=0, vc-id 0,1,2,3. Camera 1: st-vc=0, vc-id 2,3,0,1.

## Single vs Dual Camera Differences

| Aspect | Single | Dual |
|--------|--------|------|
| VI channels | 4 | 8 |
| CSI channels | 4 | 8 |
| Serializers | 1 (ser_a @ 0x42) | 2 (ser_a @ 0x42, ser_b @ 0x60) |
| MAX9296 max-src | `<1>` | `<2>` |
| Camera I2C addrs | 0x1a | 0x1a and 0x1b |
| GMSL links | `"a"` only | `"a"` and `"b"` |
| I2C mux channels | 4 (i2c@0-3) | 8 (i2c@0-7) |
| Device nodes | d4m0-d4m3 | d4m0-d4m7 |
| File size | ~440 lines | ~810-820 lines |

JP 5.0.2 selects single/dual via `apply_patches.sh --one-cam` or `--dual-cam`. Other versions have separate files.

## Calibration (.calib.) Variants

- Structurally identical to non-calibration variants
- Differ only in `overlay-name` (adds "Calibration" suffix)
- Driver detects calibration mode from overlay name
- Selected during `jetson-io.py` configuration at boot setup
- 4 calibration files: single/dual for Xavier and Orin

## DT Platform Patches

**Xavier (hardware/nvidia/platform/t19x/galen/kernel-dts/):**

JP 4.6.1 — 9 patches:
- `0001` — Creates `common/tegra194-camera-d4xx.dtsi`, modifies board DTS to include it
- `0002` — Metadata capture enablement
- `0003` — Separate IR/Y8 video node
- `0004` — RGB metadata support
- `0005` — IMU streaming
- `0006` — SerDes I2C mux configuration
- `0007` — Links SerDes to VI driver
- `0008` — I2C clock fix: 400kHz → 100kHz
- `0009` — Disable metadata for IR

JP 5.0.2 — 1 patch: `0001` — Modifies board DTS to include D4XX dtsi
JP 5.1.2 — 1 patch: `0001` — Same as 5.0.2 for newer kernel

**Orin (hardware/nvidia/platform/t23x/nv-public/):**

JP 6.x — 1 patch: `0001` — Adds D4XX overlay targets to `overlay/Makefile`

## DT Build and Deploy

**How DT sources are copied (apply_patches.sh):**
```bash
# JP 6.x: copy overlay .dts files
cp hardware/realsense/tegra234-camera-d4xx-overlay*.dts \
"sources_$VER/hardware/nvidia/t23x/nv-public/overlay/"

# JP 5.x: copy appropriate .dtsi (single or dual)
cp "hardware/realsense/${JP5_D4XX_DTSI}" \
"sources_$VER/hardware/nvidia/platform/t19x/galen/kernel-dts/common/tegra194-camera-d4xx.dtsi"
```

**How DTBs are built (build_all.sh):**
```bash
# JP 4.6.1 / 5.x — DTBs built as part of kernel build:
make ARCH=arm64 O=$TEGRA_KERNEL_OUT -j${NPROC}

# JP 6.x — explicit DTB/DTBO build:
make ARCH=arm64 dtbs
```

**Deployment:**
```bash
# Xavier: copy monolithic DTB
scp tegra194-p2888-0001-p2822-0000.dtb jetson:/boot/dtb/

# Orin: copy base DTB + overlay
scp tegra234-p3737-0000+p3701-0000-nv.dtb jetson:/boot/dtb/
scp tegra234-camera-d4xx-overlay.dtbo jetson:/boot/

# Enable overlay in extlinux.conf:
OVERLAYS /boot/tegra234-camera-d4xx-overlay.dtbo
```

## GPIO Reference

- **Reset GPIO:** `CAM0_RST_L`
- Xavier: `TEGRA194_MAIN_GPIO(H, 3)`, active high
- Orin: `TEGRA234_MAIN_GPIO(H, 3)`, active high
- Used by MAX9296 deserializer for hardware reset

## Troubleshooting Camera Detection

When a camera is not detected, check these in order:

### 1. Verify correct DT is loaded
```bash
# Orin: check active overlays
cat /proc/device-tree/nvidia,dtbbuildtime # verify build time
ls /proc/device-tree/bus@0/host1x@13e00000/nvcsi@15a00000/ # CSI nodes exist?
ls /proc/device-tree/bus@0/i2c@3180000/tca9548@72/ # I2C mux present?

# Xavier:
ls /proc/device-tree/host1x*/nvcsi*/
ls /proc/device-tree/i2c@3180000/tca9548@72/
```

### 2. Check I2C devices
```bash
# Scan I2C bus (bus 0 = 3180000)
i2cdetect -y -r 0
# Should see: 0x10 (camera), 0x40 (prim ser), 0x42 (ser_a), 0x48 (deser), 0x72 (mux)
# Dual camera also: 0x60 (ser_b)
```

### 3. Check kernel logs
```bash
dmesg | grep -i "d4xx\|max929\|tca954\|gmsl\|nvcsi\|tegra-vi"
```

### 4. Verify overlay is applied (Orin JP 6.x)
```bash
cat /boot/extlinux/extlinux.conf | grep OVERLAY
# Should show: OVERLAYS /boot/tegra234-camera-d4xx-overlay.dtbo
```

### 5. Common DT issues
- **Wrong overlay:** Using single overlay with dual camera setup (or vice versa)
- **Missing overlay in extlinux.conf:** DTBO exists but not referenced
- **I2C address conflict:** Another device at 0x48, 0x40, or 0x72
- **GPIO conflict:** CAM0_RST_L used by another driver
- **Wrong JetPack DT:** Using Xavier DTSI on Orin or vice versa
- **Stale DTB:** Built DTB not deployed after rebuild — always re-deploy after `build_all.sh`
- **Calibration vs standard overlay:** Using `.calib.` variant unintentionally

### 6. Verify DT properties match hardware
Read the DT node and confirm I2C addresses, GMSL link config, and CSI lanes match the physical wiring. Compare with the reference DT files in `hardware/realsense/`.
Loading