# Connecting a real component to the AGRIOS concept This guide describes a proposed integration contract. JSON examples are design examples, not endpoints implemented by this static package. Names, schemas and topics must be agreed and versioned before a hardware pilot. ## 1. Register identity and meaning A component needs a stable identifier, a represented asset, a declared capability and known units. Avoid using a display name as the database key. ```json { "schema": "agrios.proposal.device/v1", "deviceId": "soil-node-01", "assetId": "field-a-zone-1", "kind": "sensor", "adapter": "lorawan-uplink", "capabilities": ["observe_soil_water"], "measurements": [{ "property": "volumetric_water_content", "unit": "m3/m3", "validRange": [0, 0.65], "expectedIntervalSeconds": 600 }] } ``` The example valid range is a configuration assumption, not a universal sensor specification. Production metadata should also include owner, calibration, location and coordinate frame, manufacturer, firmware version and who may modify the registration. Never put private keys, broker passwords or shared secrets in a public manifest. ## 2. Map the native payload once For a LoRaWAN sensor, an illustrative path is: `sensor → LoRaWAN network/application uplink → payload decoder → AGRIOS adapter → validated observation` The application uplink may arrive through MQTT or another integration. The adapter should retain the raw payload and decoder version for diagnosis. LoRaWAN is useful for periodic observations; it should not be assumed to supply tight real-time robot control or immediate actuator acknowledgement. For example, a native payload may contain `moisture_pct: 21.8`. The adapter can convert that to `0.218 m3/m3`; the display can still show `21.8% VWC`. A bare value of `21.8` with no unit is ambiguous. ```json { "schema": "agrios.proposal.observation/v1", "observationId": "soil-node-01:1042", "deviceId": "soil-node-01", "assetId": "field-a-zone-1", "observedAt": "2026-10-10T10:00:00Z", "receivedAt": "2026-10-10T10:00:04Z", "property": "volumetric_water_content", "value": 0.218, "unit": "m3/m3", "quality": "valid", "provenance": { "adapterVersion": "soil-uplink-0.1", "rawEventId": "uplink-1042" } } ``` Validate types, required fields, finite numbers, permitted units, property ranges, duplicate IDs, source identity and clock plausibility. Track source time separately from receive time. A delayed observation can be valid historical data while being unsuitable for a current control decision. A missing measurement is not zero. ## 3. Turn evidence into a reviewable proposal A recommendation should identify its input observations, rule or model version, assumptions, intended action and expiry. In a pilot, also record the operator identity and permission needed to approve it. Recheck relevant conditions at approval and execution time; an old recommendation must not inherit authority indefinitely. For a valve, a proposed command might be: ```json { "schema": "agrios.proposal.command/v1", "commandId": "irrigation-017", "targetDeviceId": "valve-a", "operation": "open_for_duration", "parameters": {"durationSeconds": 120}, "issuedAt": "2026-10-10T10:05:00Z", "expiresAt": "2026-10-10T10:06:00Z", "approvedBy": "operator-01", "evidenceIds": ["soil-node-01:1042"], "constraints": {"maximumDurationSeconds": 120} } ``` The receiver must enforce the duration locally, reject expired commands and make repeated delivery of the same command ID idempotent. A valve-open acknowledgement proves only the reported valve state. Applied water volume needs flow measurement or an explicitly labeled estimate; an improved soil reading needs a subsequent observation. ## 4. Add a robot through capabilities ```json { "schema": "agrios.proposal.robot/v1", "deviceId": "scout-01", "capabilities": ["scout_crop_rows", "capture_rgb"], "supportedFrame": "field-a-local", "limits": {"maximumSpeedMetresPerSecond": 0.4}, "controller": "onboard", "missionInterfaceVersion": "0.1" } ``` A mission should include its unique ID, required capability, field geometry and coordinate frame, completion criteria, speed and operating limits, expiry, feedback interval and abort behavior. Validate all geometry units and frames before a mission can be offered. A robot that lacks a required implement or mission type should be ineligible even when it is nearby. Use separate mission states: 1. **Offered:** the supervisor requests a mission. 2. **Accepted or rejected:** the onboard controller checks feasibility and its current state. 3. **Running:** sequenced status reports carry progress and operational state. 4. **Completed, failed or cancelled:** a terminal report records the outcome and any collected evidence. Status messages need a mission ID, robot ID, timestamp and sequence number so delayed messages cannot overwrite newer state. For example: ```json { "schema": "agrios.proposal.mission-status/v1", "missionId": "scout-026", "robotId": "scout-01", "sequence": 12, "reportedAt": "2026-10-10T10:15:00Z", "state": "running", "progress": 0.35, "safetyState": "operational", "batteryPercent": 74 } ``` For a ROS 2 robot, a local adapter can translate the agreed mission contract into the robot's existing actions and translate feedback back into supervisory events. AGRIOS coordinates intent; it does not replace onboard navigation, obstacle response or emergency stopping. On communication loss, the robot follows a locally implemented and tested policy for the actual machine and site. ## 5. Add a model without hiding its limitations A twin service should declare the represented asset, model version, input properties and units, update interval, prediction horizon, parameters, outputs and validity limits. Reject or clearly flag missing, stale or out-of-range inputs. Store the assumptions alongside the prediction and compare it with later measurements. The browser's simplified soil and greenhouse responses illustrate the loop. Replace them with an appropriately calibrated model before claiming predictive accuracy, agronomic benefit, energy savings or water savings. A deterministic rule can remain useful without being presented as AI. ## 6. Build the first operational pilot Start with one sensor, one asset and one read-only workflow. Verify units, timing, duplicate handling and missing-data behavior using recorded payloads. Then introduce recommendations and manual approvals. Connect one bounded actuator only after acknowledgement, local timeout, feedback and failure behavior work reliably. Add robot missions through the same supervised contract after validating the onboard integration. Production work includes authenticated device identities, encrypted transport, per-asset authorization, schema/version migration, durable storage, replay protection, audit logs, retention settings and monitoring. Public browser code is readable by visitors; service credentials belong on a controlled backend or edge gateway. ## Static hosting and direct-file notes - Unzip the package and open its `index.html`, or upload the extracted folder to a static web host. Preserve the relative file paths and filename capitalization. - The delivered browser demonstration needs no PHP, database, Node.js server, package installation or build step. It uses bundled assets so a live CDN is not needed. - Keeping scripts as ordinary local scripts and embedding the scenario data avoids the common `file://` restrictions on module imports and local `fetch()` requests. Use a modern browser with WebGL enabled for the 3D scene. - Public hosting serves a separate simulation to each visitor; it does not create a shared farm account, synchronize users or connect their hardware. - JSON downloads describe a simulation run or example registration. Importing them into an actual controller requires an implemented adapter and validation; they are not executable deployment credentials. - If a host applies a Content Security Policy, allow the package's own scripts and styles as required by its markup. Check the browser console for blocked assets, capitalization errors or a host that rewrites missing files to an unrelated page. The final package's main README describes the actual controls and launch procedure. This guide describes the additional engineering needed for an operational system.