Getting started with the NXS unit
An NXS unit is a small sensor computer. It runs a click personality, the compiled program for the sensor on its Click. Your host gets samples in SI units and needs no code for the sensor. You connect the unit from the box, with its FXOS8700 Click, to your host and see the first samples on your screen in two minutes. At the end, your host restores the setup at every boot, and you can reach the unit by name.
What you need
Section titled “What you need”- Host: set up as in the NVIDIA Jetson deployment guide. It has
nxsinstalled, the assets in place and the camera buses up with their port names. The assets are the camera and Hub programs that ship as one download, versioned withnxs. - NXS box: the unit, a mikroBUS Shuttle with an FXOS8700 Click (an accelerometer and magnetometer) and a coax cable.
- NXS Hub: in its own box, with its power lead.
- Time: two minutes to the first samples, twenty minutes in all.
1. Connect the hardware
Section titled “1. Connect the hardware”Put the Click on the unit, then connect the unit to your host through the Hub:
- Push the Click onto the Shuttle until it sits flat.
- Push the Shuttle onto the unit’s mikroBUS socket until it sits flat.
- Run the coax from the unit to link A of the Hub.
- Plug the Hub into CAM0.
- Connect the Hub’s power lead. The unit draws its power over the coax.
The unit has one green LED, and it tells you what the unit is doing before your host can. While the unit boots, the LED flashes once a second. Within a few seconds the flash turns into a heartbeat, a short pulse followed by a longer one. The heartbeat means that the personality in slot 0 found the Click and is measuring.
2. Find the unit
Section titled “2. Find the unit”Check that your host sees the Hub and the unit. nxs probe sweeps every camera bus and prints what answers:
nxs probe/dev/i2c-cam0: NXS Hub @0x6A (hub maxim,max96792a) NXS unit @0x30 serial 2f004b0032510f0011223344no suite.yaml yet — write down what answered: nxs generateTwo devices answered on the cam0 bus: the Hub at address 0x6A and your unit at 0x30 behind link A, with its serial number. Make sure that you and nxs are looking at the same box:
nxs cam0 A identifyIdentify: status LED strobing on i2c /dev/i2c-cam0@0x30 (~10 s)The unit’s LED strobes fast for ten seconds and then returns to its heartbeat. With several units on a bench, this is how you tell them apart.
3. Read the sensor
Section titled “3. Read the sensor”Your unit keeps its personalities in a store with eight slots and boots the first slot that holds a click personality. It shipped with the FXOS8700 personality in slot 0:
nxs store lsPersonality store: 1/8 populated [0] Fxos8700 (click, 7 outputs, 6 params) ← activeThe personality has seven outputs and six parameters. The outputs are three accelerometer axes, three magnetometer axes and a temperature. Two parameters tune the sensor, a sample rate and an accelerometer range, and orientation names how the unit sits on your machine. Two more say how the Click is wired: the bus it talks on and the polarity of its reset line. The sixth, stream, starts and parks the sampling. Stream five samples:
nxs stream --count 5Streaming Fxos8700 — 7 fields, 13B/sample, every_nth=1 (ctrl-C to stop)
accel_x accel_y accel_z mag_x mag_y mag_z temp (m/s^2) (m/s^2) (m/s^2) (tesla) (tesla) (tesla) (°C)[ - Hz] n= 6126 ts=... 0.1963 -0.03352 9.855 3.39e-05 -1.7e-05 -7.34e-05 21.12[ 200.0 Hz] n= 6127 ts=... 0.1915 -0.02394 9.864 3.32e-05 -1.74e-05 -7.44e-05 21.12[ 200.0 Hz] n= 6128 ts=... 0.1915 -0.009577 9.869 3.3e-05 -1.72e-05 -7.45e-05 21.12[ 200.0 Hz] n= 6129 ts=... 0.1867 -0.02394 9.864 3.34e-05 -1.73e-05 -7.4e-05 21.12[ 200.0 Hz] n= 6130 ts=... 0.1724 -0.03352 9.855 3.3e-05 -1.64e-05 -7.51e-05 21.12
Stopped after 5 samples in 25ms (200.0 Hz avg)These are your first samples, in metres per second squared, tesla and degrees Celsius. A unit from the box streams at the personality’s default rate, 100 Hz. This one was set to 200 Hz, the way step 5 sets a range. Each line also shows the unit’s sample counter, a timestamp from the unit’s clock and the rate the unit measures at. The rate is read from the timestamps, so it needs two samples and the first row shows none. The unit describes every field it serves, with its scale, offset and unit, so nxs prints them without knowing anything about the FXOS8700.
4. Declare and switch
Section titled “4. Declare and switch”So far you have talked to the unit directly. A declaration is a file, suite.yaml, that describes your rig as nodes and the connections between them. nxs holds the hardware to the file, and the nxsd daemon runs it at boot. Let nxs generate write your first one from what answered:
nxs generatescan: can0 is down — bring it up at the device's bit timing before it can answercam0 (/dev/i2c-cam0, 2-lane): HUB maxim,max96792a @0x6A ok A (window 0x21): SER maxim,max96793 ok · no head (no identity register; no ACK) · NXS unit @0x30 serial 2f004b0032510f0011223344 fw vX.Y.Z-0-g<sha> B (window 0x22): link not locked, nothing behind itcam1 (/dev/i2c-cam1, 4-lane): nothing answers hub maxim,max96792a @0x6A does not answer and is not written (check its power and cabling, then generate again)wrote /etc/aliensense/hardware.yaml (2 port(s))seeded /etc/aliensense/suite.yaml (1 unit(s)); next: nxs tuneThe report walks both camera connectors. On cam0 the Hub answers, link A carries its serializer and your unit, with no camera head, and nothing is connected to link B. Nothing is connected to cam1 either, so nxs generate writes no Hub there. The first line is about your Jetson’s CAN interface, which this guide does not use.
nxs generate wrote hardware.yaml, which records what is wired, and seeded your declaration beside it. Both live in /etc/aliensense, where nxsd reads the declaration at boot. The deployment guide’s nxs switch made that directory for the i2c group, so you edit the file without sudo. Print the declaration:
cat /etc/aliensense/suite.yaml# Written by `nxs generate` from what it found. This file is yours to# edit, by hand or with `nxs tune`: names, personalities, settings. The wiring# lives in hardware.yaml beside it and is rewritten on every run.api: 3nodes: host: type: jetson hub-cam0: type: maxim,max96792a parameters: csi_a_lanes: 2 unit-cam0-a: type: nxs parameters: serial: 2f004b0032510f0011223344 click-unit-cam0-a: type: fxos8700connections: hub-cam0.csi.A: - host.cam0 host.bus_cam0: - hub-cam0.i2c unit-cam0-a.out: - hub-cam0.links.A click-unit-cam0-a.out: - unit-cam0-a.clickA node is one part of your rig: your Jetson, the Hub, the unit and the Click on the unit’s socket. Each node has a type, which says what the part is, and its parameters. A connection runs from a node’s port to the ports it feeds. The Hub’s CSI output feeds your Jetson’s cam0, and your Jetson runs the Hub over bus_cam0, the I²C bus beside it. The unit’s out rides link A of the Hub, and the Click feeds the unit’s socket.
The unit is named after where it hangs, unit-cam0-a, and its Click runs the personality fxos8700. serial ties the node to this unit. The Hub’s csi_a_lanes: 2 matches the two CSI lanes of your Jetson’s cam0.
Once the port is up, the Hub presents the unit at 0x32, the alias of link A, so the file names no address. The file names no bus either, because nxs knows the bus of each port by the port’s name. Nothing answered on cam1, so the file declares nothing there. Apply the file:
nxs switchcam0: nxsd reconverging✓ unit-cam0-a (i2c /dev/i2c-cam0@0x32) converged time sync seeded (±229 µs)The first line is the port: switch hands it to nxsd, which brings it up. The lines under the tick are your unit, now at its alias. On this first run, switch saves the declared personality in the unit’s store and sets the unit’s clock against your Jetson’s. No camera is declared, so switch installs no camera table and you do not need to reboot. The one reboot a unit on the Hub needs, the one that starts the camera buses, came with the deployment guide.
The port comes up at once, and from now on nxsd brings it up at every boot. Run nxs status with no arguments to judge the file against the hardware:
nxs statusdeclaration: IN TUNEpersonalities: /opt/aliensense/personalities (2 shipped, 0 installed)ports: cam0 /dev/i2c-cam0 hub hub-cam0 (maxim,max96792a) HUB: id 0xB6 ok CSI: port 2-lane (booted overlay: device tree silent) link A SER: present link A SEN: none declared (no ACK at 0x1a) link A NXS@0x32: present link A NXS@0x32: click personality Fxos8700 unit-cam0-a i2c /dev/i2c-cam0@0x32 ok serial 2f004b0032510f0011223344 fw vX.Y.Z-0-g<sha> outputs: accel_x accel_y accel_z mag_x mag_y mag_z tempIN TUNE means your declaration holds on this hardware: every setting in it is one your hardware offers, and your unit runs its declared personality. The lines between the port and your unit are the port’s own health. The Hub answers, link A is alive, and the unit behind it runs the FXOS8700 personality. The CSI and SEN lines are about cameras, and you have declared none. Your unit now answers at the alias the port gave it, 0x32, and by name. nxs --unit unit-cam0-a stream --count 5 prints the same samples as before.
From now on, you change the declaration with nxs tune. Without flags, it opens a panel that shows the rig as a tree, one line for each unit and camera port, declared or not. ↑↓ move over the nodes and the knobs of the node under the cursor. ←→ step a knob through the values its part offers there. s saves the file with a backup beside it and names nxs switch as the next command, and q quits. In a script, nxs tune --set sets one knob per flag and saves the same way, as the next step shows.
5. Change a setting
Section titled “5. Change a setting”Every personality declares its parameters and the values each one accepts. Run caps on your unit to print that table with the current setting of each parameter:
nxs --unit unit-cam0-a capsPersonality: Fxos8700 sample_rate: [400, 200, 100, 50, 25] current=200 default=100 unit=Hz accel_fs: [2, 4, 8] current=4 default=4 unit=g orientation: 0..23 current=0 default=0 [apply] bus: [0, 1] current=0 default=0 reset_active: [0, 1] current=1 default=1 stream: [0, 1] current=1 default=0The accelerometer range, accel_fs, accepts 2, 4 or 8 g and is set to 4 g. [apply] marks a parameter the unit applies in place, such as the orientation code from 0 to 23. set changes a parameter on the running personality. It re-runs the personality’s configuration so the new value reaches the sensor’s registers, and nothing is uploaded. Set the range to 8 g:
nxs --unit unit-cam0-a set accel_fs 8accel_fs: 4 → 8nxs refuses a value that is not in the list, and it prints the list. So a typo cannot put the sensor into a state the personality does not know. A set lasts until the unit reboots. To keep it, set the same value in your declaration with nxs tune:
nxs tune --set unit-cam0-a:accel_fs=8set unit-cam0-a:unit-cam0-a/fxos8700:accel_fs = 8saved (backup suite.yaml.bak-20261007-101500)IN TUNE ✓The first line names the knob it set: your unit, the section of its personality and the parameter. nxs tune offers only the values the personality declares, as set does. It saved suite.yaml and kept the previous file beside it as the backup. IN TUNE means the saved file holds on your hardware. The Click’s node, click-unit-cam0-a, now carries accel_fs: 8 under its parameters.
Run nxs switch. It uploads the personality again with the declared value and saves it in the unit’s store, so the unit boots with it. From then on the file is the record. nxs status reports the drift whenever the file and the unit differ, and the next nxs switch repairs it.
Next steps
Section titled “Next steps”- To bring up two cameras and two sensors on the same Hub in one dashboard, continue with Multi-sensor dashboard on ROS 2.
- To run the same steps from a chat with an AI agent, see Getting started with an AI agent.