Skip to content

feat(camera): add the FLIR Boson+ driver and JAJ overlays - #163

Merged
AlexKlimaj merged 6 commits into
mainfrom
AlexKlimaj/boson-adapter
Nov 19, 2026
Merged

AlexKlimaj merged 6 commits into
mainfrom
AlexKlimaj/boson-adapter

Conversation

@AlexKlimaj

@AlexKlimaj AlexKlimaj commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds nv_boson, a V4L2 driver for MIPI-model FLIR Boson+ thermal cameras, and one jetson-io overlay per JAJ and PAB CSI port for the ARK Boson Adapter. Both modes (colourised UYVY and pre-AGC RAW14) stream 640x512 at 60 fps on JAJ CAM1 and CAM0 and on all four PAB ports. CAM0 needs a longer NVCSI THS-settle than NVCSI computes; see JAJ CAM0. This is also the bring-up record for the Boson Adapter Rev 1.0, which has two wiring problems listed below.

Problem

The ARK Boson Adapter (Rev 1.0) puts a Boson+ on a carrier's 22-pin CSI connector, but nothing on the Jetson could configure the Boson or receive its MIPI video. A factory Boson+ powers up with CMOS output and MIPI off, so its CSI lanes stay idle until something switches it over.

Solution

Driver. nv_boson is a tegracam driver under kernel_overlay/, registered in build.sh next to nv_imx708 and nv_ov64b40.

  • Control over the CSI port's I2C. The Boson answers FLIR's command protocol on the camera bus at 0x6a, framed as 8E A1, a big-endian u16 length, then sequence, function id, status and arguments, with no CRC. Function ids and enums come from FLIR's Boson SDK (FunctionCodes.h, EnumTypes.h). Videology's MIT-licensed flir_boson_kernel_module showed the framing and the MIPI start sequence. The probe reads the serial number, part number and software version, and fails if the Boson does not answer.
  • Modes. Both are the same size, so mode 1 is selected with the sensor_mode control.
Mode Size fps V4L2 format Boson DVO type / format / MIPI mux
0 640x512 60 UYVY COLOR / YCbCr / COLOR
1 640x512 60 RG14 MONO14 / IR16 / MONO16
  • RAW14. The VI has no 14-bit mono format, so mode 1 is RAW14 Bayer. Samples sit in the top 14 bits of each 16-bit word, with the top two bits copied into the bottom two. The MIPI mux takes MONO16 for this mode; MONO14 fails with FLR_BAD_OUT_TYPE.
  • Embedded data. The MIPI embedded-data tag is on from the factory, even with telemetry off. Its embedded line made the VI discard every frame with EMBED_INFRINGE (err_data bit 14). The driver turns off telemetry and the tag at stream start.
  • Busy Boson. DVO_SETMIPISTATE ACTIVE takes about 300 ms. During it, the Boson holds SCL until the Tegra controller times the read out, and that read still takes the reply's 0x8e. The I2C layer treats a NAK or timeout as busy, accepts a bare 0xa1 as the start of a reply (as FLIR's own I2C transport does), and confirms ACTIVE by reading the MIPI state back. All configuration commands answer within 10 ms while MIPI is off.
  • Clock mode from the overlay. The driver sets the Boson's MIPI clock lane from the mode's discontinuous_clk, so an overlay can pick continuous or gated. Both JAJ overlays use continuous; gated also streams on CAM0.
  • Volatile only. Nothing is saved to the Boson's flash, so a power cycle brings back its own settings. Palette, FFC and sync mode are left alone.
  • No reset, clock or regulator. The adapter wires none of them, and the Boson runs from the connector's 3.3 V.

Overlays. tegra234-camera-boson.dtsi holds the VI/NVCSI graph, tegra-camera-platform, the mode macro and the sync pad. tegra234-camera-boson-sensor.dtsi holds the sensor node, and each per-port .dts wires the I2C mux and sets the port's lane polarity, clock mode and THS-settle.

Carrier Port Overlay name CSI Status
JAJ CAM1 (J25) Camera FLIR Boson+ CAM1 CSI2, x2, polarity 0, continuous clock, NVCSI's own settle Bench-tested
JAJ CAM0 (J28) Camera FLIR Boson+ CAM0 CSI1, x2, polarity 6, continuous clock, cil_settletime = "150" Bench-tested
PAB CAM0 (J28) Camera FLIR Boson+ CAM0 CSI0, x2, polarity 6, continuous clock, cil_settletime = "150" Bench-tested
PAB CAM1 (J25) Camera FLIR Boson+ CAM1 CSI1, x2, polarity 6, continuous clock, cil_settletime = "150" Bench-tested
PAB CAM2 (J29) Camera FLIR Boson+ CAM2 CSI2, x2, polarity 0, continuous clock, NVCSI's own settle Bench-tested
PAB CAM3 (J27) Camera FLIR Boson+ CAM3 CSI3, x2, polarity 0, continuous clock, NVCSI's own settle Bench-tested

