XCAICX developer documentation

An on-device computer-vision SDK for AI camera manufacturers and the factories that deploy them. Inference runs on the camera; per-unit licensing and metered API billing are part of the runtime rather than bolted on afterwards.

These pages are written for two people: the firmware engineer who has to get the SDK into a camera image that already builds, and the operator who has to issue licences and get paid. Everything here is what the code actually does — where behaviour is a deliberate trade-off, the reasoning is stated rather than hidden.

What the SDK is#

Runs on the camera. A stable C ABI over a C++17 core. No cloud dependency for inference, and with offline = 1 no network access at all.
Licensed per unit. Ed25519-signed tokens bound to a hardware fingerprint, with OEM batch keys and server-side seat accounting.
Meters API usage. Per-module inference counted on-device, spooled through outages, rated into invoices.
Four modules. Detection with tracking, defect inspection, PPE compliance, and plate localisation with OCR.

Where to start#

If you are…	Start at
Evaluating, and want it running in ten minutes	Getting started
Embedding it in camera firmware	Quickstart: C then OEM integration
Integrating from Python on a gateway or NVR	Quickstart: Python
Working out how licensing behaves	Licensing model
Operating the licensing authority	Running the authority
Debugging a camera in the field	Troubleshooting and Status codes

The shape of the system#

text

                 ┌──────────────────────────────────────┐
your firmware ──►│  xcaicx.h   (stable C ABI)           │
                 ├──────────────────────────────────────┤
                 │  Engine    entitlements, stream caps │
                 │  Meter     per-module inference count│
                 │  License   Ed25519 verify, binding,  │
                 │            clock-rollback, CRL       │
                 ├──────────────────────────────────────┤
                 │  Pipeline  convert → infer → track   │
                 │            → zones/tripwires → events│
                 ├──────────────────────────────────────┤
                 │  Backend   reference | ONNX Runtime  │
                 │            | TensorRT | RKNN | Hailo │
                 └───────────────┬──────────────────────┘
                                 │ activation + usage (HTTPS)
                 ┌───────────────▼──────────────────────┐
                 │  Licensing authority (FastAPI)       │
                 │  batches, seats, usage, CRL, invoice │
                 └──────────────────────────────────────┘

The camera side and the server side are independent implementations of the same token format on purpose. The C++ verifier and the Python signer are tested against each other's output, because drift between a signer and a verifier is what actually breaks licensing systems in the field.

The reference backend#

The SDK ships a reference backend: classical contrast, edge and colour heuristics with no model files and no accelerator.

Careful

It is genuinely useful — it runs the whole pipeline, so you can validate frame plumbing, licensing, events and metering before any model reaches you, and it makes CI deterministic. It is not production accuracy. On a real factory floor it will miss things and invent things. The engine logs this at INFO on every start so nobody discovers the distinction in the field. See Backends & models.

The live demo on xcaicx.com is this backend ported to JavaScript — same algorithms, same constants — so you can see its real behaviour, including its real failure modes, before writing any code.

Conventions in these docs#

Shell commands are shown without a prompt so they can be copied whole.
xcaicxctl is the operator CLI; it talks to the licensing authority over the same REST API documented in Licensing REST API.
Where a value is a deployment decision rather than a fixed constant, it is called out as such. Where a default exists because a worse default caused a real problem, the reason is stated.
Prices do not appear anywhere in this documentation. Commercial terms are per programme — the mechanics of how billing is computed are documented in Metering & billing, and the numbers come from your agreement.