CONNECTORS

A connection layer independent of a single manufacturer.

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.

Synthetic data · integration flow example

AMR-031 / ingestion trace

Demo reference time · 2026-10-04 01:44 UTC

  1. 01

    Register the collection path and source

    The integration team registers the source and configures the Site Agent connection.

  2. 02

    Map source fields

    AMR-031 · battery charge 48% · observed at 01:44:00 UTC

  3. 03

    Track receipt and processing

    Received → Processing → Completed

    Received 01:44:02 UTC · status query 01:44:03 UTC · 1 item
  4. 04

    Normalized state

    AMR-031 · Connected · Running · charge 48% · valid data

Integration flow · synthetic data example. This does not show a live manufacturer connection.
CONNECTION PREPARATION

What connects, and who prepares it?

Collect status, events, missions and sensor data from existing robots, equipment and FMS. Additional manufacturer interfaces use adapter extensions and connection testing.

Choose the connection

Choose direct API delivery from the manufacturer system or Site Agent collection over HTTPS GET/MQTT v5 for the site.

Prepare data and access

Prepare manufacturer/FMS documentation, de-identified samples, asset identifiers, timestamps, units and network requirements. Configure credentials separately in an authorized registration environment.

Review mapping and status

Site and manufacturer teams confirm source meaning and access; integration teams map fields and test. Operations reviews collection status before agreeing the application scope.

Open the API, schema and sample developer guide →

SITE AGENT ROUTE

Site Agent connects outbound from the customer's internal network.

Expose interruptions and buffer saturation to operators. Do not fill observation gaps with seemingly normal data.

1Robot/FMS2Site network3Site Agent4Outbound TLS5RONIQ
SUPPORTED TECHNOLOGIES

Integration technology summary for developers

Additional manufacturer interfaces can be integrated through adapter extensions, with connection tests for their data formats, authentication and site networks.

View protocols, authentication and collection methods

REST

Periodic HTTPS GET · JSON objects/NDJSON · optional Bearer token file. Retains raw data and manufacturer extension fields.

HTTPS GET · JSON/NDJSON

MQTT

MQTT v5 · fixed-topic QoS 1 subscriptions · TLS · username/password files. Supports state, event, mission and telemetry mappings.

v5 · QoS 1 · TLS

Site Agent

REST/MQTT collection · encrypted local buffer · retry. The console displays heartbeat, collection status and buffer usage.

Collection, buffer and resend

Simulator

Generates synthetic data to test field mappings and normalization rules. Does not represent a completed manufacturer SDK integration.

Synthetic trial

From registration to normalized results

Use contract files and synthetic examples to connect state, sensor, error and mission ingestion, Receipt tracking and current-state reads.

Synthetic data · no live accountAMR-031 · SOC 48%

01. Version-pinned contracts and synthetic files

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.

Download JSON, Agent config and Docker examples

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.

02. Match registration and authentication first

  1. An operator registers the customer, site and manufacturer.
  2. Within assigned PlatformAdmin scope, prepare a Connector and ingestion service credential. Confirm registered Connector ID, sourceGeneration and mappingVersion.
  3. An operator registers server sources for the Connector, data kind and generation, and binds robotExternalId to that Connector. Agent sources[] configures collection; it does not register server sources. There is no public Source registration API.
  4. Register components with a user credential authorized to change assets. Record replacement of the old component and register the new component with a new ID. Ingestion service tokens do not create assets.

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.

Current component APIs and change rules
Asset contract · UserBearerHTTP
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.

03. Send data → Receipt → current state

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.

Ingestion operation list
Current ingestion contract · ServiceBearerHTTP
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

Request · POST /ingest/v1/statesJSONDownload file
{
  "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.

Send command · registered local test environmentShell
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

Response · HTTP 202 durable acceptanceJSONDownload file
{
  "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.

Read requests · Receipt and stateShell
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"

Pending, completed, failed and error responses

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.

HTTP 200 · PROCESSINGJSONDownload file
{
  "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"
  }
}

HTTP 200 · COMPLETEDJSONDownload file
{
  "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"
  }
}

HTTP 200 · FAILEDJSONDownload file
{
  "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"
  }
}

Rejected response · HTTP 422 unregistered sourceJSONDownload file
{
  "success": false,
  "code": "BUSINESS_RULE_VIOLATION",
  "message": "등록되지 않은 원본 출처입니다.",
  "data": null,
  "meta": {
    "requestId": "request-demo-031",
    "timestamp": "2026-10-04T01:44:02Z"
  }
}

Current-state response · HTTP 200JSONDownload file
{
  "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.

04. Collect existing APIs and MQTT with Site Agent

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.

Show MQTT message, mapping and Agent settings
MQTT · factory/a/amr-031/state · QoS 1JSONDownload file
{
  "eventId": "state-demo-031-001",
  "robotId": "AMR-031",
  "observedAt": "2026-10-04T01:44:00Z",
  "sequence": 31,
  "connectivity": "ONLINE",
  "operation": "RUNNING",
  "soc": 48,
  "quality": "VALID"
}

Source config · MQTT field mappingJSONDownload file
{
  "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"
  }
}

Agent config · non-resolving HTTPS placeholderJSONDownload file
{
  "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.

Local synthetic Docker setup

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 example · synthetic OEM and Agent imageShell
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-agent

Building 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.

Configuration command · registered-ID placeholdersShell
# 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>

05. Preserve time, units and replay identity

  • observedAt is RFC3339 UTC Z, never substituted with receipt time. The server accepts observations within the past 90 days or next 5 minutes at receipt. Sequence orders equal-time states; late states do not overwrite current state.
  • Exactly one telemetry numericValue/stringValue is non-null. Include unit, source quality and mappingVersion; missing data is not zero or normal. Define current sign and cumulative-counter reset semantics in manufacturer mapping.
  • Preserve eventId, sequence, Idempotency-Key and body on replay. Renew credentials on 401; inspect generation, mapping or duplicate conflicts on 409; honor Retry-After on 429; back off and retry network/5xx errors. Preserve permanent 4xx failures for correction.
  • Ingestion is limited to 60 requests/minute per Connector with burst 10. CSV supports asset import, not sensor ingestion.

06. Supported data and validation scope

These methods support data integration. A manufacturer connection requires mapping and testing in its environment. On small screens, scroll horizontally within the table.

InterfaceData scopeBefore connecting
HTTPS RESTDirect 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 1JSON-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 AgentREST/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 APIsRobot 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.

Get started

Start with the robots you have.
A new way to operate.

Tell us about your robots, FMS and operating needs. Together, we check the environments that can connect.

Start an adoption consultation