Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
bc1517598d | ||
|
|
ebba70b9d9 | ||
|
|
47b80102a8 | ||
|
|
a2fa2c8ceb | ||
|
|
4678d87e33 |
@@ -0,0 +1,699 @@
|
||||
---
|
||||
title: "ANSCORE — System Architecture (L2 + L3)"
|
||||
subtitle: "Developer reference for the ANSVIS Communication Layer (CL) backend and the Qt/QML cross-platform desktop UI"
|
||||
author: "ANSCENTER"
|
||||
date: "2026-05-26"
|
||||
---
|
||||
|
||||
# Executive summary
|
||||
|
||||
ANSCORE is a Vision-AI Video Management System split into three layers:
|
||||
|
||||
- **Layer 1 — Edge runtime** (per target). Owns cameras, AI inference, trackers, rules, triggers. Built into the existing `ANSCORE/modules/*` C++ tree (ANSCV, ANSODEngine, ANSFR, ANSLPR, ANSOCR, ANSMOT). For this document L1 is *abstract*: we describe only the interface it exposes upward to L2.
|
||||
- **Layer 2 — ANSVIS CL** (one per customer). Aggregates targets, persists configuration, ingests events, brokers live media. Exposes a single REST contract (`/api/v1`) to L3. In v1 it is built as an **adapter layer in front of the existing ANSVIS server** — no rewrite required.
|
||||
- **Layer 3 — Qt/QML desktop UI** (Win / macOS / Linux). The operator-facing application. Talks to L2 exclusively.
|
||||
|
||||
**Build assignment:**
|
||||
|
||||
- L1 and L2 are built by the **core team** under architect-level review.
|
||||
- L3 is built by a **6-engineer team**.
|
||||
- L2 ↔ L3 is **REST + SSE + (HLS / RTSP / WebRTC)** — defined by `contracts/openapi.v1.json` (67 paths, 102 operations, 91 schemas).
|
||||
|
||||
The contract is the only artifact both sides block on. Once published, UI engineers develop against a Prism mock; the backend **core team** implements adapters per resource in parallel. Integration is the joining point.
|
||||
|
||||
\newpage
|
||||
|
||||
# Part I — System overview
|
||||
|
||||
## The three layers
|
||||
|
||||
{ width=100% }
|
||||
|
||||
L3 only ever talks to L2. L2 brokers everything else: configuration push down to edges, event upload from edges, media relay. This keeps the UI team fully decoupled from L1 velocity.
|
||||
|
||||
## Three transports between L3 and L2
|
||||
|
||||
| # | Transport | Purpose | Carries |
|
||||
|---|---|---|---|
|
||||
| 1 | REST over HTTPS | Control plane: all CRUD, configuration, deploy commands | JSON request/response, RFC 7807 errors |
|
||||
| 2 | Server-Sent Events (SSE) over HTTPS | Live event tail (push of detections, target status) | `text/event-stream`, JSON per event |
|
||||
| 3 | HLS / RTSP / WebRTC | Live video | Media segments; transport chosen per stream |
|
||||
|
||||
The REST API brokers the other two: the UI calls REST to obtain a stream descriptor or SSE endpoint URL.
|
||||
|
||||
## Why this split
|
||||
|
||||
The earlier proposal of using gRPC end-to-end was reversed because the existing ANSVIS server already exposes a REST API. Pragmatic v1: **reuse what exists**, adapt it into a standards-compliant `/api/v1` surface, ship faster. gRPC remains an option for a future v2 if needed.
|
||||
|
||||
## Build ownership at a glance
|
||||
|
||||
| Layer | Pace |
|
||||
|---|---|
|
||||
| L1 (edge runtime) | Slower — high complexity (frame bus, inference batching, plugin SDK) |
|
||||
| L2 (CL) | Faster — modular per-resource adapters |
|
||||
| L3 (Qt/QML UI) | Independent — mock-first development |
|
||||
|
||||
\newpage
|
||||
|
||||
# Part II — Layer 1 (abstract overview)
|
||||
|
||||
L1 is the **edge runtime** that runs on each target. From L2's perspective it is a black box that:
|
||||
|
||||
- Receives **configuration** (cameras, AI models, AI tasks, rules, triggers) from L2 and persists it locally.
|
||||
- Captures frames from cameras (RTSP / RTMP / SRT / ONVIF / simulated).
|
||||
- Runs **AI pipelines** (object detection, FR, LPR, OCR, MOT, custom plugins).
|
||||
- Evaluates **rules** and emits **events** with evidence (snapshot frame, optional clip).
|
||||
- Dispatches **triggers** (HTTP, MQTT, email, push, broker integrations).
|
||||
- Exposes **liveview** streams (RTSP / SRT / future WebRTC).
|
||||
- Reports **health / metrics / logs** upward.
|
||||
|
||||
L1 ↔ L2 protocol is out of scope for this document. For v1, L2's adapter calls into the legacy ANSVIS server's existing protocol with edges (this is what currently works in production).
|
||||
|
||||
For L2 and L3 developers, L1 is treated as a remote service:
|
||||
|
||||
- Configuration changes go: **L3 (UI) → L2 (REST) → L1 (legacy protocol) → target reconciles**.
|
||||
- Events flow: **target → L1 → L2 (legacy uplink) → L2 event store → L2 SSE → L3**.
|
||||
- Liveview: **L3 asks L2 for a stream descriptor → L2 media relay pulls from L1 → L3 plays from L2's relay URL**.
|
||||
|
||||
The detailed L1 architecture (camera pool, inference server, frame bus, plugin SDK, etc.) is documented separately and does not affect L2 / L3 work.
|
||||
|
||||
\newpage
|
||||
|
||||
# Part III — Layer 2 (ANSVIS CL)
|
||||
|
||||
## Architecture
|
||||
|
||||
{ width=100% }
|
||||
|
||||
L2 is composed of four logical groups:
|
||||
|
||||
1. **`/api/v1` surface** — REST router, auth middleware, OpenAPI request validation, RFC 7807 error mapper, rate limiter, SSE broadcaster.
|
||||
2. **v1 adapter layer** — one module per resource (cameras, models, edges, deployment-groups, ai-tasks, events, fr, alpr, notifications, system, jobs). Each adapter translates v1 requests to one or more legacy ANSVIS calls.
|
||||
3. **Legacy ANSVIS core** — reused as-is. Hosts the existing config store, AI task engine, FR engine, ALPR engine. The adapter is the only layer that calls into it.
|
||||
4. **Infrastructure** — auth + token store, async job queue, event metadata DB, clip / image object store (S3 / MinIO / FS), logs + metrics, media relay.
|
||||
|
||||
## Ownership inside L2
|
||||
|
||||
{ width=100% }
|
||||
|
||||
- **Architect (human)** keeps direct review on the cross-cutting concerns: REST router, auth, validation pipeline, RFC 7807 errors, RBAC, L2 ↔ L1 tunnel security.
|
||||
- The **core team** builds the per-resource adapters and infrastructure helpers (job queue, media relay). Each module has a sharp boundary so the team can work in parallel without colliding.
|
||||
- **Existing ANSVIS** is reused as-is. The adapter is the only entry point.
|
||||
|
||||
## REST API surface — `/api/v1`
|
||||
|
||||
The full contract is `contracts/openapi.v1.json` (OpenAPI 3.1, 67 paths, 102 operations, 91 typed schemas). Summary by resource group:
|
||||
|
||||
| Tag | Operations | Purpose |
|
||||
|---|---:|---|
|
||||
| `auth` | 3 | Login, logout, refresh |
|
||||
| `users` | 5 | System users CRUD |
|
||||
| `cameras` | 10 | CRUD + snapshot + liveview + ONVIF scan + probe |
|
||||
| `models` | 7 | CRUD + multipart upload + initiate/complete large upload |
|
||||
| `edges` | 7 | CRUD + health + status |
|
||||
| `deployment-groups` | 8 | CRUD + status + start/stop |
|
||||
| `ai-tasks` | 11 | CRUD + status + start/stop + liveview + catalog |
|
||||
| `events` | 6 | List + summary + SSE stream + image + clip + single |
|
||||
| `fr` | 14 | Persons + faces + groups + detection config |
|
||||
| `fr-recording` | 7 | Face-recording tasks + read/assign |
|
||||
| `alpr` | 8 | Plate + plate-group CRUD |
|
||||
| `notifications` | 5 | Recipients + groups |
|
||||
| `triggers` | 2 | Type catalog + test dispatch |
|
||||
| `system` | 7 | Status, health, info, logs, version, update |
|
||||
| `jobs` | 1 | Async job polling |
|
||||
| `composite` | 1 | Convenience endpoint (camera + tasks in one call) |
|
||||
| **Total** | **102** | |
|
||||
|
||||
## Conventions enforced by `openapi.v1.json`
|
||||
|
||||
- Plural kebab-case resource paths (`/cameras`, `/ai-tasks`, `/deployment-groups`).
|
||||
- `snake_case` field names. Units in the field name (`time_interval_seconds`, not `time_interval` with `(s)` suffix).
|
||||
- IDs in the path, never as query-string keys (replaces legacy `?867560018`).
|
||||
- `GET / POST / PUT / PATCH / DELETE` used semantically.
|
||||
- State changes via `POST /resource/{id}/start` and `POST /resource/{id}/stop` (pragmatic exception).
|
||||
- All errors as RFC 7807 problem+json with the matching HTTP status code.
|
||||
- List responses use a uniform pagination wrapper: `{items, page, page_size, total, next_cursor}`.
|
||||
- Auth: `Authorization: Bearer <token>` header, never in URL.
|
||||
- File uploads up to 10 MB use `multipart/form-data`; larger uploads use the initiate / complete pattern with a presigned PUT URL.
|
||||
- Live events as SSE; live media via HLS / RTSP / WebRTC behind a descriptor RPC.
|
||||
- All previously stringified-JSON fields (`Parameters(json)`, `RuleConfig`, `TriggerConfig`, `ModelConfigJson`) are now fully typed nested objects, validated against the schema.
|
||||
|
||||
## Migration from legacy ANSVIS endpoints
|
||||
|
||||
Every v1 endpoint description in the OpenAPI spec ends with `Replaces:` listing the legacy ANSVIS path(s) it supersedes. Examples:
|
||||
|
||||
| Legacy | v1 |
|
||||
|---|---|
|
||||
| `GET /Camera` (list mode) | `GET /api/v1/cameras` |
|
||||
| `GET /Camera?{id}` | `GET /api/v1/cameras/{id}` |
|
||||
| `DELETE /Camera?{id}` + `POST /delete/Camera?{id}` | `DELETE /api/v1/cameras/{id}` |
|
||||
| `GET /ControlAITask?ID=&State=true` | `POST /api/v1/ai-tasks/{id}/start` |
|
||||
| `POST /event/Get` (filter in body) | `GET /api/v1/events?task_id=&from=&to=&...` |
|
||||
| `POST /FR/AddFace` (base64 in JSON) | `POST /api/v1/fr/persons/{id}/faces` (multipart) |
|
||||
| `GET /SW/GetSoftwareVersion`, etc. | `GET /api/v1/system/version`, `/health`, `/info`, `/logs`, `/update` |
|
||||
|
||||
Legacy endpoints remain available during one release cycle with `Deprecation:` + `Sunset:` headers (RFC 8594).
|
||||
|
||||
\newpage
|
||||
|
||||
# Part IV — Layer 3 (Qt / QML desktop UI)
|
||||
|
||||
## Architecture
|
||||
|
||||
{ width=100% }
|
||||
|
||||
L3 is organized in four layers inside the Qt app:
|
||||
|
||||
1. **App Shell** — main window, navigation router, design system / theme, i18n, auth state + token store, global error toast / dialog.
|
||||
2. **Network layer** — generated REST client (from `openapi.v1.json`), SSE subscriber (chunked `QNetworkReply`), media client (QtMultimedia or GStreamer), bbox overlay renderer (custom `QQuickItem` with `QSGGeometryNode`), multipart + presigned uploader.
|
||||
3. **Domain state** — `QObject` + `Q_PROPERTY` + signals models per resource (CamerasModel, ModelsModel, EdgesModel, DeploymentGroupsModel, AITasksModel, EventsModel + LiveBuffer, FRPersonsModel, ALPRPlatesModel, RecipientsModel, SystemHealthModel).
|
||||
4. **Screens (QML)** — the operator surface: Login, Dashboard, Camera management, Pipeline editor, AI task config, Rules / triggers, Liveview grid, Eventview timeline, FR persons + faces, ALPR plates, Model registry, Users / admin, Settings.
|
||||
|
||||
## Screen → endpoint map
|
||||
|
||||
| Screen | Reads | Mutates | Notes |
|
||||
|---|---|---|---|
|
||||
| Login | — | `POST /auth/login` | Stores token in `AuthState` |
|
||||
| Dashboard | `GET /edges`, `GET /edges/{id}/health`, `GET /system/health` | — | Auto-refresh every 5 s |
|
||||
| Camera management | `GET /cameras`, `GET /cameras/{id}/snapshot`, `POST /cameras/probe` | `POST/PATCH/DELETE /cameras`, `POST /cameras/scan` (async job) | ONVIF discovery + calibration |
|
||||
| Pipeline editor | `GET /deployment-groups/{id}`, `GET /ai-tasks/catalog`, `GET /models` | `PUT /deployment-groups/{id}` | Highest-risk feature; QGraphicsView |
|
||||
| AI task config | `GET /ai-tasks/{id}`, `GET /ai-tasks/catalog` | `POST/PATCH/DELETE /ai-tasks`, `POST /ai-tasks/{id}/{start,stop}` | Schema-driven forms |
|
||||
| Rules / triggers | `GET /triggers/types` | Embedded in DG / task body | `POST /triggers/test` |
|
||||
| Liveview | `GET /cameras/{id}/liveview` | — | HLS v1, WebRTC v2; overlay sync to PTS |
|
||||
| Eventview | `GET /events?...`, `GET /events/stream` (SSE), `/events/{id}/{image,clip}` | — | Virtualized list for 100k+ events |
|
||||
| FR persons + faces | `GET /fr/persons`, `GET /fr/persons/{id}/faces` | `POST/PATCH/DELETE /fr/persons`, `POST /fr/persons/{id}/faces` (multipart) | Image upload |
|
||||
| ALPR plates | `GET /alpr/plates`, `GET /alpr/plate-groups` | `POST/DELETE /alpr/plates`, `PATCH /alpr/plate-groups/{id}` | Bulk register / deregister |
|
||||
| Model registry | `GET /models` | `POST /models` (multipart) or initiate / complete pattern for >100 MB | Upload progress |
|
||||
| Users / admin | `GET /users` | `POST/PATCH/DELETE /users/{id}` | Admin role only |
|
||||
| Settings | `GET /system/info`, `GET /system/version`, `GET /system/update` | `POST /system/update` | |
|
||||
|
||||
## Engineer ownership
|
||||
|
||||
{ width=100% }
|
||||
|
||||
\
|
||||
|
||||
Six engineers, each owning a vertical slice:
|
||||
|
||||
| # | Role | Owns |
|
||||
|---|---|---|
|
||||
| **E1** | UI Lead / Shell Architect | Qt 6 + CMake monorepo, generated REST client, auth state, design system, navigation router, packaging (Win/Mac/Linux signing, notarize, auto-update), CI matrix |
|
||||
| **E2** | Pipeline Editor Specialist | Visual DAG editor (`QGraphicsView` in `QQuickWidget`), node library, connection validation, schema-driven param panels, undo / redo, save / version |
|
||||
| **E3** | Liveview / Media | QtMultimedia HLS player (v1), multi-stream grid, bbox overlay (`QQuickItem` + `QSGGeometryNode`), clip player, WebRTC via GStreamer (v2) |
|
||||
| **E4** | Config Forms | Schema-driven QML forms from `openapi.v1.json`, camera + ONVIF discovery flow, camera calibration UI (ROI / zones / homography), model + plugin + trigger forms |
|
||||
| **E5** | Dashboard / Eventview | Target dashboard cards + charts, virtualized event timeline, SSE subscriber + LiveBuffer, filter / search / evidence viewer, multi-target monitoring |
|
||||
| **E6** | UX / Cross-platform QA | Design polish, accessibility, i18n, install / upgrade testing on Win / Mac / Linux, crash reporting, QML Profiler perf passes, user docs surface |
|
||||
|
||||
**Critical-path order for week 1–2:** E1 alone delivers the shell that unblocks E2–E6. E2 runs a node-editor spike in parallel to de-risk the hardest feature early. Once E1's shell lands, E3 / E4 / E5 work in parallel against the mock CL; E6 starts cross-platform validation.
|
||||
|
||||
\newpage
|
||||
|
||||
# Part V — L2 ↔ L3 communication
|
||||
|
||||
## 1. REST control plane
|
||||
|
||||
Every CRUD operation, every state change, every configuration push. JSON in, JSON out, RFC 7807 problem+json on error.
|
||||
|
||||
### Request envelope
|
||||
|
||||
```http
|
||||
GET /api/v1/cameras?page=1&page_size=50 HTTP/1.1
|
||||
Host: cms.example.com
|
||||
Authorization: Bearer eyJhbGc…
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
### Success list response
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{ "id": 123, "name": "Front gate", "driver": "rtsp", "active": true, ... }
|
||||
],
|
||||
"page": 1,
|
||||
"page_size": 50,
|
||||
"total": 247,
|
||||
"next_cursor": null
|
||||
}
|
||||
```
|
||||
|
||||
### Error response
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "https://anscenter.com/errors/validation",
|
||||
"title": "Validation failed",
|
||||
"status": 422,
|
||||
"detail": "One or more fields are invalid",
|
||||
"instance": "/api/v1/cameras",
|
||||
"errors": [
|
||||
{ "field": "address", "message": "Must be a valid RTSP URL" },
|
||||
{ "field": "capturing.time_interval_seconds", "message": "Must be > 0" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Camera create — body example (clean v1)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Front gate",
|
||||
"driver": "rtsp",
|
||||
"address": "rtsp://192.168.1.87:554/h264Preview_01_main",
|
||||
"credentials": { "username": "root", "password": "admin123" },
|
||||
"capturing": { "mode": "timer", "time_interval_seconds": 0.1 },
|
||||
"active": true,
|
||||
"logging_enabled": false,
|
||||
"edge_id": null,
|
||||
"deployment_group_ids": []
|
||||
}
|
||||
```
|
||||
|
||||
Note: no more stringified `Parameters(json)`. No more keys with parentheses or apostrophes. Credentials are nested. Units are in the field name.
|
||||
|
||||
## 2. SSE event stream
|
||||
|
||||
For live event tail:
|
||||
|
||||
```http
|
||||
GET /api/v1/events/stream?task_id=456 HTTP/1.1
|
||||
Host: cms.example.com
|
||||
Authorization: Bearer eyJhbGc…
|
||||
Accept: text/event-stream
|
||||
```
|
||||
|
||||
Each event:
|
||||
|
||||
```
|
||||
event: detection
|
||||
data: {"id":"20260526_181023-3","task_id":456,"camera_id":123,
|
||||
"timestamp":"2026-05-26T18:10:23Z","object":"car","score":0.91,
|
||||
"bbox":{"x":340,"y":210,"w":120,"h":80}}
|
||||
```
|
||||
|
||||
Qt side: `QNetworkAccessManager` with chunked reads, parse newline-delimited frames, drive `EventsModel.LiveBuffer`.
|
||||
|
||||
## 3. Live media
|
||||
|
||||
`GET /api/v1/cameras/{id}/liveview?transport=hls` returns a stream descriptor:
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://cms.example.com/relay/cam123.m3u8",
|
||||
"transport": "hls",
|
||||
"auth_token": "tkn_short_lived_…",
|
||||
"expires_at": "2026-05-26T18:15:00Z",
|
||||
"overlay_stream": "/api/v1/events/stream?task_id=456"
|
||||
}
|
||||
```
|
||||
|
||||
Qt side: hand the URL to QtMultimedia for HLS playback (v1). For sub-second latency in v2, switch transport to `webrtc` and use GStreamer `webrtcbin`.
|
||||
|
||||
\newpage
|
||||
|
||||
# Part VI — Key sequence flows
|
||||
|
||||
## 6.1 Operator configures a camera + AI task and deploys
|
||||
|
||||
{ width=92% }
|
||||
|
||||
Walk-through:
|
||||
|
||||
1. UI lists cameras via `GET /cameras?page=1`.
|
||||
2. Operator submits the new-camera form. UI sends `POST /cameras` with the *clean* body (nested credentials, capturing, image_size — no stringified JSON).
|
||||
3. UI creates an AI task for the new camera via `POST /ai-tasks`.
|
||||
4. Operator clicks "Start". UI calls `POST /ai-tasks/{id}/start` — returns `202 Accepted` with `{state: starting}`.
|
||||
5. UI polls `GET /ai-tasks/{id}/status` until `state=running`. (Will be replaced by SSE in a later iteration so polling is optional.)
|
||||
|
||||
## 6.2 Live event tail with evidence
|
||||
|
||||
{ width=92% }
|
||||
|
||||
Walk-through:
|
||||
|
||||
1. UI fetches historical events via `GET /events?task_id=&page=1` and renders the timeline.
|
||||
2. UI opens an SSE stream `GET /events/stream?task_id=` for live tail.
|
||||
3. Edge produces an event → L2 ingests → SSE broadcaster pushes the `EventRecord` to all subscribed UIs (filtered by their query).
|
||||
4. Operator clicks an event. UI fetches `GET /events/{id}/image?width=640` for the snapshot.
|
||||
5. Operator plays the clip. UI fetches `GET /events/{id}/clip` to get a presigned URL, then GETs the MP4 directly from the object store. The CL process never touches the video bytes — they flow client ↔ S3/MinIO.
|
||||
|
||||
## 6.3 Liveview with bbox overlay
|
||||
|
||||
{ width=92% }
|
||||
|
||||
Walk-through:
|
||||
|
||||
1. UI requests a liveview descriptor for camera 123: `GET /cameras/123/liveview?transport=hls`.
|
||||
2. L2's media relay ensures an HLS endpoint is running for that camera (pulling RTSP from the edge in the background).
|
||||
3. L2 returns `{url, transport:hls, auth_token, expires_at}`.
|
||||
4. UI plays the HLS URL in QtMultimedia.
|
||||
5. Simultaneously the UI subscribes to `/events/stream?task_id=456` (SSE) for the AI task's detections.
|
||||
6. The Qt overlay layer (custom `QQuickItem`) renders bounding boxes synced to the video PTS.
|
||||
|
||||
For v2 with WebRTC, the descriptor returns `transport:webrtc` and a signaling URL; GStreamer's `webrtcbin` handles negotiation.
|
||||
|
||||
## 6.4 Async camera scan via job queue
|
||||
|
||||
{ width=92% }
|
||||
|
||||
Walk-through:
|
||||
|
||||
1. Operator triggers an ONVIF scan of a subnet. UI calls `POST /cameras/scan` with `{ip_range, credentials, timeout_seconds}`.
|
||||
2. L2 enqueues the work and immediately returns `202 Accepted` with `{job_id, status:queued, links:{self:"/jobs/j1"}}`.
|
||||
3. The job worker performs the scan asynchronously.
|
||||
4. UI polls `GET /jobs/{id}` until `status` becomes `succeeded` or `failed`. The terminal response includes `result` with the discovered cameras.
|
||||
|
||||
This pattern is used for every potentially-long operation: ONVIF scan, large model upload, deploy-to-many-targets, software update.
|
||||
|
||||
## 6.5 Large model upload (presigned URL)
|
||||
|
||||
{ width=92% }
|
||||
|
||||
Walk-through:
|
||||
|
||||
1. UI calls `POST /models:initiate-upload` with `{filename, size_bytes, checksum}`. L2 returns `{upload_id, presigned_url, expires_at}`.
|
||||
2. UI PUTs the bytes directly to the object store using the presigned URL. The CL process never sees the bytes — saves CPU and avoids HTTP-body-size limits.
|
||||
3. UI calls `POST /models:complete-upload` with `{upload_id, metadata}`. L2 verifies the checksum and registers the model.
|
||||
|
||||
For files under 10 MB, the simple `POST /models` multipart endpoint can be used instead.
|
||||
|
||||
\newpage
|
||||
|
||||
# Part VII — Deployment topology
|
||||
|
||||
{ width=100% }
|
||||
|
||||
## Hosts
|
||||
|
||||
| Host | Runs | Notes |
|
||||
|---|---|---|
|
||||
| Operator workstation (Win / Mac / Linux) | Qt UI application | One per concurrent operator |
|
||||
| ANSVIS server host | Reverse proxy (nginx / caddy) + ANSVIS app (adapter + legacy core) + Media relay + Object store + Config / Event DBs | One per customer site (can be HA later) |
|
||||
| Edge target | L1 runtime | One per physical capture site |
|
||||
|
||||
## Customer network rules
|
||||
|
||||
| Direction | Port | Purpose |
|
||||
|---|---|---|
|
||||
| Workstation → ANSVIS server | TCP 443 | REST + SSE + HLS over TLS |
|
||||
| ANSVIS server → workstation | — (response only) | |
|
||||
| ANSVIS server ↔ edges | TBD per deployment | Existing ANSVIS protocol |
|
||||
| Workstation → edges | **None** | Workstations never reach edges directly. Media relay proxies. |
|
||||
|
||||
## Why workstations don't reach edges
|
||||
|
||||
- Edges typically sit behind customer firewalls / NAT.
|
||||
- One TLS endpoint (ANSVIS) is easier to firewall, monitor, and authenticate against than dozens of edges.
|
||||
- Token rotation happens centrally.
|
||||
- The media relay can transcode, cache, or split streams.
|
||||
|
||||
\newpage
|
||||
|
||||
# Part VIII — Delivery plan
|
||||
|
||||
## Mock-first development
|
||||
|
||||
The contract `openapi.v1.json` is the only artifact both teams block on. Once it is published:
|
||||
|
||||
- **UI team** runs Stoplight Prism (`prism mock contracts/openapi.v1.json`) as a local mock CL and develops against it from day 1. No need to wait for the real adapter.
|
||||
- The **backend core team** implements the adapter resource-by-resource in parallel, validating each endpoint against the same OpenAPI schema.
|
||||
- **Integration** is the joining point. UI tests run against both mock and real to detect drift.
|
||||
|
||||
## Critical path
|
||||
|
||||
{ width=100% }
|
||||
|
||||
## Sequencing
|
||||
|
||||
| Phase | Week | Activities |
|
||||
|---|---|---|
|
||||
| **Contract freeze** | 1 | Lock `openapi.v1.json` v1.0.0 (3 small decisions outstanding — see Part IX) |
|
||||
| **Foundations** | 1–2 | E1: Qt 6 + CMake monorepo, generated REST client, Prism mock wired up, design system stub, app shell. <br/> E2: node-editor spike (de-risk). <br/> Core team: cameras / models / edges / system adapters in parallel. |
|
||||
| **Vertical slices** | 3–6 | E3 (Liveview), E4 (Config forms), E5 (Dashboard / Eventview) build full features against the mock. <br/> Core team: ai-tasks / deployment-groups / events / fr / alpr / notifications adapters. |
|
||||
| **Real integration** | 7–8 | UI cuts over from mock to real `/api/v1` per screen as adapters land. E6 runs cross-platform install / upgrade testing on Win / Mac / Linux. |
|
||||
| **Hardening** | 9–10 | Performance passes (QML Profiler, REST tracing), security review (architect-led), crash reporting, packaging signing / notarization. |
|
||||
| **Ship v1** | 11–12 | Pilot deployment, customer training, feedback loop. |
|
||||
|
||||
\newpage
|
||||
|
||||
# Part IX — Open decisions
|
||||
|
||||
These need to be locked before contract v1.0.0 publishes.
|
||||
|
||||
| # | Decision | Default in spec | Notes |
|
||||
|---|---|---|---|
|
||||
| 1 | Field naming | `snake_case` | Could switch to `camelCase` — match Qt/C++ style. One find-replace pass on `openapi.v1.json` either way. |
|
||||
| 2 | Auth scheme | Bearer (existing ANSVIS token) | v1 keeps Bearer; OAuth2/OIDC for v2. |
|
||||
| 3 | Mock server tool | Stoplight Prism (free) | Alternative: build a richer custom mock with scenarios. Recommend Prism. |
|
||||
| 4 | Liveview transport for v1 | HLS via QtMultimedia | Easiest. Add WebRTC in v2 if sub-second latency is needed. |
|
||||
| 5 | Object store | S3 / MinIO / local FS | Choose per deployment; behind a generic `ObjectStore` interface. |
|
||||
| 6 | Auto-update mechanism | Sparkle (Mac), MSIX / custom (Win), AppImage (Linux) | Confirm budget for code signing per platform. |
|
||||
| 7 | Contract repo location | `ANSCORE/contracts/` (current) | Separate `anscore-contracts` repo if teams diverge. |
|
||||
|
||||
\newpage
|
||||
|
||||
# Appendix A — Full endpoint catalog
|
||||
|
||||
Complete list of v1 operations. See `contracts/openapi.v1.json` for full request / response schemas.
|
||||
|
||||
## auth
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| POST | `/auth/login` | Log in (returns `access_token`, `expires_at`, `user`) |
|
||||
| POST | `/auth/logout` | Invalidate token |
|
||||
| POST | `/auth/refresh` | Exchange refresh token for new access token |
|
||||
|
||||
## users
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/users` | List users (paginated) |
|
||||
| POST | `/users` | Create user |
|
||||
| GET | `/users/{id}` | Get user |
|
||||
| PATCH | `/users/{id}` | Update user |
|
||||
| DELETE | `/users/{id}` | Delete user |
|
||||
|
||||
## cameras
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/cameras` | List cameras (filters: driver, active, edge_id, deployment_group_id) |
|
||||
| POST | `/cameras` | Create camera |
|
||||
| GET | `/cameras/{id}` | Get camera |
|
||||
| PUT | `/cameras/{id}` | Replace camera |
|
||||
| PATCH | `/cameras/{id}` | Patch camera |
|
||||
| DELETE | `/cameras/{id}` | Delete camera |
|
||||
| GET | `/cameras/{id}/snapshot` | Get JPEG snapshot (or presigned URL) |
|
||||
| GET | `/cameras/{id}/liveview` | Get liveview descriptor (`{url, transport, token, expires_at}`) |
|
||||
| POST | `/cameras/scan` | Async ONVIF scan (returns job) |
|
||||
| POST | `/cameras/probe` | Probe single IP for ONVIF profiles |
|
||||
|
||||
## models
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/models` | List models (filter by type) |
|
||||
| POST | `/models` | Upload + register (multipart, ≤10 MB) |
|
||||
| GET | `/models/{id}` | Get model |
|
||||
| PATCH | `/models/{id}` | Update model metadata |
|
||||
| DELETE | `/models/{id}` | Delete model |
|
||||
| POST | `/models:initiate-upload` | Begin large upload (returns presigned PUT URL) |
|
||||
| POST | `/models:complete-upload` | Finalize large upload |
|
||||
|
||||
## edges
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/edges` | List edges |
|
||||
| POST | `/edges` | Register edge |
|
||||
| GET | `/edges/{id}` | Get edge |
|
||||
| PATCH | `/edges/{id}` | Update edge |
|
||||
| DELETE | `/edges/{id}` | Delete edge |
|
||||
| GET | `/edges/{id}/health` | Resource / temp / uptime |
|
||||
| GET | `/edges/{id}/status` | State (online/offline/degraded) + counts |
|
||||
|
||||
## deployment-groups
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/deployment-groups` | List groups |
|
||||
| POST | `/deployment-groups` | Create group |
|
||||
| GET | `/deployment-groups/{id}` | Get group |
|
||||
| PUT | `/deployment-groups/{id}` | Replace group |
|
||||
| DELETE | `/deployment-groups/{id}` | Delete group |
|
||||
| GET | `/deployment-groups/{id}/status` | Runtime status |
|
||||
| POST | `/deployment-groups/{id}/start` | Start group |
|
||||
| POST | `/deployment-groups/{id}/stop` | Stop group |
|
||||
|
||||
## ai-tasks
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/ai-tasks` | List tasks |
|
||||
| POST | `/ai-tasks` | Create task |
|
||||
| GET | `/ai-tasks/{id}` | Get task |
|
||||
| PUT | `/ai-tasks/{id}` | Replace task |
|
||||
| PATCH | `/ai-tasks/{id}` | Patch task |
|
||||
| DELETE | `/ai-tasks/{id}` | Delete task |
|
||||
| GET | `/ai-tasks/{id}/status` | Get task runtime status |
|
||||
| POST | `/ai-tasks/{id}/start` | Start task |
|
||||
| POST | `/ai-tasks/{id}/stop` | Stop task |
|
||||
| GET | `/ai-tasks/{id}/liveview` | Liveview descriptor for annotated stream |
|
||||
| GET | `/ai-tasks/catalog` | List supported task types |
|
||||
|
||||
## events
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/events` | List events (filters: task_id, camera_id, object, from, to) |
|
||||
| GET | `/events/summary` | Analytics rollup |
|
||||
| GET | `/events/stream` | Live event tail (Server-Sent Events) |
|
||||
| GET | `/events/{id}` | Get one event |
|
||||
| GET | `/events/{id}/image` | JPEG snapshot |
|
||||
| GET | `/events/{id}/clip` | Presigned URL for evidence clip |
|
||||
|
||||
## fr (face recognition)
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/fr/persons` | List persons |
|
||||
| POST | `/fr/persons` | Create person |
|
||||
| GET | `/fr/persons/{id}` | Get person |
|
||||
| PATCH | `/fr/persons/{id}` | Update person |
|
||||
| DELETE | `/fr/persons/{id}` | Delete person |
|
||||
| GET | `/fr/persons/{id}/faces` | List faces for person |
|
||||
| POST | `/fr/persons/{id}/faces` | Add face (multipart, no base64) |
|
||||
| DELETE | `/fr/faces/{face_id}` | Delete face |
|
||||
| GET | `/fr/person-groups` | List person groups |
|
||||
| POST | `/fr/person-groups` | Create group |
|
||||
| PATCH | `/fr/person-groups/{id}` | Update group |
|
||||
| DELETE | `/fr/person-groups/{id}` | Delete group |
|
||||
| GET | `/fr/config` | Get FR detection config |
|
||||
| PATCH | `/fr/config` | Update FR detection config |
|
||||
|
||||
## fr-recording
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/fr/recording-tasks` | List tasks |
|
||||
| POST | `/fr/recording-tasks` | Create task |
|
||||
| DELETE | `/fr/recording-tasks/{id}` | Delete task |
|
||||
| POST | `/fr/recording-tasks/{id}/start` | Start task |
|
||||
| POST | `/fr/recording-tasks/{id}/stop` | Stop task |
|
||||
| GET | `/fr/recording-tasks/{id}/faces` | Read recorded faces |
|
||||
| PATCH | `/fr/recording-tasks/{id}/faces` | Assign recorded faces to a person (bulk) |
|
||||
|
||||
## alpr
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/alpr/plates` | List plates |
|
||||
| POST | `/alpr/plates` | Register plates (bulk) |
|
||||
| DELETE | `/alpr/plates/{plate}` | Deregister single plate |
|
||||
| POST | `/alpr/plates:bulk-delete` | Deregister bulk |
|
||||
| GET | `/alpr/plate-groups` | List plate groups |
|
||||
| POST | `/alpr/plate-groups` | Create group |
|
||||
| PATCH | `/alpr/plate-groups/{id}` | Update group |
|
||||
| DELETE | `/alpr/plate-groups/{id}` | Delete group |
|
||||
|
||||
## notifications
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/notifications/recipients` | List recipients |
|
||||
| POST | `/notifications/recipients` | Create recipient |
|
||||
| PATCH | `/notifications/recipients/{id}` | Update recipient |
|
||||
| DELETE | `/notifications/recipients/{id}` | Delete recipient |
|
||||
| GET | `/notifications/recipient-groups` | List recipient groups |
|
||||
|
||||
## triggers
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/triggers/types` | List supported trigger types + config schemas |
|
||||
| POST | `/triggers/test` | Dispatch a test trigger (HTTP / MQTT / Email / etc.) |
|
||||
|
||||
## system
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/system/status` | Liveness probe |
|
||||
| GET | `/system/health` | Resources + counts |
|
||||
| GET | `/system/info` | Hostname / OS / hardware |
|
||||
| GET | `/system/logs` | Paginated logs |
|
||||
| GET | `/system/version` | Version + build date + commit |
|
||||
| GET | `/system/update` | Update status |
|
||||
| POST | `/system/update` | Trigger update (async job) |
|
||||
|
||||
## jobs
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/jobs/{id}` | Get async job status / result |
|
||||
|
||||
## composite
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| POST | `/composite/camera-with-tasks` | Create camera + deployment groups in one call |
|
||||
|
||||
\newpage
|
||||
|
||||
# Appendix B — Artifacts in the repository
|
||||
|
||||
```
|
||||
ANSCORE/
|
||||
├── contracts/
|
||||
│ └── openapi.v1.json # The single source of truth for L2 ↔ L3
|
||||
│
|
||||
├── docs/
|
||||
│ ├── ANSCORE-system-architecture.md # This document (source)
|
||||
│ ├── ANSCORE-system-architecture.pdf # This document (rendered)
|
||||
│ ├── L2-L3-architecture.md # Same content with Mermaid diagrams
|
||||
│ └── diagrams/
|
||||
│ ├── 01-system-context.puml # PlantUML sources
|
||||
│ ├── 02-l2-internals.puml
|
||||
│ ├── 03-l2-ownership.puml
|
||||
│ ├── 04-l3-internals.puml
|
||||
│ ├── 05-seq-configure-deploy.puml
|
||||
│ ├── 06-seq-live-events.puml
|
||||
│ ├── 07-seq-liveview.puml
|
||||
│ ├── 08-seq-async-scan.puml
|
||||
│ ├── 09-seq-large-upload.puml
|
||||
│ ├── 10-deployment-topology.puml
|
||||
│ ├── 11-l3-engineer-ownership.puml
|
||||
│ ├── 12-dependency-chain.puml
|
||||
│ ├── README.md
|
||||
│ ├── PREVIEW.md # Clickable plantuml.com URLs
|
||||
│ └── png/ # Pre-rendered PNGs (used in this PDF)
|
||||
│
|
||||
└── modules/ # Existing C++ building blocks (L1 ingredients)
|
||||
├── ANSCV/ ANSODEngine/ ANSFR/ ANSLPR/ ANSOCR/
|
||||
├── ANSMOT/ ANSPulsar/ ANSRabbitMQ/ ANSONVIF/
|
||||
└── ...
|
||||
```
|
||||
|
||||
# Appendix C — Glossary
|
||||
|
||||
| Term | Meaning |
|
||||
|---|---|
|
||||
| **L1** | Layer 1 — edge runtime (per target) |
|
||||
| **L2** | Layer 2 — ANSVIS CL (per customer) |
|
||||
| **L3** | Layer 3 — Qt/QML desktop UI (per operator workstation) |
|
||||
| **Adapter (v1)** | The L2 module that translates `/api/v1` requests to legacy ANSVIS calls |
|
||||
| **Edge / target** | A physical device running L1 (Windows/Linux on x86 or NVIDIA Jetson) |
|
||||
| **Deployment group** | A bundle of cameras + models + rules + triggers deployed to a target |
|
||||
| **AI task** | A configured pipeline (camera + model + rules + triggers) ready to run |
|
||||
| **Event** | A detection emitted by an AI task, with evidence (snapshot + optional clip) |
|
||||
| **Liveview** | Real-time video from a camera, with optional bbox overlay |
|
||||
| **Trigger** | An outbound action when a rule fires (HTTP, MQTT, email, push, broker) |
|
||||
| **ONVIF** | Camera-discovery and control protocol used by IP cameras |
|
||||
| **SSE** | Server-Sent Events — one-way push from server to client over HTTPS |
|
||||
| **RFC 7807** | The `application/problem+json` standard error format |
|
||||
| **Prism** | Stoplight's CLI for spinning up a mock REST server from an OpenAPI spec |
|
||||
| **OpenAPI 3.1** | The contract format used in `openapi.v1.json` |
|
||||
|
||||
---
|
||||
|
||||
*End of document.*
|
||||
@@ -0,0 +1,600 @@
|
||||
# ANSCORE — Layer 2 & Layer 3 Architecture
|
||||
|
||||
> Scope: Layer 2 (ANSVIS Communication Layer (CL), REST `/api/v1` surface, supporting services) and Layer 3 (Qt/QML cross-platform desktop UI). Layer 1 is summarized only where it interacts.
|
||||
>
|
||||
> Contract of record: [`contracts/openapi.v1.json`](../contracts/openapi.v1.json). All UI ↔ CL communication conforms to it.
|
||||
>
|
||||
> Transports:
|
||||
> 1. **REST / HTTPS** — control, CRUD, configuration, deploy
|
||||
> 2. **SSE (`text/event-stream`)** — live event tail
|
||||
> 3. **HLS / RTSP / WebRTC** — live video (descriptor obtained via REST)
|
||||
|
||||
---
|
||||
|
||||
## 1. System context — L1 / L2 / L3
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph L3["Layer 3 — Qt/QML Desktop UI (Win / Mac / Linux)"]
|
||||
UI[Qt/QML application]
|
||||
end
|
||||
|
||||
subgraph L2["Layer 2 — ANSVIS CL"]
|
||||
APIV1["/api/v1 REST surface"]
|
||||
LEGACY["Legacy ANSVIS core<br/>(reused as-is)"]
|
||||
RELAY["Media relay<br/>HLS / RTSP / WebRTC"]
|
||||
SSE["SSE event broadcaster"]
|
||||
STORE["Event DB<br/>+ clip object store"]
|
||||
JOBS["Async job queue"]
|
||||
AUTH["Auth + RBAC"]
|
||||
end
|
||||
|
||||
subgraph L1["Layer 1 — ANSCORE Edge Runtime<br/>(one per target)"]
|
||||
EDGE["Camera + Inference + Triggers"]
|
||||
end
|
||||
|
||||
UI -- "① REST / HTTPS<br/>control + CRUD" --> APIV1
|
||||
UI -- "② SSE / HTTPS<br/>live event tail" --> SSE
|
||||
UI -- "③ HLS / RTSP / WebRTC<br/>live video" --> RELAY
|
||||
|
||||
APIV1 --> AUTH
|
||||
APIV1 --> LEGACY
|
||||
APIV1 --> JOBS
|
||||
APIV1 --> STORE
|
||||
LEGACY --> STORE
|
||||
STORE --> SSE
|
||||
RELAY <--> EDGE
|
||||
LEGACY <--> EDGE
|
||||
```
|
||||
|
||||
**Key idea:** L3 only ever talks to L2. L1 ↔ L2 is a separate protocol (existing ANSVIS behavior, plus new edge work later). The UI team is fully decoupled from L1 velocity.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layer 2 — internal architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph CLIENTS["Clients"]
|
||||
QT["Qt/QML UI"]
|
||||
EXT["3rd-party integrations<br/>(optional)"]
|
||||
end
|
||||
|
||||
subgraph EDGE_API["L2 / api / v1 surface"]
|
||||
ROUTER["REST router"]
|
||||
AUTHMW["Auth middleware<br/>(Bearer)"]
|
||||
VALID["Request validation<br/>(OpenAPI schemas)"]
|
||||
ERR["Error mapper<br/>→ RFC 7807"]
|
||||
RATE["Rate limiter"]
|
||||
SSE_HUB["SSE broadcaster<br/>(per-subscription filter)"]
|
||||
end
|
||||
|
||||
subgraph ADAPTER["v1 Adapter Layer<br/>(per-resource modules)"]
|
||||
CAM_AD["cameras"]
|
||||
MOD_AD["models"]
|
||||
EDGE_AD["edges"]
|
||||
DG_AD["deployment-groups"]
|
||||
TASK_AD["ai-tasks"]
|
||||
EV_AD["events"]
|
||||
FR_AD["fr"]
|
||||
ALPR_AD["alpr"]
|
||||
NOTIF_AD["notifications"]
|
||||
SYS_AD["system"]
|
||||
JOB_AD["jobs"]
|
||||
end
|
||||
|
||||
subgraph LEGACY["Legacy ANSVIS server<br/>(reused as-is)"]
|
||||
LEG_CFG["Config store"]
|
||||
LEG_TASKS["AI task engine"]
|
||||
LEG_FR["FR engine"]
|
||||
LEG_ALPR["ALPR engine"]
|
||||
end
|
||||
|
||||
subgraph INFRA["Infrastructure"]
|
||||
AUTH_SVC["Auth + token store"]
|
||||
JOBS_Q["Job queue<br/>(scans, uploads, deploys, updates)"]
|
||||
EVENTS_DB["Event metadata DB"]
|
||||
CLIPS["Clip / image object store<br/>(S3 / MinIO / FS)"]
|
||||
LOGS["Logs + metrics + health"]
|
||||
RELAY["Media relay<br/>HLS / RTSP / WebRTC"]
|
||||
end
|
||||
|
||||
subgraph L1["Layer 1 edges"]
|
||||
E1["Edge target(s)"]
|
||||
end
|
||||
|
||||
QT --> ROUTER
|
||||
EXT --> ROUTER
|
||||
ROUTER --> AUTHMW --> VALID --> RATE
|
||||
RATE --> ADAPTER
|
||||
ADAPTER --> ERR
|
||||
ADAPTER -.-> ROUTER
|
||||
|
||||
AUTHMW --> AUTH_SVC
|
||||
|
||||
CAM_AD --> LEG_CFG
|
||||
MOD_AD --> LEG_CFG
|
||||
MOD_AD --> CLIPS
|
||||
EDGE_AD --> LEG_CFG
|
||||
DG_AD --> LEG_TASKS
|
||||
TASK_AD --> LEG_TASKS
|
||||
EV_AD --> EVENTS_DB
|
||||
EV_AD --> CLIPS
|
||||
FR_AD --> LEG_FR
|
||||
ALPR_AD --> LEG_ALPR
|
||||
SYS_AD --> LOGS
|
||||
JOB_AD --> JOBS_Q
|
||||
CAM_AD -. "scan / probe" .-> JOBS_Q
|
||||
MOD_AD -. "large upload" .-> JOBS_Q
|
||||
|
||||
LEG_TASKS --> EVENTS_DB
|
||||
EVENTS_DB --> SSE_HUB
|
||||
SSE_HUB --> ROUTER
|
||||
|
||||
LEGACY <--> E1
|
||||
RELAY <--> E1
|
||||
```
|
||||
|
||||
**Responsibilities by module:**
|
||||
|
||||
| Module | Owns |
|
||||
|---|---|
|
||||
| REST router | URL → handler, content negotiation |
|
||||
| Auth middleware | Bearer validation, principal injection, RBAC checks |
|
||||
| Request validation | OpenAPI schema-based body/query validation |
|
||||
| Error mapper | Translates legacy errors / exceptions to `application/problem+json` |
|
||||
| Rate limiter | Per-token / per-IP throttling |
|
||||
| SSE broadcaster | Subscribes to event bus, fans out to UI clients with filter + auth |
|
||||
| v1 adapter (per resource) | Translates v1 request → legacy call(s), reshapes response |
|
||||
| Job queue | Async ops (camera scan, model upload, software update, large deploy) |
|
||||
| Event DB | Indexed event metadata for `/events?...` queries |
|
||||
| Clip / object store | Snapshots and evidence video (presigned URLs) |
|
||||
| Media relay | Brokers live video from edge to UI (HLS now, WebRTC later) |
|
||||
| Auth + token store | Login, refresh, RBAC |
|
||||
|
||||
**Build ownership inside L2** (AI coders managed by you):
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph HUMAN["Human-owned (architect — you)"]
|
||||
H1["REST router + auth middleware"]
|
||||
H2["RFC 7807 error mapper"]
|
||||
H3["OpenAPI validation pipeline"]
|
||||
H4["Auth flow + token store"]
|
||||
H5["RBAC + security review"]
|
||||
H6["L2 ↔ L1 tunnel + signing"]
|
||||
end
|
||||
|
||||
subgraph AI["AI-coder-built (modular adapters)"]
|
||||
A1["cameras adapter"]
|
||||
A2["models adapter + upload pipeline"]
|
||||
A3["edges adapter"]
|
||||
A4["deployment-groups adapter"]
|
||||
A5["ai-tasks adapter"]
|
||||
A6["events adapter + SSE broadcaster"]
|
||||
A7["fr adapter"]
|
||||
A8["alpr adapter"]
|
||||
A9["notifications adapter"]
|
||||
A10["system / health / logs adapter"]
|
||||
A11["job queue + workers"]
|
||||
A12["media relay"]
|
||||
end
|
||||
|
||||
subgraph EXIST["Existing ANSVIS (reused as-is)"]
|
||||
L1["Task engine"]
|
||||
L2["FR engine"]
|
||||
L3["ALPR engine"]
|
||||
L4["Config store"]
|
||||
end
|
||||
|
||||
HUMAN --> AI
|
||||
AI --> EXIST
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Layer 3 — Qt/QML internal architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph QT["Qt 6 + QML — Layer 3"]
|
||||
subgraph SHELL["App Shell"]
|
||||
MAIN["Main window"]
|
||||
ROUTE["Navigation router"]
|
||||
THEME["Design system / theme"]
|
||||
I18N["i18n (qsTr / Linguist)"]
|
||||
AUTH_ST["Auth state + token store"]
|
||||
ERR_UI["Error toast / dialog"]
|
||||
end
|
||||
|
||||
subgraph NET["Network layer"]
|
||||
REST["Generated REST client<br/>(openapi.v1.json → C++/Qt)"]
|
||||
SSE_CL["SSE subscriber<br/>(QNetworkReply chunked)"]
|
||||
MEDIA["Media client<br/>QtMultimedia / GStreamer"]
|
||||
OVERLAY["Bbox overlay renderer<br/>(custom QQuickItem)"]
|
||||
UPLOAD["Multipart + presigned uploader"]
|
||||
end
|
||||
|
||||
subgraph STATE["Domain state (QObject + Q_PROPERTY + signals)"]
|
||||
ST_CAM["CamerasModel"]
|
||||
ST_MOD["ModelsModel"]
|
||||
ST_EDGE["EdgesModel"]
|
||||
ST_DG["DeploymentGroupsModel"]
|
||||
ST_TASK["AITasksModel"]
|
||||
ST_EV["EventsModel + LiveBuffer"]
|
||||
ST_FR["FRPersonsModel"]
|
||||
ST_ALPR["ALPRPlatesModel"]
|
||||
ST_NOTIF["RecipientsModel"]
|
||||
ST_SYS["SystemHealthModel"]
|
||||
end
|
||||
|
||||
subgraph SCREENS["Screens (QML)"]
|
||||
LOGIN["Login"]
|
||||
DASH["Dashboard / targets overview"]
|
||||
CAM_S["Camera management<br/>+ ONVIF discovery<br/>+ calibration"]
|
||||
DG_EDIT["Pipeline editor<br/>(visual DAG)"]
|
||||
TASK_EDIT["AI Task config"]
|
||||
RULE_S["Rules / triggers"]
|
||||
LIVE["Liveview grid"]
|
||||
EV_S["Eventview timeline"]
|
||||
FR_S["FR persons + faces"]
|
||||
ALPR_S["ALPR plates"]
|
||||
MODEL_S["Model registry"]
|
||||
USERS["Users / admin"]
|
||||
SETTINGS["Settings"]
|
||||
end
|
||||
end
|
||||
|
||||
subgraph L2["ANSVIS / api / v1"]
|
||||
BACKEND["REST + SSE + media"]
|
||||
end
|
||||
|
||||
SCREENS --> STATE
|
||||
STATE --> NET
|
||||
NET <--> BACKEND
|
||||
OVERLAY -.-> MEDIA
|
||||
AUTH_ST -.-> REST
|
||||
AUTH_ST -.-> SSE_CL
|
||||
```
|
||||
|
||||
**Module → screen map** (for tasking):
|
||||
|
||||
| Screen | Reads from | Writes via | Notes |
|
||||
|---|---|---|---|
|
||||
| Login | — | `POST /auth/login` | Stores token in `AuthState` |
|
||||
| Dashboard | `GET /edges`, `GET /edges/{id}/health`, `GET /system/health` | — | Auto-refresh every 5s |
|
||||
| Camera management | `GET /cameras`, `GET /cameras/{id}/snapshot`, `POST /cameras/probe` | `POST/PATCH/DELETE /cameras`, `POST /cameras/scan` (async job) | ONVIF discovery + calibration overlay |
|
||||
| Pipeline editor | `GET /deployment-groups/{id}`, `GET /ai-tasks/catalog`, `GET /models` | `PUT /deployment-groups/{id}` | Highest-risk feature; QGraphicsView |
|
||||
| AI Task config | `GET /ai-tasks/{id}`, `GET /ai-tasks/catalog` | `POST/PATCH/DELETE /ai-tasks`, `POST /ai-tasks/{id}/start|stop` | Schema-driven forms |
|
||||
| Rules / triggers | `GET /triggers/types` | embedded in deployment-group / task body | `POST /triggers/test` |
|
||||
| Liveview | `GET /cameras/{id}/liveview` | — | HLS in v1, WebRTC later; overlay sync to PTS |
|
||||
| Eventview | `GET /events?filters`, `GET /events/stream` (SSE), `GET /events/{id}/image`, `GET /events/{id}/clip` | — | Virtualized list for 100k+ events |
|
||||
| FR persons + faces | `GET /fr/persons`, `GET /fr/persons/{id}/faces` | `POST/PATCH/DELETE /fr/persons`, `POST /fr/persons/{id}/faces` (multipart) | Multipart image upload |
|
||||
| ALPR plates | `GET /alpr/plates`, `GET /alpr/plate-groups` | `POST/DELETE /alpr/plates`, `PATCH /alpr/plate-groups/{id}` | Bulk register/deregister |
|
||||
| Model registry | `GET /models` | `POST /models` (multipart), `POST /models:initiate-upload` for big files | Upload progress UI |
|
||||
| Users / admin | `GET /users` | `POST/PATCH/DELETE /users/{id}` | Admin role only |
|
||||
| Settings | `GET /system/info`, `GET /system/version`, `GET /system/update` | `POST /system/update` | |
|
||||
|
||||
---
|
||||
|
||||
## 4. Sequence flows
|
||||
|
||||
### 4.1 Configure & deploy — typical operator workflow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User as Operator
|
||||
participant UI as Qt UI
|
||||
participant API as ANSVIS /api/v1
|
||||
participant LEG as ANSVIS core
|
||||
participant EDGE as L1 edge
|
||||
|
||||
User->>UI: Open Cameras screen
|
||||
UI->>API: GET /cameras?page=1
|
||||
API->>LEG: legacy list
|
||||
LEG-->>API: cameras
|
||||
API-->>UI: 200 {items, page, total}
|
||||
|
||||
User->>UI: Add RTSP camera (form)
|
||||
UI->>API: POST /cameras
|
||||
Note right of UI: body has nested credentials,<br/>capturing, image_size — no<br/>stringified JSON
|
||||
API->>LEG: legacy add
|
||||
LEG-->>API: id=123
|
||||
API-->>UI: 201 Location: /cameras/123
|
||||
|
||||
User->>UI: Configure AI task
|
||||
UI->>API: POST /ai-tasks {camera_id:123, ...}
|
||||
API->>LEG: legacy create
|
||||
LEG-->>API: id=456
|
||||
API-->>UI: 201 {id:456}
|
||||
|
||||
User->>UI: Start task
|
||||
UI->>API: POST /ai-tasks/456/start
|
||||
API->>LEG: dispatch
|
||||
LEG->>EDGE: config + start
|
||||
EDGE-->>LEG: running
|
||||
API-->>UI: 202 {state:starting}
|
||||
|
||||
loop status poll (or SSE later)
|
||||
UI->>API: GET /ai-tasks/456/status
|
||||
API-->>UI: 200 {state:running, fps:14.2}
|
||||
end
|
||||
```
|
||||
|
||||
### 4.2 Live event tail + clicking into evidence
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant UI
|
||||
participant API as /api/v1
|
||||
participant SSE as SSE broadcaster
|
||||
participant CLIPS as Clip store
|
||||
participant EDGE
|
||||
|
||||
User->>UI: Open Eventview (task=456)
|
||||
UI->>API: GET /events?task_id=456&page=1
|
||||
API-->>UI: 200 historical events
|
||||
UI->>API: GET /events/stream?task_id=456
|
||||
API-->>UI: text/event-stream (open)
|
||||
|
||||
EDGE->>API: event arrives (via L1↔L2)
|
||||
API->>SSE: push EventRecord
|
||||
SSE-->>UI: data: {id:E1, ts, object:car, bbox, ...}
|
||||
|
||||
User->>UI: Click event E1
|
||||
UI->>API: GET /events/E1
|
||||
API-->>UI: 200 EventRecord (full)
|
||||
UI->>API: GET /events/E1/image?width=640
|
||||
API-->>UI: image/jpeg bytes
|
||||
|
||||
User->>UI: Play clip
|
||||
UI->>API: GET /events/E1/clip
|
||||
API->>CLIPS: presign GET
|
||||
CLIPS-->>API: presigned URL
|
||||
API-->>UI: 200 {url, expires_at}
|
||||
UI->>CLIPS: GET <presigned URL>
|
||||
CLIPS-->>UI: MP4 bytes
|
||||
UI->>UI: play in QtMultimedia
|
||||
```
|
||||
|
||||
### 4.3 Liveview with bbox overlay
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant UI
|
||||
participant API
|
||||
participant RELAY as Media relay
|
||||
participant EDGE
|
||||
participant SSE
|
||||
|
||||
User->>UI: Open Liveview (cam 123, task 456)
|
||||
UI->>API: GET /cameras/123/liveview?transport=hls
|
||||
API->>RELAY: ensure HLS for cam 123
|
||||
RELAY->>EDGE: pull RTSP
|
||||
RELAY-->>API: hls_url + short-lived token
|
||||
API-->>UI: 200 {url, transport:hls, auth_token, expires_at}
|
||||
|
||||
UI->>RELAY: GET hls_url (token)
|
||||
RELAY-->>UI: m3u8 + segments
|
||||
UI->>UI: Render video (QtMultimedia)
|
||||
|
||||
UI->>API: GET /events/stream?task_id=456 (SSE)
|
||||
API-->>UI: text/event-stream
|
||||
loop per event
|
||||
SSE-->>UI: bbox + ts
|
||||
UI->>UI: overlay synced to PTS
|
||||
end
|
||||
```
|
||||
|
||||
### 4.4 Async job — camera network scan
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant UI
|
||||
participant API
|
||||
participant JOBS as Job queue
|
||||
participant SCAN as ONVIF scanner
|
||||
|
||||
User->>UI: Scan 192.168.1.0/24
|
||||
UI->>API: POST /cameras/scan
|
||||
API->>JOBS: enqueue
|
||||
JOBS-->>API: job_id=j1
|
||||
API-->>UI: 202 {job_id:j1, status:queued, links:{self:/jobs/j1}}
|
||||
|
||||
JOBS->>SCAN: run
|
||||
loop poll until terminal
|
||||
UI->>API: GET /jobs/j1
|
||||
API-->>UI: 200 {status:running, progress:0.4}
|
||||
end
|
||||
SCAN-->>JOBS: results
|
||||
UI->>API: GET /jobs/j1
|
||||
API-->>UI: 200 {status:succeeded, result:{discovered:[...]}}
|
||||
```
|
||||
|
||||
### 4.5 Large model upload — initiate / complete pattern
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User
|
||||
participant UI
|
||||
participant API
|
||||
participant OBJ as Object store
|
||||
|
||||
User->>UI: Pick model.zip (500 MB)
|
||||
UI->>API: POST /models:initiate-upload {filename, size_bytes, checksum}
|
||||
API->>OBJ: presign PUT
|
||||
OBJ-->>API: presigned_url
|
||||
API-->>UI: 200 {upload_id, presigned_url, expires_at}
|
||||
|
||||
UI->>OBJ: PUT <presigned_url> (binary stream, with progress)
|
||||
OBJ-->>UI: 200 OK
|
||||
|
||||
UI->>API: POST /models:complete-upload {upload_id, metadata}
|
||||
API->>OBJ: verify checksum
|
||||
OBJ-->>API: ok
|
||||
API-->>UI: 201 Model
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Deployment topology
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph CUSTOMER["Customer site / cloud"]
|
||||
subgraph DESKTOPS["Operator workstations"]
|
||||
D1["Win desktop<br/>Qt UI"]
|
||||
D2["Mac desktop<br/>Qt UI"]
|
||||
D3["Linux desktop<br/>Qt UI"]
|
||||
end
|
||||
|
||||
subgraph SERVER["ANSVIS server host"]
|
||||
NGINX["Reverse proxy<br/>TLS terminator"]
|
||||
APP["ANSVIS app<br/>(adapter + legacy core)"]
|
||||
RELAY["Media relay"]
|
||||
OBJ["Object store<br/>(S3/MinIO/FS)"]
|
||||
DB["DBs<br/>(config / events)"]
|
||||
end
|
||||
|
||||
subgraph EDGES["Edge targets"]
|
||||
E1["Linux x86 + NV"]
|
||||
E2["Win x86 + NV"]
|
||||
E3["Jetson Orin"]
|
||||
end
|
||||
end
|
||||
|
||||
D1 -- "TLS 443<br/>REST + SSE + HLS" --> NGINX
|
||||
D2 -- "TLS 443" --> NGINX
|
||||
D3 -- "TLS 443" --> NGINX
|
||||
NGINX --> APP
|
||||
NGINX --> RELAY
|
||||
APP --> DB
|
||||
APP --> OBJ
|
||||
RELAY <--> EDGES
|
||||
APP <--> EDGES
|
||||
```
|
||||
|
||||
**Network rules to communicate to the customer:**
|
||||
- Outbound TCP 443 from each operator workstation to ANSVIS server.
|
||||
- Inbound 443 on ANSVIS server.
|
||||
- Whatever protocol L1 ↔ L2 needs (TCP 443 if everything tunneled; or per-edge ports if direct).
|
||||
- No need for the workstation to reach edges directly — Media relay proxies.
|
||||
|
||||
---
|
||||
|
||||
## 6. L3 — engineer ownership (6 engineers)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph E1["E1 — UI Lead / Shell Architect"]
|
||||
E1A["Qt 6 + CMake monorepo"]
|
||||
E1B["Generated REST client from openapi.v1.json"]
|
||||
E1C["Auth state + token store"]
|
||||
E1D["Design system / theme"]
|
||||
E1E["Navigation router"]
|
||||
E1F["Packaging Win/Mac/Linux<br/>signing, notarize, auto-update"]
|
||||
E1G["CI matrix"]
|
||||
end
|
||||
|
||||
subgraph E2["E2 — Pipeline Editor Specialist"]
|
||||
E2A["Visual DAG editor<br/>QGraphicsView in QQuickWidget"]
|
||||
E2B["Node library + connections"]
|
||||
E2C["Schema-driven param panels"]
|
||||
E2D["Undo / redo, save / version"]
|
||||
end
|
||||
|
||||
subgraph E3["E3 — Liveview / Media"]
|
||||
E3A["QtMultimedia HLS player<br/>(v1)"]
|
||||
E3B["Multi-stream grid"]
|
||||
E3C["Bbox overlay (QQuickItem + QSGGeometryNode)"]
|
||||
E3D["Clip player (evidence)"]
|
||||
E3E["WebRTC via GStreamer (v2)"]
|
||||
end
|
||||
|
||||
subgraph E4["E4 — Config Forms"]
|
||||
E4A["Schema-driven QML forms<br/>(from openapi.v1.json)"]
|
||||
E4B["Camera + ONVIF discovery flow"]
|
||||
E4C["Camera calibration UI<br/>(ROI / zones / homography)"]
|
||||
E4D["Model + plugin + trigger forms"]
|
||||
end
|
||||
|
||||
subgraph E5["E5 — Dashboard / Eventview"]
|
||||
E5A["Target dashboard cards + charts"]
|
||||
E5B["Event timeline (virtualized)"]
|
||||
E5C["SSE subscriber + LiveBuffer"]
|
||||
E5D["Filter / search / evidence viewer"]
|
||||
E5E["Multi-target monitoring"]
|
||||
end
|
||||
|
||||
subgraph E6["E6 — UX / Cross-platform QA"]
|
||||
E6A["Design polish, a11y, i18n"]
|
||||
E6B["Install / upgrade testing<br/>Win + Mac + Linux"]
|
||||
E6C["Crash reporting (Sentry/Crashpad)"]
|
||||
E6D["QML Profiler perf passes"]
|
||||
E6E["User docs surface"]
|
||||
end
|
||||
|
||||
CONTRACT[(openapi.v1.json<br/>frozen contract)]
|
||||
E1 -.-> CONTRACT
|
||||
E2 -.-> CONTRACT
|
||||
E3 -.-> CONTRACT
|
||||
E4 -.-> CONTRACT
|
||||
E5 -.-> CONTRACT
|
||||
```
|
||||
|
||||
**Critical-path order:**
|
||||
|
||||
1. **Week 1–2 (E1 only)**: monorepo, generated REST client, auth, design system stub, `make dev` brings up Prism mock. This unblocks everyone else.
|
||||
2. **Week 1–2 (E2 in parallel)**: node-editor spike. Highest schedule risk → de-risk early.
|
||||
3. **Week 2+ (E3, E4, E5 in parallel)**: each owns a vertical against the mock CL. E6 starts integration testing.
|
||||
4. **Week 4+**: cut from mock CL to real ANSVIS `/api/v1` as adapter endpoints land.
|
||||
|
||||
---
|
||||
|
||||
## 7. What gates what (dependency chain)
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CONTRACT["openapi.v1.json<br/>(frozen)"]
|
||||
MOCK["Prism mock server"]
|
||||
ADAPT["ANSVIS /api/v1 adapter<br/>(AI coders, per-resource)"]
|
||||
LEGACY["Legacy ANSVIS"]
|
||||
UI_SHELL["L3 shell + REST client (E1)"]
|
||||
UI_FEAT["L3 screens (E2-E6)"]
|
||||
REAL["Real backend integration"]
|
||||
SHIP["Ship v1"]
|
||||
|
||||
CONTRACT --> MOCK
|
||||
CONTRACT --> ADAPT
|
||||
ADAPT --> LEGACY
|
||||
MOCK --> UI_SHELL --> UI_FEAT
|
||||
UI_FEAT --> REAL
|
||||
ADAPT --> REAL
|
||||
REAL --> SHIP
|
||||
```
|
||||
|
||||
- The contract is the *only* thing both sides block on.
|
||||
- UI does not wait for the adapter — develops against Prism.
|
||||
- Adapter team does not wait for UI — implements per-resource modules in parallel.
|
||||
- Integration is the joining point.
|
||||
|
||||
---
|
||||
|
||||
## 8. Open decisions that affect this architecture
|
||||
|
||||
These are unchanged from earlier conversations; capturing here so the team has them in one place:
|
||||
|
||||
1. **Field naming** — `snake_case` (current default in `openapi.v1.json`) or `camelCase`?
|
||||
2. **Auth scheme** — keep Bearer (current) or move to OAuth2/OIDC for v1?
|
||||
3. **Mock-server pinning** — Prism for free, or build a richer custom mock?
|
||||
4. **Liveview transport for v1** — HLS only (recommended), or RTSP-direct on LAN, or jump straight to WebRTC?
|
||||
5. **Object store choice** — local FS (single host), MinIO (single host scalable), or S3 (cloud)?
|
||||
6. **Auto-update** for the Qt client — Sparkle on Mac, Squirrel/MSIX on Windows, AppImage on Linux. Confirm budget for each.
|
||||
7. **Contract repo** — co-located in `ANSCORE/contracts/` (current) or split into a separate `anscore-contracts` repo?
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-05-26 — diagrams reflect `openapi.v1.json` v1.0.0 draft.*
|
||||
@@ -0,0 +1,573 @@
|
||||
# PLAN — Port ANSCORE Licensing Core to Linux (x86_64 + Jetson aarch64)
|
||||
|
||||
**Status:** Draft, awaiting product-side decisions before execution
|
||||
**Target platforms:** Ubuntu 22.04 x86_64, JetPack 6.x (Ubuntu 22.04 aarch64)
|
||||
**Components in scope:** `core/anslicensing`, `core/ANSLicensingSystem`, `core/ANSLibsLoader`
|
||||
**Estimated effort:** ~6–7 focused weeks for one engineer
|
||||
**Risk:** Medium (HWID compatibility with license server is the dominant risk)
|
||||
**Owner:** Tuan Nghia Nguyen
|
||||
**Branch to create:** `linux-licensing-port`
|
||||
|
||||
---
|
||||
|
||||
## Decisions already made (do not re-litigate)
|
||||
|
||||
1. **Three components are in scope, in this order**: `ANSLibsLoader` (easiest), `anslicensing` (medium), `ANSLicensingSystem` (hardest). Engine modules (`ANSODEngine`, `ANSCV`, etc.) are NOT part of this plan — they come after licensing is up.
|
||||
2. **No LabVIEW support on Linux.** The `_LV` exports and `LabVIEWHeader/extcode.h` includes are stripped from the Linux build via `#ifdef _WIN32`. The C++ and C-string (`_CS`) entry points become the only Linux surface.
|
||||
3. **`lfreist/hwinfo` stays.** It is already vendored at `C:/ANSLibs/ANS-HWiNFO/` and is cross-platform (verified — its `platform.h` defines `HWINFO_UNIX` on Linux). All 8 `hwinfo::` call sites in `ANSLicense.cpp` are portable as-is. No replacement library needed.
|
||||
4. **HWID gains real signals on Linux.** Today `hwid.cpp` Linux branches stub the SMBIOS UUID slot with `"4294967296"` and leave `GetHDDPropertyList` empty (2-point HWID strength vs Windows 4-point). We will fill those slots using `hwinfo::MainBoard::serialNumber()` and `hwinfo::RAM::serialNumber()` for parity.
|
||||
5. **`rand.cpp` Linux path is replaced with `getrandom(2)`**. The current `srand(time(NULL)) + rand()` path is cryptographically broken and a security-correctness issue, not just a portability one.
|
||||
6. **`DetectClockManipulation` on Linux ships as a best-effort stub.** Reading `journalctl` history is expensive and not always available (containers, no systemd). It will log a warning and return `false`. Acceptable anti-tamper degradation; flagged for follow-up.
|
||||
7. **MediaClient and other non-licensing Windows surface stays Windows-only.** This plan does not touch them.
|
||||
8. **HWiNFO is NOT the commercial HWiNFO64.** It's the open-source MIT-licensed [`lfreist/hwinfo`](https://github.com/lfreist/hwinfo) C++ library. No commercial license concern.
|
||||
|
||||
## Pre-work already completed (discovery, not code)
|
||||
|
||||
- ✅ Confirmed `core/anslicensing/` already has Linux scaffolding: `CMakeLists.txt` branches on `WIN32` and links `curl ssl crypto`; `precomp.h` has POSIX shims; `download.cpp` has a complete libcurl path; `hwid.cpp` has Linux CPU-ID and MAC code.
|
||||
- ✅ Inventoried Windows API surface in `ANSLicensingSystem/ANSLicense.cpp` (4,021 LOC):
|
||||
- Only 2 `#ifdef _WIN32` blocks — the file assumes Windows top-to-bottom
|
||||
- 8 × `hwinfo::` calls — **portable as-is**
|
||||
- 12 × PDH counter sites — need `/proc` rewrite (Phase 3.3)
|
||||
- 7 × DXGI sites — need NVML/libdrm rewrite (Phase 3.4)
|
||||
- 1 × WMI `MSAcpi_ThermalZoneTemperature` query — Linux `/sys/class/thermal/` (Phase 3.2)
|
||||
- 1 × WinHTTP block — replace with libcurl already in `anslicensing/download.cpp` (Phase 3.5)
|
||||
- 1 × `DnsQuery_A` — replace with `getaddrinfo` (Phase 3.6)
|
||||
- Misc: `GlobalMemoryStatusEx`, `GetProcessMemoryInfo`, `GetSystemDirectoryW + GetDiskFreeSpaceExW`, `GetCurrentProcessId` (Phase 3.7)
|
||||
- ✅ Confirmed `lfreist/hwinfo` cross-platform support via its `platform.h` and the header set at `C:/ANSLibs/ANS-HWiNFO/include/hwinfo/`.
|
||||
|
||||
---
|
||||
|
||||
## Open product decisions (BLOCK Phase 0)
|
||||
|
||||
These must be resolved with the licensing-backend team before any code is written. They determine the shape of Phase 1.
|
||||
|
||||
### Decision 1 — HWID format compatibility with the license server
|
||||
|
||||
The license server validates a HWID hash that's currently produced from Windows WMI data (`Win32_ComputerSystemProduct.UUID`, `Win32_NetworkAdapter.MACAddress`, `Win32_PhysicalMedia.SerialNumber`, `Win32_Processor.ProcessorId`). On Linux we will produce hashes from different data sources (SMBIOS via `/sys/class/dmi/id/`, NIC MACs via `getifaddrs`, RAM serial via DMI, CPU ID via `__get_cpuid`). The hash format (the bit-packed 125-bit `BitStream3` in `hwid.cpp`) stays identical, but the **values being hashed differ**. Three options:
|
||||
|
||||
- **A. Unified HWID, same algorithm**: server treats Windows and Linux licenses identically; admin has to physically activate each device once and the hash is opaque. **Simplest. Recommended.**
|
||||
- **B. Separate Linux license pool**: server tracks platform field; Linux activations come from a dedicated key range. More work backend-side.
|
||||
- **C. Backward-compat dance**: keep some Windows-specific fields empty on Linux (status quo) — license matching weakens. **Reject.**
|
||||
|
||||
**Owner to confirm with backend team before Phase 0.**
|
||||
|
||||
### Decision 2 — HWiNFO `MainBoard::serialNumber()` availability on Jetson
|
||||
|
||||
`lfreist/hwinfo` reads `/sys/class/dmi/id/board_serial` on Linux. **On Jetson this file may not exist** — ARM SBCs use device-tree, not DMI. We need to:
|
||||
|
||||
- Test on a real Jetson Orin/AGX board early.
|
||||
- Define fallback signal: `/proc/device-tree/serial-number` (Jetson exposes this) or eMMC CID (`/sys/block/mmcblk*/device/cid`).
|
||||
|
||||
**Owner needs a Jetson devkit available before Phase 1.**
|
||||
|
||||
### Decision 3 — Boost dependencies on Jetson
|
||||
|
||||
`ANSLicensingSystem` currently links `libboost_log-vc143-mt-x64-1_82.lib` and uses `boost::property_tree::ptree` and `boost::date_time`. Ubuntu 22.04 ships Boost 1.74 by default (`libboost-all-dev`). Choices:
|
||||
|
||||
- **A. Use system Boost on Linux** (1.74). Accept minor API differences; pin via `find_package(Boost 1.74 REQUIRED)`.
|
||||
- **B. Vendor Boost 1.82**. Painful build but exact parity.
|
||||
- **C. Drop Boost.PropertyTree on Linux** and use `nlohmann/json` (already a project dep via `ANSLIBS_DIR/nlohmann`). Smaller dep surface but a code change in `ANSLicense.cpp` JSON output paths.
|
||||
|
||||
**Recommendation: A.** Defer until Phase 0.5 spike confirms it builds.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start for a new session
|
||||
|
||||
If you're a fresh Claude session and the user has asked you to execute this plan:
|
||||
|
||||
1. **Read this entire document end-to-end** before editing anything. The per-file checklist in Appendix A is the source of truth for what changes.
|
||||
2. **Confirm prerequisites are in place**:
|
||||
```bash
|
||||
ls "C:/ANSLibs/ANS-HWiNFO/include/hwinfo/platform.h" # cross-platform lib present
|
||||
git status # clean working tree
|
||||
git branch --show-current # should be linux-licensing-port
|
||||
```
|
||||
3. **Verify the three product decisions above are resolved.** Ask the user to paste the answers if they're not in this doc. Do NOT start Phase 1 without Decision 1 (HWID format) answered.
|
||||
4. **Ask the user which phase to start with.** Default to Phase 0.1.
|
||||
5. **Use TaskCreate** to track progress through the phases — the seven-phase structure (0 through 4 plus per-3.x sub-phases) is the natural top-level task list.
|
||||
6. **Work in small commits.** One file, one logical change, verify build on Windows AND Linux before the next change. The Windows build must stay green at every step.
|
||||
7. **Never modify a `*_LV` function signature.** Even on Linux where we don't compile it, the source still exists on the Windows-shared file. Touch only what's gated by `#ifdef _WIN32`.
|
||||
|
||||
### How to invoke this plan
|
||||
|
||||
The user can paste any of these to start:
|
||||
|
||||
> "Read `docs/PLAN_Linux_Licensing_Port.md` and walk me through Phase 0."
|
||||
|
||||
> "Continue the Linux licensing port. Read `docs/PLAN_Linux_Licensing_Port.md` and ask what's done."
|
||||
|
||||
> "Execute Phase 1.1 from `docs/PLAN_Linux_Licensing_Port.md`."
|
||||
|
||||
### Context the new session might need that isn't in this plan
|
||||
|
||||
- **Build system on Linux**: CMake 3.28+, Ninja, GCC 11+ on Ubuntu 22.04. Cross-compile to Jetson via JetPack 6.x SDK Manager + sysroot.
|
||||
- **CUDA on Linux**: CUDA 12.x, cuDNN, TensorRT 10.x from `apt` or NVIDIA's repo.
|
||||
- **Licensing server endpoint**: ask the user for the staging URL — it is NOT in source control.
|
||||
- **Test hardware**: x86 Ubuntu box AND a Jetson Orin Nano/AGX devkit are both required. Do not declare Phase 1 done from x86 testing alone.
|
||||
|
||||
---
|
||||
|
||||
## 1. Background
|
||||
|
||||
ANSCORE targets Linux (Jetson + industrial x86) per the product roadmap. The Flutter mobile app will be replaced by a Qt QML UI talking to ANSCORE over gRPC + RTSP. Licensing is the blocking dependency: **no module can be loaded without `ANSLicensingSystem` validating the license**, so it must come first.
|
||||
|
||||
The three components are layered:
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ Module DLLs (ANSCV, ANSOD,…) │ ← consumers, NOT part of this plan
|
||||
├──────────────────────────────┤
|
||||
│ ANSLicensingSystem (façade) │ ← Phase 3 (4–5 weeks)
|
||||
├──────────────────────────────┤
|
||||
│ anslicensing (SDK) │ ← Phase 1 (2–3 weeks)
|
||||
│ ANSLibsLoader (dynload) │ ← Phase 2 (1 week)
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
`ANSLicensingSystem` depends on `anslicensing`; `ANSLibsLoader` is independent of both but consumed by `ANSCV` later. Phase ordering keeps the build green at every step.
|
||||
|
||||
## 2. Goals
|
||||
|
||||
- All three components build on Ubuntu 22.04 x86_64 and JetPack 6.x aarch64.
|
||||
- `libANSLicensingSystem.so` exports the same C++ symbols and C ABI as the Windows DLL (less LabVIEW exports).
|
||||
- Linux HWID is a 4-signal hash, equivalent strength to Windows.
|
||||
- License validation works against the existing license server.
|
||||
- All Windows behavior preserved unchanged. Zero behavioral regressions on Windows builds.
|
||||
- `rand.cpp` on Linux uses `getrandom(2)` instead of insecure `rand()`.
|
||||
|
||||
## 3. Non-goals
|
||||
|
||||
- LabVIEW support on Linux.
|
||||
- macOS port (separate effort).
|
||||
- `DetectClockManipulation` feature parity on Linux (acceptable degradation, logged).
|
||||
- Re-architecting the licensing protocol (wire compat preserved).
|
||||
- Engine modules (`ANSODEngine`, `ANSCV`, etc.) — separate plans.
|
||||
- Build infra changes (Conan/vcpkg adoption, etc.).
|
||||
|
||||
## 4. Phases
|
||||
|
||||
### Phase 0 — Windows-side prep (1 week, zero behavioral change)
|
||||
|
||||
Done on Windows. No Linux changes yet. Each step must keep the Windows build green and tests passing.
|
||||
|
||||
- **0.1** Add `ANSCORE_API` visibility macro to all three components' public headers:
|
||||
```cpp
|
||||
#if defined(_WIN32)
|
||||
#if defined(ANSCORE_EXPORTS)
|
||||
#define ANSCORE_API __declspec(dllexport)
|
||||
#else
|
||||
#define ANSCORE_API __declspec(dllimport)
|
||||
#endif
|
||||
#elif defined(__GNUC__)
|
||||
#define ANSCORE_API __attribute__((visibility("default")))
|
||||
#else
|
||||
#define ANSCORE_API
|
||||
#endif
|
||||
```
|
||||
Replace `__declspec(dllexport)` / `__declspec(dllimport)` site-by-site. Test on Windows that the resulting DLL exports the same symbol set (`dumpbin /exports`).
|
||||
- **0.2** Split LabVIEW exports out of `ANSLicense.h` into a new `ANSLicense_LV.h` that includes the LabVIEW header and declares only the `_LV` functions. Update Windows-side `ANSLicense.cpp` to include `ANSLicense_LV.h`. **Result: `ANSLicense.h` has zero LabVIEW types**, so Linux consumers don't drag in `extcode.h`.
|
||||
- **0.3** Strip `<windows.h>`, `<winhttp.h>`, etc. from public headers (`ANSLIB.h:6 #include <windows.h>` line is the worst offender). Use forward declarations or guard with `#ifdef _WIN32` where needed in implementation files only.
|
||||
- **0.4** Vendor `lfreist/hwinfo` as a git submodule at `3rdparty/hwinfo` (or confirm `C:/ANSLibs/ANS-HWiNFO/` is the canonical copy and update CMake to point at it consistently). Add a top-level CMake option `ANSCORE_USE_VENDORED_HWINFO` that defaults to ON.
|
||||
- **0.5** Stand up an Ubuntu 22.04 build environment (CI runner or local VM). Install: `build-essential cmake ninja-build libboost-all-dev libcurl4-openssl-dev libssl-dev libzip-dev zlib1g-dev libnvidia-ml-dev libdrm-dev libsensors4-dev`. Verify CUDA 12.x + TensorRT 10.x are reachable. Smoke test: `cmake -B build && ninja -C build core/anslicensing` should currently fail — but it should fail with **predictable errors** (missing hwinfo Linux build, etc.), not config errors.
|
||||
|
||||
**Acceptance for Phase 0**:
|
||||
- Windows build green, all existing tests pass.
|
||||
- `dumpbin /exports ANSLicensingSystem.dll` symbol set is byte-identical to baseline.
|
||||
- `ANSLicense.h` does not include `LabVIEWHeader/extcode.h`.
|
||||
- Ubuntu environment is reproducible.
|
||||
- Decision 1, 2, 3 above are answered in writing.
|
||||
|
||||
### Phase 1 — Port `core/anslicensing` (2–3 weeks)
|
||||
|
||||
This is the lowest-level SDK. Already 80% portable.
|
||||
|
||||
- **1.1** **Strengthen Linux HWID** in `hwid.cpp`:
|
||||
- Replace the `propList.push_back("4294967296")` stub at line 254 with `hwinfo::MainBoard board; propList.push_back(board.serialNumber());`. Falls back to `/proc/device-tree/serial-number` on aarch64 if board_serial is missing.
|
||||
- Implement `GetHDDPropertyList` on Linux at line 142: enumerate block devices via `/sys/block/*/device/wwid` or `/sys/block/*/device/serial`. Filter to non-removable (skip `/sys/block/*/removable == 1`).
|
||||
- Add the same source to the `MatchCurrentHardwareId` Linux branches (lines 416, 538).
|
||||
- Cross-test: HWID produced on Ubuntu must validate on the same machine across reboots.
|
||||
- **1.2** **Replace `rand.cpp` Linux RNG** with `getrandom(2)`:
|
||||
```cpp
|
||||
#include <sys/random.h>
|
||||
// ::srand(time(NULL)); ← DELETE
|
||||
// rnd = ::rand(); ← DELETE
|
||||
ssize_t n = getrandom(&rnd, sizeof(rnd), 0);
|
||||
if (n != sizeof(rnd)) {
|
||||
// fallback: open /dev/urandom directly
|
||||
}
|
||||
```
|
||||
Keep `random::random()` constructor cheap (no kernel call); make `random::rand()` the syscall site. Document the change in a header comment.
|
||||
- **1.3** **`DetectClockManipulation` Linux stub** in `helper.cpp` — return `false` with `ANS_DBG("ClockTamper", "skipped on Linux — no-op fallback")`. Document as a known degradation.
|
||||
- **1.4** **Wire CMake on Linux**. The CMakeLists already has the Linux branch; verify:
|
||||
- `find_package(CURL REQUIRED)` resolves
|
||||
- `target_link_libraries(... curl ssl crypto)` links cleanly
|
||||
- Add `find_package(hwinfo REQUIRED)` or use the submodule
|
||||
- **1.5** **Round-trip test**: a small test binary that calls `HardwareId::GetCurrentHardwareId()`, persists the string, then calls `HardwareId::MatchCurrentHardwareId(saved)` and asserts true. Run on Ubuntu x86 AND a Jetson devkit.
|
||||
|
||||
**Acceptance for Phase 1**:
|
||||
- `libanslicensing.so` builds on Ubuntu 22.04 x86_64 and Jetson aarch64.
|
||||
- Round-trip HWID test passes on both targets across at least 3 reboots.
|
||||
- `strings libanslicensing.so | grep -c '4294967296'` returns 0.
|
||||
- Static analysis (cppcheck or clang-tidy) shows no new warnings on Linux build.
|
||||
|
||||
### Phase 2 — Port `core/ANSLibsLoader` (1 week)
|
||||
|
||||
Mechanical port from `LoadLibrary`/`GetProcAddress` to `dlopen`/`dlsym`. Independent of Phase 1 and Phase 3 — can be done in parallel.
|
||||
|
||||
- **2.1** Port `DynLibUtils.cpp` core helpers:
|
||||
```cpp
|
||||
#ifdef _WIN32
|
||||
HMODULE LoadLib(const char* p) { return LoadLibraryA(p); }
|
||||
void* GetSym(HMODULE h, const char* s) { return GetProcAddress(h, s); }
|
||||
void UnloadLib(HMODULE h) { FreeLibrary(h); }
|
||||
#else
|
||||
void* LoadLib(const char* p) { return dlopen(p, RTLD_NOW | RTLD_LOCAL); }
|
||||
void* GetSym(void* h, const char* s) { return dlsym(h, s); }
|
||||
void UnloadLib(void* h) { dlclose(h); }
|
||||
#endif
|
||||
```
|
||||
Wrap the handle type behind an opaque `DynLibHandle` typedef so callers don't see the difference.
|
||||
- **2.2** Update `CvLoader.cpp`, `NvDynLoader.cpp`, `OvLoader.cpp`, `EPLoader.cpp` to use the cross-platform helpers. Most logic is search-path discovery — that needs branching too:
|
||||
- Windows: `C:/ANSLibs/...` paths
|
||||
- Linux: `/opt/ANSLibs/...`, `/usr/lib/x86_64-linux-gnu/`, `/usr/local/cuda/lib64/`, and `${LD_LIBRARY_PATH}`
|
||||
- **2.3** Naming convention: Windows `.dll`, Linux `.so` with `lib` prefix. Centralize in a `PLATFORM_DLL_NAME("opencv_world")` macro that expands to `"opencv_world.dll"` on Windows and `"libopencv_world.so"` on Linux.
|
||||
- **2.4** Symbol visibility: Linux `.so` exports everything by default unless built with `-fvisibility=hidden`. Apply `-fvisibility=hidden` globally in the top-level CMakeLists and use the `ANSCORE_API` macro to opt in to exports.
|
||||
- **2.5** Smoke test: `ANSLibsLoader` opens `libopencv_world.so` on Ubuntu and returns valid handles for a known set of OpenCV symbols.
|
||||
|
||||
**Acceptance for Phase 2**:
|
||||
- `libANSLibsLoader.so` builds and runs.
|
||||
- All four sub-loaders (CV/OV/NV/EP) load their respective libraries successfully on Linux.
|
||||
- No symbol-visibility regressions on Windows (verify with `dumpbin /exports`).
|
||||
|
||||
### Phase 3 — Port `core/ANSLicensingSystem` (4–5 weeks)
|
||||
|
||||
The big one. Split into independently mergeable PRs.
|
||||
|
||||
#### 3.1 — Misc Win32 cleanup (1 day)
|
||||
|
||||
- `GlobalMemoryStatusEx` → read `/proc/meminfo` MemTotal / MemAvailable
|
||||
- `GetProcessMemoryInfo` → read `/proc/self/status` VmRSS, VmSwap, VmPeak
|
||||
- `GetSystemDirectoryW + GetDiskFreeSpaceExW` (line 1056-1064) → `statvfs("/")`
|
||||
- `GetCurrentProcessId` → `getpid()`
|
||||
- `WideCharToMultiByte` / `WideToUtf8` → `std::wstring_convert` or just use `std::string` throughout the Linux path (no wide chars needed without WMI)
|
||||
|
||||
#### 3.2 — CPU thermal (1 day)
|
||||
|
||||
Replace `ReadCpuTempCelsiusViaWmi()` (line 603) with a Linux reader:
|
||||
|
||||
```cpp
|
||||
double ReadCpuTempCelsiusLinux() {
|
||||
// Scan /sys/class/thermal/thermal_zone*/type for "x86_pkg_temp" (x86)
|
||||
// or "CPU-therm" / "thermal-fan-est" (Jetson)
|
||||
// Read corresponding /sys/class/thermal/thermal_zone*/temp (milli-Celsius)
|
||||
// Return max across all CPU zones, or -1 if none found
|
||||
}
|
||||
```
|
||||
|
||||
Keep the Windows function intact behind `#ifdef _WIN32`. Dispatch through a single `ReadCpuTempCelsius()` wrapper.
|
||||
|
||||
#### 3.3 — System health sampler / PDH rewrite (1 week)
|
||||
|
||||
The `HealthSampler` class (lines 906–1089) is the largest single port. Build a Linux `HealthSamplerLinux` class with the same public API as the Windows one. Then dispatch at instantiation:
|
||||
|
||||
```cpp
|
||||
#ifdef _WIN32
|
||||
using HealthSampler = HealthSamplerWin;
|
||||
#else
|
||||
using HealthSampler = HealthSamplerLinux;
|
||||
#endif
|
||||
```
|
||||
|
||||
PDH counter → Linux source mapping:
|
||||
|
||||
| PDH counter | Linux source |
|
||||
|---|---|
|
||||
| `\Processor Information(_Total)\% Processor Time` | `/proc/stat` delta of (user+nice+system) vs idle |
|
||||
| `\Processor Information(_Total)\% Processor Performance` | `/sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq` / base freq |
|
||||
| `\Processor Information(_Total)\% Processor Utility` | Same as Processor Time on Linux (no MS-specific util concept) |
|
||||
| `\PhysicalDisk(_Total)\% Disk Time` | `/proc/diskstats` field 13 (io_time ms / interval ms) |
|
||||
| `\PhysicalDisk(_Total)\Disk Read Bytes/sec` | `/proc/diskstats` field 6 × 512 / interval |
|
||||
| `\PhysicalDisk(_Total)\Disk Write Bytes/sec` | `/proc/diskstats` field 10 × 512 / interval |
|
||||
| `\Network Interface(*)\Bytes Received/Sent/sec` | `/proc/net/dev` rx_bytes / tx_bytes deltas |
|
||||
| `\Network Interface(*)\Current Bandwidth` | `/sys/class/net/*/speed` (Mbit/s) |
|
||||
| `\GPU Engine(*)\Utilization Percentage` | NVML `nvmlDeviceGetUtilizationRates` |
|
||||
| `\GPU Process Memory(*)\Dedicated Usage` | NVML `nvmlDeviceGetMemoryInfo` |
|
||||
|
||||
The sampler keeps a `prev_*` snapshot for delta computation (no PDH built-in differencing on Linux). Sample interval: same 2-second cadence as Windows.
|
||||
|
||||
Acceptance: the populated `ANSCENTER::SystemHealthInfo` struct has all the same fields filled on Linux as on Windows (allowing -1 / empty for fields that genuinely don't exist).
|
||||
|
||||
#### 3.4 — GPU adapter enumeration (1 week)
|
||||
|
||||
Replace `EnumerateGpuAdapters` (line 721) with NVML on systems with NVIDIA drivers, falling back to libdrm:
|
||||
|
||||
```cpp
|
||||
std::vector<GpuAdapter> EnumerateGpuAdaptersLinux() {
|
||||
std::vector<GpuAdapter> out;
|
||||
|
||||
// Try NVML first (covers Jetson + dGPU x86)
|
||||
if (nvmlInit_v2() == NVML_SUCCESS) {
|
||||
unsigned int count = 0;
|
||||
nvmlDeviceGetCount_v2(&count);
|
||||
for (unsigned int i = 0; i < count; ++i) {
|
||||
nvmlDevice_t dev;
|
||||
nvmlDeviceGetHandleByIndex_v2(i, &dev);
|
||||
GpuAdapter a;
|
||||
// populate a.name, a.vendorId=0x10DE, a.dedicatedVramMB...
|
||||
out.push_back(a);
|
||||
}
|
||||
nvmlShutdown();
|
||||
}
|
||||
|
||||
// Then enumerate non-NVIDIA via libdrm (/dev/dri/card*)
|
||||
// for Intel/AMD users on x86 Linux
|
||||
// ...
|
||||
|
||||
return out;
|
||||
}
|
||||
```
|
||||
|
||||
`AggregateGpuCounter` (line 773) — the LUID-based attribution machinery — collapses on Linux because NVML hands you per-device handles directly. Replace with a simpler `for (auto& dev : nvmlDevices)` loop.
|
||||
|
||||
Caveat: `nvmlDeviceGetUtilizationRates` returns whole-device utilization, not per-process. Per-process GPU memory needs `nvmlDeviceGetProcessUtilization` (where supported) or `nvmlDeviceGetComputeRunningProcesses`. On Jetson, NVML support is partial — test early.
|
||||
|
||||
#### 3.5 — License-server HTTP (1 day)
|
||||
|
||||
Delete the `WinHttpHandle` block (lines 1101–1166) on Linux. Reuse `anslicensing/download.cpp`'s `UrlDownloadToString` libcurl path. The function signature is already compatible. One small wrinkle: `UrlDownloadToString` is in `anslicensing.dll`, so `ANSLicensingSystem` must link against it — it already does.
|
||||
|
||||
#### 3.6 — DNS public-IP probe (0.5 day)
|
||||
|
||||
Replace `DnsQuery_A` (line 1228) with `getaddrinfo`:
|
||||
|
||||
```cpp
|
||||
struct addrinfo hints{}, *res = nullptr;
|
||||
hints.ai_family = AF_INET;
|
||||
if (getaddrinfo("myip.opendns.com", nullptr, &hints, &res) == 0 && res) {
|
||||
char buf[INET_ADDRSTRLEN];
|
||||
inet_ntop(AF_INET, &((sockaddr_in*)res->ai_addr)->sin_addr, buf, sizeof(buf));
|
||||
publicIp = buf;
|
||||
freeaddrinfo(res);
|
||||
}
|
||||
```
|
||||
|
||||
If the existing Windows query uses a TXT record specifically, fall back to `libresolv res_query` for parity. Verify with the user which probe is in use.
|
||||
|
||||
#### 3.7 — CMake + linking (3 days)
|
||||
|
||||
Rewrite `ANSLicensingSystem/CMakeLists.txt` Linux branch:
|
||||
|
||||
```cmake
|
||||
if(WIN32)
|
||||
target_link_libraries(ANSLicensingSystem PRIVATE
|
||||
HWiNFO.lib OpenCL.lib OpenCLExt.lib
|
||||
bz2.lib zip.lib
|
||||
libboost_log-vc143-mt-x64-1_82.lib
|
||||
shlwapi.lib winhttp.lib pdh.lib psapi.lib
|
||||
wbemuuid.lib oleaut32.lib ole32.lib dxgi.lib dnsapi.lib
|
||||
${WIN_COMMON_LIBS}
|
||||
)
|
||||
else()
|
||||
find_package(Boost REQUIRED COMPONENTS log date_time)
|
||||
find_package(CURL REQUIRED)
|
||||
target_link_libraries(ANSLicensingSystem PRIVATE
|
||||
hwinfo::hwinfo # vendored or apt
|
||||
Boost::log Boost::date_time
|
||||
CURL::libcurl
|
||||
zip # libzip-dev
|
||||
z # zlib1g-dev
|
||||
nvidia-ml # libnvidia-ml-dev (NVML)
|
||||
drm # libdrm-dev (optional, for non-NVIDIA)
|
||||
pthread dl
|
||||
)
|
||||
endif()
|
||||
|
||||
target_compile_definitions(ANSLicensingSystem PRIVATE
|
||||
ANSLICENSE_EXPORTS
|
||||
ANSLICENSINGSYSTEM_EXPORTS
|
||||
$<$<PLATFORM_ID:Windows>:UNICODE _UNICODE>
|
||||
)
|
||||
```
|
||||
|
||||
Drop `ANSLIBS_DIR/ANS-HWiNFO/lib` and `ANSLIBS_DIR/boost/lib` from `target_link_directories` on Linux.
|
||||
|
||||
#### 3.8 — End-to-end license activation (3 days)
|
||||
|
||||
Run the full activation flow from a Linux client against the staging license server:
|
||||
|
||||
1. `GenerateHardwareId()` returns a string
|
||||
2. Operator pastes it into the activation portal
|
||||
3. Server returns license blob
|
||||
4. Linux client `ValidateLicense(blob)` returns `SUCCESS`
|
||||
5. Subsequent `IsLicenseValid()` calls return true
|
||||
6. Restart process — license still valid
|
||||
7. Move drive to second machine — license **invalid** (HWID mismatch detected)
|
||||
|
||||
The last item is the critical anti-piracy check. If it fails (license validates on second machine), the HWID is too lax — go back to Phase 1.1.
|
||||
|
||||
**Acceptance for Phase 3 overall**:
|
||||
- `libANSLicensingSystem.so` builds and links cleanly.
|
||||
- All public symbols (less `_LV` set) match Windows-side exports.
|
||||
- Full activation round-trip succeeds against staging server.
|
||||
- `SystemHealthInfo` struct populates all fields with real (non -1) data on Jetson and on x86 Ubuntu.
|
||||
- Anti-piracy test passes (HWID mismatch is detected).
|
||||
|
||||
### Phase 4 — Integration & Hardening (1 week)
|
||||
|
||||
- **4.1** **Cross-arch CI**: add an `aarch64` build matrix entry. Cross-compile from x86 host using JetPack 6.x sysroot, or natively on a Jetson runner. Both options work; pick whichever the team prefers.
|
||||
- **4.2** **Soak test**: run an ANSLicensingSystem-based test harness on a Jetson for 24 hours. Watch for memory leaks (`valgrind --leak-check=full` for a short run, then `top` / smaps tracking long-term). NVML on Jetson has known leak patterns — defend against them.
|
||||
- **4.3** **Documentation**: write `docs/LINUX_BUILD_GUIDE.md` covering apt deps, Boost version notes, Jetson cross-compile, and the HWID format change (so support knows licenses don't transfer Windows↔Linux without re-issuance).
|
||||
- **4.4** **Top-level CMake gating**: in the root `CMakeLists.txt`, remove `if(WIN32)` gates around the three components — they now build everywhere. Engine modules stay Windows-only for now since this plan doesn't cover them.
|
||||
|
||||
**Acceptance for Phase 4**:
|
||||
- CI green on Windows, Ubuntu x86, Jetson aarch64.
|
||||
- 24h soak shows stable memory profile.
|
||||
- LINUX_BUILD_GUIDE.md merged and reviewed.
|
||||
|
||||
---
|
||||
|
||||
## 5. Risks & mitigations
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| License server rejects Linux HWID format | Medium | **Blocks Phase 1 acceptance** | Resolve Decision 1 before Phase 0; coordinate with backend team early |
|
||||
| Jetson `/sys/class/dmi/id/board_serial` missing | High | Phase 1 HWID is weak on Jetson | Decision 2: validate on real Jetson hardware; fall back to device-tree serial |
|
||||
| NVML on Jetson missing some APIs | Medium | GPU telemetry sparse on Jetson | Test `nvmlDeviceGetUtilizationRates` early; gracefully degrade fields that aren't available |
|
||||
| Boost version mismatch (1.74 system vs 1.82 vendored) | Medium | Subtle behavioral differences | Phase 0.5 spike build; switch to nlohmann/json if PropertyTree breaks |
|
||||
| `lfreist/hwinfo` ARM support gaps | Low | HWID source incomplete on Jetson | Read its `cpuid.h` Linux branch; have device-tree fallback ready |
|
||||
| Symbol visibility differences cause ABI breakage | Low | Linker errors at integration time | `-fvisibility=hidden` from day one; `ANSCORE_API` discipline |
|
||||
| WMI thermal-zone has no Linux semantic equivalent | Low | `cpuTempDegC` field is less accurate | Document field as "best-effort, may be -1 on hardware without thermal zones" |
|
||||
| `libnvidia-ml` not present on dev-only x86 box | Low | Build fails on developer machines | dynamic-load NVML via dlopen with weak symbol; fallback to "no GPU" state |
|
||||
|
||||
---
|
||||
|
||||
## 6. Dependencies for Ubuntu / Jetson development
|
||||
|
||||
```bash
|
||||
# Build essentials
|
||||
sudo apt install -y \
|
||||
build-essential cmake ninja-build pkg-config git \
|
||||
libboost-all-dev libcurl4-openssl-dev libssl-dev \
|
||||
libzip-dev zlib1g-dev \
|
||||
libnvidia-ml-dev libdrm-dev libsensors4-dev \
|
||||
libgtest-dev cppcheck clang-tidy
|
||||
|
||||
# CUDA 12.x + cuDNN + TensorRT 10.x — from NVIDIA's apt repo (separate setup)
|
||||
# JetPack 6.x — flash via SDK Manager onto target board
|
||||
```
|
||||
|
||||
For Jetson cross-compile: install JetPack 6.x SDK on host, point CMake at `/opt/nvidia/jetson-linux-sysroot/aarch64-ubuntu22.04`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Testing strategy
|
||||
|
||||
- **Unit tests** (`tests/anslicensing-unittest`): exercise each platform-specific helper with known synthetic data. New tests: HWID-determinism, getrandom-fallback, /proc/meminfo parser, /proc/stat delta computation.
|
||||
- **Integration tests** (`tests/anslicensingsystem-integration`): in-process activation round-trip against a mock license server. Run on Windows + Linux + Jetson.
|
||||
- **E2E tests**: real staging server. Run **once per phase acceptance**, not on every commit (slow + flaky over real network).
|
||||
- **Anti-piracy regression test**: documented in Phase 3.8. **Must run before merging Phase 3 to main.**
|
||||
- **Determinism test**: generate HWID 10× across reboots on the same machine; assert all identical. Generate on two physically different Jetsons; assert different.
|
||||
|
||||
---
|
||||
|
||||
## Appendix A — Per-file change checklist
|
||||
|
||||
Files marked **NEW** are created; **MOD** is modified; **DELETE** is removed.
|
||||
|
||||
### `core/anslicensing/`
|
||||
|
||||
| File | Action | Phase | Change |
|
||||
|---|---|---|---|
|
||||
| `hwid.cpp` | MOD | 1.1 | Linux branches: use `hwinfo::MainBoard::serialNumber()` for UUID slot; implement `GetHDDPropertyList` reading `/sys/block/*/device/wwid` |
|
||||
| `rand.cpp` | MOD | 1.2 | Replace `srand`/`rand` with `getrandom(2)` + `/dev/urandom` fallback |
|
||||
| `helper.cpp` | MOD | 1.3 | `DetectClockManipulation` Linux stub with ANS_DBG warning |
|
||||
| `download.cpp` | — | — | Already done — libcurl path exists |
|
||||
| `precomp.h` | — | — | Already done — POSIX shims exist |
|
||||
| `CMakeLists.txt` | MOD | 1.4 | Add `find_package(hwinfo)` on non-Windows |
|
||||
|
||||
### `core/ANSLicensingSystem/`
|
||||
|
||||
| File | Action | Phase | Change |
|
||||
|---|---|---|---|
|
||||
| `ANSLicense.h` | MOD | 0.2 | Remove `#include "LabVIEWHeader/extcode.h"`; remove `LDbl`/`LDblPtr`/`LDblHandle` (moved to `ANSLicense_LV.h`) |
|
||||
| `ANSLicense_LV.h` | NEW | 0.2 | Windows-only header with all `_LV` exports, includes `extcode.h` |
|
||||
| `ANSLicense.cpp` | MOD | 3.1–3.6 | Replace each Win32 call site with `#ifdef _WIN32` / `#else` branch |
|
||||
| `HealthSamplerLinux.cpp` | NEW | 3.3 | New file: `/proc`-based sampler |
|
||||
| `HealthSamplerLinux.h` | NEW | 3.3 | Class declaration matching `HealthSampler`'s public API |
|
||||
| `Utility.h` | MOD | 0.3 | Strip any Windows-specific types from declarations |
|
||||
| `Utility.cpp` | MOD | 3.1 | Verify std::filesystem path operations work on Linux |
|
||||
| `CMakeLists.txt` | MOD | 3.7 | Add Linux branch with curl/boost/hwinfo/nvml |
|
||||
|
||||
### `core/ANSLibsLoader/`
|
||||
|
||||
| File | Action | Phase | Change |
|
||||
|---|---|---|---|
|
||||
| `DynLibUtils.cpp` | MOD | 2.1 | dlopen/dlsym/dlclose Linux branches |
|
||||
| `CvLoader.cpp` | MOD | 2.2 | Linux search paths + `.so` naming |
|
||||
| `NvDynLoader.cpp` | MOD | 2.2 | Linux search paths |
|
||||
| `OvLoader.cpp` | MOD | 2.2 | Linux search paths |
|
||||
| `EPLoader.cpp` | MOD | 2.2 | Linux search paths |
|
||||
| `ANSLibsLoader.def` | — | — | Windows-only `.def`; leave alone, use `__attribute__((visibility))` on Linux |
|
||||
| `CMakeLists.txt` | MOD | 2.4 | `-fvisibility=hidden`; link `dl` on Linux |
|
||||
|
||||
### Top-level
|
||||
|
||||
| File | Action | Phase | Change |
|
||||
|---|---|---|---|
|
||||
| `CMakeLists.txt` | MOD | 0.4, 4.4 | `ANSCORE_USE_VENDORED_HWINFO` option; ungate three core components from `if(WIN32)` |
|
||||
| `cmake/Dependencies.cmake` | MOD | 0.4, 3.7 | Add `hwinfo`, `NVML` (`CUDA::nvml`), `libdrm` resolution |
|
||||
| `3rdparty/hwinfo/` | NEW (submodule) | 0.4 | `git submodule add https://github.com/lfreist/hwinfo 3rdparty/hwinfo` |
|
||||
| `docs/LINUX_BUILD_GUIDE.md` | NEW | 4.3 | Developer onboarding |
|
||||
|
||||
---
|
||||
|
||||
## Appendix B — Symbol map (Win32 → Linux)
|
||||
|
||||
Reference table for the engineer porting `ANSLicense.cpp`:
|
||||
|
||||
| Win32 symbol / API | File:line | Linux replacement |
|
||||
|---|---|---|
|
||||
| `PdhOpenQueryW` / `PdhAddEnglishCounterW` / `PdhCollectQueryData` | ANSLicense.cpp:906–928 | Custom `/proc/stat`, `/proc/diskstats`, `/proc/net/dev` delta sampler (Phase 3.3) |
|
||||
| `IWbemLocator::ConnectServer("ROOT\\WMI")` + `MSAcpi_ThermalZoneTemperature` | ANSLicense.cpp:618–663 | `/sys/class/thermal/thermal_zone*/temp` (Phase 3.2) |
|
||||
| `CreateDXGIFactory1` / `IDXGIAdapter1::GetDesc1` | ANSLicense.cpp:721–747 | `nvmlDeviceGetCount_v2` + per-device queries; libdrm for non-NVIDIA (Phase 3.4) |
|
||||
| `WinHttpOpen` / `WinHttpSendRequest` / etc. | ANSLicense.cpp:1101–1166 | Reuse `anslicensing/download.cpp` libcurl path (Phase 3.5) |
|
||||
| `DnsQuery_A` | ANSLicense.cpp:1228 | `getaddrinfo` or `res_query` (Phase 3.6) |
|
||||
| `GlobalMemoryStatusEx` | ANSLicense.cpp:1036 | `/proc/meminfo` parser (Phase 3.1) |
|
||||
| `GetProcessMemoryInfo` | ANSLicense.cpp:1048 | `/proc/self/status` parser (Phase 3.1) |
|
||||
| `GetSystemDirectoryW` + `GetDiskFreeSpaceExW` | ANSLicense.cpp:1056–1064 | `statvfs("/")` (Phase 3.1) |
|
||||
| `GetCurrentProcessId` | ANSLicense.cpp:993, 1026 | `getpid()` (Phase 3.1) |
|
||||
| `WideCharToMultiByte` / `WideToUtf8` | ANSLicense.cpp:712 | drop on Linux — no wide chars needed without WMI |
|
||||
| `CoInitializeEx` / `CoSetProxyBlanket` / `CoUninitialize` | ANSLicense.cpp:604, 611, 669 | delete on Linux — COM not needed |
|
||||
| `__declspec(dllexport)` | (everywhere) | `__attribute__((visibility("default")))` via `ANSCORE_API` macro (Phase 0.1) |
|
||||
| `LStrHandle`, `LDbl`, `extcode.h` | ANSLicense.h:75 + many | move to `ANSLicense_LV.h`, Windows-only (Phase 0.2) |
|
||||
|
||||
---
|
||||
|
||||
## Appendix C — License-server coordination checklist
|
||||
|
||||
Before Phase 1 starts, the license-server team confirms in writing:
|
||||
|
||||
- [ ] Server accepts HWID format generated by the new Linux `hwid.cpp` path
|
||||
- [ ] Server's HWID validation algorithm matches the new client-side hash inputs
|
||||
- [ ] Decision on license-pool separation: unified vs. Linux-only pool
|
||||
- [ ] Staging environment endpoint available for E2E testing in Phase 3.8
|
||||
- [ ] Activation portal supports pasting a Linux-generated HWID
|
||||
|
||||
---
|
||||
|
||||
## Appendix D — What this plan deliberately does NOT cover
|
||||
|
||||
So a future session doesn't accidentally scope-creep:
|
||||
|
||||
- **MediaClient port to Linux** — separate plan; ANSCV depends on this but licensing does not
|
||||
- **GStreamer backend for ANSCV** — separate plan
|
||||
- **Engine modules** (ANSODEngine, ANSFR, ANSLPR, ANSOCR, etc.) — separate plans, post-licensing
|
||||
- **gRPC service layer** (ANSService) — planned after engine modules are up
|
||||
- **Qt QML UI** — separate repo, depends on gRPC layer
|
||||
- **macOS support** — not in roadmap currently
|
||||
- **Dropping LabVIEW on Windows** — `_LV` exports stay on Windows builds untouched
|
||||
- **License protocol changes** — wire compatibility preserved; only the input data to the HWID hash changes on Linux
|
||||
|
||||
---
|
||||
|
||||
*End of plan.*
|
||||
@@ -0,0 +1,48 @@
|
||||
@startuml 01-system-context
|
||||
title ANSCORE — System Context (L1 / L2 / L3)
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
skinparam packageStyle rectangle
|
||||
|
||||
package "Layer 3 — Qt/QML Desktop UI\n(Windows / macOS / Linux)" as L3 {
|
||||
component "Qt/QML application" as UI
|
||||
}
|
||||
|
||||
package "Layer 2 — ANSVIS Communication Layer (CL)" as L2 {
|
||||
component "/api/v1\nREST surface" as APIV1
|
||||
component "Legacy ANSVIS core\n(reused as-is)" as LEGACY
|
||||
component "Media relay\nHLS / RTSP / WebRTC" as RELAY
|
||||
component "SSE event\nbroadcaster" as SSEHUB
|
||||
database "Event DB\n+ clip object store" as STORE
|
||||
queue "Async job queue" as JOBS
|
||||
component "Auth + RBAC" as AUTH
|
||||
}
|
||||
|
||||
package "Layer 1 — ANSCORE Edge Runtime\n(one per target)" as L1 {
|
||||
component "Camera + Inference\n+ Triggers" as EDGE
|
||||
}
|
||||
|
||||
UI --> APIV1 : (1) REST / HTTPS\ncontrol + CRUD
|
||||
UI --> SSEHUB : (2) SSE / HTTPS\nlive event tail
|
||||
UI --> RELAY : (3) HLS / RTSP / WebRTC\nlive video
|
||||
|
||||
APIV1 --> AUTH
|
||||
APIV1 --> LEGACY
|
||||
APIV1 --> JOBS
|
||||
APIV1 --> STORE
|
||||
LEGACY --> STORE
|
||||
STORE --> SSEHUB
|
||||
RELAY <--> EDGE
|
||||
LEGACY <--> EDGE
|
||||
|
||||
note bottom of L3
|
||||
L3 only talks to L2 — never directly to edges.
|
||||
end note
|
||||
|
||||
note bottom of L2
|
||||
All three UI transports are brokered by the REST API:
|
||||
the URL + token for live media and the SSE filter for
|
||||
events are obtained via REST calls first.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,84 @@
|
||||
@startuml 02-l2-internals
|
||||
title Layer 2 — ANSVIS internal architecture
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
skinparam packageStyle rectangle
|
||||
|
||||
actor "Qt / QML UI" as QT
|
||||
actor "3rd-party\nintegrations" as EXT
|
||||
|
||||
package "L2 /api/v1 surface" as EDGE_API {
|
||||
component "REST router" as ROUTER
|
||||
component "Auth middleware\n(Bearer)" as AUTHMW
|
||||
component "Request validation\n(OpenAPI schemas)" as VALID
|
||||
component "Error mapper\n(RFC 7807)" as ERR
|
||||
component "Rate limiter" as RATE
|
||||
component "SSE broadcaster\n(per-subscription filter)" as SSEHUB
|
||||
}
|
||||
|
||||
package "v1 Adapter Layer\n(per-resource modules)" as ADAPTER {
|
||||
component "cameras" as CAM_AD
|
||||
component "models" as MOD_AD
|
||||
component "edges" as EDGE_AD
|
||||
component "deployment-groups" as DG_AD
|
||||
component "ai-tasks" as TASK_AD
|
||||
component "events" as EV_AD
|
||||
component "fr" as FR_AD
|
||||
component "alpr" as ALPR_AD
|
||||
component "notifications" as NOTIF_AD
|
||||
component "system" as SYS_AD
|
||||
component "jobs" as JOB_AD
|
||||
}
|
||||
|
||||
package "Legacy ANSVIS server\n(reused as-is)" as LEGACY {
|
||||
component "Config store" as LEG_CFG
|
||||
component "AI task engine" as LEG_TASKS
|
||||
component "FR engine" as LEG_FR
|
||||
component "ALPR engine" as LEG_ALPR
|
||||
}
|
||||
|
||||
package "Infrastructure" as INFRA {
|
||||
component "Auth + token store" as AUTH_SVC
|
||||
queue "Job queue\n(scans, uploads, deploys, updates)" as JOBS_Q
|
||||
database "Event metadata DB" as EVENTS_DB
|
||||
database "Clip / image object store\n(S3 / MinIO / FS)" as CLIPS
|
||||
component "Logs + metrics + health" as LOGS
|
||||
component "Media relay\nHLS / RTSP / WebRTC" as RELAY
|
||||
}
|
||||
|
||||
actor "L1 edge target(s)" as E1
|
||||
|
||||
QT --> ROUTER
|
||||
EXT --> ROUTER
|
||||
ROUTER --> AUTHMW
|
||||
AUTHMW --> VALID
|
||||
VALID --> RATE
|
||||
RATE --> ADAPTER
|
||||
ADAPTER --> ERR
|
||||
ADAPTER ..> ROUTER : response
|
||||
|
||||
AUTHMW --> AUTH_SVC
|
||||
|
||||
CAM_AD --> LEG_CFG
|
||||
MOD_AD --> LEG_CFG
|
||||
MOD_AD --> CLIPS
|
||||
EDGE_AD --> LEG_CFG
|
||||
DG_AD --> LEG_TASKS
|
||||
TASK_AD --> LEG_TASKS
|
||||
EV_AD --> EVENTS_DB
|
||||
EV_AD --> CLIPS
|
||||
FR_AD --> LEG_FR
|
||||
ALPR_AD --> LEG_ALPR
|
||||
SYS_AD --> LOGS
|
||||
JOB_AD --> JOBS_Q
|
||||
CAM_AD ..> JOBS_Q : scan / probe
|
||||
MOD_AD ..> JOBS_Q : large upload
|
||||
|
||||
LEG_TASKS --> EVENTS_DB
|
||||
EVENTS_DB --> SSEHUB
|
||||
SSEHUB --> ROUTER
|
||||
|
||||
LEGACY <--> E1
|
||||
RELAY <--> E1
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,51 @@
|
||||
@startuml 03-l2-ownership
|
||||
title Layer 2 — Build ownership
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
skinparam packageStyle rectangle
|
||||
|
||||
package "Architect-owned\n(lead review)" as HUMAN #LightYellow {
|
||||
component "REST router\n+ auth middleware" as H1
|
||||
component "RFC 7807\nerror mapper" as H2
|
||||
component "OpenAPI validation\npipeline" as H3
|
||||
component "Auth flow\n+ token store" as H4
|
||||
component "RBAC\n+ security review" as H5
|
||||
component "L2 ↔ L1 tunnel\n+ signing" as H6
|
||||
}
|
||||
|
||||
package "Core team\n(modular adapters)" as AI #LightBlue {
|
||||
component "cameras adapter" as A1
|
||||
component "models adapter\n+ upload pipeline" as A2
|
||||
component "edges adapter" as A3
|
||||
component "deployment-groups\nadapter" as A4
|
||||
component "ai-tasks adapter" as A5
|
||||
component "events adapter\n+ SSE broadcaster" as A6
|
||||
component "fr adapter" as A7
|
||||
component "alpr adapter" as A8
|
||||
component "notifications adapter" as A9
|
||||
component "system / health /\nlogs adapter" as A10
|
||||
component "job queue + workers" as A11
|
||||
component "media relay" as A12
|
||||
}
|
||||
|
||||
package "Existing ANSVIS\n(reused as-is)" as EXIST #LightGray {
|
||||
component "Task engine" as L_TASKS
|
||||
component "FR engine" as L_FR
|
||||
component "ALPR engine" as L_ALPR
|
||||
component "Config store" as L_CFG
|
||||
}
|
||||
|
||||
HUMAN --> AI
|
||||
AI --> EXIST
|
||||
|
||||
note bottom of HUMAN
|
||||
Cross-cutting concerns kept under direct architect review:
|
||||
request validation, errors, auth, RBAC, tunnel security.
|
||||
end note
|
||||
|
||||
note bottom of AI
|
||||
Highly modular by resource — the core team works in parallel
|
||||
on independent adapters without colliding.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,65 @@
|
||||
@startuml 04-l3-internals
|
||||
title Layer 3 — Qt 6 / QML internal architecture
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
skinparam packageStyle rectangle
|
||||
|
||||
package "Qt 6 + QML — Layer 3" as QT {
|
||||
|
||||
package "App Shell" as SHELL {
|
||||
component "Main window" as MAIN
|
||||
component "Navigation router" as ROUTE
|
||||
component "Design system / theme" as THEME
|
||||
component "i18n (qsTr / Linguist)" as I18N
|
||||
component "Auth state + token store" as AUTH_ST
|
||||
component "Error toast / dialog" as ERR_UI
|
||||
}
|
||||
|
||||
package "Network layer" as NET {
|
||||
component "Generated REST client\n(openapi.v1.json → C++/Qt)" as REST
|
||||
component "SSE subscriber\n(QNetworkReply chunked)" as SSE_CL
|
||||
component "Media client\nQtMultimedia / GStreamer" as MEDIA
|
||||
component "Bbox overlay renderer\n(custom QQuickItem)" as OVERLAY
|
||||
component "Multipart + presigned\nuploader" as UPLOAD
|
||||
}
|
||||
|
||||
package "Domain state (QObject + signals)" as STATE {
|
||||
component "CamerasModel" as ST_CAM
|
||||
component "ModelsModel" as ST_MOD
|
||||
component "EdgesModel" as ST_EDGE
|
||||
component "DeploymentGroupsModel" as ST_DG
|
||||
component "AITasksModel" as ST_TASK
|
||||
component "EventsModel + LiveBuffer" as ST_EV
|
||||
component "FRPersonsModel" as ST_FR
|
||||
component "ALPRPlatesModel" as ST_ALPR
|
||||
component "RecipientsModel" as ST_NOTIF
|
||||
component "SystemHealthModel" as ST_SYS
|
||||
}
|
||||
|
||||
package "Screens (QML)" as SCREENS {
|
||||
component "Login" as LOGIN
|
||||
component "Dashboard /\ntargets overview" as DASH
|
||||
component "Camera management\n+ ONVIF discovery\n+ calibration" as CAM_S
|
||||
component "Pipeline editor\n(visual DAG)" as DG_EDIT
|
||||
component "AI Task config" as TASK_EDIT
|
||||
component "Rules / triggers" as RULE_S
|
||||
component "Liveview grid" as LIVE
|
||||
component "Eventview timeline" as EV_S
|
||||
component "FR persons + faces" as FR_S
|
||||
component "ALPR plates" as ALPR_S
|
||||
component "Model registry" as MODEL_S
|
||||
component "Users / admin" as USERS
|
||||
component "Settings" as SETTINGS
|
||||
}
|
||||
}
|
||||
|
||||
actor "ANSVIS /api/v1" as BACKEND
|
||||
|
||||
SCREENS --> STATE : reads / mutates
|
||||
STATE --> NET : calls
|
||||
NET <--> BACKEND
|
||||
OVERLAY ..> MEDIA : sync to PTS
|
||||
AUTH_ST ..> REST : injects Bearer
|
||||
AUTH_ST ..> SSE_CL : injects Bearer
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,45 @@
|
||||
@startuml 05-seq-configure-deploy
|
||||
title Sequence — Operator configures camera + AI task and deploys
|
||||
|
||||
actor "Operator" as User
|
||||
participant "Qt UI" as UI
|
||||
participant "ANSVIS\n/api/v1" as API
|
||||
participant "ANSVIS core" as LEG
|
||||
participant "L1 edge" as EDGE
|
||||
|
||||
User -> UI : Open Cameras screen
|
||||
UI -> API : GET /cameras?page=1
|
||||
API -> LEG : legacy list
|
||||
LEG --> API : cameras
|
||||
API --> UI : 200 {items, page, total}
|
||||
|
||||
User -> UI : Add RTSP camera (form)
|
||||
UI -> API : POST /cameras
|
||||
note right of UI
|
||||
body has nested credentials,
|
||||
capturing, image_size —
|
||||
no stringified JSON
|
||||
end note
|
||||
API -> LEG : legacy add
|
||||
LEG --> API : id=123
|
||||
API --> UI : 201 Location: /cameras/123
|
||||
|
||||
User -> UI : Configure AI task
|
||||
UI -> API : POST /ai-tasks\n{camera_id:123, ...}
|
||||
API -> LEG : legacy create
|
||||
LEG --> API : id=456
|
||||
API --> UI : 201 {id:456}
|
||||
|
||||
User -> UI : Start task
|
||||
UI -> API : POST /ai-tasks/456/start
|
||||
API -> LEG : dispatch
|
||||
LEG -> EDGE : config + start
|
||||
EDGE --> LEG : running
|
||||
API --> UI : 202 {state:starting}
|
||||
|
||||
loop status poll (or SSE later)
|
||||
UI -> API : GET /ai-tasks/456/status
|
||||
API --> UI : 200 {state:running, fps:14.2}
|
||||
end
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,36 @@
|
||||
@startuml 06-seq-live-events
|
||||
title Sequence — Live event tail + clicking into evidence
|
||||
|
||||
actor "Operator" as User
|
||||
participant "Qt UI" as UI
|
||||
participant "ANSVIS\n/api/v1" as API
|
||||
participant "SSE broadcaster" as SSE
|
||||
participant "Clip store\n(S3 / MinIO / FS)" as CLIPS
|
||||
participant "L1 edge" as EDGE
|
||||
|
||||
User -> UI : Open Eventview (task=456)
|
||||
UI -> API : GET /events?task_id=456&page=1
|
||||
API --> UI : 200 historical events
|
||||
UI -> API : GET /events/stream?task_id=456
|
||||
API --> UI : text/event-stream (open)
|
||||
|
||||
EDGE -> API : event arrives (via L1↔L2)
|
||||
API -> SSE : push EventRecord
|
||||
SSE --> UI : data: {id:E1, ts, object:car, bbox, ...}
|
||||
|
||||
User -> UI : Click event E1
|
||||
UI -> API : GET /events/E1
|
||||
API --> UI : 200 EventRecord (full)
|
||||
UI -> API : GET /events/E1/image?width=640
|
||||
API --> UI : image/jpeg bytes
|
||||
|
||||
User -> UI : Play clip
|
||||
UI -> API : GET /events/E1/clip
|
||||
API -> CLIPS : presign GET
|
||||
CLIPS --> API : presigned URL
|
||||
API --> UI : 200 {url, expires_at}
|
||||
UI -> CLIPS : GET <presigned URL>
|
||||
CLIPS --> UI : MP4 bytes
|
||||
UI -> UI : play in QtMultimedia
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,30 @@
|
||||
@startuml 07-seq-liveview
|
||||
title Sequence — Liveview with bbox overlay
|
||||
|
||||
actor "Operator" as User
|
||||
participant "Qt UI" as UI
|
||||
participant "ANSVIS\n/api/v1" as API
|
||||
participant "Media relay" as RELAY
|
||||
participant "L1 edge" as EDGE
|
||||
participant "SSE broadcaster" as SSE
|
||||
|
||||
User -> UI : Open Liveview (cam 123, task 456)
|
||||
UI -> API : GET /cameras/123/liveview?transport=hls
|
||||
API -> RELAY : ensure HLS for cam 123
|
||||
RELAY -> EDGE : pull RTSP
|
||||
RELAY --> API : hls_url + short-lived token
|
||||
API --> UI : 200 {url, transport:hls,\nauth_token, expires_at}
|
||||
|
||||
UI -> RELAY : GET hls_url (token)
|
||||
RELAY --> UI : m3u8 + segments
|
||||
UI -> UI : Render video\n(QtMultimedia)
|
||||
|
||||
UI -> API : GET /events/stream?task_id=456 (SSE)
|
||||
API --> UI : text/event-stream
|
||||
|
||||
loop per event
|
||||
SSE --> UI : bbox + ts
|
||||
UI -> UI : overlay synced to PTS
|
||||
end
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,27 @@
|
||||
@startuml 08-seq-async-scan
|
||||
title Sequence — Async camera network scan (job pattern)
|
||||
|
||||
actor "Operator" as User
|
||||
participant "Qt UI" as UI
|
||||
participant "ANSVIS\n/api/v1" as API
|
||||
participant "Job queue" as JOBS
|
||||
participant "ONVIF scanner" as SCAN
|
||||
|
||||
User -> UI : Scan 192.168.1.0/24
|
||||
UI -> API : POST /cameras/scan
|
||||
API -> JOBS : enqueue
|
||||
JOBS --> API : job_id=j1
|
||||
API --> UI : 202 {job_id:j1,\n status:queued,\n links:{self:/jobs/j1}}
|
||||
|
||||
JOBS -> SCAN : run
|
||||
|
||||
loop poll until terminal
|
||||
UI -> API : GET /jobs/j1
|
||||
API --> UI : 200 {status:running, progress:0.4}
|
||||
end
|
||||
|
||||
SCAN --> JOBS : results
|
||||
UI -> API : GET /jobs/j1
|
||||
API --> UI : 200 {status:succeeded,\n result:{discovered:[...]}}
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,23 @@
|
||||
@startuml 09-seq-large-upload
|
||||
title Sequence — Large model upload (initiate / complete pattern)
|
||||
|
||||
actor "Operator" as User
|
||||
participant "Qt UI" as UI
|
||||
participant "ANSVIS\n/api/v1" as API
|
||||
participant "Object store\n(S3 / MinIO / FS)" as OBJ
|
||||
|
||||
User -> UI : Pick model.zip (500 MB)
|
||||
UI -> API : POST /models:initiate-upload\n{filename, size_bytes, checksum}
|
||||
API -> OBJ : presign PUT
|
||||
OBJ --> API : presigned_url
|
||||
API --> UI : 200 {upload_id, presigned_url, expires_at}
|
||||
|
||||
UI -> OBJ : PUT <presigned_url>\n(binary stream, with progress)
|
||||
OBJ --> UI : 200 OK
|
||||
|
||||
UI -> API : POST /models:complete-upload\n{upload_id, metadata}
|
||||
API -> OBJ : verify checksum
|
||||
OBJ --> API : ok
|
||||
API --> UI : 201 Model
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,51 @@
|
||||
@startuml 10-deployment-topology
|
||||
title Deployment Topology
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
|
||||
node "Customer site / cloud" {
|
||||
|
||||
node "Operator workstations" {
|
||||
component "Windows desktop\nQt UI" as D1
|
||||
component "macOS desktop\nQt UI" as D2
|
||||
component "Linux desktop\nQt UI" as D3
|
||||
}
|
||||
|
||||
node "ANSVIS server host" {
|
||||
component "Reverse proxy\nTLS terminator\n(nginx / caddy)" as NGINX
|
||||
component "ANSVIS app\n(adapter + legacy core)" as APP
|
||||
component "Media relay" as RELAY
|
||||
database "Object store\n(S3 / MinIO / FS)" as OBJ
|
||||
database "Config + Event DBs" as DB
|
||||
}
|
||||
|
||||
node "Edge targets" {
|
||||
node "Linux x86 + NVIDIA" as E1
|
||||
node "Windows x86 + NVIDIA" as E2
|
||||
node "Jetson Orin" as E3
|
||||
}
|
||||
}
|
||||
|
||||
D1 --> NGINX : TLS 443\nREST + SSE + HLS
|
||||
D2 --> NGINX : TLS 443
|
||||
D3 --> NGINX : TLS 443
|
||||
NGINX --> APP
|
||||
NGINX --> RELAY
|
||||
APP --> DB
|
||||
APP --> OBJ
|
||||
RELAY <--> E1
|
||||
RELAY <--> E2
|
||||
RELAY <--> E3
|
||||
APP <--> E1
|
||||
APP <--> E2
|
||||
APP <--> E3
|
||||
|
||||
note bottom
|
||||
Network rules for the customer:
|
||||
- Outbound TCP 443 from each workstation → ANSVIS host
|
||||
- Inbound TCP 443 on ANSVIS host
|
||||
- L2 ↔ L1 protocol per edge (port + tunnel TBD)
|
||||
- Workstations never reach edges directly — Media relay proxies
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,71 @@
|
||||
@startuml 11-l3-engineer-ownership
|
||||
title Layer 3 — Engineer ownership (6 engineers)
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
skinparam packageStyle rectangle
|
||||
|
||||
package "E1 — UI Lead / Shell Architect" as E1 #LightYellow {
|
||||
component "Qt 6 + CMake monorepo" as E1A
|
||||
component "Generated REST client\nfrom openapi.v1.json" as E1B
|
||||
component "Auth state + token store" as E1C
|
||||
component "Design system / theme" as E1D
|
||||
component "Navigation router" as E1E
|
||||
component "Packaging Win/Mac/Linux\nsigning, notarize,\nauto-update" as E1F
|
||||
component "CI matrix" as E1G
|
||||
}
|
||||
|
||||
package "E2 — Pipeline Editor Specialist" as E2 #LightBlue {
|
||||
component "Visual DAG editor\n(QGraphicsView in QQuickWidget)" as E2A
|
||||
component "Node library +\nconnection validation" as E2B
|
||||
component "Schema-driven param panels" as E2C
|
||||
component "Undo / redo,\nsave / version" as E2D
|
||||
}
|
||||
|
||||
package "E3 — Liveview / Media" as E3 #LightGreen {
|
||||
component "QtMultimedia HLS player\n(v1)" as E3A
|
||||
component "Multi-stream grid" as E3B
|
||||
component "Bbox overlay\n(QQuickItem + QSGGeometryNode)" as E3C
|
||||
component "Clip player (evidence)" as E3D
|
||||
component "WebRTC via GStreamer\n(v2)" as E3E
|
||||
}
|
||||
|
||||
package "E4 — Config Forms" as E4 #LightPink {
|
||||
component "Schema-driven QML forms\n(from openapi.v1.json)" as E4A
|
||||
component "Camera + ONVIF discovery flow" as E4B
|
||||
component "Camera calibration UI\n(ROI / zones / homography)" as E4C
|
||||
component "Model + plugin +\ntrigger forms" as E4D
|
||||
}
|
||||
|
||||
package "E5 — Dashboard / Eventview" as E5 #LightCoral {
|
||||
component "Target dashboard\ncards + charts" as E5A
|
||||
component "Event timeline\n(virtualized)" as E5B
|
||||
component "SSE subscriber + LiveBuffer" as E5C
|
||||
component "Filter / search /\nevidence viewer" as E5D
|
||||
component "Multi-target monitoring" as E5E
|
||||
}
|
||||
|
||||
package "E6 — UX / Cross-platform QA" as E6 #Lavender {
|
||||
component "Design polish,\na11y, i18n" as E6A
|
||||
component "Install / upgrade testing\nWin + Mac + Linux" as E6B
|
||||
component "Crash reporting\n(Sentry / Crashpad)" as E6C
|
||||
component "QML Profiler perf passes" as E6D
|
||||
component "User docs surface" as E6E
|
||||
}
|
||||
|
||||
artifact "openapi.v1.json\n(frozen contract)" as CONTRACT
|
||||
|
||||
E1 ..> CONTRACT
|
||||
E2 ..> CONTRACT
|
||||
E3 ..> CONTRACT
|
||||
E4 ..> CONTRACT
|
||||
E5 ..> CONTRACT
|
||||
|
||||
note bottom of E1
|
||||
Week 1–2: E1 alone delivers the shell that unblocks E2–E6.
|
||||
end note
|
||||
|
||||
note bottom of E2
|
||||
Week 1–2 spike in parallel — de-risks the hardest UI feature.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,43 @@
|
||||
@startuml 12-dependency-chain
|
||||
title Dependency chain — what gates what
|
||||
|
||||
skinparam componentStyle rectangle
|
||||
|
||||
artifact "openapi.v1.json\n(frozen)" as CONTRACT
|
||||
component "Prism mock server" as MOCK
|
||||
component "ANSVIS /api/v1 adapter\n(core team, per-resource)" as ADAPT
|
||||
component "Legacy ANSVIS" as LEGACY
|
||||
component "L3 shell + REST client\n(E1)" as UI_SHELL
|
||||
component "L3 screens\n(E2 – E6)" as UI_FEAT
|
||||
component "Real backend integration" as REAL
|
||||
component "Ship v1" as SHIP
|
||||
|
||||
CONTRACT --> MOCK
|
||||
CONTRACT --> ADAPT
|
||||
ADAPT --> LEGACY
|
||||
MOCK --> UI_SHELL
|
||||
UI_SHELL --> UI_FEAT
|
||||
UI_FEAT --> REAL
|
||||
ADAPT --> REAL
|
||||
REAL --> SHIP
|
||||
|
||||
note bottom of CONTRACT
|
||||
Only artifact that BOTH sides block on.
|
||||
Frozen once published; additive changes only.
|
||||
end note
|
||||
|
||||
note bottom of MOCK
|
||||
UI develops here from day 1.
|
||||
end note
|
||||
|
||||
note bottom of ADAPT
|
||||
Built in parallel by the core team.
|
||||
Per-resource modularity = independent progress.
|
||||
end note
|
||||
|
||||
note bottom of REAL
|
||||
Joining point. UI tests run against both mock and real
|
||||
to detect drift.
|
||||
end note
|
||||
|
||||
@enduml
|
||||
@@ -0,0 +1,19 @@
|
||||
# ANSCORE — L2 & L3 diagrams (preview)
|
||||
|
||||
Click each PNG link to view the rendered diagram in your browser.
|
||||
SVG links are higher-quality (vector). Both come from plantuml.com.
|
||||
|
||||
| # | Diagram | What it shows | PNG | SVG |
|
||||
|---|---|---|---|---|
|
||||
| 01 | **system context** | L1 / L2 / L3 with the 3 transports (REST / SSE / HLS-RTSP-WebRTC). | [PNG](https://www.plantuml.com/plantuml/png/RLJRRjf047ttLupo51HH2dchgYe6h43bD8alYIhnihO7ic6zw-wkQL1LgH_HB-oNT7ODWf2y6E_ud3ENiyELiKpRjXRmSTWtMsEnxfTAMdonWULM88JVqibj4i6_FtyXzG2OT00uZuSmW7Za7fUz831hBXkcMGsbgXibKThKRab3OscPN0ayWZIiNBCLdWA2NHpEOhP53PS-yRqTtD_4C4Mpjgg1VBwGvuzSLkgdeUGrAszJLmINxKll39YXUk1N08Swu6mdmPf6y99PhgG7vlFWzvka8v-KEd-Ofp2vIJl9qQdaW3Lyi1akP1Ab6PXMBrc97XlUpH-6hy4nhbYvtOkMIYFreB4rM16ZpyskyEWwd7n_JRt1YZEQaM3RXPp5hjKaI-_evn6B99juOXB5uGalJIF03RqkPA4Lgqf6zccFfa-pV4pmYbbMC4EjHmu9q_52Na0fU0EgU2PRm5YgjIDbT168ywF5bWYXsSeIdbNH1Jpaw-quVLr4sDedk81a77PrXdasUsVam_t8_MMBAlgIjDBoses9fA0X4DtL5ThTe8QdTanOZPfHhhbSeaPPecibqtorGcqyAPfUHovvFeT-_qjd4to2ys4Fl8S3c6NPNRgGRWUq4YGsIVBf7jzDpH56FNSuu0NVO3ThAfABFS6Rul2NFNZ7k1rlmojKGT1Lu-joCpeSTtVY4F1JFXmxNphKKS0_Z-eEkce-kuWVn8vn20HIMOH2MQjgK4lQ8femhPAIOajzYRK1gzmYEAyajQkXucvttMS5IAwP3m7A2fpGMxaHoOL2W7tIYBHwO3MJfb7Q6c2Qe5gjoRaA2j9xmiuJwlCJyTmvJs9on198mb9fyDEh_NOmIkeWpfKb5tJF7O9utfHENXNaZIJv3H6yTic4C8JNnXxNVKMlz9yO_0S0) | [SVG](https://www.plantuml.com/plantuml/svg/RLJRRjf047ttLupo51HH2dchgYe6h43bD8alYIhnihO7ic6zw-wkQL1LgH_HB-oNT7ODWf2y6E_ud3ENiyELiKpRjXRmSTWtMsEnxfTAMdonWULM88JVqibj4i6_FtyXzG2OT00uZuSmW7Za7fUz831hBXkcMGsbgXibKThKRab3OscPN0ayWZIiNBCLdWA2NHpEOhP53PS-yRqTtD_4C4Mpjgg1VBwGvuzSLkgdeUGrAszJLmINxKll39YXUk1N08Swu6mdmPf6y99PhgG7vlFWzvka8v-KEd-Ofp2vIJl9qQdaW3Lyi1akP1Ab6PXMBrc97XlUpH-6hy4nhbYvtOkMIYFreB4rM16ZpyskyEWwd7n_JRt1YZEQaM3RXPp5hjKaI-_evn6B99juOXB5uGalJIF03RqkPA4Lgqf6zccFfa-pV4pmYbbMC4EjHmu9q_52Na0fU0EgU2PRm5YgjIDbT168ywF5bWYXsSeIdbNH1Jpaw-quVLr4sDedk81a77PrXdasUsVam_t8_MMBAlgIjDBoses9fA0X4DtL5ThTe8QdTanOZPfHhhbSeaPPecibqtorGcqyAPfUHovvFeT-_qjd4to2ys4Fl8S3c6NPNRgGRWUq4YGsIVBf7jzDpH56FNSuu0NVO3ThAfABFS6Rul2NFNZ7k1rlmojKGT1Lu-joCpeSTtVY4F1JFXmxNphKKS0_Z-eEkce-kuWVn8vn20HIMOH2MQjgK4lQ8femhPAIOajzYRK1gzmYEAyajQkXucvttMS5IAwP3m7A2fpGMxaHoOL2W7tIYBHwO3MJfb7Q6c2Qe5gjoRaA2j9xmiuJwlCJyTmvJs9on198mb9fyDEh_NOmIkeWpfKb5tJF7O9utfHENXNaZIJv3H6yTic4C8JNnXxNVKMlz9yO_0S0) |
|
||||
| 02 | **l2 internals** | L2 adapter modules in front of legacy ANSVIS + infrastructure. | [PNG](https://www.plantuml.com/plantuml/png/TLPVRzis47_NfpZagSFcfaaVEWp3KDcM7NLoR4jAkW0535ewosmaIYEf34PHO1zYdt2VP4TIScmPUp6fkzyTx-yl-QWqaxgjIdXtEoflHrneb8ALojDSbmWHEw24M_Ztxt_0lqyUmmHw232PxRd6JBSIFKyzSz4moIh8wggf1GgTw0Eva8HWeYZn1DAmx9aLE0HuBDErXAkrXcjOBo9u2A-0ALYdlUQzp4VaGX--21D78PdcjL0M5VoHUbxd6QwYMxXc3Rz-kG7LoXtBq86cys3ZhqBuvi5hf70L1qaAicufDukBbmzf49zZ_5RleU9vNk9VJE8NyMQCTCeVh8N_aDujFW-yufyjAWqlhEIv3PMCbWqA4u7AzbWnvQmV_IYSdXi7KbBA5MiQb6GMpoRmuUTt7nm-Y0V1nKmZbBpYnmpyD3Y794a0MrcpF6DAMv_aUQJQhSeaRqnqiEEbxXCY-Dt3sFj-KbGgff-pXY1kCZeN4bNToWoXglEsn2ubV-glg8R3IcUiGibSooR-OkCFqYOVM3hrOZczK6DUe3ffvK2TOrFMXuhkeuBQsJZeT7u1P7oacNfs-jHFVhzywOMExgd72-tELNaMNtek6wVpezMbLjIQxtXsChVtopISNU3KWNfKkKOy9HVgh_NMMNzQZetoj4iH5YmxzFkgKBxOJabi5UPaC-9TXw9Wxa-UXWsQr6B72r2qSDZ3DfFPVB0C8PZw0Og2YrUSgMHoZfp5Gz1ik5XKg276oCwo2iMEnaRBrXAEnONtizWVXc-tz4VGzJEAaoJCUcwInmc1QITRSlYfthehrKPbJAYVeANXOJbTt1XP2UrjFz5KwsIp9WyaOrkco4bWXWGgrCp8O3hkvYMuJvFDT7o6dPIy8MBZbScdtdubtdC1KW39Uz8ik0YNTCuIzzua2bU3OaPreIWxUb3opDpso4gzTsLRpWVe1UQS4S6MZ0ZpBah8TvmcApe-upPE9uueWiX_CgNkE3Qw0RDar5vPe7xJvHxSUDuwXT7ejvuRYMzFFzrX9HqLkiDA7BtPNsTZoCdyEBnZ2gzd32Cp1DT_lttRlmA_K3QAqbFqr-B4_x6xdgCKA-pdrj78_ubSaJioEGDPrZXAt6HtJ36GMdvmOHyx_ofpBrYcEDhH2dJqS1JPYNUxxcIcdMwzxNStVLs2fYPEGZKnuqjDRMIznJwtCq1fUjcDj-ST0xy8kRjPUSV_xZZjjDVnng_M-iQp0tJyyZwYoEa_2ky_) | [SVG](https://www.plantuml.com/plantuml/svg/TLPVRzis47_NfpZagSFcfaaVEWp3KDcM7NLoR4jAkW0535ewosmaIYEf34PHO1zYdt2VP4TIScmPUp6fkzyTx-yl-QWqaxgjIdXtEoflHrneb8ALojDSbmWHEw24M_Ztxt_0lqyUmmHw232PxRd6JBSIFKyzSz4moIh8wggf1GgTw0Eva8HWeYZn1DAmx9aLE0HuBDErXAkrXcjOBo9u2A-0ALYdlUQzp4VaGX--21D78PdcjL0M5VoHUbxd6QwYMxXc3Rz-kG7LoXtBq86cys3ZhqBuvi5hf70L1qaAicufDukBbmzf49zZ_5RleU9vNk9VJE8NyMQCTCeVh8N_aDujFW-yufyjAWqlhEIv3PMCbWqA4u7AzbWnvQmV_IYSdXi7KbBA5MiQb6GMpoRmuUTt7nm-Y0V1nKmZbBpYnmpyD3Y794a0MrcpF6DAMv_aUQJQhSeaRqnqiEEbxXCY-Dt3sFj-KbGgff-pXY1kCZeN4bNToWoXglEsn2ubV-glg8R3IcUiGibSooR-OkCFqYOVM3hrOZczK6DUe3ffvK2TOrFMXuhkeuBQsJZeT7u1P7oacNfs-jHFVhzywOMExgd72-tELNaMNtek6wVpezMbLjIQxtXsChVtopISNU3KWNfKkKOy9HVgh_NMMNzQZetoj4iH5YmxzFkgKBxOJabi5UPaC-9TXw9Wxa-UXWsQr6B72r2qSDZ3DfFPVB0C8PZw0Og2YrUSgMHoZfp5Gz1ik5XKg276oCwo2iMEnaRBrXAEnONtizWVXc-tz4VGzJEAaoJCUcwInmc1QITRSlYfthehrKPbJAYVeANXOJbTt1XP2UrjFz5KwsIp9WyaOrkco4bWXWGgrCp8O3hkvYMuJvFDT7o6dPIy8MBZbScdtdubtdC1KW39Uz8ik0YNTCuIzzua2bU3OaPreIWxUb3opDpso4gzTsLRpWVe1UQS4S6MZ0ZpBah8TvmcApe-upPE9uueWiX_CgNkE3Qw0RDar5vPe7xJvHxSUDuwXT7ejvuRYMzFFzrX9HqLkiDA7BtPNsTZoCdyEBnZ2gzd32Cp1DT_lttRlmA_K3QAqbFqr-B4_x6xdgCKA-pdrj78_ubSaJioEGDPrZXAt6HtJ36GMdvmOHyx_ofpBrYcEDhH2dJqS1JPYNUxxcIcdMwzxNStVLs2fYPEGZKnuqjDRMIznJwtCq1fUjcDj-ST0xy8kRjPUSV_xZZjjDVnng_M-iQp0tJyyZwYoEa_2ky_) |
|
||||
| 03 | **l2 ownership** | Human-owned vs AI-coder-built vs reused legacy modules in L2. | [PNG](https://www.plantuml.com/plantuml/png/PLNRRXCn47tVhnYL5r2xj0tG5XvGjo5f8qAfkWM15AborfEDYTTUR6_32Y7nn1Vq2_aIPYzfO_CKQtNE-FZCcScfTSougf1my2AMWrYl5Hgx56NaX9C8KrQZWG7y_NqFPvMG71uHaLq9LJB32iXqKMg5ogMk9fR1p36LIzo2b2nRiHn3GDH_XvsBgc2g5S1dwYapsL8uWZtR0MRXujE7v1AUJ4M-T5zHIhs6dn4ytWixrwFq1eok79gPsWLMkIKKWdE9QsQmAt8OKCP3E3uvE9xHYumsKB2oHDD11pxqOuagkPh07PE2CoUqcgbIb2Y5wck_y0b9S_-2T3PYd5wX0klqHiZBGCXPCcnm5hFA25UJFtS2rntsbO-TKZF-tCFq45ob5CgM9t8bLDxXZw9VMwucapZJ74qyf-uvChRGl9BC0EEi9AzivsyowSqzanM6rcQiG4EWdj8H0Y-fBCe7I2EgAgLc73oNai1Mv3a6TGCVELAPkg1pd5DtIpjJ7ZnmaedOCRiAQWOMuXtzU5hJT0HpGt8pPXzOHpvhOVoYny7DiWm09pv0QISM8cl34-XxxIDjJI8As8SbCaansfyfgVFG_mEVz4tFuNk5rBrTM6kpejRsmB1Jo0MZX4bMzu21bvZH3s4TfGcIo_Jp9AN86AmiSiB6ee_BwCk4fgrBpBbXTPYO6-e1eCetVP_UtYJf-zG7ZQzzoFWw6A7fLO1ellYOeLOBaM-DrlHsE3vltjDjZ3X-IzcEADxDgPKTHTG9XBbsJXUW5zrkeRBlQ2CXPSp2N50yt1A1tcrWXLXQg1HD4N3HhAv-FjyGoI2PRjtMOjY3TflOlNO7xK5cjBLnLhdMrCs8FuzGSMYK_AU7z09SaBMoXisqpfkTO7LbCcntCJse7MiB6LDjlq4eQ3Qjb2Y9hnLzeE6XMngZDjCEQ-6Mj2I9BKamATeMSaf7-Y-8_W40) | [SVG](https://www.plantuml.com/plantuml/svg/PLNRRXCn47tVhnYL5r2xj0tG5XvGjo5f8qAfkWM15AborfEDYTTUR6_32Y7nn1Vq2_aIPYzfO_CKQtNE-FZCcScfTSougf1my2AMWrYl5Hgx56NaX9C8KrQZWG7y_NqFPvMG71uHaLq9LJB32iXqKMg5ogMk9fR1p36LIzo2b2nRiHn3GDH_XvsBgc2g5S1dwYapsL8uWZtR0MRXujE7v1AUJ4M-T5zHIhs6dn4ytWixrwFq1eok79gPsWLMkIKKWdE9QsQmAt8OKCP3E3uvE9xHYumsKB2oHDD11pxqOuagkPh07PE2CoUqcgbIb2Y5wck_y0b9S_-2T3PYd5wX0klqHiZBGCXPCcnm5hFA25UJFtS2rntsbO-TKZF-tCFq45ob5CgM9t8bLDxXZw9VMwucapZJ74qyf-uvChRGl9BC0EEi9AzivsyowSqzanM6rcQiG4EWdj8H0Y-fBCe7I2EgAgLc73oNai1Mv3a6TGCVELAPkg1pd5DtIpjJ7ZnmaedOCRiAQWOMuXtzU5hJT0HpGt8pPXzOHpvhOVoYny7DiWm09pv0QISM8cl34-XxxIDjJI8As8SbCaansfyfgVFG_mEVz4tFuNk5rBrTM6kpejRsmB1Jo0MZX4bMzu21bvZH3s4TfGcIo_Jp9AN86AmiSiB6ee_BwCk4fgrBpBbXTPYO6-e1eCetVP_UtYJf-zG7ZQzzoFWw6A7fLO1ellYOeLOBaM-DrlHsE3vltjDjZ3X-IzcEADxDgPKTHTG9XBbsJXUW5zrkeRBlQ2CXPSp2N50yt1A1tcrWXLXQg1HD4N3HhAv-FjyGoI2PRjtMOjY3TflOlNO7xK5cjBLnLhdMrCs8FuzGSMYK_AU7z09SaBMoXisqpfkTO7LbCcntCJse7MiB6LDjlq4eQ3Qjb2Y9hnLzeE6XMngZDjCEQ-6Mj2I9BKamATeMSaf7-Y-8_W40) |
|
||||
| 04 | **l3 internals** | Qt/QML layers: app shell, network, domain state, screens. | [PNG](https://www.plantuml.com/plantuml/png/RPRTQkD65CVlzHI7NAM4n0rRoXBAieebEsBbBqasB0J2M3gHPosDr9cHiwOKUjK7A7t2VPAU6IcXzYGtiSU_cVFrdx_qMMacTLTNyFClrzM7QouqIi4gvMckAuIO7L721_Znrx-mql0hZ60rY-4L0oRp7TUOwqwYvwaz5osJh8QygTj6eD2fFj8naWWcoWh_XxGitxCIpm5lM8SB6-_AnZFXXrGkW2bOPV27vm6yiNxRGhh3gh8_fmzX71C1zFUM2LpC61VmmaNHl5XivaVpSsRE3hnacZS2PDDHbPPC5kiiF4S3LBmKe8vAOqsDqJkiqUBPGpXpS7xxKS3bxogJnCPSb1rN-YVBHxSVdKJyJk-0fgEHUg2RFL8atSW-WB_E7fxIx7nFA6KZ2MPAKuo2iwefBHycoTCw8lpFawxDKRyqSW-LQQq5vs7czcsA0YKbKa0IfXda5QVbHt7Pj2XOosyEjpVV53Ninz__mFZgQhGQoZBq-Lbf6eBgjYgNV8kI3baDIIJOLaV8TvtOOz7l9_Pf73jJH2hiBOcLddMLvhLT7C4qrH9PFLGp2uF8Fzz_lss-GtD0ILMJxaI1qYQITzJV6bQhZkVxY4RQ9x7OX4diVtMoC559o9gcqqgh12mUHTTM3Ik6yEjblF03f-j1KniXzhEzN2sstqZyT8mvWsxUK7lcPw4xYh6fZQbPK-0WzUnfxC-SxCplfzHi4JXoAKeyXS9W-exCgQPZJP-dT2FQqmt1rD5jb36rFwKoF_tY13_GlnwZscD-mFlk-Nded4bbSxvZaYnHaivEpvuaJWRnCbbMrDnJq2oVemdclELlYRoYyqKMJHpbsdl-WApIknCw_PewCqvpYIWKZNSM3mCT9s4uJzsHnat9XKNYnTGrf82ftRPXie3Heo2pBb4hAzy3nzx60ZzzU5ydK3D1wTJsfbp1Ohw99cGBAZVxZsOfPnNVIkjtzYpIqbDwVjYIjrXnWK2NZ2o8xig1guxSF_2dVN71bAGJEPVTZy28WPR4C--To4ZXNJRfAbJ6HIKlIvfpxo3hE7JpCM8nrKCfUT5tBjeukhK2ivYn1vD_RuKRzy190cqlBPBYCyknZpv9NDIe25ghhjw9wRjBzRAMM9B5osFlHOiWZ5rohIWmbSsAUb31EWqJ1qjHQtfaz37JCCkY-RHN7UcEvJGLIcsURg8KHcJ9eyEj9U_zyPTm7dZUg_gkhpyDrd97wR72XAuxuqJAwzSDOPu2TqORz1vWFlzc5b_F6WmHRcu-zGPBg3gAd9uxiCnIRtWssT_jy-AENXUCnL4woCXhJuZUurt6-qpEJEybtdy0) | [SVG](https://www.plantuml.com/plantuml/svg/RPRTQkD65CVlzHI7NAM4n0rRoXBAieebEsBbBqasB0J2M3gHPosDr9cHiwOKUjK7A7t2VPAU6IcXzYGtiSU_cVFrdx_qMMacTLTNyFClrzM7QouqIi4gvMckAuIO7L721_Znrx-mql0hZ60rY-4L0oRp7TUOwqwYvwaz5osJh8QygTj6eD2fFj8naWWcoWh_XxGitxCIpm5lM8SB6-_AnZFXXrGkW2bOPV27vm6yiNxRGhh3gh8_fmzX71C1zFUM2LpC61VmmaNHl5XivaVpSsRE3hnacZS2PDDHbPPC5kiiF4S3LBmKe8vAOqsDqJkiqUBPGpXpS7xxKS3bxogJnCPSb1rN-YVBHxSVdKJyJk-0fgEHUg2RFL8atSW-WB_E7fxIx7nFA6KZ2MPAKuo2iwefBHycoTCw8lpFawxDKRyqSW-LQQq5vs7czcsA0YKbKa0IfXda5QVbHt7Pj2XOosyEjpVV53Ninz__mFZgQhGQoZBq-Lbf6eBgjYgNV8kI3baDIIJOLaV8TvtOOz7l9_Pf73jJH2hiBOcLddMLvhLT7C4qrH9PFLGp2uF8Fzz_lss-GtD0ILMJxaI1qYQITzJV6bQhZkVxY4RQ9x7OX4diVtMoC559o9gcqqgh12mUHTTM3Ik6yEjblF03f-j1KniXzhEzN2sstqZyT8mvWsxUK7lcPw4xYh6fZQbPK-0WzUnfxC-SxCplfzHi4JXoAKeyXS9W-exCgQPZJP-dT2FQqmt1rD5jb36rFwKoF_tY13_GlnwZscD-mFlk-Nded4bbSxvZaYnHaivEpvuaJWRnCbbMrDnJq2oVemdclELlYRoYyqKMJHpbsdl-WApIknCw_PewCqvpYIWKZNSM3mCT9s4uJzsHnat9XKNYnTGrf82ftRPXie3Heo2pBb4hAzy3nzx60ZzzU5ydK3D1wTJsfbp1Ohw99cGBAZVxZsOfPnNVIkjtzYpIqbDwVjYIjrXnWK2NZ2o8xig1guxSF_2dVN71bAGJEPVTZy28WPR4C--To4ZXNJRfAbJ6HIKlIvfpxo3hE7JpCM8nrKCfUT5tBjeukhK2ivYn1vD_RuKRzy190cqlBPBYCyknZpv9NDIe25ghhjw9wRjBzRAMM9B5osFlHOiWZ5rohIWmbSsAUb31EWqJ1qjHQtfaz37JCCkY-RHN7UcEvJGLIcsURg8KHcJ9eyEj9U_zyPTm7dZUg_gkhpyDrd97wR72XAuxuqJAwzSDOPu2TqORz1vWFlzc5b_F6WmHRcu-zGPBg3gAd9uxiCnIRtWssT_jy-AENXUCnL4woCXhJuZUurt6-qpEJEybtdy0) |
|
||||
| 05 | **seq configure deploy** | Operator workflow: add camera → AI task → deploy → start. | [PNG](https://www.plantuml.com/plantuml/png/XLJHRjem57ttLrpnr6e98QpT0rAxeWuX9bHOq-wfKkN59bWpTchVJA88QH-nBzoNz3efJ0IalUJ1vvnxp_6zper7xh1QQUXTnbw-nBar2rLKJiP2bjgk6IhK4ZBvKacJI_Zx-m_CIkauMWTxieUSh-WGFi1m0iZzJ-16G5F2CyRpGE_iX1tW7XwzTAoaxYfN9JS8dMy8ZvC6cnmYmxli-oHxCWalLV8hhJd3-KaIcNAo9an7uqF2D0KfYWOSVHcF60iU8BwcVZ08iGpSrZay-Dn9QHW115ChmiUZ1qYQdFvpoGjvbRA0485Q4K7BWkThqCeZ2oVnNlgkQkYxVlrU3pOAvSf74Cf5W1QvthPi3OM0-uTilhlYiuLrg_C3P_DPziyQCnObE5Ki4UmYN2N03olMiAHOHdgK0YYSa0OLrpuYEESbLawP8WAr8YVFNhtMeoRCMF0OCBLGfFoQpUwOfDc6BYVZSo5QwPMuIliVs-5JcDgSex9ciFUU1DvX_DlTZkqswqHohkA0-2UpQGezAp6WKX5qkztjIPTq0vm271czkFnqR7H3vGXeJoOBR-T_dX8I9lKhE_GXb2yvvil6mdMza65JwhZqZXf9VHhlHQuoXaRHTjY73T5H3ceH4SYfjhOCHR3oK5gjuOnUO9QDG1FHdTDaZtQxRPcaH3lUsQRNkvS85gKVf1VT_ZRi1MCtzAKV2di3) | [SVG](https://www.plantuml.com/plantuml/svg/XLJHRjem57ttLrpnr6e98QpT0rAxeWuX9bHOq-wfKkN59bWpTchVJA88QH-nBzoNz3efJ0IalUJ1vvnxp_6zper7xh1QQUXTnbw-nBar2rLKJiP2bjgk6IhK4ZBvKacJI_Zx-m_CIkauMWTxieUSh-WGFi1m0iZzJ-16G5F2CyRpGE_iX1tW7XwzTAoaxYfN9JS8dMy8ZvC6cnmYmxli-oHxCWalLV8hhJd3-KaIcNAo9an7uqF2D0KfYWOSVHcF60iU8BwcVZ08iGpSrZay-Dn9QHW115ChmiUZ1qYQdFvpoGjvbRA0485Q4K7BWkThqCeZ2oVnNlgkQkYxVlrU3pOAvSf74Cf5W1QvthPi3OM0-uTilhlYiuLrg_C3P_DPziyQCnObE5Ki4UmYN2N03olMiAHOHdgK0YYSa0OLrpuYEESbLawP8WAr8YVFNhtMeoRCMF0OCBLGfFoQpUwOfDc6BYVZSo5QwPMuIliVs-5JcDgSex9ciFUU1DvX_DlTZkqswqHohkA0-2UpQGezAp6WKX5qkztjIPTq0vm271czkFnqR7H3vGXeJoOBR-T_dX8I9lKhE_GXb2yvvil6mdMza65JwhZqZXf9VHhlHQuoXaRHTjY73T5H3ceH4SYfjhOCHR3oK5gjuOnUO9QDG1FHdTDaZtQxRPcaH3lUsQRNkvS85gKVf1VT_ZRi1MCtzAKV2di3) |
|
||||
| 06 | **seq live events** | Eventview: SSE event tail + click into evidence (image + clip). | [PNG](https://www.plantuml.com/plantuml/png/VLJ1Rjf04BtlLumuLA1YZ5FA0HMIYBeHacb8N7gA52ts52PPR6TtJOYYI3tr2_A5-PBksawAQUd9gtblthnvk_A9qbpgV2sWstSKtZc2DkZW1XEjc2Oj44Ayop6945v-FaDWO2XWq9m4l8T8K7HBoH8eqQc1ABPandYaKmcDymmbDwS6S0LpXP9bPY15b76ZqRZGC9-KsAIEd7uDlq_2gyJb6RaRh-2SplP8OUZ3GgOyZhZIM0unjJffB2W3PJpWLT8CFu0BKqecv-Rx9MmLBUDWCWlhJO4762-nWFtFPpvZrZmu8sCK1c3MIi2tEMm8xw6fkReTzZxsMyp0XcIS6jQP_mtSCinZoxYcs9BUPNo9GuzPalEgUDJjmegiJOguWEeA3gYvIalawrtHkfh6hIwvJac5PceijnYpo_pHBA-IIsdkLK5pGnm2x-NNSt3KAWL7Daz3p7ArAXU-n2YLCRFbjt4nrtm0ZnGFVAyDMhKXNTnWf0SHbsrOBD9j6pgTpjDUYcFxTYeFldTmMVyVKUrOWUQFN8Y3oPjsbzOcyUDxYlLgsEzrwt85wDvak8J5WqQrPt8c-8DzvTd_1XHu5LZnccna4XKj4qjbPSrvQwymZ65-6VoztMCkHHjmcv7XNNFzLCr-bRRJFzKqHZiZ2fdfh5UjKxOMnSpkGWbSw6akDAqn9ixO2IQn-GMmtm00) | [SVG](https://www.plantuml.com/plantuml/svg/VLJ1Rjf04BtlLumuLA1YZ5FA0HMIYBeHacb8N7gA52ts52PPR6TtJOYYI3tr2_A5-PBksawAQUd9gtblthnvk_A9qbpgV2sWstSKtZc2DkZW1XEjc2Oj44Ayop6945v-FaDWO2XWq9m4l8T8K7HBoH8eqQc1ABPandYaKmcDymmbDwS6S0LpXP9bPY15b76ZqRZGC9-KsAIEd7uDlq_2gyJb6RaRh-2SplP8OUZ3GgOyZhZIM0unjJffB2W3PJpWLT8CFu0BKqecv-Rx9MmLBUDWCWlhJO4762-nWFtFPpvZrZmu8sCK1c3MIi2tEMm8xw6fkReTzZxsMyp0XcIS6jQP_mtSCinZoxYcs9BUPNo9GuzPalEgUDJjmegiJOguWEeA3gYvIalawrtHkfh6hIwvJac5PceijnYpo_pHBA-IIsdkLK5pGnm2x-NNSt3KAWL7Daz3p7ArAXU-n2YLCRFbjt4nrtm0ZnGFVAyDMhKXNTnWf0SHbsrOBD9j6pgTpjDUYcFxTYeFldTmMVyVKUrOWUQFN8Y3oPjsbzOcyUDxYlLgsEzrwt85wDvak8J5WqQrPt8c-8DzvTd_1XHu5LZnccna4XKj4qjbPSrvQwymZ65-6VoztMCkHHjmcv7XNNFzLCr-bRRJFzKqHZiZ2fdfh5UjKxOMnSpkGWbSw6akDAqn9ixO2IQn-GMmtm00) |
|
||||
| 07 | **seq liveview** | Liveview: HLS player + bbox overlay synced to PTS. | [PNG](https://www.plantuml.com/plantuml/png/PLFHQjj047o_hrZyP1CRsKdRb42Q62fIWzCwbbCe6CnPsiP7JYVbRgKub48_8b_OB-dUIMhYzaK8pUpEpExgqf6qLEKQngSZXmyZhMgi5JuAKgGH4doeqAG8ltyzmxp5u57H3hRROWz5ZLRB9o5aIeM5tfSIhUIt7aW7jmwjABc_IbKf3K7lXk1src2pGsJwEVawIzOcagMAwadWJ1V_aAunKn8iic8WBEFvzDiXPJu1pEummF77g_WGJP8OjhQGMIeTOUEIlmdXhSBe0zk2C-0GvYLiFvKvJ8vFXa3ItSERj-y6WcbCPd_ClefN4367Wxk8UL4tmWkoqhYoi7I-qqvuDXS5pro6nbKMuTCyWUyykLP4D33pl7ccbPNMi5mbYmxvgyizDvNLS0HknnfXSnbGSO-cqUhY78_7y8EP7A0pTCR5mxMH5UqseM88k2-LHRUHz5Eq-JghFc6drW_qmIitGIC_gTvx9tYNeo7NDWZG4at6mwrLXiNQz6_ekjAaSh_AWVX_abZx1f4ZYpA_y2FVgEoSfmvztjJWC1hXdfgAKLCWX2wA4lWA8NmMuFVxKX2EzWZO8S0hZ-qPWtlYM_T3XCKg4MnSY4j-ylyX_W00) | [SVG](https://www.plantuml.com/plantuml/svg/PLFHQjj047o_hrZyP1CRsKdRb42Q62fIWzCwbbCe6CnPsiP7JYVbRgKub48_8b_OB-dUIMhYzaK8pUpEpExgqf6qLEKQngSZXmyZhMgi5JuAKgGH4doeqAG8ltyzmxp5u57H3hRROWz5ZLRB9o5aIeM5tfSIhUIt7aW7jmwjABc_IbKf3K7lXk1src2pGsJwEVawIzOcagMAwadWJ1V_aAunKn8iic8WBEFvzDiXPJu1pEummF77g_WGJP8OjhQGMIeTOUEIlmdXhSBe0zk2C-0GvYLiFvKvJ8vFXa3ItSERj-y6WcbCPd_ClefN4367Wxk8UL4tmWkoqhYoi7I-qqvuDXS5pro6nbKMuTCyWUyykLP4D33pl7ccbPNMi5mbYmxvgyizDvNLS0HknnfXSnbGSO-cqUhY78_7y8EP7A0pTCR5mxMH5UqseM88k2-LHRUHz5Eq-JghFc6drW_qmIitGIC_gTvx9tYNeo7NDWZG4at6mwrLXiNQz6_ekjAaSh_AWVX_abZx1f4ZYpA_y2FVgEoSfmvztjJWC1hXdfgAKLCWX2wA4lWA8NmMuFVxKX2EzWZO8S0hZ-qPWtlYM_T3XCKg4MnSY4j-ylyX_W00) |
|
||||
| 08 | **seq async scan** | ONVIF camera scan via async job queue (poll /jobs/{id}). | [PNG](https://www.plantuml.com/plantuml/png/TPBTJjj048Nlvob6kMeb_1UXYbe24Qgs2XS9oC0DL6XP3sZ3PcnsrrHL58c7u0dx98pNuLVYRktlUCuvuzttGRdGBItcEucdkqJvVwmJhnL3CC4ILdJN4Ml2_m-FEEafQhKafv0f_6tSBVPY_B9ehh1L8P3Zhm1AXyRXQDwAK4uZL1vFFJbenSveqoeEE3eEU3eTsFGzcSogisbrmPbgJNPVHCtaw8FeK2mbN4SH7yuFglTyFZkR_ehnc8O8rO_93A0FWicUc6A9LP---3vEYsyxQP7csNWR10WMF-57y-e4iw6op-9YUY2yDnG1SSm0yJ5v-KxsSMdgtKKno9_jnlaOLmCh5yNM1QFyWT3vCWwf-nVMyAqlLvxiTPc9r6UBOhs6ZS5UB26JNCS0jcbQR1jhiUDWBChwbuQL1SIt9Nx_b0wRKO8-9CfnjGaXCzdmpHQshhbnv7sPfzjh8Au1ectosbjmPuE7Jtq-TV6TraJrq7OOKwvgutLpJuxgyZnDqpzzutqnbhi9Jm00) | [SVG](https://www.plantuml.com/plantuml/svg/TPBTJjj048Nlvob6kMeb_1UXYbe24Qgs2XS9oC0DL6XP3sZ3PcnsrrHL58c7u0dx98pNuLVYRktlUCuvuzttGRdGBItcEucdkqJvVwmJhnL3CC4ILdJN4Ml2_m-FEEafQhKafv0f_6tSBVPY_B9ehh1L8P3Zhm1AXyRXQDwAK4uZL1vFFJbenSveqoeEE3eEU3eTsFGzcSogisbrmPbgJNPVHCtaw8FeK2mbN4SH7yuFglTyFZkR_ehnc8O8rO_93A0FWicUc6A9LP---3vEYsyxQP7csNWR10WMF-57y-e4iw6op-9YUY2yDnG1SSm0yJ5v-KxsSMdgtKKno9_jnlaOLmCh5yNM1QFyWT3vCWwf-nVMyAqlLvxiTPc9r6UBOhs6ZS5UB26JNCS0jcbQR1jhiUDWBChwbuQL1SIt9Nx_b0wRKO8-9CfnjGaXCzdmpHQshhbnv7sPfzjh8Au1ectosbjmPuE7Jtq-TV6TraJrq7OOKwvgutLpJuxgyZnDqpzzutqnbhi9Jm00) |
|
||||
| 09 | **seq large upload** | Large model upload: initiate → presigned PUT → complete. | [PNG](https://www.plantuml.com/plantuml/png/TPB1Jjj048Rl-nIZd1B9RWA80wX2mA5I2i519Zr5YYRs4AQnrylkc3OW91wYJzWdwJXEqYPIJxlQ-NU-V_xToo3efIuB69p5WPxZ0ls2ujeL5UP6M0g2b9vhiXd1xuzVSDlKeQnoAg1LGPSj2wCGz26hIbUGRXsAaBSzOp2JoaCdSUHHTnt009D0tZWbSyOEhK3dNc0oR6l3_ShLNVfjc4vj7nttNuxMcglnWIYPVwTC82Y0fhQRdgYN4TjXekkNjBU-b5n_DQOXGtoX53Y7CMVBTfPFh-oWUpeOmEYwPxIe4eKqcYHzWFvQ5Cwtasu2cjgtHox8OaaH17wbsNmb52B8dYXRXhfyDqqJxQLixUKy1LvO64yUJ7CIxoYR2kMpsXVjfQt9OpNrrl9cd4VxqWZefsCzcQ6ycutn5gOG-Bmdlj1avcpHhpGeJrX6y8FbIJjM2zM5tixK3fpScF-diNtilsdyOxCamHm53o9u8S-Fgrr01p5KoyFPZs3Km8ov99lhFpL_0000) | [SVG](https://www.plantuml.com/plantuml/svg/TPB1Jjj048Rl-nIZd1B9RWA80wX2mA5I2i519Zr5YYRs4AQnrylkc3OW91wYJzWdwJXEqYPIJxlQ-NU-V_xToo3efIuB69p5WPxZ0ls2ujeL5UP6M0g2b9vhiXd1xuzVSDlKeQnoAg1LGPSj2wCGz26hIbUGRXsAaBSzOp2JoaCdSUHHTnt009D0tZWbSyOEhK3dNc0oR6l3_ShLNVfjc4vj7nttNuxMcglnWIYPVwTC82Y0fhQRdgYN4TjXekkNjBU-b5n_DQOXGtoX53Y7CMVBTfPFh-oWUpeOmEYwPxIe4eKqcYHzWFvQ5Cwtasu2cjgtHox8OaaH17wbsNmb52B8dYXRXhfyDqqJxQLixUKy1LvO64yUJ7CIxoYR2kMpsXVjfQt9OpNrrl9cd4VxqWZefsCzcQ6ycutn5gOG-Bmdlj1avcpHhpGeJrX6y8FbIJjM2zM5tixK3fpScF-diNtilsdyOxCamHm53o9u8S-Fgrr01p5KoyFPZs3Km8ov99lhFpL_0000) |
|
||||
| 10 | **deployment topology** | Workstations / ANSVIS server / edges + ports + customer network. | [PNG](https://www.plantuml.com/plantuml/png/RLJ1Rjf04BtxAqQSY2hKWgEgYgeg4Bkj8m8qfaahSLdiYREDlMljhXEig59F_O0gNvWlwQmtW25mC3kUDxCpR-RvL1kcJ5Naq7_NIx7CPLsWC3qZIvdBhFOCDpb2iF70VEtnz1qN9LEiW4GMfHJaZKrDQ8M9OIBBqVE4J14wPvKsia05cXk4jv3aiaexyEXv00unBL4n8nKyI7L7DHakXRO8eDycFNIkkKZbWuOKzHtLk13V37oFEi0q1FrzSC6IQNmGEjY7ZhceLWUXFa5_RmiTJkAhA0QDwfxwkPNQ7AZo4icf4KebL_L2pCSn65G55xR5XUYAZ8kLvO6bQNtKt3Fv4ar-xETvkOoLL5ANfQoaBF06SinOKXDGeGiUpcRxeHUOSaQJo5dTG2x3yV1d0qgPOKkcBUdBNpGfeDaef0jYdqgwu2AQql_dsAMUZixteiwakE4PbH7Usvk2aNP4ZNQ92jCCWPOhGxCPfFCuhbSVtbEEoLKKHCCcGTXlOTPpVeqQj53db5iAc2ekdDCDYwe8-j3hVNAimWdO2HmV-mjn6SPpIXZ78Js_ZcCl61m2Ue5_yBMphSTIlhKSk_IkiOYAzT7IrpZXepMfnxOrsB7y9cgDsvu7hRDl9KKQMaf3Yg9k9sYiP41LEMgu8GMPMuJaHN0dbgmUJ2kpb9L8ONusitt0ZP8584jkstg3vx__u6Nbx6Axs4ZiXXBk5MOyeDWd6FVjnXkPo1n8pu1s1RgbL8R8DfKGcCDy51oveEkMqa5OnT2wsf9i62cSsyz8NiFpdoTeRNCZAexQGohASk5vftIaJvZt7m00) | [SVG](https://www.plantuml.com/plantuml/svg/RLJ1Rjf04BtxAqQSY2hKWgEgYgeg4Bkj8m8qfaahSLdiYREDlMljhXEig59F_O0gNvWlwQmtW25mC3kUDxCpR-RvL1kcJ5Naq7_NIx7CPLsWC3qZIvdBhFOCDpb2iF70VEtnz1qN9LEiW4GMfHJaZKrDQ8M9OIBBqVE4J14wPvKsia05cXk4jv3aiaexyEXv00unBL4n8nKyI7L7DHakXRO8eDycFNIkkKZbWuOKzHtLk13V37oFEi0q1FrzSC6IQNmGEjY7ZhceLWUXFa5_RmiTJkAhA0QDwfxwkPNQ7AZo4icf4KebL_L2pCSn65G55xR5XUYAZ8kLvO6bQNtKt3Fv4ar-xETvkOoLL5ANfQoaBF06SinOKXDGeGiUpcRxeHUOSaQJo5dTG2x3yV1d0qgPOKkcBUdBNpGfeDaef0jYdqgwu2AQql_dsAMUZixteiwakE4PbH7Usvk2aNP4ZNQ92jCCWPOhGxCPfFCuhbSVtbEEoLKKHCCcGTXlOTPpVeqQj53db5iAc2ekdDCDYwe8-j3hVNAimWdO2HmV-mjn6SPpIXZ78Js_ZcCl61m2Ue5_yBMphSTIlhKSk_IkiOYAzT7IrpZXepMfnxOrsB7y9cgDsvu7hRDl9KKQMaf3Yg9k9sYiP41LEMgu8GMPMuJaHN0dbgmUJ2kpb9L8ONusitt0ZP8584jkstg3vx__u6Nbx6Axs4ZiXXBk5MOyeDWd6FVjnXkPo1n8pu1s1RgbL8R8DfKGcCDy51oveEkMqa5OnT2wsf9i62cSsyz8NiFpdoTeRNCZAexQGohASk5vftIaJvZt7m00) |
|
||||
| 11 | **l3 engineer ownership** | L3 engineers 1–6 and the components each owns. | [PNG](https://www.plantuml.com/plantuml/png/RLRRRYet57tdAxRIbnmb194BglfG7K88HI8NGYwjn8kPsGmkWpsoFIJagDBvX_OBpvTqUSOamISl8VQiVLlxvg_M2UFALKxjTZC_QRBAf68sJVsisDY5B1fEkfnf93Piw8H-VF-F-W54Ro3Qxz1Mr7vfDEnIga8OiQ94hmgjMBc9sq2DuSG9bUNy0LA8P2aoZW6DS4zx_NPbzc588nOfjMYou3odhaaMqW6_Hy8IGB-CPBPmV-6RVgPl3NetJdjZHnqweDwLM3AjjDA62nq4kxlG0ICguJYbk_xadf9SudggvaQlI1UiH26FrksZlwrMGS7vhe9kwHO4OXt3ejDBLZZ1O43tTj4NR6K6nCOwNY4uj-3L5dgn2xqMQva99xKYeql79i3wkx3RYZYfCdgIgdKbajP8gl9bghmXN1-IqaYxVEN3gHAbqysoIE5jq7Qvgwqtf9LmHhw4puF6FnzpSrpbvbOMd2Fzr4ybGgL9mOaKkRGXESSXEUTvoN5g7gKjHKuNtG5n9JrL--E14SL29lPHyZD9HUDnAPFbaqmpTb-2pYXlrpfbokNC2BEXWwbAj5Ae3i_M6gwa5N51DChO907fefaQkKQojcMfEBS17-NiGQKQgJASQb1enPfnMgFstorSxD9KTyu8-jS-eXPT8LPHOqy2EGF3iFvJuLwLkPCh3wS_HXCgSj-Au6ZT3aISH4HK0ath32ECpCWqmAAWpsVwXJIyXa9FUSNmq1VX0OqdWm7h5JkpyRHk3KKqz7AqVkqFxIEmb5NoXergzubdT_SzMYEAmQHohGxYU8llxn9sMX7MqsekCxhKPXLISHh8kfLg6NErcyRnrOZcNX1cFclUOFWqOg_dFHFWuERwSNX9gRI99sb3SuoL87B-gKWYgkghAkvX2AjtDqDa-XKeYz-5NkdCb_LcQpcYymfCvp1Sv2MwrvSmsYxBGExyG_nHOPrLF5q8kvXfOVnqx2Duvwki5ZWBXFMqGPT5ZDqBWuQYT2kEhi5V2oUI1HP3i7aMKLHP85-KlkTz5YMM2A9_vJJ4TXPtsAHFjfpPnCWP0ZgeMk6ydC-tG-mi8kDIvXXm2CUomA2drbHjAunyS6zo5vyLlwlZmg3t0mKpBu2Z8klKY-LFcEaPRMqJnUmysJJkrX8Ti8VsLYby-VRfu2uqnjp2Jz9sUtD8ilrh606TYBMXmax0tcfHMQ0ECAmSMmVVfkh9fvimgIjYCAk3XhZE3F94VdEPMcv_WdkKfdSVdmgnfRyJiUbxuTRekSmHHy5cZl5cBOVyTY8E7onGgKuiKcRc8WcReLEnXxAGk0CiwgUwpLxHUPYypW1IEzExkRw_w_Rk6mtiwAEZtzyli1PspoVH-JGwd-sU6zXZJ3FjdE_kEPOJudXYNbBxn_T_Zt_pZmAH8oX2Oqa_d_rs9Liz7zn2E2hLBDV9qWziIFGxHmsasgz7_bdvyOvoieN4KqBMwoBFqRc-bb9k6ccNjI6qK8eK-vVBd8Kh3N_K_nN_ukNL-1y0) | [SVG](https://www.plantuml.com/plantuml/svg/RLRRRYet57tdAxRIbnmb194BglfG7K88HI8NGYwjn8kPsGmkWpsoFIJagDBvX_OBpvTqUSOamISl8VQiVLlxvg_M2UFALKxjTZC_QRBAf68sJVsisDY5B1fEkfnf93Piw8H-VF-F-W54Ro3Qxz1Mr7vfDEnIga8OiQ94hmgjMBc9sq2DuSG9bUNy0LA8P2aoZW6DS4zx_NPbzc588nOfjMYou3odhaaMqW6_Hy8IGB-CPBPmV-6RVgPl3NetJdjZHnqweDwLM3AjjDA62nq4kxlG0ICguJYbk_xadf9SudggvaQlI1UiH26FrksZlwrMGS7vhe9kwHO4OXt3ejDBLZZ1O43tTj4NR6K6nCOwNY4uj-3L5dgn2xqMQva99xKYeql79i3wkx3RYZYfCdgIgdKbajP8gl9bghmXN1-IqaYxVEN3gHAbqysoIE5jq7Qvgwqtf9LmHhw4puF6FnzpSrpbvbOMd2Fzr4ybGgL9mOaKkRGXESSXEUTvoN5g7gKjHKuNtG5n9JrL--E14SL29lPHyZD9HUDnAPFbaqmpTb-2pYXlrpfbokNC2BEXWwbAj5Ae3i_M6gwa5N51DChO907fefaQkKQojcMfEBS17-NiGQKQgJASQb1enPfnMgFstorSxD9KTyu8-jS-eXPT8LPHOqy2EGF3iFvJuLwLkPCh3wS_HXCgSj-Au6ZT3aISH4HK0ath32ECpCWqmAAWpsVwXJIyXa9FUSNmq1VX0OqdWm7h5JkpyRHk3KKqz7AqVkqFxIEmb5NoXergzubdT_SzMYEAmQHohGxYU8llxn9sMX7MqsekCxhKPXLISHh8kfLg6NErcyRnrOZcNX1cFclUOFWqOg_dFHFWuERwSNX9gRI99sb3SuoL87B-gKWYgkghAkvX2AjtDqDa-XKeYz-5NkdCb_LcQpcYymfCvp1Sv2MwrvSmsYxBGExyG_nHOPrLF5q8kvXfOVnqx2Duvwki5ZWBXFMqGPT5ZDqBWuQYT2kEhi5V2oUI1HP3i7aMKLHP85-KlkTz5YMM2A9_vJJ4TXPtsAHFjfpPnCWP0ZgeMk6ydC-tG-mi8kDIvXXm2CUomA2drbHjAunyS6zo5vyLlwlZmg3t0mKpBu2Z8klKY-LFcEaPRMqJnUmysJJkrX8Ti8VsLYby-VRfu2uqnjp2Jz9sUtD8ilrh606TYBMXmax0tcfHMQ0ECAmSMmVVfkh9fvimgIjYCAk3XhZE3F94VdEPMcv_WdkKfdSVdmgnfRyJiUbxuTRekSmHHy5cZl5cBOVyTY8E7onGgKuiKcRc8WcReLEnXxAGk0CiwgUwpLxHUPYypW1IEzExkRw_w_Rk6mtiwAEZtzyli1PspoVH-JGwd-sU6zXZJ3FjdE_kEPOJudXYNbBxn_T_Zt_pZmAH8oX2Oqa_d_rs9Liz7zn2E2hLBDV9qWziIFGxHmsasgz7_bdvyOvoieN4KqBMwoBFqRc-bb9k6ccNjI6qK8eK-vVBd8Kh3N_K_nN_ukNL-1y0) |
|
||||
| 12 | **dependency chain** | Critical path: contract → mock → UI + adapter → integration → ship. | [PNG](https://www.plantuml.com/plantuml/png/VLFRRjD047ttLnpb2GH9bIBnWa1rKvS6GXF50Ga92MtiYRDqlMljJeB24_y0NyYNC5utQG9INxoxupDdRcSk0YlFczfWUDulgI5RaYrs_MAjj4rOio5S7So8Plpv-HlVrufHAQOGhqaIxhHjb5Sr2bStpfBbd7VYxgbWPIj3IIAXz4eLZ9uJIjNemNOu-1QS_MAVhBpxGVPf3ofWDBrTpDFH8ZbGeJVpEjIeNN67G7vBFY8_J4VlZr7fRVvfdEDCkC-sGwXIDKnUwDEnv5MI3y_HaEzx2cxZ2-hYfLVfx2JOX2ebvNPi4JB9tgQZpoUO5mXhCWRFCC_o1GgZnIwXic77-d7yDR_99fD_dGfFP4CBF9TM_aBsye2_pjAJFEQa39Qgk9C1G5kcoYlMpaRyF4jFkFErRh0Tnd_vpNYM9Fi-ejz_qxNgnDAL7R_nVLzZ2uplGm7xozuQqxm_eoscya0Kd-qdlhfSh6F2qZ6x6cxrC69WQiqE1sbmAwpBwU86GPUYhgLfH-xiG93NKIFoA0ZDPccq3A1y9LCkDUijjVAqbVWuOHmaRS_QgF_5Zfs058AIjcHS4x0cJn09rYZL3iD7dBkc0PSRRLXcWbRqnf3CIGIpLrcRxUn8PoBSScEKrxp3Q_7QhngZyQuIL7WaP6mdyCvfgss5HauUjEdBzd60trYeIXOpSEkqxfP42PiN-OWZEocKPGrHUhtYuqWNSfNjJ_u2) | [SVG](https://www.plantuml.com/plantuml/svg/VLFRRjD047ttLnpb2GH9bIBnWa1rKvS6GXF50Ga92MtiYRDqlMljJeB24_y0NyYNC5utQG9INxoxupDdRcSk0YlFczfWUDulgI5RaYrs_MAjj4rOio5S7So8Plpv-HlVrufHAQOGhqaIxhHjb5Sr2bStpfBbd7VYxgbWPIj3IIAXz4eLZ9uJIjNemNOu-1QS_MAVhBpxGVPf3ofWDBrTpDFH8ZbGeJVpEjIeNN67G7vBFY8_J4VlZr7fRVvfdEDCkC-sGwXIDKnUwDEnv5MI3y_HaEzx2cxZ2-hYfLVfx2JOX2ebvNPi4JB9tgQZpoUO5mXhCWRFCC_o1GgZnIwXic77-d7yDR_99fD_dGfFP4CBF9TM_aBsye2_pjAJFEQa39Qgk9C1G5kcoYlMpaRyF4jFkFErRh0Tnd_vpNYM9Fi-ejz_qxNgnDAL7R_nVLzZ2uplGm7xozuQqxm_eoscya0Kd-qdlhfSh6F2qZ6x6cxrC69WQiqE1sbmAwpBwU86GPUYhgLfH-xiG93NKIFoA0ZDPccq3A1y9LCkDUijjVAqbVWuOHmaRS_QgF_5Zfs058AIjcHS4x0cJn09rYZL3iD7dBkc0PSRRLXcWbRqnf3CIGIpLrcRxUn8PoBSScEKrxp3Q_7QhngZyQuIL7WaP6mdyCvfgss5HauUjEdBzd60trYeIXOpSEkqxfP42PiN-OWZEocKPGrHUhtYuqWNSfNjJ_u2) |
|
||||
@@ -0,0 +1,78 @@
|
||||
# ANSCORE — L2 & L3 Architecture Diagrams (PlantUML)
|
||||
|
||||
12 PlantUML diagrams covering Layer 2 (ANSVIS Communication Layer (CL)) and Layer 3 (Qt/QML UI).
|
||||
|
||||
## Files
|
||||
|
||||
| # | File | Type | Purpose |
|
||||
|---|---|---|---|
|
||||
| 01 | `01-system-context.puml` | Component | L1 / L2 / L3 overview with the 3 transports |
|
||||
| 02 | `02-l2-internals.puml` | Component | L2 adapter layer + legacy + infrastructure |
|
||||
| 03 | `03-l2-ownership.puml` | Component | Human-owned vs AI-coder vs reused legacy modules |
|
||||
| 04 | `04-l3-internals.puml` | Component | Qt/QML shell / network / state / screens |
|
||||
| 05 | `05-seq-configure-deploy.puml` | Sequence | Operator adds camera → AI task → deploys |
|
||||
| 06 | `06-seq-live-events.puml` | Sequence | SSE event tail + evidence image/clip |
|
||||
| 07 | `07-seq-liveview.puml` | Sequence | Liveview with bbox overlay sync |
|
||||
| 08 | `08-seq-async-scan.puml` | Sequence | Async ONVIF scan via job queue |
|
||||
| 09 | `09-seq-large-upload.puml` | Sequence | Large model upload via presigned URL |
|
||||
| 10 | `10-deployment-topology.puml` | Deployment | Workstations / server / edges + ports |
|
||||
| 11 | `11-l3-engineer-ownership.puml` | Component | 6-engineer L3 task allocation |
|
||||
| 12 | `12-dependency-chain.puml` | Component | What gates what, critical path |
|
||||
|
||||
---
|
||||
|
||||
## How to view these in StarUML
|
||||
|
||||
StarUML doesn't render `.puml` natively, but the official **PlantUML extension** does:
|
||||
|
||||
1. In StarUML: `Tools → Extension Manager → search "PlantUML" → Install`
|
||||
2. Restart StarUML.
|
||||
3. `File → Open` → pick any `.puml` file from this folder, **or** use `Tools → PlantUML → Preview Diagram`.
|
||||
4. To get an editable StarUML diagram (`.mdj`), use the extension's "Generate Diagram from PlantUML" feature, then save as `.mdj`.
|
||||
|
||||
Caveat: the extension renders accurately but the auto-generated StarUML elements may need light layout cleanup. If you want fully native StarUML diagrams, use these `.puml` files as the specification and recreate in StarUML — they're small enough that this takes ~10 min each.
|
||||
|
||||
---
|
||||
|
||||
## Alternative viewers (no install needed)
|
||||
|
||||
| Tool | How |
|
||||
|---|---|
|
||||
| **PlantUML web server** | <https://www.plantuml.com/plantuml> → paste any `.puml` content → get PNG/SVG/PDF |
|
||||
| **VS Code** | Install the "PlantUML" extension by jebbs → `Alt+D` to preview |
|
||||
| **JetBrains (CLion / IntelliJ / Rider)** | Install the "PlantUML Integration" plugin → preview on the side panel |
|
||||
| **PlantUML CLI** (batch export) | `brew install plantuml` then `plantuml -tpng docs/diagrams/*.puml -o ../out/` |
|
||||
| **PlantUML CLI** (SVG for slides) | `plantuml -tsvg docs/diagrams/*.puml -o ../out/` |
|
||||
|
||||
The web server is the fastest path if you just want to grab images for a slide deck or PDF.
|
||||
|
||||
---
|
||||
|
||||
## Render all to PNG in one shot
|
||||
|
||||
```bash
|
||||
# from the repo root
|
||||
brew install plantuml # macOS; or: apt install plantuml
|
||||
mkdir -p out/diagrams
|
||||
plantuml -tpng -o "$(pwd)/out/diagrams" docs/diagrams/*.puml
|
||||
```
|
||||
|
||||
Output: one PNG per diagram in `out/diagrams/`.
|
||||
|
||||
For high-DPI presentations use `-tsvg` instead of `-tpng`.
|
||||
|
||||
---
|
||||
|
||||
## Editing tips
|
||||
|
||||
- Diagrams use only stable PlantUML features — should render in any PlantUML version ≥ 1.2022.0.
|
||||
- Colors used: `#LightYellow` (human/lead), `#LightBlue` (AI/E2), `#LightGreen` (E3), `#LightPink` (E4), `#LightCoral` (E5), `#Lavender` (E6), `#LightGray` (reused legacy). Change consistently if you want a different palette.
|
||||
- Each file declares its own `@startuml NAME` so multiple files can render to predictable filenames.
|
||||
- Notes (`note bottom of ...`) are intentional — leave them in; they explain non-obvious decisions.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `docs/L2-L3-architecture.md` — same diagrams in Mermaid + accompanying prose.
|
||||
- `contracts/openapi.v1.json` — the REST contract these diagrams reference.
|
||||
|
After Width: | Height: | Size: 42 KiB |
|
After Width: | Height: | Size: 59 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 42 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 25 KiB |
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 21 KiB |
|
After Width: | Height: | Size: 37 KiB |
|
After Width: | Height: | Size: 104 KiB |
|
After Width: | Height: | Size: 27 KiB |
@@ -0,0 +1,191 @@
|
||||
@page {
|
||||
size: A4;
|
||||
margin: 22mm 18mm 22mm 18mm;
|
||||
@top-right {
|
||||
content: "ANSCORE — System Architecture (L2 + L3)";
|
||||
font-family: -apple-system, "Helvetica Neue", Arial, sans-serif;
|
||||
font-size: 8.5pt;
|
||||
color: #888;
|
||||
}
|
||||
@bottom-right {
|
||||
content: "Page " counter(page) " / " counter(pages);
|
||||
font-family: -apple-system, "Helvetica Neue", Arial, sans-serif;
|
||||
font-size: 8.5pt;
|
||||
color: #888;
|
||||
}
|
||||
@bottom-left {
|
||||
content: "v1.0 • 2026-05-26 • ANSCENTER";
|
||||
font-family: -apple-system, "Helvetica Neue", Arial, sans-serif;
|
||||
font-size: 8.5pt;
|
||||
color: #888;
|
||||
}
|
||||
}
|
||||
|
||||
@page :first {
|
||||
@top-right { content: ""; }
|
||||
@bottom-right { content: ""; }
|
||||
@bottom-left { content: ""; }
|
||||
}
|
||||
|
||||
html, body {
|
||||
font-family: -apple-system, "Helvetica Neue", "Segoe UI", Arial, "Apple Symbols", "STIXGeneral", "Lucida Grande", sans-serif;
|
||||
font-size: 10.5pt;
|
||||
line-height: 1.45;
|
||||
color: #222;
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 22pt;
|
||||
color: #102a55;
|
||||
border-bottom: 2px solid #102a55;
|
||||
padding-bottom: 4pt;
|
||||
margin-top: 0;
|
||||
page-break-before: always;
|
||||
page-break-after: avoid;
|
||||
}
|
||||
|
||||
h1:first-of-type {
|
||||
page-break-before: avoid;
|
||||
}
|
||||
|
||||
h2 {
|
||||
font-size: 15pt;
|
||||
color: #1a4080;
|
||||
margin-top: 1.4em;
|
||||
page-break-after: avoid;
|
||||
}
|
||||
|
||||
h3 {
|
||||
font-size: 12.5pt;
|
||||
color: #1a4080;
|
||||
margin-top: 1.1em;
|
||||
page-break-after: avoid;
|
||||
}
|
||||
|
||||
h4 {
|
||||
font-size: 11pt;
|
||||
color: #333;
|
||||
margin-top: 0.9em;
|
||||
page-break-after: avoid;
|
||||
}
|
||||
|
||||
p, ul, ol {
|
||||
margin: 0.5em 0;
|
||||
}
|
||||
|
||||
ul, ol {
|
||||
padding-left: 1.4em;
|
||||
}
|
||||
|
||||
li {
|
||||
margin: 0.15em 0;
|
||||
}
|
||||
|
||||
a {
|
||||
color: #1a4080;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
code {
|
||||
font-family: "SF Mono", "Menlo", Consolas, monospace;
|
||||
font-size: 9pt;
|
||||
background: #f4f4f6;
|
||||
padding: 1px 4px;
|
||||
border-radius: 3px;
|
||||
color: #2c2c2c;
|
||||
}
|
||||
|
||||
pre {
|
||||
font-family: "SF Mono", "Menlo", Consolas, monospace;
|
||||
font-size: 9pt;
|
||||
background: #f6f8fa;
|
||||
border: 1px solid #e1e4e8;
|
||||
border-radius: 4px;
|
||||
padding: 10pt 12pt;
|
||||
line-height: 1.4;
|
||||
overflow-x: auto;
|
||||
page-break-inside: avoid;
|
||||
}
|
||||
|
||||
pre code {
|
||||
background: transparent;
|
||||
padding: 0;
|
||||
font-size: 9pt;
|
||||
}
|
||||
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
margin: 0.8em 0;
|
||||
font-size: 9.5pt;
|
||||
page-break-inside: avoid;
|
||||
}
|
||||
|
||||
th, td {
|
||||
border: 1px solid #d0d4dc;
|
||||
padding: 5pt 7pt;
|
||||
text-align: left;
|
||||
vertical-align: top;
|
||||
}
|
||||
|
||||
th {
|
||||
background: #eef2f8;
|
||||
color: #102a55;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
tr:nth-child(even) td {
|
||||
background: #fafbfd;
|
||||
}
|
||||
|
||||
img {
|
||||
max-width: 100%;
|
||||
display: block;
|
||||
margin: 0.6em auto;
|
||||
page-break-inside: avoid;
|
||||
}
|
||||
|
||||
hr {
|
||||
border: 0;
|
||||
border-top: 1px solid #d0d4dc;
|
||||
margin: 1.5em 0;
|
||||
}
|
||||
|
||||
blockquote {
|
||||
border-left: 3px solid #c3cad6;
|
||||
margin: 0.6em 0;
|
||||
padding: 0.2em 0.9em;
|
||||
color: #555;
|
||||
background: #f7f8fa;
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
/* Title block (pandoc emits a header div) */
|
||||
header#title-block-header {
|
||||
text-align: center;
|
||||
margin-top: 18%;
|
||||
padding-bottom: 35%;
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
header#title-block-header h1.title {
|
||||
font-size: 30pt;
|
||||
color: #102a55;
|
||||
border-bottom: none;
|
||||
page-break-before: avoid;
|
||||
margin-bottom: 12pt;
|
||||
}
|
||||
|
||||
header#title-block-header p.subtitle {
|
||||
font-size: 14pt;
|
||||
color: #555;
|
||||
font-style: italic;
|
||||
margin: 6pt 0;
|
||||
}
|
||||
|
||||
header#title-block-header p.author,
|
||||
header#title-block-header p.date {
|
||||
font-size: 11pt;
|
||||
color: #777;
|
||||
margin: 4pt 0;
|
||||
}
|
||||
@@ -1,6 +1,8 @@
|
||||
#include "ANSUtilities.h"
|
||||
#ifdef _WIN32
|
||||
#include <windows.h>
|
||||
#include <winevt.h> // EvtQuery / EvtRender for GetANSLoggerErrorEvents
|
||||
#pragma comment(lib, "wevtapi.lib")
|
||||
#endif
|
||||
#include <iostream>
|
||||
#include <CkFileAccess.h>
|
||||
@@ -1309,5 +1311,623 @@ namespace ANSCENTER
|
||||
}
|
||||
return result;
|
||||
}
|
||||
// ====================================================================
|
||||
// GetANSLoggerErrorEvents
|
||||
//
|
||||
// Reads every Error-level event written by the "ANSLogger" source in
|
||||
// the Application channel using the modern winevt API. Events are
|
||||
// produced by WindowsEventSink in ANSLicensingSystem (see
|
||||
// ANSLicense.cpp::ReportEventW) — each carries a single inserted
|
||||
// string in <EventData><Data>...</Data></EventData>.
|
||||
//
|
||||
// DebugView: filter "[EVTLOG]".
|
||||
// ====================================================================
|
||||
std::string ANSUtilities::GetANSLoggerErrorEvents(bool clearAfterRead) {
|
||||
// XPath: Provider name "ANSLogger" AND Level 2 (EVENTLOG_ERROR_TYPE).
|
||||
// Forward direction keeps chronological insertion order so output
|
||||
// matches a fresh "oldest first" scroll through Event Viewer.
|
||||
constexpr const wchar_t* kQuery =
|
||||
L"*[System[Provider[@Name='ANSLogger'] and Level=2]]";
|
||||
|
||||
EVT_HANDLE hResults = EvtQuery(nullptr, L"Application", kQuery,
|
||||
EvtQueryChannelPath | EvtQueryForwardDirection);
|
||||
if (!hResults) {
|
||||
ANS_DBG("EVTLOG", "EvtQuery failed err=%lu", GetLastError());
|
||||
return std::string();
|
||||
}
|
||||
|
||||
std::string out;
|
||||
constexpr DWORD kBatch = 64;
|
||||
EVT_HANDLE events[kBatch];
|
||||
DWORD returned = 0;
|
||||
|
||||
// Render-buffer reused across events to avoid per-event allocation.
|
||||
std::vector<wchar_t> buf(8192);
|
||||
|
||||
while (EvtNext(hResults, kBatch, events, INFINITE, 0, &returned)) {
|
||||
for (DWORD i = 0; i < returned; ++i) {
|
||||
DWORD used = 0, propCount = 0;
|
||||
if (!EvtRender(nullptr, events[i], EvtRenderEventXml,
|
||||
static_cast<DWORD>(buf.size() * sizeof(wchar_t)),
|
||||
buf.data(), &used, &propCount)) {
|
||||
DWORD lastErr = GetLastError();
|
||||
if (lastErr == ERROR_INSUFFICIENT_BUFFER) {
|
||||
buf.resize(used / sizeof(wchar_t) + 1);
|
||||
if (!EvtRender(nullptr, events[i], EvtRenderEventXml,
|
||||
static_cast<DWORD>(buf.size() * sizeof(wchar_t)),
|
||||
buf.data(), &used, &propCount)) {
|
||||
EvtClose(events[i]);
|
||||
continue;
|
||||
}
|
||||
} else {
|
||||
ANS_DBG("EVTLOG", "EvtRender failed err=%lu", lastErr);
|
||||
EvtClose(events[i]);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
std::wstring xml(buf.data());
|
||||
|
||||
// ---- TimeCreated SystemTime='2026-05-18T11:52:07.123Z' ----
|
||||
// EvtRender produces either single- or double-quoted attrs
|
||||
// depending on Windows version, so handle both.
|
||||
std::string formattedTime;
|
||||
auto tcPos = xml.find(L"TimeCreated SystemTime=");
|
||||
if (tcPos != std::wstring::npos) {
|
||||
tcPos += 23; // length of "TimeCreated SystemTime="
|
||||
if (tcPos < xml.size() &&
|
||||
(xml[tcPos] == L'"' || xml[tcPos] == L'\'')) {
|
||||
wchar_t quote = xml[tcPos];
|
||||
++tcPos;
|
||||
auto endQuote = xml.find(quote, tcPos);
|
||||
if (endQuote != std::wstring::npos) {
|
||||
std::wstring iso = xml.substr(tcPos, endQuote - tcPos);
|
||||
int Y = 0, M = 0, D = 0, h = 0, m = 0, s = 0;
|
||||
if (swscanf_s(iso.c_str(), L"%d-%d-%dT%d:%d:%d",
|
||||
&Y, &M, &D, &h, &m, &s) == 6) {
|
||||
SYSTEMTIME utc{};
|
||||
utc.wYear = (WORD)Y; utc.wMonth = (WORD)M; utc.wDay = (WORD)D;
|
||||
utc.wHour = (WORD)h; utc.wMinute = (WORD)m; utc.wSecond = (WORD)s;
|
||||
SYSTEMTIME local{};
|
||||
if (!SystemTimeToTzSpecificLocalTime(nullptr, &utc, &local)) {
|
||||
local = utc; // fallback: show UTC
|
||||
}
|
||||
wchar_t dateBuf[64] = {}, timeBuf[64] = {};
|
||||
GetDateFormatW(LOCALE_USER_DEFAULT, 0, &local, nullptr,
|
||||
dateBuf, _countof(dateBuf));
|
||||
GetTimeFormatW(LOCALE_USER_DEFAULT, 0, &local, nullptr,
|
||||
timeBuf, _countof(timeBuf));
|
||||
std::wstring combined = std::wstring(dateBuf) + L" " + timeBuf;
|
||||
int need = WideCharToMultiByte(CP_UTF8, 0,
|
||||
combined.c_str(), -1, nullptr, 0, nullptr, nullptr);
|
||||
if (need > 1) {
|
||||
formattedTime.resize(need - 1);
|
||||
WideCharToMultiByte(CP_UTF8, 0, combined.c_str(), -1,
|
||||
formattedTime.data(), need, nullptr, nullptr);
|
||||
}
|
||||
} // close: if (swscanf_s ... == 6)
|
||||
} // close: if (endQuote != npos)
|
||||
} // close: if (xml[tcPos] is quote)
|
||||
} // close: if (tcPos != npos)
|
||||
|
||||
// ---- Concatenate every <Data>...</Data> inside <EventData> ----
|
||||
// ReportEventW with N strings produces N consecutive <Data>
|
||||
// elements. ANSLogger sends just one but we handle the general
|
||||
// case so the function works for other sources too.
|
||||
std::wstring wdata;
|
||||
auto edStart = xml.find(L"<EventData");
|
||||
auto edEnd = xml.find(L"</EventData>", edStart);
|
||||
if (edStart != std::wstring::npos && edEnd != std::wstring::npos) {
|
||||
auto bodyEnd = edEnd;
|
||||
auto cursor = edStart;
|
||||
while (cursor < bodyEnd) {
|
||||
auto dOpen = xml.find(L"<Data", cursor);
|
||||
if (dOpen == std::wstring::npos || dOpen >= bodyEnd) break;
|
||||
auto dGt = xml.find(L'>', dOpen);
|
||||
if (dGt == std::wstring::npos || dGt >= bodyEnd) break;
|
||||
auto dClose = xml.find(L"</Data>", dGt);
|
||||
if (dClose == std::wstring::npos || dClose > bodyEnd) break;
|
||||
if (!wdata.empty()) wdata += L' ';
|
||||
wdata.append(xml, dGt + 1, dClose - dGt - 1);
|
||||
cursor = dClose + sizeof("</Data>") - 1;
|
||||
}
|
||||
}
|
||||
std::string utf8Data;
|
||||
if (!wdata.empty()) {
|
||||
int need = WideCharToMultiByte(CP_UTF8, 0, wdata.c_str(), -1,
|
||||
nullptr, 0, nullptr, nullptr);
|
||||
if (need > 1) {
|
||||
utf8Data.resize(need - 1);
|
||||
WideCharToMultiByte(CP_UTF8, 0, wdata.c_str(), -1,
|
||||
utf8Data.data(), need, nullptr, nullptr);
|
||||
}
|
||||
}
|
||||
|
||||
// Flatten embedded CR/LF in the message body so the
|
||||
// "one line per event" contract holds. ChilkatLog and
|
||||
// similar multi-line payloads otherwise break callers
|
||||
// that split on '\n'.
|
||||
for (char& c : utf8Data) if (c == '\r' || c == '\n') c = ' ';
|
||||
|
||||
out += formattedTime;
|
||||
out += ": ";
|
||||
out += utf8Data;
|
||||
out += '\n';
|
||||
|
||||
EvtClose(events[i]);
|
||||
}
|
||||
}
|
||||
DWORD lastErr = GetLastError();
|
||||
if (lastErr != ERROR_NO_MORE_ITEMS) {
|
||||
ANS_DBG("EVTLOG", "EvtNext stopped err=%lu", lastErr);
|
||||
}
|
||||
EvtClose(hResults);
|
||||
|
||||
if (clearAfterRead) {
|
||||
// Clears the entire Application channel — see header warning.
|
||||
if (!EvtClearLog(nullptr, L"Application", nullptr, 0)) {
|
||||
DWORD e = GetLastError();
|
||||
ANS_DBG("EVTLOG", "EvtClearLog failed err=%lu (need admin)", e);
|
||||
} else {
|
||||
ANS_DBG("EVTLOG", "EvtClearLog: Application channel cleared");
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
} // namespace ANSCENTER
|
||||
|
||||
// ============================================================================
|
||||
// ScanDevices — AIBOX / ANSVIS discovery on the local LAN
|
||||
//
|
||||
// Port of the AIBOX Flutter app's MulticastService
|
||||
// (lib/src/core/network/multicast/multicast_service.dart). AIBOX boxes and
|
||||
// ANSVIS servers answer the same UDP probe and the same /ServerApi HTTP
|
||||
// endpoint, so one scan finds both. DebugView: filter "[ANSDISC]".
|
||||
//
|
||||
// Wire protocol:
|
||||
// UDP: probe text "Hello, Multicast" -> 230.50.200.150:58839 and subnet
|
||||
// broadcast :58839. Devices reply to UDP/58838 with
|
||||
// "<a>:<b>:<deviceName>:<firmware>".
|
||||
// HTTP: GET http://<ip>/ServerApi -> 200 + JSON with
|
||||
// {"OK": true, "Version": "<firmware>"}.
|
||||
//
|
||||
// Implementation: a UDP listener thread + a periodic UDP sender + a 64-way
|
||||
// HTTP sweep populate one mutex-guarded map. After `timeoutMs` the map is
|
||||
// converted to a deduplicated vector and returned.
|
||||
// ============================================================================
|
||||
#include <winsock2.h>
|
||||
#include <ws2tcpip.h>
|
||||
#include <iphlpapi.h>
|
||||
#include <winhttp.h>
|
||||
#include <mutex>
|
||||
#include <condition_variable>
|
||||
#include <unordered_map>
|
||||
#include <chrono>
|
||||
#include <queue>
|
||||
|
||||
#pragma comment(lib, "ws2_32.lib")
|
||||
#pragma comment(lib, "iphlpapi.lib")
|
||||
#pragma comment(lib, "winhttp.lib")
|
||||
|
||||
namespace {
|
||||
|
||||
// ---- Protocol constants (mirror AIBOX MulticastService) -----------------
|
||||
constexpr const char* kMulticastGroup = "230.50.200.150";
|
||||
constexpr unsigned short kProbePort = 58839; // device listens here
|
||||
constexpr unsigned short kListenPort = 58838; // we listen here
|
||||
constexpr const char* kProbeMessage = "Hello, Multicast";
|
||||
constexpr int kMulticastTtl = 225;
|
||||
constexpr int kHttpConcurrency = 64;
|
||||
constexpr int kHttpConnectTimeoutMs = 700;
|
||||
constexpr int kHttpProbeTimeoutMs = 2500;
|
||||
constexpr int kUdpProbeIntervalMs = 2000;
|
||||
constexpr const wchar_t* kHttpUserAgent = L"ANSUtilities-Scan/1.0";
|
||||
constexpr const wchar_t* kHttpPath = L"/ServerApi";
|
||||
|
||||
// HTTP ports answered by AIBOX boxes / ANSVIS servers. AIBOX listens on the
|
||||
// default HTTP port; the ANSVIS LabVIEW web server (App_serverConfig.httpPort
|
||||
// in ANSVIS.lvproj) listens on 22211. Each host gets probed on both ports.
|
||||
constexpr unsigned short kPortAibox = 80;
|
||||
constexpr unsigned short kPortAnsvis = 22211;
|
||||
constexpr unsigned short kSweepPorts[] = { kPortAibox, kPortAnsvis };
|
||||
|
||||
// ---- Winsock init (refcounted; safe to call repeatedly) -----------------
|
||||
struct WsaScope {
|
||||
bool ok{false};
|
||||
WsaScope() {
|
||||
WSADATA d{};
|
||||
ok = (WSAStartup(MAKEWORD(2, 2), &d) == 0);
|
||||
}
|
||||
~WsaScope() { if (ok) WSACleanup(); }
|
||||
WsaScope(const WsaScope&) = delete;
|
||||
WsaScope& operator=(const WsaScope&) = delete;
|
||||
};
|
||||
|
||||
// ---- Local IPv4 interfaces ----------------------------------------------
|
||||
struct LocalSubnet {
|
||||
std::string prefix; // "192.168.1." (final dot included)
|
||||
in_addr localAddr{};
|
||||
in_addr broadcast{};
|
||||
};
|
||||
|
||||
std::vector<LocalSubnet> EnumerateLocalSubnets() {
|
||||
std::vector<LocalSubnet> out;
|
||||
ULONG bufLen = 16 * 1024;
|
||||
std::vector<char> buf(bufLen);
|
||||
DWORD rc = GetAdaptersAddresses(AF_INET,
|
||||
GAA_FLAG_SKIP_ANYCAST | GAA_FLAG_SKIP_MULTICAST | GAA_FLAG_SKIP_DNS_SERVER,
|
||||
nullptr, reinterpret_cast<PIP_ADAPTER_ADDRESSES>(buf.data()), &bufLen);
|
||||
if (rc == ERROR_BUFFER_OVERFLOW) {
|
||||
buf.resize(bufLen);
|
||||
rc = GetAdaptersAddresses(AF_INET,
|
||||
GAA_FLAG_SKIP_ANYCAST | GAA_FLAG_SKIP_MULTICAST | GAA_FLAG_SKIP_DNS_SERVER,
|
||||
nullptr, reinterpret_cast<PIP_ADAPTER_ADDRESSES>(buf.data()), &bufLen);
|
||||
}
|
||||
if (rc != NO_ERROR) {
|
||||
ANS_DBG("ANSDISC", "GetAdaptersAddresses failed rc=%lu", static_cast<unsigned long>(rc));
|
||||
return out;
|
||||
}
|
||||
auto* adapter = reinterpret_cast<PIP_ADAPTER_ADDRESSES>(buf.data());
|
||||
for (; adapter; adapter = adapter->Next) {
|
||||
if (adapter->OperStatus != IfOperStatusUp) continue;
|
||||
if (adapter->IfType == IF_TYPE_SOFTWARE_LOOPBACK) continue;
|
||||
for (auto* ua = adapter->FirstUnicastAddress; ua; ua = ua->Next) {
|
||||
if (!ua->Address.lpSockaddr || ua->Address.lpSockaddr->sa_family != AF_INET) continue;
|
||||
auto* sin = reinterpret_cast<sockaddr_in*>(ua->Address.lpSockaddr);
|
||||
// Skip APIPA 169.254.x.x — multicast on link-local rarely useful.
|
||||
unsigned char b0 = reinterpret_cast<unsigned char*>(&sin->sin_addr)[0];
|
||||
unsigned char b1 = reinterpret_cast<unsigned char*>(&sin->sin_addr)[1];
|
||||
if (b0 == 169 && b1 == 254) continue;
|
||||
if (b0 == 127) continue;
|
||||
|
||||
char ipStr[INET_ADDRSTRLEN] = {};
|
||||
inet_ntop(AF_INET, &sin->sin_addr, ipStr, sizeof(ipStr));
|
||||
std::string s(ipStr);
|
||||
auto lastDot = s.find_last_of('.');
|
||||
if (lastDot == std::string::npos) continue;
|
||||
|
||||
LocalSubnet net;
|
||||
net.prefix = s.substr(0, lastDot + 1);
|
||||
net.localAddr = sin->sin_addr;
|
||||
inet_pton(AF_INET, (net.prefix + "255").c_str(), &net.broadcast);
|
||||
out.push_back(net);
|
||||
ANS_DBG("ANSDISC", "iface ip=%s subnet=%s/24", ipStr, net.prefix.c_str());
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
// ---- Parse "<a>:<b>:<name>:<firmware>" reply ----------------------------
|
||||
// parts[0] and parts[1] are not used by the AIBOX Flutter app but the device
|
||||
// still sends them. Observed devices put their listen port in one of those
|
||||
// two fields, so we try both — first numeric wins. Unparseable -> port = 0.
|
||||
void ParseUdpReply(const std::string& body, std::string& name,
|
||||
std::string& firmware, int& port) {
|
||||
std::vector<std::string> parts;
|
||||
size_t start = 0;
|
||||
for (size_t i = 0; i <= body.size(); ++i) {
|
||||
if (i == body.size() || body[i] == ':') {
|
||||
parts.emplace_back(body.data() + start, i - start);
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
if (parts.size() > 3) { name = parts[2]; firmware = parts[3]; }
|
||||
else { name = "Unknown"; firmware = "-"; }
|
||||
|
||||
port = 0;
|
||||
auto tryPort = [&](const std::string& s) {
|
||||
if (port != 0 || s.empty() || s.size() > 5) return;
|
||||
for (char c : s) if (c < '0' || c > '9') return;
|
||||
int v = std::atoi(s.c_str());
|
||||
if (v > 0 && v < 65536) port = v;
|
||||
};
|
||||
if (parts.size() > 0) tryPort(parts[0]);
|
||||
if (parts.size() > 1) tryPort(parts[1]);
|
||||
}
|
||||
|
||||
// ---- Parse {"OK":true,"Version":"x"} ------------------------------------
|
||||
// Tiny scan rather than a JSON dependency. Looks for the two keys with any
|
||||
// amount of whitespace; rejects anything that doesn't say "OK":true.
|
||||
bool ParseServerApiJson(const std::string& body, std::string& version) {
|
||||
auto pos = body.find("\"OK\"");
|
||||
if (pos == std::string::npos) return false;
|
||||
pos = body.find(':', pos);
|
||||
if (pos == std::string::npos) return false;
|
||||
++pos;
|
||||
while (pos < body.size() && (body[pos] == ' ' || body[pos] == '\t')) ++pos;
|
||||
if (body.compare(pos, 4, "true") != 0) return false;
|
||||
|
||||
version.clear();
|
||||
pos = body.find("\"Version\"");
|
||||
if (pos == std::string::npos) { version = "-"; return true; }
|
||||
pos = body.find(':', pos);
|
||||
if (pos == std::string::npos) { version = "-"; return true; }
|
||||
pos = body.find('"', pos);
|
||||
if (pos == std::string::npos) { version = "-"; return true; }
|
||||
++pos;
|
||||
auto end = body.find('"', pos);
|
||||
if (end == std::string::npos) { version = "-"; return true; }
|
||||
version = body.substr(pos, end - pos);
|
||||
if (version.empty()) version = "-";
|
||||
return true;
|
||||
}
|
||||
|
||||
// ---- Shared scan state --------------------------------------------------
|
||||
enum SourceMask { kSrcMulticast = 1, kSrcSweep = 2 };
|
||||
|
||||
struct ScanState {
|
||||
std::mutex mu;
|
||||
std::unordered_map<std::string, ANSCENTER::ANSDeviceInfo> found;
|
||||
std::atomic<bool> stop{false};
|
||||
|
||||
void merge(const std::string& ip, const std::string& name,
|
||||
const std::string& firmware, int port, int srcBit) {
|
||||
std::lock_guard<std::mutex> lk(mu);
|
||||
auto& d = found[ip];
|
||||
if (d.ip.empty()) d.ip = ip;
|
||||
// Prefer non-empty / non-"-" values, regardless of which source ran first.
|
||||
if (!name.empty() && d.name.empty()) d.name = name;
|
||||
if (!firmware.empty() && firmware != "-" &&
|
||||
(d.firmware.empty() || d.firmware == "-")) d.firmware = firmware;
|
||||
else if (!firmware.empty() && d.firmware.empty()) d.firmware = firmware;
|
||||
// Port precedence: an HTTP probe proves the port actually responds,
|
||||
// so a sweep-supplied port overwrites whatever UDP parsing guessed.
|
||||
// A UDP-supplied port is only kept if HTTP hasn't filled it in.
|
||||
if (port > 0) {
|
||||
const bool fromHttp = (srcBit == kSrcSweep);
|
||||
const bool fromHttpAlready = (d.source & kSrcSweep) != 0;
|
||||
if (fromHttp || !fromHttpAlready) d.port = port;
|
||||
}
|
||||
d.source |= srcBit;
|
||||
}
|
||||
};
|
||||
|
||||
// ---- UDP listener thread -------------------------------------------------
|
||||
// Single socket bound to 0.0.0.0:58838, joined to 230.50.200.150 on every
|
||||
// local interface. Reads with a short timeout so it can poll `stop`.
|
||||
void RunUdpListener(ScanState& state, const std::vector<LocalSubnet>& subnets) {
|
||||
SOCKET s = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
|
||||
if (s == INVALID_SOCKET) {
|
||||
ANS_DBG("ANSDISC", "UDP socket() failed err=%d", WSAGetLastError());
|
||||
return;
|
||||
}
|
||||
BOOL on = TRUE;
|
||||
setsockopt(s, SOL_SOCKET, SO_REUSEADDR, reinterpret_cast<char*>(&on), sizeof(on));
|
||||
setsockopt(s, SOL_SOCKET, SO_BROADCAST, reinterpret_cast<char*>(&on), sizeof(on));
|
||||
|
||||
sockaddr_in bindAddr{};
|
||||
bindAddr.sin_family = AF_INET;
|
||||
bindAddr.sin_port = htons(kListenPort);
|
||||
bindAddr.sin_addr.s_addr = htonl(INADDR_ANY);
|
||||
if (bind(s, reinterpret_cast<sockaddr*>(&bindAddr), sizeof(bindAddr)) != 0) {
|
||||
ANS_DBG("ANSDISC", "UDP bind :%u failed err=%d", kListenPort, WSAGetLastError());
|
||||
closesocket(s);
|
||||
return;
|
||||
}
|
||||
|
||||
// Join multicast group on every interface so we receive replies on any path.
|
||||
for (const auto& net : subnets) {
|
||||
ip_mreq mreq{};
|
||||
inet_pton(AF_INET, kMulticastGroup, &mreq.imr_multiaddr);
|
||||
mreq.imr_interface = net.localAddr;
|
||||
if (setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP,
|
||||
reinterpret_cast<char*>(&mreq), sizeof(mreq)) != 0) {
|
||||
ANS_DBG("ANSDISC", "IP_ADD_MEMBERSHIP on %.*s failed err=%d",
|
||||
static_cast<int>(net.prefix.size() - 1), net.prefix.c_str(),
|
||||
WSAGetLastError());
|
||||
}
|
||||
}
|
||||
|
||||
char buf[2048];
|
||||
sockaddr_in from{};
|
||||
int fromLen = sizeof(from);
|
||||
while (!state.stop.load(std::memory_order_relaxed)) {
|
||||
fd_set rfds; FD_ZERO(&rfds); FD_SET(s, &rfds);
|
||||
timeval tv{ 0, 200 * 1000 }; // 200 ms
|
||||
int sel = select(0, &rfds, nullptr, nullptr, &tv);
|
||||
if (sel <= 0) continue;
|
||||
int n = recvfrom(s, buf, sizeof(buf), 0,
|
||||
reinterpret_cast<sockaddr*>(&from), &fromLen);
|
||||
if (n <= 0) continue;
|
||||
std::string body(buf, n);
|
||||
if (body == kProbeMessage) continue; // our own echo
|
||||
char ipStr[INET_ADDRSTRLEN] = {};
|
||||
inet_ntop(AF_INET, &from.sin_addr, ipStr, sizeof(ipStr));
|
||||
std::string name, fw;
|
||||
int port = 0;
|
||||
ParseUdpReply(body, name, fw, port);
|
||||
ANS_DBG("ANSDISC", "UDP reply from %s name=%s fw=%s port=%d raw=%s",
|
||||
ipStr, name.c_str(), fw.c_str(), port, body.c_str());
|
||||
state.merge(ipStr, name, fw, port, kSrcMulticast);
|
||||
}
|
||||
closesocket(s);
|
||||
}
|
||||
|
||||
// ---- UDP sender thread ---------------------------------------------------
|
||||
// Sends "Hello, Multicast" to the multicast group out each interface and
|
||||
// to each subnet broadcast. Repeats every kUdpProbeIntervalMs.
|
||||
void RunUdpSender(ScanState& state, const std::vector<LocalSubnet>& subnets) {
|
||||
SOCKET s = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
|
||||
if (s == INVALID_SOCKET) {
|
||||
ANS_DBG("ANSDISC", "sender socket() failed err=%d", WSAGetLastError());
|
||||
return;
|
||||
}
|
||||
BOOL on = TRUE;
|
||||
setsockopt(s, SOL_SOCKET, SO_BROADCAST, reinterpret_cast<char*>(&on), sizeof(on));
|
||||
int ttl = kMulticastTtl;
|
||||
setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL,
|
||||
reinterpret_cast<char*>(&ttl), sizeof(ttl));
|
||||
|
||||
sockaddr_in mc{};
|
||||
mc.sin_family = AF_INET;
|
||||
mc.sin_port = htons(kProbePort);
|
||||
inet_pton(AF_INET, kMulticastGroup, &mc.sin_addr);
|
||||
|
||||
auto sendOnce = [&]() {
|
||||
for (const auto& net : subnets) {
|
||||
// Pin multicast egress to this interface so it leaves each NIC.
|
||||
setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF,
|
||||
reinterpret_cast<const char*>(&net.localAddr),
|
||||
sizeof(net.localAddr));
|
||||
sendto(s, kProbeMessage, static_cast<int>(strlen(kProbeMessage)), 0,
|
||||
reinterpret_cast<sockaddr*>(&mc), sizeof(mc));
|
||||
sockaddr_in bc{};
|
||||
bc.sin_family = AF_INET;
|
||||
bc.sin_port = htons(kProbePort);
|
||||
bc.sin_addr = net.broadcast;
|
||||
sendto(s, kProbeMessage, static_cast<int>(strlen(kProbeMessage)), 0,
|
||||
reinterpret_cast<sockaddr*>(&bc), sizeof(bc));
|
||||
}
|
||||
};
|
||||
|
||||
sendOnce();
|
||||
auto next = std::chrono::steady_clock::now() + std::chrono::milliseconds(kUdpProbeIntervalMs);
|
||||
while (!state.stop.load(std::memory_order_relaxed)) {
|
||||
auto now = std::chrono::steady_clock::now();
|
||||
if (now >= next) {
|
||||
sendOnce();
|
||||
next = now + std::chrono::milliseconds(kUdpProbeIntervalMs);
|
||||
} else {
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(100));
|
||||
}
|
||||
}
|
||||
closesocket(s);
|
||||
}
|
||||
|
||||
// ---- One synchronous HTTP probe via WinHTTP -----------------------------
|
||||
// On AIBOX/ANSVIS reply: out_version is set and returns true. Otherwise false.
|
||||
bool ProbeHttp(const std::string& ip, unsigned short port, std::string& out_version) {
|
||||
HINTERNET hSession = WinHttpOpen(kHttpUserAgent,
|
||||
WINHTTP_ACCESS_TYPE_NO_PROXY,
|
||||
WINHTTP_NO_PROXY_NAME, WINHTTP_NO_PROXY_BYPASS, 0);
|
||||
if (!hSession) return false;
|
||||
WinHttpSetTimeouts(hSession,
|
||||
kHttpConnectTimeoutMs, kHttpConnectTimeoutMs,
|
||||
kHttpProbeTimeoutMs, kHttpProbeTimeoutMs);
|
||||
|
||||
std::wstring host(ip.begin(), ip.end());
|
||||
HINTERNET hConn = WinHttpConnect(hSession, host.c_str(),
|
||||
static_cast<INTERNET_PORT>(port), 0);
|
||||
if (!hConn) { WinHttpCloseHandle(hSession); return false; }
|
||||
|
||||
HINTERNET hReq = WinHttpOpenRequest(hConn, L"GET", kHttpPath,
|
||||
nullptr, WINHTTP_NO_REFERER, WINHTTP_DEFAULT_ACCEPT_TYPES, 0);
|
||||
if (!hReq) {
|
||||
WinHttpCloseHandle(hConn); WinHttpCloseHandle(hSession);
|
||||
return false;
|
||||
}
|
||||
|
||||
bool ok = false;
|
||||
if (WinHttpSendRequest(hReq, L"Accept: application/json\r\n", static_cast<DWORD>(-1L),
|
||||
WINHTTP_NO_REQUEST_DATA, 0, 0, 0) &&
|
||||
WinHttpReceiveResponse(hReq, nullptr))
|
||||
{
|
||||
DWORD status = 0, statusSize = sizeof(status);
|
||||
if (WinHttpQueryHeaders(hReq,
|
||||
WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
|
||||
WINHTTP_HEADER_NAME_BY_INDEX, &status, &statusSize,
|
||||
WINHTTP_NO_HEADER_INDEX) && status == 200)
|
||||
{
|
||||
std::string body;
|
||||
DWORD avail = 0;
|
||||
// Cap body at 64 KB — /ServerApi is a few hundred bytes.
|
||||
while (body.size() < 65536 && WinHttpQueryDataAvailable(hReq, &avail) && avail) {
|
||||
std::vector<char> buf(avail);
|
||||
DWORD read = 0;
|
||||
if (!WinHttpReadData(hReq, buf.data(), avail, &read)) break;
|
||||
body.append(buf.data(), read);
|
||||
}
|
||||
ok = ParseServerApiJson(body, out_version);
|
||||
}
|
||||
}
|
||||
WinHttpCloseHandle(hReq);
|
||||
WinHttpCloseHandle(hConn);
|
||||
WinHttpCloseHandle(hSession);
|
||||
return ok;
|
||||
}
|
||||
|
||||
// ---- HTTP sweep: 64-way worker pool consuming a queue of (ip, port) -----
|
||||
// Each host is probed on every port in kSweepPorts (80 + 22211) so one
|
||||
// sweep covers both AIBOX and ANSVIS.
|
||||
void RunHttpSweep(ScanState& state, const std::vector<LocalSubnet>& subnets) {
|
||||
struct Target { std::string ip; unsigned short port; };
|
||||
std::queue<Target> q;
|
||||
for (const auto& net : subnets) {
|
||||
for (int h = 1; h <= 254; ++h) {
|
||||
std::string ip = net.prefix + std::to_string(h);
|
||||
for (unsigned short p : kSweepPorts) q.push({ ip, p });
|
||||
}
|
||||
}
|
||||
ANS_DBG("ANSDISC", "HTTP sweep targets=%zu workers=%d", q.size(), kHttpConcurrency);
|
||||
|
||||
std::mutex qmu;
|
||||
auto worker = [&]() {
|
||||
for (;;) {
|
||||
if (state.stop.load(std::memory_order_relaxed)) return;
|
||||
Target t;
|
||||
{
|
||||
std::lock_guard<std::mutex> lk(qmu);
|
||||
if (q.empty()) return;
|
||||
t = std::move(q.front());
|
||||
q.pop();
|
||||
}
|
||||
std::string ver;
|
||||
if (ProbeHttp(t.ip, t.port, ver)) {
|
||||
ANS_DBG("ANSDISC", "HTTP hit %s:%u version=%s",
|
||||
t.ip.c_str(), static_cast<unsigned>(t.port), ver.c_str());
|
||||
state.merge(t.ip, std::string(), ver, static_cast<int>(t.port), kSrcSweep);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
std::vector<std::thread> pool;
|
||||
pool.reserve(kHttpConcurrency);
|
||||
for (int i = 0; i < kHttpConcurrency; ++i) pool.emplace_back(worker);
|
||||
for (auto& t : pool) t.join();
|
||||
}
|
||||
|
||||
} // anonymous namespace
|
||||
|
||||
namespace ANSCENTER {
|
||||
|
||||
std::vector<ANSDeviceInfo> ANSUtilities::ScanDevices(int timeoutMs) {
|
||||
if (timeoutMs < 500) timeoutMs = 500; // floor: enough for one UDP burst
|
||||
|
||||
ANS_DBG("ANSDISC", "ScanDevices: enter timeoutMs=%d", timeoutMs);
|
||||
WsaScope wsa;
|
||||
if (!wsa.ok) {
|
||||
ANS_DBG("ANSDISC", "WSAStartup failed");
|
||||
return {};
|
||||
}
|
||||
|
||||
auto subnets = EnumerateLocalSubnets();
|
||||
if (subnets.empty()) {
|
||||
ANS_DBG("ANSDISC", "no usable IPv4 interfaces; aborting scan");
|
||||
return {};
|
||||
}
|
||||
|
||||
ScanState state;
|
||||
|
||||
std::thread tListen([&]{ RunUdpListener(state, subnets); });
|
||||
std::thread tSend ([&]{ RunUdpSender (state, subnets); });
|
||||
std::thread tSweep ([&]{ RunHttpSweep (state, subnets); });
|
||||
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(timeoutMs));
|
||||
state.stop.store(true, std::memory_order_relaxed);
|
||||
|
||||
tListen.join();
|
||||
tSend.join();
|
||||
tSweep.join();
|
||||
|
||||
std::vector<ANSDeviceInfo> result;
|
||||
{
|
||||
std::lock_guard<std::mutex> lk(state.mu);
|
||||
result.reserve(state.found.size());
|
||||
for (auto& kv : state.found) result.push_back(std::move(kv.second));
|
||||
}
|
||||
ANS_DBG("ANSDISC", "ScanDevices: exit found=%zu", result.size());
|
||||
return result;
|
||||
}
|
||||
|
||||
} // namespace ANSCENTER
|
||||
|
||||
|
||||
@@ -20,6 +20,16 @@
|
||||
#include <functional>
|
||||
|
||||
namespace ANSCENTER {
|
||||
// Discovered AIBOX / ANSVIS server on the local network.
|
||||
struct ANSDeviceInfo {
|
||||
std::string ip; // IPv4 address (dotted-decimal)
|
||||
std::string name; // Device name from UDP probe, empty if HTTP-only
|
||||
std::string firmware; // Version string ("-" if device did not report one)
|
||||
int port{ 0 }; // TCP port the device's HTTP API answers on
|
||||
// (AIBOX = 80, ANSVIS = 22211). 0 = unknown.
|
||||
int source{ 0 }; // 1 = multicast, 2 = HTTP sweep, 3 = both
|
||||
};
|
||||
|
||||
class ANSULT_API ANSUtilities {
|
||||
private:
|
||||
// Protects all shared mutable data
|
||||
@@ -144,6 +154,34 @@ namespace ANSCENTER {
|
||||
// Unescape double-escaped Unicode: "Th\\u1ee7y" becomes "Th\u1ee7y".
|
||||
// Reverses DoubleEscapeUnicode so other languages can parse \uXXXX correctly.
|
||||
static std::string UnescapeDoubleEscapedUnicode(const std::string& str);
|
||||
|
||||
// Read every Error-level event from "ANSLogger" in the Windows
|
||||
// Application event log. Output: one line per event in the form
|
||||
// "<DD/MM/YYYY h:mm:ss tt>: <event data string>\n"
|
||||
// Time is converted to the user's local timezone and formatted
|
||||
// using LOCALE_USER_DEFAULT (matches Event Viewer's display).
|
||||
//
|
||||
// If `clearAfterRead` is true, calls EvtClearLog on the entire
|
||||
// Application channel after reading. WARNING: this wipes every
|
||||
// event from every source in the Application log, not just
|
||||
// ANSLogger entries — there is no per-event delete API in
|
||||
// Windows. Requires Administrator privileges; without elevation
|
||||
// the clear silently fails (events are still returned).
|
||||
[[nodiscard]] static std::string GetANSLoggerErrorEvents(bool clearAfterRead = false);
|
||||
|
||||
// Scan the local network for AIBOX / ANSVIS servers.
|
||||
// Runs two strategies in parallel and merges results by IP:
|
||||
// 1) UDP multicast probe to 230.50.200.150:58839 (with subnet
|
||||
// broadcast fallback). App listens on UDP/58838 for replies
|
||||
// in the form "<a>:<b>:<deviceName>:<firmware>".
|
||||
// 2) HTTP /24 subnet sweep on every local IPv4 interface, GETing
|
||||
// http://<host>/ServerApi with up to 64 concurrent connections.
|
||||
// A device is recognized when the JSON body contains
|
||||
// {"OK": true, "Version": "<firmware>"}.
|
||||
// `timeoutMs` is the maximum scan window (default 5000 ms). Shorter
|
||||
// values return faster but may miss slow devices. The call blocks
|
||||
// until the window elapses, then returns the deduplicated list.
|
||||
[[nodiscard]] static std::vector<ANSDeviceInfo> ScanDevices(int timeoutMs = 5000);
|
||||
};
|
||||
// Connection bundle for pool
|
||||
struct S3Connection {
|
||||
@@ -345,6 +383,21 @@ extern "C" ANSULT_API int SendEmail(const char* smtpServer, int port,
|
||||
|
||||
extern "C" ANSULT_API int RebootSystem();
|
||||
|
||||
// Discover AIBOX / ANSVIS servers on the local network.
|
||||
// Returns a JSON array of objects: [{"ip":"...","name":"...","firmware":"...","source":3}, ...]
|
||||
// `source` is 1 = multicast, 2 = HTTP sweep, 3 = both.
|
||||
// `timeoutMs` caps the scan duration (typical: 3000-10000 ms).
|
||||
extern "C" ANSULT_API int ScanANSDevices(int timeoutMs, LStrHandle resultJson);
|
||||
extern "C" ANSULT_API int ScanANSDevicesCpp(int timeoutMs, std::string& resultJson);
|
||||
|
||||
// Read all Error-level events from "ANSLogger" in the Windows Application
|
||||
// event log. Returns a UTF-8 string with one event per line:
|
||||
// "<DD/MM/YYYY h:mm:ss tt>: <event data>\n"
|
||||
// `clearAfterRead` != 0 clears the entire Application channel afterwards
|
||||
// (requires Administrator; see header comment on the C++ method).
|
||||
extern "C" ANSULT_API int GetANSLoggerErrorEvents(int clearAfterRead, LStrHandle result);
|
||||
extern "C" ANSULT_API int GetANSLoggerErrorEventsCpp(int clearAfterRead, std::string& result);
|
||||
|
||||
// Unicode conversion utilities for LabVIEW
|
||||
extern "C" ANSULT_API int ANSConvertUTF8ToUTF16LE(const char* utf8Str, LStrHandle result, int includeBOM = 1);
|
||||
extern "C" ANSULT_API int ANSDecodeJsonUnicodeToUTF16LE(const char* escapedStr, LStrHandle result);
|
||||
|
||||
@@ -21,7 +21,10 @@ target_link_libraries(ANSUtilities
|
||||
)
|
||||
|
||||
if(WIN32)
|
||||
target_link_libraries(ANSUtilities PRIVATE ${WIN_COMMON_LIBS} crypt32)
|
||||
# WIN_COMMON_LIBS covers ws2_32, iphlpapi, etc. winhttp is needed for the
|
||||
# ScanDevices HTTP /ServerApi sweep. wevtapi is needed for
|
||||
# GetANSLoggerErrorEvents (EvtQuery / EvtRender / EvtClearLog).
|
||||
target_link_libraries(ANSUtilities PRIVATE ${WIN_COMMON_LIBS} crypt32 winhttp wevtapi)
|
||||
endif()
|
||||
|
||||
target_compile_definitions(ANSUtilities PRIVATE UNICODE _UNICODE ANSUTILITIES_EXPORTS)
|
||||
|
||||
@@ -2973,3 +2973,123 @@ extern "C" ANSULT_API int DownloadFileStreamANSAWSHandle_V2(uint64_t handleVal,
|
||||
catch (std::exception& e) { return 0; }
|
||||
catch (...) { return 0; }
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// ScanANSDevices — discover AIBOX / ANSVIS servers on the local network.
|
||||
// Returns 1 on success (resultJson populated, possibly with empty "[]"), 0
|
||||
// on internal failure. The static C++ method does its own license/error
|
||||
// handling; this wrapper just serializes the device list to JSON.
|
||||
// ---------------------------------------------------------------------------
|
||||
static std::string JsonEscape(const std::string& s) {
|
||||
std::string out;
|
||||
out.reserve(s.size() + 2);
|
||||
for (char c : s) {
|
||||
switch (c) {
|
||||
case '"': out += "\\\""; break;
|
||||
case '\\': out += "\\\\"; break;
|
||||
case '\n': out += "\\n"; break;
|
||||
case '\r': out += "\\r"; break;
|
||||
case '\t': out += "\\t"; break;
|
||||
default:
|
||||
if (static_cast<unsigned char>(c) < 0x20) {
|
||||
char buf[8];
|
||||
snprintf(buf, sizeof(buf), "\\u%04x", static_cast<unsigned char>(c));
|
||||
out += buf;
|
||||
} else {
|
||||
out += c;
|
||||
}
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
static std::string DevicesToJson(const std::vector<ANSCENTER::ANSDeviceInfo>& devs) {
|
||||
std::string j = "[";
|
||||
for (size_t i = 0; i < devs.size(); ++i) {
|
||||
if (i) j += ',';
|
||||
j += "{\"ip\":\""; j += JsonEscape(devs[i].ip); j += "\",";
|
||||
j += "\"name\":\""; j += JsonEscape(devs[i].name); j += "\",";
|
||||
j += "\"firmware\":\""; j += JsonEscape(devs[i].firmware); j += "\",";
|
||||
j += "\"port\":"; j += std::to_string(devs[i].port); j += ',';
|
||||
j += "\"source\":"; j += std::to_string(devs[i].source);
|
||||
j += '}';
|
||||
}
|
||||
j += ']';
|
||||
return j;
|
||||
}
|
||||
|
||||
extern "C" ANSULT_API int ScanANSDevicesCpp(int timeoutMs, std::string& resultJson) {
|
||||
ANS_DBG("ANSUTIL", "ScanANSDevicesCpp: timeoutMs=%d", timeoutMs);
|
||||
try {
|
||||
auto devs = ANSCENTER::ANSUtilities::ScanDevices(timeoutMs);
|
||||
resultJson = DevicesToJson(devs);
|
||||
return 1;
|
||||
}
|
||||
catch (const std::exception& e) {
|
||||
ANS_DBG("ANSUTIL", "ScanANSDevicesCpp threw: %s", e.what());
|
||||
resultJson = "[]";
|
||||
return 0;
|
||||
}
|
||||
catch (...) {
|
||||
ANS_DBG("ANSUTIL", "ScanANSDevicesCpp threw unknown");
|
||||
resultJson = "[]";
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
extern "C" ANSULT_API int ScanANSDevices(int timeoutMs, LStrHandle resultJson) {
|
||||
ANS_DBG("ANSUTIL", "ScanANSDevices: timeoutMs=%d", timeoutMs);
|
||||
if (!resultJson) return -1;
|
||||
try {
|
||||
std::string j;
|
||||
ScanANSDevicesCpp(timeoutMs, j);
|
||||
int size = static_cast<int>(j.size());
|
||||
MgErr error = DSSetHandleSize(resultJson, sizeof(int32) + size * sizeof(uChar));
|
||||
if (error != noErr) return -2;
|
||||
(*resultJson)->cnt = size;
|
||||
if (size > 0) memcpy((*resultJson)->str, j.data(), size);
|
||||
return 1;
|
||||
}
|
||||
catch (...) { return -1; }
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// GetANSLoggerErrorEvents — read Error-level events from the ANSLogger source
|
||||
// in the Windows Application event log. Returns 1 on success (string may be
|
||||
// empty if no events match), 0 on internal failure.
|
||||
// `clearAfterRead != 0` triggers EvtClearLog on the entire Application
|
||||
// channel — see ANSUtilities.h header comment for caveats.
|
||||
// ---------------------------------------------------------------------------
|
||||
extern "C" ANSULT_API int GetANSLoggerErrorEventsCpp(int clearAfterRead, std::string& result) {
|
||||
ANS_DBG("ANSUTIL", "GetANSLoggerErrorEventsCpp: clearAfterRead=%d", clearAfterRead);
|
||||
try {
|
||||
result = ANSCENTER::ANSUtilities::GetANSLoggerErrorEvents(clearAfterRead != 0);
|
||||
return 1;
|
||||
}
|
||||
catch (const std::exception& e) {
|
||||
ANS_DBG("ANSUTIL", "GetANSLoggerErrorEventsCpp threw: %s", e.what());
|
||||
result.clear();
|
||||
return 0;
|
||||
}
|
||||
catch (...) {
|
||||
ANS_DBG("ANSUTIL", "GetANSLoggerErrorEventsCpp threw unknown");
|
||||
result.clear();
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
extern "C" ANSULT_API int GetANSLoggerErrorEvents(int clearAfterRead, LStrHandle result) {
|
||||
ANS_DBG("ANSUTIL", "GetANSLoggerErrorEvents: clearAfterRead=%d", clearAfterRead);
|
||||
if (!result) return -1;
|
||||
try {
|
||||
std::string s;
|
||||
GetANSLoggerErrorEventsCpp(clearAfterRead, s);
|
||||
int size = static_cast<int>(s.size());
|
||||
MgErr error = DSSetHandleSize(result, sizeof(int32) + size * sizeof(uChar));
|
||||
if (error != noErr) return -2;
|
||||
(*result)->cnt = size;
|
||||
if (size > 0) memcpy((*result)->str, s.data(), size);
|
||||
return 1;
|
||||
}
|
||||
catch (...) { return -1; }
|
||||
}
|
||||
|
||||
@@ -386,6 +386,123 @@ int ANSLLMOllamaTest() {
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Exercise ANSCENTER::ANSUtilities::ScanDevices — discovers AIBOX boxes and
|
||||
// ANSVIS servers on the local LAN via UDP multicast + HTTP /ServerApi sweep.
|
||||
// Run on a machine connected to the same subnet as at least one device.
|
||||
// DebugView (filter "[ANSDISC]") shows per-device hits and per-interface joins.
|
||||
int ScanDevicesTest()
|
||||
{
|
||||
std::cout << "\n===== ScanDevices (AIBOX / ANSVIS discovery) =====" << std::endl;
|
||||
|
||||
// 1) Direct static C++ call.
|
||||
const int timeoutMs = 5000;
|
||||
std::cout << "Scanning for " << timeoutMs << " ms ..." << std::endl;
|
||||
auto devices = ANSCENTER::ANSUtilities::ScanDevices(timeoutMs);
|
||||
|
||||
std::cout << "Found " << devices.size() << " device(s):" << std::endl;
|
||||
for (const auto& d : devices) {
|
||||
const char* src = (d.source == 3) ? "both"
|
||||
: (d.source == 2) ? "sweep"
|
||||
: (d.source == 1) ? "multicast"
|
||||
: "unknown";
|
||||
std::cout << " " << d.ip << ":" << d.port
|
||||
<< " name=\"" << d.name << "\""
|
||||
<< " firmware=\"" << d.firmware << "\""
|
||||
<< " source=" << src << std::endl;
|
||||
}
|
||||
|
||||
// 2) Exercise the C extern entrypoint that LabVIEW uses.
|
||||
std::string json;
|
||||
int rc = ScanANSDevicesCpp(timeoutMs, json);
|
||||
std::cout << "\nScanANSDevicesCpp rc=" << rc << " json=" << json << std::endl;
|
||||
|
||||
return static_cast<int>(devices.size());
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Example: ANSCENTER::ANSUtilities::GetANSLoggerErrorEvents
|
||||
//
|
||||
// Reads every Error-level event written by the "ANSLogger" source in the
|
||||
// Windows Application event log. Output is a UTF-8 string with one event
|
||||
// per line in the form:
|
||||
// "<DD/MM/YYYY h:mm:ss tt>: <event data>\n"
|
||||
//
|
||||
// Three usage patterns are demonstrated below:
|
||||
// 1. Read everything as one blob — simplest, what LabVIEW will do.
|
||||
// 2. Iterate line-by-line and split out timestamp + message — useful for
|
||||
// programmatic filtering, alerting, or writing to your own sink.
|
||||
// 3. Destructive clear (commented out) — wipes the entire Application
|
||||
// channel; only use if you genuinely want every event from every
|
||||
// source removed. Requires Administrator privileges.
|
||||
//
|
||||
// To verify against Event Viewer:
|
||||
// eventvwr.msc → Windows Logs → Application → Filter Current Log:
|
||||
// Event sources = ANSLogger, Event level = Error
|
||||
// The number this function returns must match Event Viewer's "Number of
|
||||
// events" line shown above the list.
|
||||
// ============================================================================
|
||||
int GetEventLogErrorsTest()
|
||||
{
|
||||
std::cout << "\n===== GetANSLoggerErrorEvents (Windows Event Log) =====" << std::endl;
|
||||
|
||||
// ── 1. Read every Error event from ANSLogger ────────────────────────────
|
||||
const bool kClearAfterRead = false; // NEVER true unless you really mean it
|
||||
std::string events = ANSCENTER::ANSUtilities::GetANSLoggerErrorEvents(kClearAfterRead);
|
||||
|
||||
// Count events (one per newline).
|
||||
int lineCount = 0;
|
||||
for (char c : events) if (c == '\n') ++lineCount;
|
||||
std::cout << "Read " << lineCount << " ANSLogger error event(s), "
|
||||
<< events.size() << " bytes total" << std::endl;
|
||||
|
||||
// ── 2. Iterate line-by-line: extract timestamp + message ────────────────
|
||||
// Format is "<timestamp>: <message>" — split on the first ": ".
|
||||
// Prints the most recent 5 events so output isn't overwhelming.
|
||||
std::cout << "\n--- last 5 events (timestamp / message) ---" << std::endl;
|
||||
std::vector<std::pair<std::string, std::string>> parsed;
|
||||
parsed.reserve(static_cast<size_t>(lineCount));
|
||||
size_t lineStart = 0;
|
||||
for (size_t i = 0; i < events.size(); ++i) {
|
||||
if (events[i] != '\n') continue;
|
||||
std::string line = events.substr(lineStart, i - lineStart);
|
||||
lineStart = i + 1;
|
||||
auto sep = line.find(": ");
|
||||
if (sep == std::string::npos) {
|
||||
parsed.emplace_back(std::string(), std::move(line));
|
||||
} else {
|
||||
parsed.emplace_back(line.substr(0, sep), line.substr(sep + 2));
|
||||
}
|
||||
}
|
||||
const size_t showFrom = parsed.size() > 5 ? parsed.size() - 5 : 0;
|
||||
for (size_t i = showFrom; i < parsed.size(); ++i) {
|
||||
// Truncate noisy messages so the console stays readable.
|
||||
std::string msg = parsed[i].second;
|
||||
if (msg.size() > 120) msg = msg.substr(0, 117) + "...";
|
||||
std::cout << " [" << parsed[i].first << "] " << msg << std::endl;
|
||||
}
|
||||
|
||||
// ── 3. C extern entry point (this is what LabVIEW calls) ────────────────
|
||||
// Signature: int GetANSLoggerErrorEventsCpp(int clearAfterRead, std::string& out)
|
||||
// Passing 0 for clearAfterRead = read only.
|
||||
std::string fromExtern;
|
||||
int rc = GetANSLoggerErrorEventsCpp(0, fromExtern);
|
||||
std::cout << "\nGetANSLoggerErrorEventsCpp rc=" << rc
|
||||
<< " bytes=" << fromExtern.size() << std::endl;
|
||||
|
||||
// ── 4. (DANGER) clear the Application channel after reading ─────────────
|
||||
// Uncomment ONLY if you actually want to wipe every event from every
|
||||
// source in the Application log (not just ANSLogger). Run as Admin or
|
||||
// the clear silently fails (the read still succeeds either way).
|
||||
//
|
||||
// std::string cleared;
|
||||
// int rcClear = GetANSLoggerErrorEventsCpp(1 /* clearAfterRead */, cleared);
|
||||
// std::cout << "After clear: rc=" << rcClear
|
||||
// << " events returned=" << std::count(cleared.begin(), cleared.end(), '\n')
|
||||
// << " (next call should report 0)" << std::endl;
|
||||
|
||||
return lineCount;
|
||||
}
|
||||
|
||||
int main()
|
||||
{
|
||||
//ANSLLMOllamaTest();
|
||||
@@ -393,11 +510,14 @@ int main()
|
||||
//std::cout << "===== MinIO (path-style) =====" << std::endl;
|
||||
//ANSFTechMinIOTest();
|
||||
|
||||
std::cout << "\n===== AWS S3 (virtual-host) =====" << std::endl;
|
||||
ANSAWSTest();
|
||||
//std::cout << "\n===== AWS S3 (virtual-host) =====" << std::endl;
|
||||
//ANSAWSTest();
|
||||
//ANSLLMTest();
|
||||
//SendEmailExample();
|
||||
//uploadFileToGoogleStorage();
|
||||
// EncrypyionExample();
|
||||
|
||||
ScanDevicesTest();
|
||||
GetEventLogErrorsTest();
|
||||
}
|
||||
|
||||
|
||||