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.
What you need
Section titled “What you need”- 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-ainsuite.yaml, with no camera node on it yet.suite.yamlis 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.
1. Install the skill
Section titled “1. Install the skill”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:
host$ git clone --depth 1 https://github.com/aliensense/nxshost$ mkdir -p ~/.claude/skills && cp -r nxs/skills/nxs-generate-cam-personality ~/.claude/skills/host$ python3 -m venv ~/nxs-venvhost$ source ~/nxs-venv/bin/activatehost$ python3 -m pip install aliensense-nxshost$ claudeIn 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 cam1The 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 60The 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.
2. Check and compile
Section titled “2. Check and compile”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:
host$ nxs personality check ./cam1host$ nxs upload ./cam1/cam1.py -o cam1.nxspersonality cam1: cam · acme,cam1 · 2 mode(s) ok — bench proof: nxs <port> <link> on --sensor cam1, then capture --frames 60Compiled 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 4096Wrote cam1.nxs: 671B imageThe 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.
3. Install the personality
Section titled “3. Install the personality”Copy the directory to your Jetson and install it. The personality store is root-owned, so the install asks for your password:
host$ scp -r cam1 <user>@<jetson>:orin$ nxs personality install ./cam1installed cam1 (cam) into /opt/aliensense/personalities/cam1; next: nxs <port> <link> on --sensor cam1The 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.
4. Bring the sensor up
Section titled “4. Bring the sensor up”Bring the link up on the new personality, on link A of port cam0:
orin$ nxs cam0 A on --sensor cam1link A: the pod runs cam1, mode mode_full, trigger freerunthe port is cold: constructing itpod A: cam1 uploaded to slot 1pod A: configure (cam1)pod A: start (cam1)link A: acme,cam1 1920x1080 RAW10 @ 30 fpsup A: okvideo lockedcam0: verified 30.0 fps (A 30.0)next: nxs cam0 A streamon 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:
orin$ nxs cam0 statusorin$ nxs cam0 A capture --frames 60cam0: hub maxim,max96792a ok, capture stack readycam0/A: acme,cam1 1920x1080 RAW10 30.0 fps, up, pod unit-cam0-a (cam1, head ok)cam0 on /dev/i2c-cam0, sync free_runcam0: verified 30.0 fps 20 s ago (A 30.0)…cam0/A: 60/60 at 30.0 fpsstatus 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.
5. Declare the camera
Section titled “5. Declare the camera”Give link A its camera in your declaration with nxs tune, the sensor and its mode in one batch:
orin$ nxs tune --set cam0/A:CAM=acme,cam1 --set cam0/A:mode=mode_fullset cam0/A:DECLARE:CAM = acme,cam1set cam0/A:camera:mode = mode_fullsaved (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_fullconnections: camera-cam0-a.out: - unit-cam0-a.headFor 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:
- Set the port’s hub knob with
cam0:HUB=connector. - Set link A’s sensor with
cam0/A:CAM=acme,cam1in the same batch.
orin$ nxs tune --set cam0:HUB=connector --set cam0/A:CAM=acme,cam1The 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:
orin$ nxs switchcam0: boot table installedcam0: installed /boot/camera-dtbos/tegra234-p3767-camera-p3768-aliensense_universal-cam0-2lane-overlay.dtbocam0: 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.dtbcam0: boot label aliensense_gen (DEFAULT) written; reboot to apply: sudo reboot; original extlinux.conf at /boot/extlinux/extlinux.conf.bak-nxsREBOOT NEEDEDThe 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:
orin$ sudo rebootAfter 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:
orin$ nxs cam0 statusorin$ nxs cam0 A capture --frames 60cam0: hub maxim,max96792a ok, capture stack readycam0/A: acme,cam1 1920x1080 RAW10 30.0 fps, up, pod unit-cam0-a (cam1, head ok)cam0 on /dev/i2c-cam0, sync free_runcam0: verified 30.0 fps 20 s ago (A 30.0)…cam0/A: 60/60 at 30.0 fpsYour 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.
Next steps
Section titled “Next steps”- Do the same steps from a chat: Custom cam personality with an AI agent.
- Look up the facts file’s keys, the law families and the validation gates in the Cam Personality Reference.
- Look up the verbs of the Python class in the Click Personality Reference §4.14.