The PAB overlays put the Boson on the port's TCA9546 channel, laid out like the PAB Hadron overlays. PAB's connectors are 15-pin, so the adapter goes through a 22-to-15-pin FFC adapter.

The adapter routes the port's CAMn_MCLK net to Boson pin 72 EXT_SYNC through R12. As in the Hadron overlays, each overlay makes that pad a pulled-down input in the exp-header-pinmux state, so it does not fight the Boson.

Docs. docs/boson.md covers the overlays, modes, capture commands, wiring, settle time, frame sync and hardware notes. docs/cameras.md and the README index link to it.

Bench

JAJ, Orin Nano 4GB, R36.5 image from b697c62, Boson+ 640 22640A095-6IAAX (SN 427619, software 4.1.27660), on CAM1 and then on CAM0. The module was built on the target against the image's headers, and the overlay with cpp + dtc. The same recipe reproduces the installed Hadron CAM1 .dtbo byte for byte. I did not run a full ./build.sh.

  • Capture, CAM1: both modes run at 60.00 fps (v4l2-ctl, 300 frames per run) with no NVCSI/VI errors. Five runs alternating UYVY, RAW14, UYVY, RAW14 and UYVY each start cleanly, so mode switches and start/stop both work.
  • Capture, CAM0: at 5d715f0, after a reboot onto the CAM0 overlay, four alternating 300-frame runs and an 1800-frame UYVY run all ran at 60.00 fps with nothing in dmesg, from a Boson power-cycled back to its factory settings.
  • Image: UYVY and RAW14 frames both show a real thermal scene. RAW14 counts sit at about 5,700–6,400.
  • Streaming: v4l2src into software x264enc (the Orin Nano has no hardware encoder) over RTP to the host on the USB network ran for 8,400 frames at 60 fps with none dropped. Encoding uses about 80% of one core.
  • Palette: switching the Boson to Ironbow over its UART while streaming changed the picture with no interruption.

PAB

PAB, Orin Nano 8GB, image from a local ./build.sh PAB of e7d1f0f, same Boson+ (SN 427619). The PAB overlays were built on the host with cpp + the staged tree's dtc, which reproduces the image's Hadron CAM3 .dtbo byte for byte, and copied to /boot. J3's I2C went to a PAB I2C connector (IMU on i2c-1). The PAB has no spare UART for J3, so the sync checks made the Boson sync master with the same FLIR command over the camera I2C (I2C_SLAVE_FORCE on 0x6a, nothing streaming).

Check CAM0 CAM1 CAM2 CAM3
Probe boson 9-006a boson 10-006a boson 11-006a boson 12-006a
UYVY, 600 frames 60.00 fps 60.00 fps 60.00 fps 60.00 fps
RAW14, 600 frames 60.00 fps 60.00 fps 60.00 fps 60.00 fps
IMU WHO_AM_I 0xe9 0xe9 0xe9 0xe9
Sync pad, sync off / master PP.00 0 / 59.89 Hz PP.01 0 / 60.01 Hz PQ.05 0 / 60.18 Hz PQ.06 0 / 60.08 Hz
IMU FSYNC tags 59.60 Hz 59.46 Hz 59.55 Hz 59.49 Hz

No run had a gap or an error frame, and a frame of each mode on each port shows a clean scene. CAM0 and CAM1 were not tried with NVCSI's own settle.

Original Boson (not supported)

An original Boson 640 does not work with this driver or adapter, because it has no MIPI output. The bench tried one on PAB CAM0 after the Boson+ runs: part number 20640AS32-6PARX, software 3.0.25868, SN 227597, sensor 500-0773.

  • I2C: it does not answer on the camera bus at 0x6a, on any mux channel, even after a power cycle. The probe fails with no Boson answering at 0x6a (-121), and the Pi driver on the Just A Pi logs the same.
  • UART: it does answer over the adapter's UART, through J3 on the Just A Pi's UART2 at 921600. There it reports the part number and software version above. DVO_GETOUTPUTINTERFACE returns 0x161 (R_CAM_DSPCH_BAD_CMD_ID), and DVO_GETMIPISTATE, DVO_GETMIPISTARTSTATE and DVO_GETMIPICLOCKLANEMODE return 0x1B0 (R_CAM_FEATURE_NOT_ENABLED).

