Skip to content
NXS aliensense / documentation
NXS · v1.2.0
Guides

Custom cam personality

An image sensor that nxs has never seen needs a cam personality. A cam personality is a YAML facts file, a small Python class and the vendor’s register tables beside them. The facts file digitizes the sensor’s datasheet, and the class programs the sensor. You write the personality with an AI coding agent from the datasheet and the vendor’s setting file. Then you check and compile it on your workstation and install it on your Jetson. At the end your sensor streams on your Jetson at a rate nxs has verified, and the nxsd daemon brings it up at every boot.

Custom cam personality at a glance
  • Hardware: your Jetson and the NXS Hub, set up as in Getting started with the NXS unit. The Hub is the GMSL deserializer board on your Jetson’s camera connector. It carries two coax links, A and B. nxs calls that connector a port, here cam0.
  • Camera pod: your sensor on a camera pod, connected to link A in place of the sensor unit. A camera pod is an NXS unit with the camera head it carries and its serializer. The NXS unit is a small sensor computer, and it runs the personality’s Python class to program the sensor.
  • Declaration: the pod declared as the unit unit-cam0-a in suite.yaml, with no camera node on it yet. suite.yaml is your declaration, the file that names each part of your rig as a node. It names the personality each unit runs and the settings it runs with.
  • Sensor files: the sensor’s datasheet and the vendor’s setting file. The setting file is the register sequence that programs each mode. It comes as a kernel driver’s mode tables or as an application note’s setting list.
  • Workstation: a computer with Claude Code, git, and Python 3.10 or newer.
  • Time: about an hour, plus the reboot.

Commands that start with host$ run on your workstation, and commands that start with orin$ run on your Jetson.

The nxs-generate-cam-personality skill for Claude Code reads a datasheet and a setting file. It picks the law family that nxs serves the sensor with, and writes the personality. Install it once on your workstation, with nxs beside it so the skill can compile what it writes:

Terminal window
host$ git clone --depth 1 https://github.com/aliensense/nxs
host$ mkdir -p ~/.claude/skills && cp -r nxs/skills/nxs-generate-cam-personality ~/.claude/skills/
host$ python3 -m venv ~/nxs-venv
host$ source ~/nxs-venv/bin/activate
host$ python3 -m pip install aliensense-nxs
host$ claude

In the Claude Code session, point the skill at the datasheet and the setting file, and give the personality a name:

/nxs-generate-cam-personality ./cam1-datasheet.pdf ./cam1_settings_v3.txt — name it cam1

The skill extracts the address, the register widths, the identity register, and the modes with their geometry, lanes and rates. It also extracts the stream gate, the register that starts and stops the stream. It splits the setting file into a shared table and one table per mode, and writes cam1.yaml and cam1.py. Then it compiles the personality and prints its report card:

nxs personality: cam1 — cam
files ./cam1/cam1.py · ./cam1/cam1.yaml
tables ./cam1/cam1_init.yaml · ./cam1/cam1_mode_full.yaml · ./cam1/cam1_mode_bin.yaml
family generic
address 0x36 · registers 16-bit · values 8-bit
modes mode_full 1920x1080 RAW10 2-lane 30 fps · mode_bin 960x540 RAW10 2-lane 60 fps
trigger freerun
budget 109 B bytecode of 4096 · trailer 458 B of 4096
nxs personality check ./cam1
nxs upload ./cam1/cam1.py -o cam1.nxs
nxs personality install ./cam1
nxs cam0 A on --sensor cam1
nxs cam0 status
nxs cam0 A capture --frames 60

The card lists the files, the sensor’s facts and the budget, and ends with the commands you run next. The family line names the law family, the set of laws nxs uses for the sensor. generic is for a part whose runtime controls are direct register writes and whose modes run at the rate their tables set. sony_imx is for a part with that family’s register vocabulary. Such a part gets the timing law, the exposure and gain conversions, and the trigger.

The skill never invents a register value. Without a setting file, it stops and says so.

Before you install the personality, check it and compile it on your workstation. nxs personality check reads the personality the way nxs will and names anything wrong with its shape, including a mode whose table is missing. nxs upload -o compiles it without a device and prints the budget:

Terminal window
host$ nxs personality check ./cam1
host$ nxs upload ./cam1/cam1.py -o cam1.nxs
personality cam1: cam · acme,cam1 · 2 mode(s)
ok — bench proof: nxs <port> <link> on --sensor cam1, then capture --frames 60
Compiled Cam1: 109B bytecode, 2 params → 671B cam image
probe 16 B
configure (shared) 30 B
action in [0] block 14 B
mode dispatch 16 B
mode=0 block 12 B
mode=1 block 12 B
action in [1] block 4 B
action in [2] block 4 B
action in [3, 4, 5] block 0 B
halt 1 B
bytecode 109 B of 4096 (2%)
params 2 of 16
descriptor trailer 458 B of 4096
Wrote cam1.nxs: 671B image

The first two lines are the check: a cam personality for acme,cam1 with two modes, and nothing wrong with its shape. The rest is the compile, with the bytes each block of the program costs. The compiler adds the action parameter from the stream gate, and its blocks configure, park and start the sensor. The budget is the unit’s: the program must stay under 4096 bytes and the descriptor trailer under 4096 bytes. If a personality goes over either cap, the compile stops with CompileError and names the cap. Remove a whole mode from the personality, never a row of a table, and compile again.

