Choose the connection
Choose direct API delivery from the manufacturer system or Site Agent collection over HTTPS GET/MQTT v5 for the site.
Connect direct manufacturer/FMS delivery APIs or HTTPS GET and MQTT v5 collection. Prepare data formats and connection access so site and integration teams can review ingestion and mapping together.
Demo reference time · 2026-10-04 01:44 UTC
The integration team registers the source and configures the Site Agent connection.
AMR-031 · battery charge 48% · observed at 01:44:00 UTC
Received → Processing → Completed
Received 01:44:02 UTC · status query 01:44:03 UTC · 1 itemAMR-031 · Connected · Running · charge 48% · valid data
Collect status, events, missions and sensor data from existing robots, equipment and FMS. Additional manufacturer interfaces use adapter extensions and connection testing.
Choose direct API delivery from the manufacturer system or Site Agent collection over HTTPS GET/MQTT v5 for the site.
Prepare manufacturer/FMS documentation, de-identified samples, asset identifiers, timestamps, units and network requirements. Configure credentials separately in an authorized registration environment.
Site and manufacturer teams confirm source meaning and access; integration teams map fields and test. Operations reviews collection status before agreeing the application scope.
Expose interruptions and buffer saturation to operators. Do not fill observation gaps with seemingly normal data.
Additional manufacturer interfaces can be integrated through adapter extensions, with connection tests for their data formats, authentication and site networks.
Periodic HTTPS GET · JSON objects/NDJSON · optional Bearer token file. Retains raw data and manufacturer extension fields.
HTTPS GET · JSON/NDJSONMQTT v5 · fixed-topic QoS 1 subscriptions · TLS · username/password files. Supports state, event, mission and telemetry mappings.
v5 · QoS 1 · TLSREST/MQTT collection · encrypted local buffer · retry. The console displays heartbeat, collection status and buffer usage.
Collection, buffer and resendGenerates synthetic data to test field mappings and normalization rules. Does not represent a completed manufacturer SDK integration.
Synthetic trialUse contract files and synthetic examples to connect state, sensor, error and mission ingestion, Receipt tracking and current-state reads.
The public contract covers six operations for ingestion, receipt tracking and current-state reads. It does not provide administration, credential issuance or prediction APIs. Contract version reference: docs/api/openapi.yaml, SHA-256 ab41dd6bd8e19bb94613f19aaa9319fb639ba546368f37a6784a1a9eea67ebc6.
Displayed code and downloads use the same data; the manifest contains byte hashes. Fixed IDs and times are documentation values. Match registration and measurement time before first transmission.
Ingestion and Receipt reads use a client_credentials ServiceBearer. Robot state and component reads use a scoped UserBearer. Request bodies cannot widen customer or site access.
GET /api/v1/robots/{id}/components
POST /api/v1/robots/{id}/components
PATCH /api/v1/robot-components/{id}Manage model, serial, installation and replacement times for BATTERY, MOTOR, LIDAR and OTHER. Changes require asset permission and expectedVersion checks. Server Source registration is separate from these component APIs.
Use the operator-assigned local HTTPS gateway and OIDC token endpoint. RONIQ_TEST_BASE_URL, RONIQ_SERVICE_TOKEN and RONIQ_USER_TOKEN below are environment variables for assigned test values, not a public sandbox or real token.
This example reports OEM SOC 48% for AMR-031. Runtime estimates and risk scores are not OEM fields in this DTO. Batches contain 1–500 items within 1MiB overall and 512KiB decoded raw bytes per item.
Response message fields preserve the current server language (Korean); codes and schema are unchanged.
POST /ingest/v1/states ingestStates
POST /ingest/v1/telemetry ingestTelemetry
POST /ingest/v1/events ingestEvents
POST /ingest/v1/missions ingestMissions
GET /ingest/v1/receipts/{id} getIngestReceipt{
"connectorId": "connector-demo-031",
"sourceGeneration": 1,
"synthetic": true,
"items": [
{
"eventId": "state-demo-031-001",
"robotExternalId": "AMR-031",
"observedAt": "2026-10-04T01:44:00Z",
"sequence": 31,
"connectivity": "ONLINE",
"operation": "RUNNING",
"batterySoc": 48,
"source": {
"sourceId": "source-demo-states",
"mappingVersion": "mapping-demo-1",
"sourceQuality": "VALID",
"freshnessSeconds": 0
},
"rawPayload": {
"mediaType": "application/json",
"body": "eyJyb2JvdElkIjoiQU1SLTAzMSIsImJhdHRlcnlTb2MiOjQ4fQ==",
"sha256": "c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
},
"extensions": {
"ext.sim.source": "SIMULATOR"
}
}
]
}Raw bytes are UTF-8 {"robotId":"AMR-031","batterySoc":48}. body is their base64 encoding and sha256 hashes the same bytes. This example declares VALID; absent or undefined source quality is preserved as UNKNOWN.
curl --request POST "$RONIQ_TEST_BASE_URL/ingest/v1/states" \
--header "Authorization: Bearer $RONIQ_SERVICE_TOKEN" \
--header "Idempotency-Key: demo-state-031-001" \
--header "Content-Type: application/json" \
--data-binary @apps/web/public/integration/1.1.6/states.request.json{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "RECEIVED",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}HTTP 202 confirms durable acceptance, not completed normalization. Query data.receiptId within the same service scope.
curl "$RONIQ_TEST_BASE_URL/ingest/v1/receipts/<RECEIPT_ID>" \
--header "Authorization: Bearer $RONIQ_SERVICE_TOKEN"
curl "$RONIQ_TEST_BASE_URL/api/v1/robots/<REGISTERED_ROBOT_ID>/state" \
--header "Authorization: Bearer $RONIQ_USER_TOKEN"Receipts progress RECEIVED → PROCESSING → COMPLETED or FAILED. These are alternatives, not completion followed by failure. Reading FAILED still returns HTTP 200 and success:true; data.status describes processing failure. Error objects reject the request itself.
{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "PROCESSING",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "COMPLETED",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "FAILED",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": false,
"code": "BUSINESS_RULE_VIOLATION",
"message": "등록되지 않은 원본 출처입니다.",
"data": null,
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"robotId": "robot-demo-031",
"connectivity": "ONLINE",
"operation": "RUNNING",
"healthOem": null,
"batterySoc": 48,
"observedAt": "2026-10-04T01:44:00Z",
"receivedAt": "2026-10-04T01:44:02Z",
"stale": false,
"synthetic": true,
"sourceId": "source-demo-states",
"mappingVersion": "mapping-demo-1",
"freshnessSeconds": 0,
"extensions": {
"ext.sim.source": "SIMULATOR"
}
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:03Z"
}
}robotId is the server ID; AMR-031 is robotExternalId. observedAt is OEM observation time; receivedAt is server receipt time. After normalization, reconcile source, SOC and mapping version.
The REST adapter polls a registered HTTPS URL with GET and reads JSON objects or NDJSON. Optional Bearer tokens are read from files; redirects and environment proxies are not followed. JSON arrays need a separate adapter defining item boundaries.
MQTT v5 subscribes to a fixed site-broker topic at QoS 1. External connections use TLS and username/password files. +/# wildcards are rejected. The message and Source mapping below describe the same synthetic source.
{
"eventId": "state-demo-031-001",
"robotId": "AMR-031",
"observedAt": "2026-10-04T01:44:00Z",
"sequence": 31,
"connectivity": "ONLINE",
"operation": "RUNNING",
"soc": 48,
"quality": "VALID"
}{
"sourceId": "source-demo-states",
"transport": "mqtt",
"kind": "states",
"mappingVersion": "mapping-demo-1",
"mqttTopic": "factory/a/amr-031/state",
"fields": {
"eventId": "eventId",
"robotExternalId": "robotId",
"observedAt": "observedAt",
"sequence": "sequence",
"connectivity": "connectivity",
"operation": "operation",
"batterySoc": "soc",
"sourceQuality": "quality"
}
}{
"agentId": "agent-demo-031",
"tenantId": "tenant-demo",
"customerId": "customer-demo",
"siteId": "site-demo",
"connectorId": "connector-demo-031",
"sourceGeneration": 1,
"synthetic": true,
"bufferCapacityBytes": 1073741824,
"bufferReserveBytes": 67108864,
"heartbeatSeconds": 60,
"sources": [
{
"sourceId": "source-demo-states",
"transport": "rest",
"kind": "states",
"mappingVersion": "mapping-demo-1",
"fields": {
"eventId": "eventId",
"robotExternalId": "robotId",
"observedAt": "observedAt",
"sequence": "sequence",
"connectivity": "connectivity",
"operation": "operation",
"batterySoc": "batterySoc",
"sourceQuality": "quality"
},
"restUrl": "https://oem.example.invalid/state",
"pollSeconds": 10
}
]
}Agent commits raw data to its encrypted spool before MQTT ACK. QoS 1 duplicates remain possible; delivery is bounded by broker persistent-session retention. Agent-to-Core delivery follows the same HTTPS ingestion and Receipt contract.
Compose is a configuration example for a synthetic OEM REST service. Execution requires Docker and tools/simulator from a separately supplied RONIQ repository. Public downloads alone are not a runnable package. Confirm repository access with your operator, work from its root and ensure port 18081 is available.
docker compose --project-directory . \
-f apps/web/public/integration/1.1.6/compose.synthetic.yaml config --quiet
docker compose --project-directory . \
-f apps/web/public/integration/1.1.6/compose.synthetic.yaml up --build simulator
curl http://127.0.0.1:18081/vendor/atlas/states
docker build -t roniq-site-agent:local apps/site-agentBuilding the Agent requires apps/site-agent from the repository. Before execution, obtain registered scope and an assigned API/OIDC test environment from your operator, then prepare private spool-key and service-secret files and UID 10001 volume permissions. Copy and download provide files; they do not execute APIs or issue credentials. The twelve synthetic sources generated by simulator.agent_config also require a separate MQTT broker.
# Set PYTHONPATH=tools/simulator in an isolated Python environment.
python -m simulator.agent_config --help
python -m simulator.agent_config --output <LOCAL_AGENT_JSON> \
--agent-id <REGISTERED_AGENT_ID> --tenant-id <REGISTERED_TENANT_ID> \
--customer-id <REGISTERED_CUSTOMER_ID> --site-id <REGISTERED_SITE_ID> \
--connector-id <REGISTERED_CONNECTOR_ID>These methods support data integration. A manufacturer connection requires mapping and testing in its environment. On small screens, scroll horizontally within the table.
| Interface | Data scope | Before connecting |
|---|---|---|
| HTTPS REST | Direct POST: states, telemetry, events and missions. Agent GET: JSON-object/NDJSON mapping. | Prepare a test URL, access permissions, field mapping, units and observation times; reconcile acceptance and normalized results. |
| MQTT v5 / QoS 1 | JSON-object state, sensor, error and mission data. Fixed topics and explicit source mappings. | Prepare a fixed topic, TLS and credential files; check disconnection, reconnection and duplicates with the site broker. |
| Site Agent | REST/MQTT → encrypted spool → HTTPS ingestion → Receipt. Preserve provenance, units, time and quality. | Prepare sources, registered scope, private files and volume permissions; check mapping, replay, quality and status in a test environment. |
| UserBearer asset APIs | Robot state reads; model, serial, installation/replacement records for BATTERY, MOTOR, LIDAR and OTHER. | Current-scope, asset-permission and expectedVersion checks. Separate from ingestion credentials. |
Current Health, Battery and Anomaly APIs provide trial observations with quality, coverage, evidence and analysis versions. New runtime estimates, component failure risk, cumulative counters and prediction feeds require further development and are excluded from this public contract. Existing signed Incident webhooks are distinct from prediction notifications. Driving and safety control remain with the OEM/FMS.
Validation checks units, time, provenance, duplicates, reordering, disconnection/replay, invalid sensor values, component replacement and out-of-scope access. Record synthetic tests, manufacturer connections and prediction evaluation separately. Static file/schema conformance does not prove a live integration.
Tell us about your robots, FMS and operating needs. Together, we check the environments that can connect.
Start an adoption consultation