The adapter leaves the Boson's USB unconnected on purpose, to save space, so MIPI is its only video path. It therefore needs a Boson+ with the MIPI option, whose part numbers start with 22640 and run 4.x software. An original Boson's part number starts with 20640 and its software is 3.x. The same adapter, port and overlay streamed the Boson+ just before, and the adapter's UART path worked with the original Boson.

JAJ CAM0

On JAJ CAM0 the Boson probed on mux channel 0 (boson 10-006a) and took its whole configuration, but no frame completed. The VI caught the Boson's frame start in only a few percent of frames (corr_err ... frame <n>, err_data 131072, a forced frame end), and with a continuous clock it decoded none. A second cable behaved the same, and the JAJ routes CSI1 straight to J28.

NVCSI reads lane_polarity and cil_settletime from the driver's parsed mode properties at every stream start, so an experimental build (not in this PR) that overrode them on load swept both without a reboot each, at 60 frames per point:

Setting Result on CAM0
lane_polarity 0–15 Frame starts decode only with bit 2 set and bit 3 clear (4–7): per-brick bits, CSI1_D0 inverted, so "6" is right
cil_settletime 0 (NVCSI's own), 1–68 No frames
cil_settletime 72–230 60/60 frames, no errors
cil_settletime 255 No frames

At 150, both clock modes then ran 1200 UYVY, 600 RAW14, 600 UYVY and 600 RAW14 frames at 60.00 fps with no errors. NVCSI's own THS-settle, computed from the mode's 246 MHz MIPI clock, is too short on CSI1 for the Boson's bursts, though it works on CSI2. The CAM0 overlay sets cil_settletime = "150", the middle of the window. CAM1 keeps NVCSI's own value, which it was tested with; 150 has not been tried on CAM1.

Adapter Rev 1.0 findings

Interface Result
Boson USB Not connected, on purpose, to save space. Video goes over MIPI only
3V3 from CSI pin 22, 1V8 LDO OK
MIPI lanes and clock (J1 34–37, 42/44) OK, 60 fps both modes
Boson I2C (J1 63/67 to J2) via TXS0104E OK, 0x6a on the CAM1 mux channel
ICM-45686 on J3 I2C via TXS0104E OK: 0x68, WHO_AM_I 0xe9, about 1.00 g at rest
EXT_SYNC (J1 72) to the MCLK pin via R12 OK: with the Boson as sync master, 60.0–60.2 pulses/s on PP.01 (CAM1) and PP.00 (CAM0)
EXT_SYNC to the IMU's FSYNC via R13 Unfitted on Rev 1.0. With R13 fitted on the bench unit, the IMU tags 59.6–59.8 samples/s
Boson UART (J1 33/43 to J3) via LSF0102 Swapped: works only with J3 pins 2/3 crossed
J3 pinout against JAJ connectors Mismatch, see below
  • UART swap. FLIR's datasheet gives pin 33 as uart_apb_sin (the Boson's input) and pin 43 as uart_apb_sout (its output). The adapter labels 33 UART_TX_BOSON and 43 UART_RX_BOSON, so a 1:1 J3 cable joins the host TX to the Boson's TX. The fix for the next revision is to swap the two nets at J1 and leave R7 and R8 on their nets: R7 (604 Ω to 1V8, on U4 A2) then pulls up uart_apb_sin, where FLIR asks for a pull-up, and R8 (604 Ω to 3V3, on U4 B1) pulls up the Boson's TX on the 3.3 V side, which the LSF needs to translate a high up. The Rev 1.0 workaround, crossing J3 pins 2 and 3, leaves the Boson's TX with no 3.3 V pull-up of its own; it works on the JAJ only because the JAJ pulls up its RX line.
  • J3 on the JAJ. J3 matches the JAJ's UART2/I2C0 connector 1:1, but JAJ UART2 is module pins 236/238. Those are the Tegra debug UART (UARTC, pads uart3_*_pcc5/6), which the TCU console (ttyTCU0) owns at a fixed 115200. On UART0 or UART1, J3's I2C lands on CTS (SCL) and RTS (SDA). The IMU answered there over bit-banged I2C after setting both pads to drive and read: 0x2430090 and 0x2430098 = 0x440, runtime only. The video does not need J3 at all, since the driver controls the Boson over the CSI port's I2C.
  • The other J1 pins match FLIR: EXT_SYNC on 72, and the pin 58 pull-up FLIR recommends.

