＋ Add to collection

Install (CLI)

npx skillmds add nvidia/jetson-customize-pinmux

Or Copy and Paste in Your Agent chat

Please install the Agent Skill "nvidia/jetson-customize-pinmux" for me from skillmd.com. A SkillMD skill is a SKILL.md file — plain markdown plus a few companion files — that you save into my skills directory. Use whichever fetch route fits your setup: (1) if you have a terminal, run npx -y skillmds add nvidia/jetson-customize-pinmux; (2) otherwise fetch the file manifest at https://api.skillmd.com/api/skills/nvidia/jetson-customize-pinmux/bundle?format=manifest and download each listed file from its "url" into jetson-customize-pinmux/ in your skills directory; (3) if the SkillMD MCP tools are connected, call skillmd_download with slug "nvidia/jetson-customize-pinmux" and save the returned files under jetson-customize-pinmux/. Show me the SKILL.md before saving if you'd like me to review it. If your skills directory is read-only (e.g. the Claude desktop app), save the files to a working folder instead and tell me — I'll add them through my app's skills settings.

README badge

Show this skill's registry status in your repo:

[![SkillMD](https://skillmd.com/badge/nvidia/jetson-customize-pinmux.svg)](https://skillmd.com/skills/nvidia/jetson-customize-pinmux)

jetson-customize-pinmux

Name: jetson-customize-pinmux
Rating: 4.5 (4 reviews)
Author: NVIDIA

nvidia/jetson-customize-pinmux · Agent Skill (multi-file)

by NVIDIA · bundle

Published Jun 29, 2026 · Last updated Jul 6, 2026

Parse a Jetson Orin/Thor pinmux XLSM spreadsheet and generate per-pin BCT DTSI files for a custom carrier board.

SKILL.md

Customize pinmux (per-pin SFIO / direction / state)

Overview

The Tegra pinmux spreadsheet (.xlsm) is the ground truth for every CVM ball: SoC pin name, supported SFIOs, customer-selected function, direction, and initial state. This skill parses that XLSM, runs a per-pin Q1–Q6 interactive loop, and emits the three BCT DTSIs (pinmux, gpio, padvoltage) in one shot into the overlay tracker at <source.root_path>/Linux_for_Tegra/bootloader/.

Unlike sibling skills jetson-customize-uphy / jetson-customize-pcie / jetson-customize-camera, pinmux has no kernel-DT overlay surface and no ODMDATA edit. The XLSM is the source of truth; the three emitted DTSIs land at flash time via the carrier conf's PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= references (which /jetson-derive-carrier set up).

Pad classification (silicon-fixed): only BD* and BI* pads have configurable pull / drive / open-drain attributes. LP5XA_*, UPHYDS_*, DP_SINGLE_*, BDMIPI16X_*, BDUSB2_*, OSCI27_* are fixed-function and skip Q4–Q6 (configurable: no).

The bundled scripts/modify_pinmux.py is the workhorse: it parses the XLSM via openpyxl>=3.1, builds the per-carrier pinmap JSON, captures pin edits into a session shim, and (on generate) writes the three DTSIs.

When to invoke

The user says "configure pin", "set SFIO", "edit pinmux DTSI", "set pin direction", "set initial state", or asks to repurpose a CVM ball (e.g. flip a pin between GPIO and a peripheral function).
A sibling skill (jetson-customize-camera, jetson-customize-pcie, jetson-customize-usb, jetson-customize-mgbe) reports an HSIO pin mismatch via pin_verifier.py and the user wants to fix it.
The user pre-derived a custom carrier with /jetson-derive-carrier and now wants to author the pinmux from a freshly-edited .xlsm.

Prerequisites:

Active profile selected (target-platform/active_target.yml → <profile>.yaml with reference_devkit: AND custom_carrier:).
<source.root_path>/Linux_for_Tegra/ exists as a git repo (/jetson-init-source).
/jetson-derive-carrier has run — the three pinmux-side BCT DTSIs (PINMUX_CONFIG, GPIOINT_CONFIG, PMC_CONFIG references in the carrier conf) exist in the overlay tracker.
A pinmux .xlsm is registered in the active profile at documents.custom_carrier_pinmux_xls (preferred when custom-carrier- specific) or documents.ref_devkit_pinmux_xls (fallback). The bundled modify_pinmux.py requires openpyxl>=3.1.

Procedure

See references/procedure.md for the full step-by-step procedure (Steps 1–8). Summary:

Resolve active target + XLSM. Validate active profile, custom_carrier:, overlay-tracker prerequisites; resolve the pinmux .xlsm path from documents.custom_carrier_pinmux_xls → documents.ref_devkit_pinmux_xls → single XLSM under documents.root_path → user prompt.
Probe. Run modify_pinmux.py probe to parse the XLSM into the per-skill scratch <KB>/pinmap/<custom-carrier>.json plus session.json shim.
Lookup. Resolve a free-form user query (CVM ball, Verilog name, signal, DT pin) via modify_pinmux.py lookup; surface supported SFIO list, defaults, and configurable: yes/no.
Set-pin (HARD GATE — Q1–Q6 via AskUserQuestion). Q1–Q3 (sfio / direction / initial_state) always asked; Q4–Q6 (pull / drive_type / open_drain) only when configurable: yes. tristate and e_input are derived from direction, never asked.
Generate. modify_pinmux.py generate --out-dir <source.root_path>/Linux_for_Tegra/bootloader/ (root, not bootloader/generic/BCT/ — derive-carrier .dts forks live there, do not colocate). Emits: tegra<soc>-mb1-bct-{pinmux,gpio,padvoltage}-<carrier-key>.dtsi. <carrier-key> comes from the carrier conf's PINMUX_CONFIG= reference, NOT the kebab-cased carrier name.
Commit (single batched commit per workflow rule). All three DTSIs are one logical edit → one customization commit. Run the commit-preview gate before each commit.
Run-state sidecar + session shim. Write the user-facing <profile-stem>.jetson-customize-pinmux.json sidecar and the transient session.json shim under <workspace>/target-platform/.
Summary. Emit the standard one-line + table summary.

Gotchas

No kernel-DT overlay; no OVERLAY_DTB_FILE edit; no render_conf.py hand-off. This skill ends at the three BCT DTSIs — the carrier conf already references them via PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= (set up by /jetson-derive-carrier).
Re-point the .dts wrapper's #include after generate. /jetson-derive-carrier forks the .dts wrappers at bootloader/generic/BCT/, but their #include lines may still pull the upstream devkit .dtsi (e.g. …-p3834-xxxx-p4071-0000.dtsi). After generate writes the new <CARRIER_KEY>.dtsi to bootloader/ root, edit each wrapper's #include to the new filename — by bare basename (#include "tegra<soc>-mb1-bct-pinmux-<CARRIER_KEY>.dtsi"), not ../../… filesystem-relative. The BCT build's cpp -I bootloader/ resolves bare basenames; that's the convention every other BCT include in the tree follows. Roll the wrapper edits into the same customization commit as the three DTSIs. See references/procedure.md Step 5 ("Sanity-check the carrier .dts wrapper").
Q4–Q6 gated on configurable: yes. Asking pull / drive_type / open_drain on a fixed-function pad (LP5XA_*, UPHYDS_*, BDMIPI16X_*, etc.) is silently dropped by the script and confuses the user. lookup prints configurable: yes/no — always check it before prompting Q4–Q6.
tristate and e_input are derived, never asked. unused → tristate=ENABLE; input / bidirectional → enable-input=ENABLE. Exposing them as separate prompts produces inconsistent DTSIs.
sfio=gpio requires a parseable gpio=GPIOn_PD.NN entry in the pinmap row's sfio list. Pins without one are GPIO-incapable silicon; set-pin rejects the call. Surface the rejection — don't silently fall back to a non-GPIO SFIO.
Marker idempotency. Every per-pin edit carries // custom-bsp: pinmux on the closing brace; gpio default-state entries carry the same marker as a trailing comment. Re-running generate must detect and update — never duplicate.
modify_pinmux.py is unchanged from the original framework — it reads its own session.json shim under --kb-dir. The shim is regenerated each run from the active profile + the user-facing sidecar. Do not hand-edit the shim; it's transient.
Multiple pinmux DTSI variants per Thor module SKU. Some carrier pins live in a different DTSI variant than the one the carrier conf references. modify_pinmux.py commit (legacy patch-in-place flow) tolerates missing per-pin blocks via pinmux.warnings[] rather than failing. Surface the warning; point at the alternate DTSI variant.
Don't touch the upstream BSP at <bsp_image.root_path>. All edits land in <source.root_path>/Linux_for_Tegra/bootloader/ under the pristine + customization commit pattern.

Available Scripts

Script	Purpose	Arguments
`scripts/modify_pinmux.py`	XLSM parser + per-pin DTSI generator. Invoked via `run_script()` from Steps 3-6 with the subcommand of the current phase.	`probe \| lookup \| set-pin \| apply \| generate \| commit [...]` (see `--help`)
`scripts/generate_dtsi.py`	Renders pinmux/GPIO/padvoltage DTSI fragments from the bundled session state. Called by `modify_pinmux.py generate`.	`--session <path> --out-dir <dir>`

Invoke from the skill body as a subprocess via run_script():

# run_script: probe the carrier pinmux XLSM and write a session state
scripts/modify_pinmux.py probe --xlsm carrier.xlsm --session .pinmux-session.json

# run_script: render DTSI fragments from the final session state
scripts/modify_pinmux.py generate --session .pinmux-session.json --out-dir bsp_sources/pinmux/

References

references/procedure.md — full Step 1–8 procedure prose.
questions.json — Q1–Q6 prompt schema consumed by Step 4.
../../references/platform_template.yaml — documents: block (ref_devkit_pinmux_xls, custom_carrier_pinmux_xls).
../../context/bsp-customization-workflow.md — overlay edit protocol (single-commit per DTSI fork).
../jetson-derive-carrier/SKILL.md — must run first; produces the pinmux / gpio / padvoltage DTSI forks this skill edits, and rewrites the carrier conf's PINMUX_CONFIG= / GPIOINT_CONFIG= / PMC_CONFIG= lines to point at them.
../jetson-init-source/SKILL.md — produces the overlay tracker this skill commits into.
../jetson-link-docs/SKILL.md — author the profile's documents: block, including the pinmux XLSM bindings.

---
name: jetson-customize-pinmux
description: Parse a Jetson Orin/Thor pinmux XLSM spreadsheet and generate per-pin BCT DTSI files for a custom carrier board.
license: Apache-2.0
---

# Customize pinmux (per-pin SFIO / direction / state)

## Overview

The Tegra pinmux spreadsheet (`.xlsm`) is the ground truth for every
CVM ball: SoC pin name, supported SFIOs, customer-selected function,
direction, and initial state. This skill parses that XLSM, runs a
per-pin Q1–Q6 interactive loop, and emits the three BCT DTSIs
(`pinmux`, `gpio`, `padvoltage`) in one shot into the overlay tracker
at `<source.root_path>/Linux_for_Tegra/bootloader/`.

Unlike sibling skills `jetson-customize-uphy` / `jetson-customize-pcie` /
`jetson-customize-camera`, **pinmux has no kernel-DT overlay surface and no
ODMDATA edit**. The XLSM is the source of truth; the three emitted
DTSIs land at flash time via the carrier conf's
`PINMUX_CONFIG=` / `GPIOINT_CONFIG=` / `PMC_CONFIG=` references (which
`/jetson-derive-carrier` set up).

**Pad classification (silicon-fixed):** only `BD*` and `BI*` pads have
configurable pull / drive / open-drain attributes. `LP5XA_*`,
`UPHYDS_*`, `DP_SINGLE_*`, `BDMIPI16X_*`, `BDUSB2_*`, `OSCI27_*` are
fixed-function and **skip Q4–Q6** (`configurable: no`).

The bundled `scripts/modify_pinmux.py` is the workhorse: it parses
the XLSM via `openpyxl>=3.1`, builds the per-carrier pinmap JSON,
captures pin edits into a session shim, and (on `generate`) writes
the three DTSIs.

## When to invoke

- The user says "configure pin", "set SFIO", "edit pinmux DTSI",
  "set pin direction", "set initial state", or asks to repurpose a
  CVM ball (e.g. flip a pin between GPIO and a peripheral function).
- A sibling skill (`jetson-customize-camera`, `jetson-customize-pcie`,
  `jetson-customize-usb`, `jetson-customize-mgbe`) reports an HSIO pin mismatch
  via `pin_verifier.py` and the user wants to fix it.
- The user pre-derived a custom carrier with `/jetson-derive-carrier`
  and now wants to author the pinmux from a freshly-edited `.xlsm`.

**Prerequisites:**

- Active profile selected (`target-platform/active_target.yml` →
  `<profile>.yaml` with `reference_devkit:` AND `custom_carrier:`).
- `<source.root_path>/Linux_for_Tegra/` exists as a git repo
  (`/jetson-init-source`).
- `/jetson-derive-carrier` has run — the three pinmux-side BCT DTSIs
  (`PINMUX_CONFIG`, `GPIOINT_CONFIG`, `PMC_CONFIG` references in the
  carrier conf) exist in the overlay tracker.
- A pinmux `.xlsm` is registered in the active profile at
  `documents.custom_carrier_pinmux_xls` (preferred when custom-carrier-
  specific) or `documents.ref_devkit_pinmux_xls` (fallback). The
  bundled `modify_pinmux.py` requires `openpyxl>=3.1`.

## Procedure

See [`references/procedure.md`](references/procedure.md) for the full
step-by-step procedure (Steps 1–8). Summary:

1. **Resolve active target + XLSM.** Validate active profile,
   `custom_carrier:`, overlay-tracker prerequisites; resolve the
   pinmux `.xlsm` path from
   `documents.custom_carrier_pinmux_xls` →
   `documents.ref_devkit_pinmux_xls` → single XLSM under
   `documents.root_path` → user prompt.
2. **Probe.** Run `modify_pinmux.py probe` to parse the XLSM into the
   per-skill scratch `<KB>/pinmap/<custom-carrier>.json` plus
   `session.json` shim.
3. **Lookup.** Resolve a free-form user query (CVM ball, Verilog
   name, signal, DT pin) via `modify_pinmux.py lookup`; surface
   supported SFIO list, defaults, and `configurable: yes/no`.
4. **Set-pin (HARD GATE — Q1–Q6 via `AskUserQuestion`).** Q1–Q3
   (`sfio` / `direction` / `initial_state`) always asked; Q4–Q6
   (`pull` / `drive_type` / `open_drain`) only when
   `configurable: yes`. `tristate` and `e_input` are derived from
   `direction`, never asked.
5. **Generate.** `modify_pinmux.py generate --out-dir
   <source.root_path>/Linux_for_Tegra/bootloader/` (root, **not**
   `bootloader/generic/BCT/` — derive-carrier `.dts` forks live there,
   do not colocate). Emits:
   `tegra<soc>-mb1-bct-{pinmux,gpio,padvoltage}-<carrier-key>.dtsi`.
   **`<carrier-key>` comes from the carrier conf's `PINMUX_CONFIG=`
   reference, NOT the kebab-cased carrier name.**
6. **Commit (single batched commit per workflow rule).** All three
   DTSIs are one logical edit → one customization commit. Run the
   commit-preview gate before each commit.
7. **Run-state sidecar + session shim.** Write the user-facing
   `<profile-stem>.jetson-customize-pinmux.json` sidecar and the
   transient `session.json` shim under
   `<workspace>/target-platform/`.
8. **Summary.** Emit the standard one-line + table summary.

## Gotchas

- **No kernel-DT overlay; no `OVERLAY_DTB_FILE` edit; no
  `render_conf.py` hand-off.** This skill ends at the three BCT
  DTSIs — the carrier conf already references them via
  `PINMUX_CONFIG=` / `GPIOINT_CONFIG=` / `PMC_CONFIG=` (set up by
  `/jetson-derive-carrier`).
- **Re-point the `.dts` wrapper's `#include` after `generate`.**
  `/jetson-derive-carrier` forks the `.dts` wrappers at
  `bootloader/generic/BCT/`, but their `#include` lines may still
  pull the upstream devkit `.dtsi` (e.g.
  `…-p3834-xxxx-p4071-0000.dtsi`). After `generate` writes the new
  `<CARRIER_KEY>.dtsi` to `bootloader/` root, edit each wrapper's
  `#include` to the new filename — by **bare basename**
  (`#include "tegra<soc>-mb1-bct-pinmux-<CARRIER_KEY>.dtsi"`), not
  `../../…` filesystem-relative. The BCT build's `cpp -I bootloader/`
  resolves bare basenames; that's the convention every other BCT
  include in the tree follows. Roll the wrapper edits into the same
  customization commit as the three DTSIs. See `references/procedure.md`
  Step 5 ("Sanity-check the carrier `.dts` wrapper").
- **Q4–Q6 gated on `configurable: yes`.** Asking pull / drive_type /
  open_drain on a fixed-function pad (`LP5XA_*`, `UPHYDS_*`,
  `BDMIPI16X_*`, etc.) is silently dropped by the script and confuses
  the user. `lookup` prints `configurable: yes/no` — always check it
  before prompting Q4–Q6.
- **`tristate` and `e_input` are derived, never asked.** `unused` →
  tristate=ENABLE; `input` / `bidirectional` → enable-input=ENABLE.
  Exposing them as separate prompts produces inconsistent DTSIs.
- **`sfio=gpio` requires a parseable `gpio=GPIOn_PD.NN` entry in the
  pinmap row's `sfio` list.** Pins without one are GPIO-incapable
  silicon; `set-pin` rejects the call. Surface the rejection — don't
  silently fall back to a non-GPIO SFIO.
- **Marker idempotency.** Every per-pin edit carries
  `// custom-bsp: pinmux` on the closing brace; gpio default-state
  entries carry the same marker as a trailing comment. Re-running
  `generate` must detect and update — never duplicate.
- **`modify_pinmux.py` is unchanged from the original framework** —
  it reads its own `session.json` shim under `--kb-dir`. The shim
  is regenerated each run from the active profile + the user-facing
  sidecar. Do not hand-edit the shim; it's transient.
- **Multiple pinmux DTSI variants per Thor module SKU.** Some carrier
  pins live in a different DTSI variant than the one the carrier
  conf references. `modify_pinmux.py commit` (legacy patch-in-place
  flow) tolerates missing per-pin blocks via
  `pinmux.warnings[]` rather than failing. Surface the warning;
  point at the alternate DTSI variant.
- **Don't touch the upstream BSP at `<bsp_image.root_path>`.** All
  edits land in `<source.root_path>/Linux_for_Tegra/bootloader/` under
  the pristine + customization commit pattern.

## Available Scripts

| Script | Purpose | Arguments |
|---|---|---|
| `scripts/modify_pinmux.py` | XLSM parser + per-pin DTSI generator. Invoked via `run_script()` from Steps 3-6 with the subcommand of the current phase. | `probe \| lookup \| set-pin \| apply \| generate \| commit [...]` (see `--help`) |
| `scripts/generate_dtsi.py` | Renders pinmux/GPIO/padvoltage DTSI fragments from the bundled session state. Called by `modify_pinmux.py generate`. | `--session <path> --out-dir <dir>` |

Invoke from the skill body as a subprocess via `run_script()`:

```bash
# run_script: probe the carrier pinmux XLSM and write a session state
scripts/modify_pinmux.py probe --xlsm carrier.xlsm --session .pinmux-session.json

# run_script: render DTSI fragments from the final session state
scripts/modify_pinmux.py generate --session .pinmux-session.json --out-dir bsp_sources/pinmux/
```

## References
- [`references/procedure.md`](references/procedure.md) — full Step 1–8
  procedure prose.
- [`questions.json`](questions.json) — Q1–Q6 prompt schema consumed
  by Step 4.
- [`../../references/platform_template.yaml`](../../references/platform_template.yaml) — `documents:` block (`ref_devkit_pinmux_xls`, `custom_carrier_pinmux_xls`).
- [`../../context/bsp-customization-workflow.md`](../../context/bsp-customization-workflow.md#workflow-invariants) — overlay edit protocol (single-commit per DTSI fork).
- [`../jetson-derive-carrier/SKILL.md`](../jetson-derive-carrier/SKILL.md) — must run first; produces the pinmux / gpio / padvoltage DTSI forks this skill edits, and rewrites the carrier conf's `PINMUX_CONFIG=` / `GPIOINT_CONFIG=` / `PMC_CONFIG=` lines to point at them.
- [`../jetson-init-source/SKILL.md`](../jetson-init-source/SKILL.md) — produces the overlay tracker this skill commits into.
- [`../jetson-link-docs/SKILL.md`](../jetson-link-docs/SKILL.md) — author the profile's `documents:` block, including the pinmux XLSM bindings.

Files

This skill is a package of 11 files. Install with the command above, or download the folder.

📄SKILL.md entry
📁evals
◆evals.json 4.0 KB
📁references
📄procedure.md 16.6 KB
📁scripts
⚙️_pinmux_common.py 8.2 KB
⚙️_pinmux_dt.py 8.9 KB
⚙️generate_dtsi.py 32.8 KB
⚙️modify_pinmux.py 29.4 KB
📄BENCHMARK.md 3.9 KB
◆questions.json 2.5 KB
📄skill-card.md 3.5 KB
📄skill.oms.sig GitHub 0 B

NVIDIA/skills/tree/main/skills/jetson-customize-pinmux commit · 63c02e122e

▌
jetson-optimize-memory · nvidia bundle
Reclaim DRAM on NVIDIA Jetson devices by disabling unused display, camera, and DMA subsystems across MB1 BCT, MB2 BCT, kernel reserved-memory, and SWIOTLB layers for headless or no-camera deployments.

2.2k
repo stars
▌
jetson-set-target · nvidia bundle
Switch the active Jetson target-platform pointer to an existing profile YAML. Use before customize/build/flash to change target; not for authoring profiles — use jetson-init-target instead.

2.2k
repo stars
▌
jetson-flash-image · nvidia bundle
Flash a promoted BSP image to a Jetson device in RCM mode using NVIDIA's flash.sh or l4t_initrd_flash.sh toolchain.

2.2k
repo stars
▌
jetson-init-image · nvidia bundle
Extract Jetson Linux BSP and sample-rootfs tarballs, run apply_binaries.sh with the correct GPU stack flag, and record the image metadata in the active target profile.

2.2k
repo stars
▌
jetson-init-target · nvidia bundle
Creates a new Jetson target-platform profile YAML by selecting a reference devkit and optional custom carrier, then updates the active target pointer.

2.2k
repo stars
▌
jetson-customize-uphy · nvidia bundle
Configure Jetson UPHY lane allocation on Orin/Thor custom carriers by editing ODMDATA tokens and dispatching per-controller kernel-DT overlay skills.

2.2k
repo stars

Frequently asked questions

How do I install the jetson-customize-pinmux skill?

Run npx skillmds add nvidia/jetson-customize-pinmux in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the jetson-customize-pinmux skill do?

Parse a Jetson Orin/Thor pinmux XLSM spreadsheet and generate per-pin BCT DTSI files for a custom carrier board. It is listed under DevOps & Infra, Coding & Dev Tools, Deployment & Release on SkillMD.

Is jetson-customize-pinmux safe to use?

SkillMD's automated safety review verdict for this skill is CAUTION. Independent scanners report: SkillSpector: WARNING, Skill Scanner: PASS. Capability flags: executes scripts, makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with jetson-customize-pinmux?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is jetson-customize-pinmux free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under Apache-2.

Who published jetson-customize-pinmux?

NVIDIA (@nvidia) published this skill as a verified publisher. Their other Agent Skills are listed on their SkillMD profile.