Integrating Intended in C++ Industrial Controls Audience: controls engineers writing C++ for TwinCAT 3 / Beckhoff ADS, Rockwell ControlLogix add-on instructions, Siemens Open Controller / TIA Portal blocks, or custom industrial PCs. C++ integrations call the physical-AI cloud HTTP API directly from a small mediator process you write. This guide shows that pattern; the wire contract is the Authority API reference. Recommended architecture Do not make HTTP calls from your real-time task. A SIL-rated controller's hot path has no business waiting on a cloud round-trip. Run a non-RT mediator process on the same industrial PC, route requests to it over local IPC (Unix socket / shared memory / loopback TCP), and let the mediator own TLS, retries, and idempotency. `` ┌─────────────────────────────┐ ┌──────────────────────────────┐ │ RT task (TwinCAT, Studio) │ │ Non-RT mediator (this guide)│ │ │ │ │ │ 1. fill request struct │───▶│ 2. POST /v1/physical/… │──▶ Intended Cloud │ 6. read decision struct │◀───│ 3. parse response │ │ 7. dispatch motion / SD │ │ 4. publish to local IPC │ └─────────────────────────────┘ └──────────────────────────────┘ ` The mediator owns issuance. Downstream components that need to check a token before actuating verify its RS256 signature against the cloud-served JWKS at /.well-known/jwks.json — see Verify Decision Tokens. Register the actor first Issuance for an unregistered actorIdentity returns 403 actornotregistered. Register each robot once at commissioning. Registering actors and minting tokens both require an API key (or user) holding the admin:config:write permission; otherwise the API returns 403 forbidden. `bash curl -X POST "$INTENDEDAPIURL/v1/physical/actors" \ -H "Authorization: Bearer $INTENDEDAPIKEY" \ -H "x-tenant-id: $INTENDEDTENANTID" \ -H "Content-Type: application/json" \ -d '{"actorIdentity": "axis-station-7", "actorKind": "robot"}' ` `cpp nlohmann::json actor = { {"actorIdentity", "axis-station-7"}, {"actorKind", "robot"}, }; httppostjson(baseurl + "/v1/physical/actors", actor.dump(), apikey, tenantid, /timeoutms=/2000); ` Minimum viable mediator Any reasonable HTTP/JSON stack works. Below: libcurl + nlohmann/json. `cpp #include #include #include #include #include #include #include using nlohmann::json; namespace intended { struct StructuredGoal { std::string schema; // e.g. "opc-ua:1.04:method" std::string verb; // e.g. "move-axis" std::string object; // optional target ("" = omit) json parameters = json::object(); std::string actorkind; // "robot" | "cobot" | "agv" | … std::string actoridentifier; // must be registered }; struct PhysicalDagNode { std::string nodeid; std::string oicode; // "OI-" + 3-4 digits int deadlinems; // == the token's lifetime (max 300000) std::string safedefault; // "stop" | "hold-position" | … std::string realtimetier; // "best-effort" | "rt-soft" | "rt-hard" }; // Fields of the 200 response body of POST /v1/physical/authority-tokens. struct AuthorityResult { std::string decision; // "ALLOW" | "ESCALATE" (DENY arrives as 422/423) std::string token; // ALLOW only std::string tokenjti; // ALLOW only int64t expiresatms = 0; // ALLOW: issuedAt + deadlineMs; ESCALATE: ticket expiry std::string oicode; // ALLOW only bool safetybit = false; std::vector safetycitations; std::string safedefault; // ESCALATE only std::string escalationticketid; // ESCALATE only }; inline json topayload(const StructuredGoal& g) { json j = { {"schema", g.schema}, {"verb", g.verb}, {"parameters", g.parameters}, {"actor", {{"kind", g.actorkind}, {"identifier", g.actoridentifier}}}, }; if (!g.object.empty()) j["object"] = g.object; return j; } inline json topayload(const PhysicalDagNode& n) { return { {"nodeId", n.nodeid}, {"oiCode", n.oicode}, {"deadlineMs", n.deadlinems}, {"safeDefault", n.safedefault}, {"realTimeTier", n.realtimetier}, }; } class Client { public: Client(std::string baseurl, std::string apikey, std::string tenantid) : baseurl(std::move(baseurl)), apikey(std::move(apikey)), tenantid(std::move(tenantid)) {} AuthorityResult classifyandissue( const StructuredGoal& goal, const PhysicalDagNode& dag, const json& physicalstate, const std::string& missionid, const std::string& idempotencykey) { json payload = { {"intent", {{"structuredGoal", topayload(goal)}}}, {"dagNode", topayload(dag)}, {"missionId", missionid}, {"claims", { {"actorIdentity", goal.actoridentifier}, {"deadlineMs", dag.deadlinems}, {"safeDefault", dag.safedefault}, {"safetyBit", true}, }}, }; // physicalState is optional; omit it rather than sending null. if (physicalstate.isobject()) payload["physicalState"] = physicalstate; return post("/v1/physical/authority-tokens", payload, idempotencykey); } private: AuthorityResult post(const std::string& path, const json& body, const std::string& idempotencykey); // … see the libcurl appendix; sets Authorization, x-tenant-id, // Idempotency-Key, Content-Type, and CURLOPTTIMEOUTMS. std::string baseurl, apikey, tenantid; }; } // namespace intended ` The physical issuer returns ALLOW / ESCALATE / DENY. ALLOW and ESCALATE arrive as HTTP 200; a policy DENY arrives as HTTP 422 (policydenied, or 423 for an audit-gap clause) with decision, clauseId, and safeDefault under error.details. Other non-200 responses (400 validation, 402 spendcapreached, 403 actornotregistered / forbidden, 409 idempotency conflicts) mean no token was minted. Branch on the HTTP status, then on decision, and actuate the safe-default on anything other than ALLOW. Calling from a TwinCAT / PLC RT task Don't link libcurl into your RT task. Expose the mediator over ADS / shared memory and let the PLC poll a typed structure: `structured-text ( TwinCAT 3 ST — request issuance ) TYPE STIntentRequest : STRUCT schema : STRING(80); verb : STRING(40); object : STRING(80); deadlinems : UDINT; requestid : UDINT; ENDSTRUCT ENDTYPE TYPE STAuthorityResponse : STRUCT requestid : UDINT; decision : INT; ( 0=ALLOW 1=ESCALATE 2=DENY ) tokenhandle : UDINT; ( mediator-side handle into a token cache ) expiresatms : LINT; safetybit : BOOL; safedefault : STRING(40); ENDSTRUCT ENDTYPE ` The mediator owns the token blob (an RS256 JWT, ~700 bytes). The PLC holds a handle so it can hand the token to a downstream verifier, which checks it against the cloud-served JWKS before motion is commanded. Surfacing safety-bus state The cloud needs structured predicate values, not raw register reads. Bridge once in the mediator and pass the snapshot to each issuance: `cpp json snapshot; snapshot["safety/emergencystop"] = { {"kind", "boolean"}, {"value", readestopchain()}, // ADS read or PROFIsafe register {"asOfTimestampMs", nowms()}, {"attestation", { {"channel", "twincat-safety-plc/estop-chain"}, {"safetyRated", true}, {"protocol", "profisafe"}, }}, }; ` Mark a predicate safetyRated: true only when it actually traverses a safety-rated channel. Misclaiming attestation is a control failure an auditor will catch — and it is the clause that gates "is this robot allowed to move at all." Mediator responsibilities - Fail closed. Classification and issuance happen in the cloud. If the cloud is unreachable or returns anything other than an ALLOW, the mediator reports the safe-default to the PLC. - Author the JSON to the schema. The request and response shapes are defined in packages/contracts/src/physical-ai.ts and documented in the Authority API reference — treat them as the spec. - Budget for the round trip. Each issuance is an HTTP call. For high-rate cycles, pre-issue and cache against expiresAtMs, and send an Idempotency-Key so retries replay the original response instead of minting twice. Appendix — libcurl POST helper `cpp namespace { sizet writecb(char ptr, sizet size, sizet nmemb, void userdata) { staticcast(userdata)->append(ptr, size nmemb); return size nmemb; } std::string httppostjson( const std::string& url, const std::string& body, const std::string& bearer, const std::string& tenantid, long timeoutms, const std::string& idempotencykey = "") { CURL curl = curleasyinit(); if (!curl) throw std::runtimeerror("curleasyinit failed"); curlslist hdrs = nullptr; hdrs = curlslistappend(hdrs, "Content-Type: application/json"); std::string auth = "Authorization: Bearer " + bearer; std::string tenant = "x-tenant-id: " + tenantid; hdrs = curlslistappend(hdrs, auth.cstr()); hdrs = curlslistappend(hdrs, tenant.cstr()); if (!idempotencykey.empty()) { std::string idem = "Idempotency-Key: " + idempotencykey; hdrs = curlslistappend(hdrs, idem.cstr()); } std::string out; curleasysetopt(curl, CURLOPTURL, url.cstr()); curleasysetopt(curl, CURLOPTHTTPHEADER, hdrs); curleasysetopt(curl, CURLOPTPOSTFIELDS, body.cstr()); curleasysetopt(curl, CURLOPTWRITEFUNCTION, writecb); curleasysetopt(curl, CURLOPTWRITEDATA, &out); curleasysetopt(curl, CURLOPTTIMEOUTMS, timeoutms); CURLcode rc = curleasyperform(curl); long httpcode = 0; curleasygetinfo(curl, CURLINFORESPONSECODE, &httpcode); curlslistfreeall(hdrs); curleasycleanup(curl); if (rc != CURLEOK) throw std::runtimeerror(std::string("curl: ") + curleasystrerror(rc)); // 422/423 are policy denials, not transport errors — return the body and // branch on it in the caller rather than throwing. if (httpcode >= 400 && httpcode != 422 && httpcode != 423) throw std::runtimeerror("http " + std::tostring(httpcode) + ": " + out); return out; } int64t nowms() { using namespace std::chrono; return durationcast(systemclock::now().timesinceepoch()).count(); } } // namespace ` See also - Authority API reference — every endpoint, field, and error. - PLC migration patterns — ladder / SCL interlocks translated to policy clauses. - packages/contracts/src/physical-ai.ts` — canonical schemas.

Reference#