Not in this PR

  • No PAB_V3 overlays.
  • No i2c-gpio overlay for the IMU on UART1 RTS/CTS.
  • ARK's gitbook JAJ "Connections" page lists UART2 as /dev/ttyTHS2. It is the debug console (ttyTCU0), and ttyTHS2 is UARTE. That needs a separate docs fix.

🤖 Generated with Claude Code

A MIPI Boson+ reaches a carrier's CSI port through the ARK Boson
Adapter: 640x512 at 60 Hz on two D-PHY lanes with a continuous 246 MHz
clock, and FLIR's command protocol on I2C at 0x6a. Add nv_boson, a
tegracam driver that sets the Boson up over that I2C, and one jetson-io
overlay per JAJ CSI port.

The driver offers two 640x512 modes at 60 fps: post-colorize UYVY and
pre-AGC 14-bit, which the VI takes as RAW14 Bayer since it has no 14-bit
mono format. Mode 1 needs the sensor_mode control, as both are the same
size. At stream start it switches the Boson to MIPI, sets the mode's DVO
type, output format and MIPI mux, and turns off telemetry and the MIPI
embedded-data tag: the tag is on from the factory and its embedded line
makes the VI discard every frame (EMBED_INFRINGE). Nothing is saved to
the Boson's flash.

Starting MIPI keeps the Boson busy for about 300 ms. It holds SCL until
the Tegra controller times the read out, and that read still takes the
reply's 0x8e. The I2C layer treats NAKs and timeouts as busy, accepts a
bare 0xa1 as a reply start, as FLIR's own I2C transport does, and checks
MIPI ACTIVE by reading the state back.

The adapter routes the port's MCLK net to Boson EXT_SYNC through R12, so
each overlay makes that pad a pulled-down input, as the Hadron overlays
do. CAM1 is bench-tested on a JAJ; CAM0 is not.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 14, 2026 01:21

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Hardware-aware human review is needed because CAM0 is untested, the full JAJ build was not run, and normal PR CI does not compile the new overlays.

No open issues 🎉

What changed in this PR

Adds FLIR Boson+ thermal-camera support through the ARK Boson Adapter, integrating a new driver and JAJ camera overlays into the existing kernel build.

Changes:

  • Adds an I2C-controlled nv_boson driver for 640×512 at 60 fps in colourised UYVY and pre-AGC RAW14 modes.
  • Adds per-port JAJ overlays with shared camera graph, mode definitions and sync-pin configuration. CAM1 is bench-tested; CAM0 remains untested.
  • Documents capture commands, mode selection and adapter wiring limitations.
File Description
README.md Links to the Boson documentation.
products/​JAJ/​overlay/​tegra234-p3767-camera-p3768-boson-cam1.dts Configures Boson wiring for JAJ CAM1.
products/​JAJ/​overlay/​tegra234-p3767-camera-p3768-boson-cam0.dts Configures Boson wiring for JAJ CAM0.
products/​JAJ/​overlay/​tegra234-camera-boson.dtsi Defines shared capture graph, mode properties and sync pinmux.
products/​JAJ/​overlay/​tegra234-camera-boson-sensor.dtsi Defines the sensor node and both capture modes.
products/​JAJ/​overlay/​dtbo.list Registers both Boson overlays for the JAJ build.
kernel_overlay/​nvidia-oot/​drivers/​media/​i2c/​nv_boson.c Implements identification, command transport, mode setup and streaming.
docs/​cameras.md Adds Boson to the supported-camera list.
docs/​boson.md Documents setup, capture, validation status and hardware caveats.
build.sh Registers nv_boson alongside existing sensor modules.

Review effort: Balanced

AlexKlimaj and others added 3 commits November 13, 2026 18:54
The driver hard-coded a continuous MIPI clock. It now sets the Boson's
clock lane from the mode's discontinuous_clk, and each port's overlay
picks it: CAM1 stays continuous, as it was bench-tested, and CAM0 is
gated, like the IMX219, IMX477 and Hadron overlays on that port.

CAM0 does not stream yet. The Boson probes on the CAM0 mux channel and
takes its configuration, but the VI receives almost no valid packets.
With a continuous clock no frame start is recognised. With a gated clock
on both ends the Boson's frame numbers decode for a few percent of
frames, so lane mapping and polarity are right, and every frame still
ends in a forced frame end. Two cables behaved the same, the port
settings match the overlays that work there, and the board routes CSI1
straight to J28. docs/boson.md records this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On JAJ CAM0 (CSI1) the Boson probed and took its configuration, but no
frame completed: the VI caught the Boson's frame start in only a few
percent of frames. NVCSI's own THS-settle, which it computes from the
mode's 246 MHz MIPI clock, is too short there for the Boson's bursts.

