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

NXS — MCP Tool Reference

Applies to: NXS SDK 1.1.x · nxs mcp · the mcp extra · Model Context Protocol (stdio)

Document set
Glossaryone word for each thing
Technical Specificationscapability summary tables
Device Referenceinterfaces, performance and limits, shipped personalities, versioning
Interface Descriptiontransports, register map, commands, procedures
Integration & Operation Manualdesign-in, host setup, workflows
Click Personality Referenceauthoring personalities for unsupported sensors
Cam Personality Referencedescribing camera chains for the camera ports
MCP Tool Reference (this document)operating and configuring through an AI agent

nxs mcp serves the nxs verbs to an AI agent as tools. The agent calls on, capture, set, status. Each tool runs the same command line an operator types. The agent gets the same words, the same refusals, the same laws.

The machine’s declaration is suite.yaml. It has three doors:

DoorWhoHow values are chosen
The filean engineer with an editortyped, and the shipped JSON Schema flags shape errors in the editor
nxs tunean operator at the terminalpicked from offered options only
nxs mcpan agentpicked from offered options only (suite_get, suite_set)

All three are judged by the same findings, the ones a bare nxs status prints under declaration:. switch converges the units to the file, and nxsd the ports. A value the hardware cannot do is refused on every door. The refusal names the lawful values. Nothing is clamped silently.

MCP operates the hardware as well as the declaration. nxs tune reaches the hardware too: --play signals nxsd, and i in the panel strobes a unit’s LED. on writes registers, and power-dips a port’s camera heads when a link does not lock.

The agent must read before it writes. caps says what a sensor offers. status without a port says whether the declaration is lawful and which declared nodes answer. status with a port says what the hardware is doing now.

The server runs on the machine that owns the buses. An agent elsewhere reaches it over ssh.

The agent loop: the agent on a workstation reaches nxs mcp over ssh, and its tools read the rig, operate the hardware and write the declaration under the laws

On the Jetson (or any host with the buses):

Terminal window
orin$ pipx inject aliensense-nxs 'aliensense-nxs[mcp]'
orin$ nxs mcp --doc-table

The second command prints the Tools table of §3 and exits. It proves the extra is installed. Without it, nxs mcp says so and exits.

Claude Code on a workstation, reaching the Jetson over ssh (key-based login, the Jetson user in the i2c and video groups). An ssh command runs no login profile, so name the user install’s executable by its path, quoted so the Jetson expands $HOME, not the workstation:

Terminal window
host$ claude mcp add nxs -- ssh <user>@<jetson> '$HOME/.local/bin/nxs' mcp

Claude Desktop, in its MCP configuration file:

{
"mcpServers": {
"nxs": {"command": "ssh", "args": ["<user>@<jetson>", "$HOME/.local/bin/nxs", "mcp"]}
}
}

An agent on the Jetson itself uses "command": "nxs", "args": ["mcp"].

Smoke test from the client: list the tools. 20 names appear, in the order of §3. Then call status with no port. Its declaration carries in_tune: true or the findings, and each declared node its presence. The buses are read and nothing is written.