Copy the directory to your Jetson and install it. The personality store is root-owned, so the install asks for your password:

Terminal window
host$ scp -r cam1 <user>@<jetson>:
orin$ nxs personality install ./cam1
installed cam1 (cam) into /opt/aliensense/personalities/cam1; next: nxs <port> <link> on --sensor cam1

The personality sits in the store at /opt/aliensense/personalities/cam1, and every port offers it. So nxs cam0 caps lists its modes, and your declaration may name acme,cam1 as a sensor. nxs describe acme,cam1 prints the parameters a camera node of that type takes, its modes by name among them.

Bring the link up on the new personality, on link A of port cam0:

Terminal window
orin$ nxs cam0 A on --sensor cam1
link A: the pod runs cam1, mode mode_full, trigger freerun
the port is cold: constructing it
pod A: cam1 uploaded to slot 1
pod A: configure (cam1)
pod A: start (cam1)
link A: acme,cam1 1920x1080 RAW10 @ 30 fps
up A: ok
video locked
cam0: verified 30.0 fps (A 30.0)
next: nxs cam0 A stream

on compiles the personality, uploads it into the pod’s store, and hands the pod the bus so the pod programs the sensor. The personality’s start then writes the stream gate the YAML names. The pod held nothing, so on uploaded cam1 into slot 1, and the unit ran its configure and its start in mode_full. Then on counted two seconds of frames and verified that link A delivers 30.0 fps. A rate the link does not deliver is refused with the rate it delivered. Next, check the port and count 60 frames:

Terminal window
orin$ nxs cam0 status
orin$ nxs cam0 A capture --frames 60
cam0: hub maxim,max96792a ok, capture stack ready
cam0/A: acme,cam1 1920x1080 RAW10 30.0 fps, up, pod unit-cam0-a (cam1, head ok)
cam0 on /dev/i2c-cam0, sync free_run
cam0: verified 30.0 fps 20 s ago (A 30.0)
…
cam0/A: 60/60 at 30.0 fps

status shows acme,cam1 at 1920x1080 RAW10 and 30.0 fps on the pod, with its head answering. The capture got 60 of 60 frames at 30.0 fps. Run nxs cam0 stream to open a viewer on the picture.

If you see a colour cast in the picture, the pixel_phase was transcribed wrong. Check it in the YAML.

If the stream never locks, the lane count or the link rate does not match the mode’s table. Check the mode’s lanes and rate in the YAML against its table.

Give link A its camera in your declaration with nxs tune, the sensor and its mode in one batch:

Terminal window
orin$ nxs tune --set cam0/A:CAM=acme,cam1 --set cam0/A:mode=mode_full
set cam0/A:DECLARE:CAM = acme,cam1
set cam0/A:camera:mode = mode_full
saved (backup suite.yaml.bak-20261007-101500)
IN TUNE ✓

nxs tune offers acme,cam1 because the personality is installed, and mode_full because the personality names that mode. It saved suite.yaml and kept the previous file beside it, and IN TUNE means the file holds on your rig. The file gains a camera node on link A, wired into the pod’s head:

nodes:
camera-cam0-a:
type: acme,cam1
parameters:
mode: mode_full
connections:
camera-cam0-a.out:
- unit-cam0-a.head

For a camera on the connector, the port has no Hub and link A has no pod. Declare it in one batch, with the port’s knob first:

  1. Set the port’s hub knob with cam0:HUB=connector.
  2. Set link A’s sensor with cam0/A:CAM=acme,cam1 in the same batch.
Terminal window
orin$ nxs tune --set cam0:HUB=connector --set cam0/A:CAM=acme,cam1

The saved file has no Hub node and no pod. The camera node feeds your Jetson’s port directly, as camera-cam0-a.out: [host.cam0]. A sensor set without the hub knob is refused with set cam0:HUB first.

Apply the declaration:

Terminal window
orin$ nxs switch
cam0: boot table installed
cam0: installed /boot/camera-dtbos/tegra234-p3767-camera-p3768-aliensense_universal-cam0-2lane-overlay.dtbo
cam0: FDT /boot/dtb/kernel_tegra234-p3768-0000+p3767-0005-nv-super.dtb named in aliensense_gen: the boot entry it copies names /boot/dtb/kernel_tegra234-p3768-0000+p3767-0005-nv-super.dtb
cam0: boot label aliensense_gen (DEFAULT) written; reboot to apply: sudo reboot; original extlinux.conf at /boot/extlinux/extlinux.conf.bak-nxs
REBOOT NEEDED

The pod already holds cam1, so switch prints no line for it. switch installed the port’s boot table, and your Jetson must reboot before the port comes up:

Terminal window
orin$ sudo reboot

After the reboot, nxsd brings the port up on its own, and the declaration is the record from now on. Check the port and count frames:

Terminal window
orin$ nxs cam0 status
orin$ nxs cam0 A capture --frames 60
cam0: hub maxim,max96792a ok, capture stack ready
cam0/A: acme,cam1 1920x1080 RAW10 30.0 fps, up, pod unit-cam0-a (cam1, head ok)
cam0 on /dev/i2c-cam0, sync free_run
cam0: verified 30.0 fps 20 s ago (A 30.0)
…
cam0/A: 60/60 at 30.0 fps

Your sensor is now one of the sensors nxs serves. If you replace the pod, switch brings the new pod to the declaration. status judges the sensor, and nxsd runs it at boot and publishes its frames on ROS 2 like any other camera’s.