On‑Truck System Architecture — ArcGIS / QGIS Integration

1) Overview

The edge device (Pi‑5/Jetson) hosts sensors, a lightweight message broker (MQTT), a geofence engine, and a sync worker. It renders offline maps (tiles) for the driver tablet and publishes events (points + media) to GIS. The architecture is dual‑path so you can deploy either ArcGIS‑first or QGIS‑first without re‑wiring sensors.

2) Components

• Edge compute: Raspberry Pi 5 or Jetson Nano/Orin Nano; Ubuntu/Raspberry Pi OS; Docker optional.
• Message bus: MQTT (Mosquitto). Topics like truck/<route_id>/events/#.
• Edge geo‑service: Python (GeoPandas/Shapely/pyproj) writing to GeoPackage/SpatiaLite + an outbox (SQLite) for store‑and‑forward.
• Map client (cab): ArcGIS Field Maps (ArcGIS path) or QField (QGIS path) on a tablet; read‑only driver UI optional.
• Cloud GIS: ArcGIS Online/Enterprise Feature Services (ArcGIS path) or PostGIS + QGIS Server/GeoServer + Mergin Maps (QGIS path).
• Media store: GIS attachments (ArcGIS) or object storage (S3/MinIO) with URL fields (QGIS).
• Identity: OAuth 2.0 against ArcGIS or application tokens/service accounts for QGIS/PostGIS.

3) Data flow (ASCII diagrams)

3A) Common on‑truck flow

[Sensors: camera, GNSS, temp/TVOC, etc.]
         │
     (MQTT topics)
         │
 [Edge Geo‑Service] ──► writes ► [GeoPackage (local)] + [Outbox (SQLite)]
         │                                 │
         │                                 └─► [Offline tiles (MBTiles)] for cab map
         └─► [Geofence engine] compares GNSS to local polygons (schools/noise zones)
  

3B) ArcGIS‑first (ArcGIS Online/Enterprise)

[Outbox] ─(batch/secure HTTPS)─► [ArcGIS Feature Service (points/lines)]
                      └─────────► [ArcGIS Add Attachment] (images/video)
                                    ▲
                      [Field Maps] ◄─┴─ syncs offline areas + shows events
  

3C) QGIS‑first (PostGIS / QGIS Server)

[Outbox] ─(batch/HTTPS)─► [Sync API] ─► [PostGIS]
                                 └──► [Object store] (S3) for media
        QField (tablet) ◄──── WFS‑T / Mergin sync ───► PostGIS
  

4) Feature schemas

Use normalized layers with small, stable fields. Store heavy media as attachments/objects; keep only URLs in features.

4A) truck_events (point)

4B) truck_tracks (line or point‑time series)

• Fields: route_id, ts_utc, speed_kph, idle_flag, fuel_mode, soc_pct (if EV).
• Generalize older tracks to reduce storage; keep raw points 30–90 days.

Taxonomy (examples)

• contam_flag (hopper camera)
• bin_lift, overage, geofence_enter/exit
• noise_peak, tvoc_peak, battery_risk
• incident_flag (safety/near‑miss)

5) Sync & offline

1. Local cache: write all edits/events to GeoPackage and an outbox (SQLite) with retry metadata.
2. Batching: flush every N events or M seconds; compact large payloads.
3. Conflict strategy: edge is append‑only; server resolves by event_id uniqueness.
4. Offline maps: ArcGIS: prepare Offline Areas in Field Maps (MMPK/VTPK). QGIS: use MBTiles/GeoPackage tiles.
5. Attachments: ArcGIS: Add Attachment API. QGIS: upload to object store; save URL in feature.

6) Security & privacy

• TLS‑only egress; pin CA or use mTLS between truck and sync API.
• Tokens: ArcGIS OAuth 2.0 refresh tokens with short‑lived access tokens; QGIS path uses service account with least privilege to PostGIS schema.
• Privacy: blur faces/plates on device; publish derived features, not raw video. Purge raw media after attachment confirmation.
• PII minimization: avoid storing addresses/plate numbers in attributes; keep route IDs generic.

7) Performance & reliability (targets)

• Edge budget: < 15% CPU avg; < 1 GB RAM for geo‑service; write‑ahead log enabled on SQLite.
• Throughput: batch 50–250 events; backoff (2, 4, 8… min) on network failure.
• Health: /healthz endpoint; MQTT LWT topic for device heartbeat.

8) API examples

8A) ArcGIS — Add Features (REST)

POST https://services.arcgis.com/<orgid>/arcgis/rest/services/truck_events/FeatureServer/0/addFeatures
Content-Type: application/x-www-form-urlencoded
f=json&token=<ACCESS_TOKEN>&features=[{
  "attributes": {
    "event_id":"6f8c9…","ts_utc":1730409726,"route_id":"R-12A","event_type":"contam_flag","severity":2
  },
  "geometry": {"x": -122.3352,"y": 47.6080,"spatialReference":{"wkid":4326}}
}]
  

8B) ArcGIS — Add Attachment

POST .../FeatureServer/0/{objectId}/addAttachment
Headers: Authorization: Bearer <ACCESS_TOKEN>
Form-Data: attachment=@frame_2025-11-01_132206.jpg
  

8C) QGIS path — WFS‑T (GeoServer/QGIS Server)

POST /geoserver/wfs
Content-Type: text/xml
<wfs:Transaction service="WFS" version="1.1.0">
  <wfs:Insert>
    <feature:truck_events>
      <feature:event_id>6f8c9…</feature:event_id>
      <feature:geom><gml:Point srsName="EPSG:4326"><gml:pos>47.6080 -122.3352</gml:pos></gml:Point></feature:geom>
      <feature:event_type>contam_flag</feature:event_type>
    </feature:truck_events>
  </wfs:Insert>
</wfs:Transaction>
  

8D) Example GeoJSON feature (edge outbox)

{
  "type":"Feature",
  "geometry":{"type":"Point","coordinates":[-122.3352,47.6080]},
  "properties":{"event_id":"6f8c9…","ts_utc":"2025-11-01T13:22:06Z","route_id":"R-12A",
                "event_type":"contam_flag","severity":2,"image_url":"file://.../frame.jpg"}
}
  

8E) Minimal edge config (YAML)

mqtt:
  broker: mqtt://localhost:1883
  topics:
    events: truck/+/events/#
outbox:
  db: /var/lib/ontruck/outbox.sqlite
  batch_size: 100
  retry_backoff_min: 120s
geofence:
  gpkg: /opt/maps/geofences.gpkg
  layers: ["schools","noise_zones"]
sync:
  mode: arcgis   # or "qgis"
  arcgis:
    feature_url: https://services.arcgis.com/<org>/.../FeatureServer/0
    token_url: https://www.arcgis.com/sharing/rest/oauth2/token
    client_id: ABC...  # stored securely
  qgis:
    api_base: https://gis.example.com/api
    media_bucket: s3://ontruck-media/
  

9) Source links (primary docs)

• ArcGIS Feature Service (REST)
• ArcGIS — Feature Service overview
• ArcGIS Field Maps — Offline areas
• ArcGIS — OAuth 2.0
• QGIS Documentation
• QField — Mobile GIS
• Mergin Maps — Sync for QGIS
• PostGIS Documentation
• GeoServer • WFS‑T docs
• OGC GeoPackage standard • GeoJSON (RFC 7946)
• Eclipse Mosquitto (MQTT)
• GeoPandas • Shapely