ToolPurposeArgumentsHardware effectRefuses when
probethe units that answer, on every bus or a port’sport?, link?none (reads identity registers)no ACK rows, or an unknown port, which lists the ports
generatethe rig as it answers: ports, hubs, links, sensors, unitsdry_run?walks every camera port and bus. With dry_run false it writes hardware.yaml, the report of what answered, and seeds suite.yaml when there is none. It writes a declaration of api 2 or the 1.0 form again in api 3, the earlier file kept beside it. A unit on a bare bus running nothing is named by trying every personality on itno hub and no camera port, or the wiring file is not writable
statusthe declaration against the rig, or a port’s presence and healthport?, link?none (reads identity and status registers)hub does not answer
identifystrobe a unit’s LED to find the boxunit?the unit’s LED strobes ~10 sunit does not answer
samplesread decoded samples from a unitunit?, count?reads the sample window. Over Cyphal it sets the output decimation for the read and puts the previous value backno personality measuring, or the unit does not answer
capswhat the sensor offers, with the lawsport, link?none (reads facts)no hub serves the port, or nothing installed describes its sensor
onbring a link or the whole port upport, link?, sensor?, mode?, fps?, dry_run?writes the program, trains links, follows video lock, counts two seconds of frames on every camera linkthe laws refuse the mode or rate, the hub does not answer, video did not lock, or the links do not deliver the rate
offpark the whole portportbare heads to standby, CSI gate closed, viewers stopped, each pod’s head parked by its unitkernel-owned hub
captureheadless delivery proofport, link, frames?, timeout_s?opens a capture session on the up link, the tool’s viewer on it stopped firstthe link is not up, or the frames were not delivered
getread a knob: the port’s sync, the sensor’s, the unit’sport, link, knobnone (reads a row of the map, a bare head’s registers or the unit’s parameter)unknown knob lists the knobs
setchange a knob under the laws, sync being the port’s frame syncport, link?, knob, value, dry_run?, fps?, exposure_us?a row’s commit on a pod’s or smart camera’s map, a bare head’s registers, or the link’s unit for its personality’s parameter. Sync starts or stops the hub’s generator, and a sync or fps change counts two seconds of framesan unlawful value, with the lawful alternatives. A sync or rate the links do not deliver, the previous one restored. A live sibling link, for a bare head’s camera knob. The port is not up
suite_getthe declaration as options—noneno camera port on the host and no declaration
suite_schemaeach node’s rows on this rig as JSON Schema—nonethe declaration does not parse
suite_setset declared values from their options, one or a batchchannel?, field?, value?, section?, sets?writes suite.yaml once (a timestamped backup, created when absent)a value not among the options, a field that repeats without its section, or a knob a set moved that the batch does not name
switchapply the saved declaration to the unitsdry_run?, accept_new_serial?retunes or re-uploads the personality on units whose entry differsthe declaration is out of tune, or a declared unit does not answer
reloadapply the saved declaration to the ports—nxsd reconverges changed portsthe declaration is out of tune, or nxsd is not running
freezeadopt live tuning into the declaration: the units’, or the camera ports’unit?, ports?, port?, dry_run?writes suite.yamlunit unreachable, or a port no host bus answers to
uploadcompile and upload a personality to a unit (or compile only)name, port?, link?, unit?, params?, slot?, compile_only?a click personality runs, and a cam personality lands in a store slotan unknown name, a source that does not compile, a full store, or several units that answer with none named
host_infothe capture host and what it booted—none (reads the device tree and boot config)never
host_modesthe booted capture table of a portportnone (reads the device tree)an unknown port, or a silent device tree

Arguments marked ? are optional. fps is the rate set runs the port’s frame sync at (knob: sync, value: fsync). Without it the declared rate applies, else 30 fps. exposure_us is refused with the fact that sets the exposure. Under frame sync that is the trigger pulse’s low time at the rate, in free run the capture stack’s loop.

port is a port name (cam1). link is a link name (A, B). knob names come from caps. channel, section, and field come from suite_get.

On a pod’s link and on a smart camera, a camera knob is a row of the map (Interface Description §4.5). caps lists those rows, set commits a row by its name in the row’s unit, and get reads the row’s value in effect. A value past a range row’s bounds commits at the bound, and the output names the value in effect and the one asked. On a head with no unit that is not a smart camera, set writes the sensor’s registers. A knob the camera does not have goes to the link’s unit as its personality’s parameter.

unit is the name of a unit node in the declaration. When it is omitted, identify and samples address the one unit answering on the host’s camera buses. So a unit can be found and read before it is declared.

Read tools return the same JSON the command line prints with --json: probe, generate, status, samples, caps, suite_get, suite_set, reload. Every such document carries contract: 2, and the SDK’s tests validate every surface against the shipped surface schema. suite_schema returns the rig schema itself, a JSON Schema document with no contract member. Live tools return the verb’s text.

A refused call is a tool error. Its text is the verb’s refusal: the fact on one line, then one line per lawful alternative. A JSON tool’s refusal is the document {"refused": {"fact": …, "alternatives": […]}}, so a program reads the alternatives without parsing a sentence. The agent asks for one of them.

A finding in a status document has the same parts. where is the node path it names, such as nodes.hub-cam0.parameters.sync_source, and text is the sentence the command line prints, beside fact and alternatives. A bare status document also carries the declaration’s graph: each node with its state, present, absent or unknown, and each connection as from and to. The graph definition of the shipped surface schema states its shape.

Each format has one role. The declaration file is YAML, because a person edits it. Every tool result and every --json document is JSON. The contract between them is JSON Schema 2020-12. The shipped suite schema covers the file, the surface schema the results, and the rig schema that suite_schema returns covers one rig. A declaration rendered as JSON loads and validates identically, so an agent may write either.