An experimental build that overrode the parsed mode properties at load
time swept both settings without a reboot each. Only lane polarities
with bit 2 set and bit 3 clear decoded frame starts, which confirms "6".
With cil_settletime from 72 to 230, both modes streamed cleanly with
either clock mode; at 0 (automatic), 68 or less, and 255 they did not.

Make cil_settletime a per-port overlay setting. CAM0 uses 150, the
middle of the window, and goes back to a continuous clock like CAM1;
CAM1 keeps NVCSI's own value, which it was tested with. With the repo
driver and the new CAM0 overlay, both modes run at 60.00 fps with no
VI errors over alternating runs and an 1800-frame run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The hardware notes said R13 would route EXT_SYNC to the IMU's FSYNC
"instead". R12 and R13 both hang off the same node, so with R13 fitted
the Boson, the port's MCLK pad and the IMU's FSYNC share one net. Rev 1.0
leaves R13 unfitted; the bench unit now has it.

A Frame sync section, as hadron.md has, records what the bench measured
with the adapter on JAJ CAM1: the Boson as sync master over its UART puts
60.0-60.2 pulses per second on PP.01 (none with sync off), and the
ICM-45686 tags 59.6-59.8 samples per second through R13. With the ribbon
in the port whose overlay is not applied, that port's MCLK pad stays a
driven output and holds the net.

The Rev 1.0 UART note now gives the fix: swap the two nets at J1 and
leave R7 and R8 where they are.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The four PAB overlays put the Boson on the port's TCA9546 channel, as the
PAB Hadron overlays do, and make the port's MCLK pad the sync input.
CAM0 and CAM1 set THS-settle 150, the value JAJ CAM0 (CSI1) needed;
CAM2 and CAM3 keep NVCSI's own.

Bench-tested on a PAB with an Orin Nano 8GB on all four ports: UYVY
and RAW14 at 60 fps with no gaps, the IMU, and the Boson's sync pulses
at the MCLK pad and at the IMU's FSYNC, with the Boson made sync master
over the camera I2C.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dakejahl

Copy link
Copy Markdown
Collaborator

Claude review on behalf of @dakejahl

Merge after fixes. The driver and overlays look sound and are bench-tested on every port they ship for. Only the camera table and the PR title still describe the JAJ-only version of this PR.

Must fix

  • docs/cameras.md:13 still says "one per CSI port (JAJ)" and "Working on JAJ CAM0 and CAM1", although this PR adds all four PAB overlays and tested them. Make it "one per CSI port" and "Working", as the Hadron row has it.
  • The PR title becomes the squash commit subject, and it says "JAJ overlays" though the PR also adds the PAB ones. Something like feat(camera): add the FLIR Boson+ driver and per-port overlays would match feat(camera): add the FLIR Hadron EO driver and per-port overlays #149.

Optional

  • nv_boson.c:458 turns MIPI off a second time after DVO_SETOUTPUTINTERFACE with no comment. Is that because setting the interface to MIPI starts it? If so, a one-line comment would stop someone from deleting it. If not, one of the two calls can go.
  • products/PAB/overlay/tegra234-p3767-camera-p3768-boson-cam0.dts:20 explains the 150 setting with the CSI1 result, but this port is CSI0. It could say that CSI0 shares CSI1's brick and that NVCSI's own value was not tried there. The "and so does PAB CAM0" sentence in docs/boson.md needs the same reason.
  • nv_boson.c:431 is missing a space after clock =. Line 8 of tegra234-camera-boson.dtsi and its mode comment at lines 44–47 have broken line wrapping.
  • The "Current contents" list in kernel_overlay/README.md doesn't mention nv_boson.c yet.
  • The I2C and busy-Boson bullets at docs/boson.md:74-75 describe driver internals a user can't act on, and the driver's header comment already covers them. They could be cut.

…son+ with MIPI

The adapter leaves the Boson's USB unconnected on purpose, to save
space, so MIPI is its only video path. An original Boson (part number
20640 or 20320, 3.x software) has no MIPI output; the one tried on the
bench did not answer on the camera I2C at 0x6a.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AlexKlimaj
AlexKlimaj merged commit 94ef16d into main Nov 19, 2026
1 check passed
@AlexKlimaj
AlexKlimaj deleted the AlexKlimaj/boson-adapter branch November 19, 2026 00:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants