Use The Raspberry Pi AI Camera¶
The Raspberry Pi AI Camera is a visible-light camera built around Sony's IMX500 sensor. Sensoraia can use it for ordinary photographs, compatible vehicle detection or experimental visual return. Choose one profile at a time.
AI Camera terms | Spottercam | LOOMcam
Connect The Hardware¶
Power off before connecting or removing the ribbon cable. Use the cable matching the board's connector; the Pi Zero family needs the smaller Zero-compatible connection. Seat the cable squarely and close the latch. Check your board's camera/display connector documentation rather than assuming similar-looking sockets have the same role.
Prepare Raspberry Pi OS¶
The current reference setup uses 64-bit Raspberry Pi OS Trixie and its camera tools, drivers and matching resources. MORA is not limited to a Pi, but using this camera on another board depends on a compatible camera stack and requires that board's own integration and validation. On the reference Pi:
Use the distribution's camera documentation if that package is unavailable. Review OS/kernel updates as board maintenance: compatibility needs checking with the actual installed camera stack, not a dated version copied from a guide.
Check Camera Discovery¶
Stop USHER and any other camera client before a standalone check:
Look for the IMX500. With no local display, take a photo without preview:
Open the JPEG on your PC and check that it is sharp, correctly exposed and oriented as expected. Use the actual reported camera index when multiple devices are present. A nonempty file alone does not prove image quality.
Choose A Sensoraia Profile¶
| Profile | Use It For |
|---|---|
--aicam |
Ordinary photographs using the OS camera tool |
--aicam --native-photo |
Native photographs without a model or rpicam-still |
--spottercam |
Compatible vehicle detection and same-image results |
--spottercam --native-photo |
Native photographs with Spottercam detection disabled |
--loomcam |
Experimental visual-return observations and bounded target policy |
All three use the same physical camera. Do not start two owners, and do not run a standalone camera application beside an active USHER capture profile. Installing camera packages alone does not select a model or enable detection.
An IMX500 model uses a compatible RPK. A CPU ONNX model is a separate choice; see choose a model. Renaming an unrelated model does not make its outputs meaningful to the application.
Deploy And Select A Profile¶
The full MORA package installs all camera workers ready to run. You do not
need to hand-edit systemd service templates to switch between them—simply set
CAMERA in camera.conf at the Sensoraia root (or pass CAMERA=<name> on the
make command line):
| Desired IMX500 MORA Mode | camera.conf / Command-Line Selection |
Resulting Service Command |
|---|---|---|
| Plain AI Camera photos (native libcamera, no model) | CAMERA=aicam |
usher --aicam --native-photo |
Spottercam (default: IMX500 + nn_vehicles.rpk) |
CAMERA=spottercam |
usher --spottercam |
| LOOMcam (visual-return homing) | CAMERA=loomcam |
usher --loomcam |
(Advanced: if you specifically want OS rpicam-still instead of --native-photo,
or --spottercam --native-photo, you can customize ExecStart in
usher.service.in directly.)
From your PC checkout, build, upload, and activate the AI Camera profile in one step:
make mora-deploy CAMERA=aicam MORA_SSH_TARGET=air@theatre.local
ssh air@theatre.local 'systemctl --no-pager --full status usher.service'
ssh air@theatre.local 'journalctl -u usher.service -n 50 --no-pager'
Adjust the SSH target and MORA_INSTALL_DIR for your installation. Deployment
rebuilds the ARM64 package on the PC, stages it on MORA, checks dependencies
and restarts USHER. The packaged service uses its configured UART; send a
camera-2 request from the connected flight controller and inspect the saved
image under the service account's ~/Pictures/sensoraia/. Filenames begin
with a, and existing photographs are not overwritten. See the complete
deployment procedure for setup,
password handling and recovery.
Native Photographs¶
For photographs without object recognition, select either native photo mode:
Both use the same libcamera capture and JPEG code. The AIcam selection starts
bin/aicam; the Spottercam selection starts bin/spottercam without a model.
Neither starts rpicam-still, loads a model or produces detection results.
USHER also skips SODA analysis for these photo-only captures.
The IMX500's previously retained network is cleared from volatile sensor state;
its model file is unchanged and a later detection session loads it again.
Each request waits for a new frame and saves a 2028x1520 JPEG at quality 90
with 4:2:0 sampling and sensor timing evidence. The camera and storage determine
the available rate. Use the camera speed test
to measure your setup. A failed native capture is not replayed through another
backend. --native-photo cannot be combined with mock capture or detector
settings.
| Option | Purpose |
|---|---|
--aicam |
Select ordinary AI Camera photographs; without --native-photo, use rpicam-still |
--spottercam |
Select the same IMX500 for vehicle detection, or photo-only capture when combined with --native-photo |
--native-photo |
Use the native libcamera worker without a model, detector, SODA or rpicam-still |
--speedtest |
Take one warm-up and ten timed photographs, report the observed rate, then exit |
USHER_AI_CAM_TIMING=1 |
Log native acquisition and JPEG-save times; useful for diagnosing capture latency |
If the native worker fails during a request, that request fails without an automatic replay. A later request can start a replacement worker after the old one has exited. Check the service journal and storage space if failures repeat.
For a standalone photograph, stop other camera owners and choose a new absolute output path:
./bin/aicam --probe
./bin/aicam --capture /home/air/Pictures/aicam-photo.jpg
./bin/spottercam --photo-only --probe
./bin/spottercam --photo-only --capture /home/air/Pictures/spotter-photo.jpg
Run these from /home/air/sensoraia on MORA, after stopping USHER if it owns
the camera. --probe checks that a frame is available without saving a JPEG;
--capture saves one new file and exits. Restore the service afterward.
The target needs its compatible libcamera runtime, IMX500 driver and Raspberry
Pi camera tuning files; no model is needed for native photo mode.
For a short throughput measurement, follow the
camera speed test, selecting either
./usher --aicam --native-photo --speedtest or
./usher --spottercam --native-photo --speedtest. It stops and restores the
service manually around the standalone measurement and retains the test photographs.
Capture Through USHER¶
After the board/sensor check, select the intended backend in your reviewed service configuration and follow deployment. For a separately managed live bench session with no other owner:
Connect the prepared FC/UART integration and request one photo. Check both the saved JPEG and its available flight metadata. Use the capture guide for service diagnostics and result interpretation.
If Something Does Not Work¶
Check cable seating and power before software changes. A busy-camera error often means another application owns it. For model failures, inspect the module's descriptor/export requirements rather than switching randomly between RPK, ONNX and camera-tool configuration files.
Camera mode, crop, delivered dimensions and mounting affect geometry. A nominal product field of view is not a calibration of your installed camera.