A declaration carries api: 3, its nodes by name and its connections. A node is a type and its parameters, the rows of its block by name in display form and its identity pins. A connection is keyed by the port that feeds, <node>.<port>, and lists the ports it feeds (Integration & Operation Manual §5.1).

The rig schema is the declaration schema narrowed by the nodes on this rig. Each declared node’s type is a constant. Its parameters admit its identity pins and the rows its block offers at its place in the graph, with the values each takes there. A row the block does not offer there is left out:

  • A hub’s rows follow its frame sync: sync_fps under fsync where the trigger laws leave a rate, and exposure in free run. Its csi_a_lanes takes the lanes the host’s connector takes.
  • A camera’s mode names the modes its program carries, and its fps spans the rates its mode runs free at on its port. Under frame sync it has no fps.
  • A click’s rows are its personality’s, and a host’s are its connectors’ lanes and drivers.
  • A unit’s own rows are integers, judged where the unit answers.

A violation names the key it broke and the values that key admits.

The schema is necessary and not sufficient. It judges names and values one node at a time. The loader holds the connections’ laws. status judges what spans nodes, such as two cameras on one port or the lanes against the hub’s output.

Findings and refusals follow the shape of the Linux kernel’s netlink extended ACK. That ACK carries the message, the offset of the invalid attribute, and the policy for a rejected attribute: here fact, where, and alternatives. suite_schema is the counterpart of netlink’s policy dump, which gives the supported attributes with the ranges of values the kernel accepts (netlink introduction).

Edit the declaration, validate it, apply it.

  1. Call suite_get: every channel, its fields, the values each may take.
  2. Call suite_set with channel: cam1/A, field: fps and value: 25, a rate the knob offers. A batch goes in sets (cam1:HUB=maxim,max96792a, cam1/A:CAM=framos,imx900), applied in order. It writes the declaration once, in api 3 with a timestamped backup, and the result carries the findings.
  3. Call status with no port. It answers declaration.in_tune: true, or findings that name the lawful alternatives, each under the node it concerns.
  4. Call switch: it retunes or re-uploads every declared unit whose personality or settings differ from its entry. It leaves a matching unit alone. Call reload: nxsd reconverges only the ports whose declaration changed. It also reconverges the ports a by-hand on brought up away from theirs.

A stream on an untouched port keeps running. A changed rate, or a mode of another bit depth, moves the port’s boot table. switch then installs the port’s overlay and ends with REBOOT NEEDED, and the port runs the new declaration once the operator reboots. A frame-sync rate is counted on the running port first, and one the links do not deliver is refused before the table.

A field name that exists in two sections of a channel (two personalities on one unit carry sample_rate) is refused. Pass section with the section’s label (imu-a/iam20680). A set that moves another knob (a mode whose rate the laws pull) is refused unless the batch names that knob after it.

A channel with declared: false is a port the platform names, or a unit that answered with no node in the declaration yet. presence says whether a hub or a unit answers on it. Its DECLARE section carries the knobs that write its nodes. A port carries HUB: an installed hub, or connector for a camera wired to the host’s connector. Each of its links (the channel cam1/A) carries CAM and POD. A unit or a pod carries one CLICK knob per click node on its socket, CLICK, then CLICK-2.

suite_set on those knobs declares the nodes and their connections, and creates the declaration when absent. Each block the knobs declare opens its rows section on the next suite_get. That is the port’s hub and host, the link’s camera, a click’s <unit>/<personality> and the unit’s own. A section’s kind is declare for the knobs that write nodes and rows for a block’s rows.

A rows section’s fields are the block’s rows by name. A value is the row’s display form: a name such as fsync, or a number in the row’s unit, 12 for a gain in dB. A row the block does not offer at that point is absent, such as the hub’s sync_fps in free run.

Change values on the hardware, verify, then write what works into the declaration.

  1. Call on with port: cam1, link: A. The link comes up. The result reads video locked, and the delivery check that counted two seconds of its frames, cam1: verified 30.0 fps (A 30.0).
  2. Call set with knob: exposure, value: 8ms, applied under the sensor’s laws.
  3. Call capture with frames: 1700: sixty seconds of frames must arrive. on counted two seconds of frames, and this count proves the stream holds for a minute. A locked link proves nothing.
  4. Call freeze: the units’ live parameters become their click nodes’ parameters. It leaves a camera’s exposure alone. In free run the capture stack’s loop sets it, unless the hub node declares exposure with gain.

capture opens a headless Argus session with the CSI-gate choreography the viewers use. Four frames prove the path. 1700 frames (~60 s) is the steadiness oracle. The result names delivered frames against requested ones.

on, set sync and set fps count two seconds of frames on the links they change. status with the port carries the last count that passed as verified. On a frame-synced pair ae names who decides the gain. When nxsd copies no gain for a followed pair (ae.mode: follow, ae.following: false), status fails. The tool error carries the document, and sudo systemctl restart nxsd brings the follower back.

After a pulled cable or a head holding stale state the video does not lock. on recovers once by itself: it power-dips the heads on that port, resets and retrains them, then follows video lock again. A running stream on the sibling link stops. When on still ends with video did not lock, check the cabling and call on again.

  1. Call host_modes with port: cam1: the booted capture table. The capture stack cannot capture a sensor mode missing here yet.
  2. Call switch to realize the declaration. When the booted table lacks a declared mode, it generates the port’s overlay. The sources are the hub directory and the installed cam personalities, and the overlay goes under the aliensense_gen boot label. The result ends with REBOOT NEEDED, and nothing reboots. The operator reboots.
  3. Call on with port: cam1, link: A, sensor: imx335: the link with that sensor. The port remembers the sensor, and later calls omit it. on stops with REBOOT NEEDED when the booted table lacks the mode and has installed the overlays itself.
  4. Call capture with port: cam1, link: A, frames: 60 to prove delivery at the declared rate through the capture stack. status is the verdict, declared against actual.

4.6 Validate a declaration before writing it

Section titled “4.6 Validate a declaration before writing it”

A whole declaration, written by an agent or pushed from a fleet server, is checked against the rig’s own rules before it reaches the file.

  1. Call suite_schema: the rig’s rules as JSON Schema (§3.1).
  2. Check the declaration against it locally, with any JSON Schema 2020-12 validator. A violation names the key and the values it admits. Take one of them.
  3. Call suite_set with the knobs in sets, saved once, or write the file for a whole declaration.
  4. Call status with no port: the findings the schema cannot see, each with where, fact, and alternatives. declaration.in_tune: true is the pass.
  5. Call switch for the units, reload for the ports.

The schema stops a wrong name or an out-of-range value before anything is written. It approves no arithmetic across nodes, so step 4 is never skipped.

  1. Call generate with dry_run: true, the default. It lists every camera port with the nodes that answered on it (the hub, each link’s serializer, sensor, and unit). After the ports come the units on the bare buses. It writes nothing. Over a declaration of an earlier language, the 1.0 form or api 2, the dry run refuses and names nxs generate.
  2. Read unanswered. A port carries it when the wiring or the platform names a hub and nothing answers at its address. That hub stays out of hardware.yaml. With its power and cabling checked, call generate again.
  3. Call generate with dry_run: false. It writes hardware.yaml from the walk, a report that no verb reads, and seeds suite.yaml when there is none. It writes an earlier declaration again in api 3, the earlier file kept as suite.yaml.1.0 or suite.yaml.api2. It names a unit on a bare bus running nothing by trying every personality on it. hardware, seeded, kept and migrated in the result say what it wrote. undeclared lists the ports where a Hub, head or unit answered and a kept declaration does not name.
  4. Call status with no port: the declaration against what answered.

A declared hub that does not answer is a finding in step 4: cam1: the hub does not answer at 0x6a, with the power and cabling check as the alternative. A type nothing installed describes is refused when the declaration loads, with nxs describe <type> and nxs personality install <directory> among the alternatives.

  • Refusals are results. on with fps: 500 answers link A: 500 fps is outside 1920x1080 RAW10's 1.50–160.49 fps (the datasheet frame law's range with 1 camera on 2 CSI lanes) and names the whole rates at the ends, fps 160 and fps 2, as its alternatives. The agent asks for a rate inside the range. Retrying 500 gets the same answer. A rate inside the range that the rig does not deliver is refused the same way, after on or set counts two seconds of frames. The answer is cam0: 60 fps asked, 58.1 delivered on A, 57.9 on B, naming the whole rate at or under the lowest.
  • Register-level access does not exist. No tool writes a named register. Every write goes through a declared knob or a captured program.
  • Live siblings are protected. On a bare head set on one link refuses while the other link streams, because isolating a link’s control window would drop the sibling’s video. Park first (off), or set before on. A pod’s or a smart camera’s knob commits on its camera door and selects no window, so the other link keeps streaming. A unit’s parameter (a Click’s rate) is no camera knob: set writes it to the link’s unit and parks nothing.
  • on’s recovery is destructive on purpose. When video does not lock it power-dips every head on the port. Nothing else does.
  • A hub this host does not run is read-only. With the host’s row <connector>_driver: kernel, on, off and set refuse, and status answers from directly readable registers. On a passive host, where a module owns the Hub, they refuse the same way.
  • A hub change keeps the cameras. Every hub offers every installed cam personality, so a port whose hub changes keeps its camera nodes. A sensor no installed cam personality describes is not among the options. A sensor set on a port with no hub is refused with set cam1:HUB first, in the same --set batch or before. sets carries both in one call, the hub first: cam1:HUB=…, then cam1/A:CAM=….
  • The declaration is optional. Ports resolve from the platform (udev aliases, the mux channel ids). reload and freeze need a declaration, and switch without one runs the host’s steps alone. On a host that boots no camera bus it installs the boot table that starts them and ends REBOOT NEEDED, else it names nxs generate. suite_get lists the platform’s ports and what answered without one, suite_set declares into one, and the live tools never read it.
  • An earlier declaration is refused. Every tool that reads the declaration refuses one of the 1.0 form or api 2 and names nxs generate. generate with dry_run: false writes it again in api 3 and keeps the earlier file beside it, suite.yaml.1.0 or suite.yaml.api2.
  • switch writes /boot. On a host that boots no camera bus it writes the camera kernel package’s multiplexer overlay into one boot label (aliensense_gen). When the booted table lacks a declared mode, or its rows miss the declared rate and bit depth, the generated overlay goes in too. It copies that overlay into /boot/camera-dtbos, adds it to the same label and backs up extlinux.conf. The operator’s own labels are untouched, and nothing reboots.
  • Time. on takes seconds to a minute (training). capture with 1700 frames takes about a minute. on with a recovery takes up to several minutes. The server applies a timeout per tool and reports it as a refusal.
SymptomCauseAction
nxs mcp needs: pipx inject aliensense-nxs 'aliensense-nxs[mcp]'the mcp package is not installedrun the line the message names. In an environment pip made, it names pip install 'aliensense-nxs[mcp]'
on answers REBOOT NEEDEDthe booted capture table lacks the sensor mode, and switch regenerated and installed the overlayreboot the Jetson, then call on again
on answers <port>/<link>: … boots on no row of this port's table (…)the mode is of another pixel format than the port’s declaration runs, so its table carries no row for itdeclare the mode on every camera node of the port (nodes.<camera>.parameters.mode) and call switch, or call on with a mode the answer names
on answers MISMATCH: declared …, answers as …another sensor sits behind the linkcall on with the detected sensor, or fix the camera node’s type
the client lists no tools, or Connection closed at initializethe server did not start: ssh asked for a password, or the client launched ssh with a minimal environment that hides the key agent (SSH_AUTH_SOCK)run the ssh command by hand. Use the dedicated key the deploy guide restricts to the server, named by IdentityFile in ~/.ssh/config, or hand the agent through in the client’s env. Claude Desktop passes no agent socket
hub … does not answerdeserializer unpowered, wrong bus, wrong module SKU in the boot configprobe without a port, and DEPLOY.md §2 of the camera kernel package
capture fails, Failed to create CaptureSessionnvargus-daemon wedged by an earlier raw sessionsudo systemctl restart nvargus-daemon, and capture restarts it once by itself
video did not lock after ona head holding stale stateon recovers once by itself. Check the cabling, then on again (§4.4)
suite_set refuses ambiguoustwo sections of the channel carry the fieldpass section
suite_set refuses … — name the knob in the same --set batcha set moved a dependent knob (a mode change pulled the rate)add the moved knob to sets after the set that moved it
a tool refuses <path>: declares the 1.0 form (ports and units), and this nxs reads api 3, or <path>.api: 2, an earlier declaration language, and this nxs reads api 3the declaration is in an earlier languagecall generate with dry_run: false: it writes the declaration again in api 3 and keeps the earlier file beside it
reload answers played: falsenxsd is not running, or the declaration is out of tunestatus with no port, and start nxsd
nxs cam1 A stream shows nothing for the agentviewers need a displayagents use capture, and viewers are for a person at the screen