@sterfive/i3x2ua-node

Bring the i3X REST API to Your OPC UA Server

Executive Summary

Your OPC UA servers already hold rich, structured data — typed objects, variables, namespaces, historical values. But exposing that data to web applications, AI/ML pipelines, and enterprise systems typically requires custom REST APIs, complex middleware, or expensive integration platforms.

@sterfive/i3x2ua-node eliminates that work. It is a complete implementation of the i3X Beta API specification that translates your OPC UA address space into clean, standardized REST/JSON endpoints. Any developer who can call fetch() gets instant access to your industrial data — no OPC UA SDK required.

For decision-makers and system architects, this component delivers:

• Standards-Based: Implements the CESMII i3X specification — the emerging vendor-neutral API standard for smart manufacturing.
• Zero Separate Infrastructure: Integrates directly into your existing OPC UA server — no separate gateway, no additional deployment.
• Web-Native Access: REST/JSON + Server-Sent Events (SSE). Any language, any platform, any cloud.
• Accelerated IT/OT Convergence: IT teams consume OPC UA data via standard web APIs, without learning the OPC UA stack.

Architecture

The component is built with a hexagonal (ports & adapters) DDD architecture, ensuring clean separation of concerns and easy extensibility:

┌──────────────────────────────────────────────────────┐
│                    @i3x/app                          │
│             (Composition Root / Wiring)               │
│                                                      │
│  ┌──────────────────┐    ┌─────────────────────────┐ │
│  │  @i3x/rest-server │    │  @i3x/opcua-connector  │ │
│  │  Fastify routes   │    │  node-opcua client      │ │
│  │  INBOUND ADAPTER  │    │  OUTBOUND ADAPTER       │ │
│  └────────┬─────────┘    └───────────┬─────────────┘ │
│           │  uses ports      implements ports        │
│           ▼                          ▼               │
│  ┌──────────────────────────────────────────────────┐│
│  │                 @i3x/core                        ││
│  │   Domain Models — Services — Port Interfaces     ││
│  │                ZERO DEPENDENCIES                 ││
│  └──────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────┘

The OPC UA → i3X Mapping

The component automatically translates your OPC UA address space into the i3X data model:

Stable Element IDs

Element IDs are deterministic SHA1 hashes of namespace-URI-qualified browse paths — not volatile OPC UA NodeIds. This means IDs survive server restarts, even when namespace indices shift.

Key Features

Decomposable Asset Model

The component's most powerful feature: query any OPC UA object and receive its entire internal state in a single REST call.

POST /v1/objects/value
{ "elementIds": ["nsu=http://example.org/:CNCMachine"], "maxDepth": 0 }

→ {
    "isComposition": true,
    "components": {
      "SpindleSpeed":  { "value": 12000, "quality": "Good", "timestamp": "..." },
      "FeedRate":      { "value": 500,   "quality": "Good", "timestamp": "..." },
      "ToolId":        { "value": 7,     "quality": "Good", "timestamp": "..." }
    }
  }

Set maxDepth to control recursion: 1 = this element only, 0 = infinite depth. The isComposition flag signals whether an element has internal structure.

Smart Monitoring Defaults

The component detects each node's DataType and auto-selects the optimal OPC UA monitoring strategy:

Full i3X API Surface

Real-Time Streaming (SSE)

Subscribe to value changes via Server-Sent Events — composite updates with all child properties in a single event stream.

@sterfive/opcua-optimized-client Integration

For high-performance deployments, the component auto-detects and uses the optional @sterfive/opcua-optimized-client module for up to 200% throughput improvement:

• Intelligent transaction batching
• Automatic server-limit handling
• Advanced auto-healing connection logic

No code changes required — just install the module and it's detected automatically.

Quick Start

Environment Variables

Run with Docker

docker build -t i3x2ua-node .
docker run -p 8000:8000 \
  -e I3X_OPCUA_ENDPOINT=opc.tcp://your-server:4840 \
  i3x2ua-node

Run in Development

npm install
npm run dev

Extensions & Roadmap

Beyond the i3X Beta specification, we are developing extensions that address known gaps between i3X and OPC UA's full capabilities. These are extensions we would be happy to propose to the i3X standard once they are battle-tested in production.

Licensing

@sterfive/i3x2ua-node is dual-licensed to fit both open-source and commercial use cases:

The AGPL-3.0 restrictions can be lifted by acquiring a commercial license. Contact contact@sterfive.com for pricing and terms.

Related Components

• @sterfive/opcua-optimized-client — Drop-in performance module for up to 200% throughput improvement
• node-opcua — The leading open-source OPC UA SDK for Node.js
• OPC UA Modeler — Visual editor for designing OPC UA information models

Learn More

• i3X and OPC UA — a practical introduction — What i3X is and how it relates to OPC UA
• i3X Meets OPC UA: When REST Meets Real-Time (Part 1/3) — Shared DNA and architecture
• One API Call to Rule Them All (Part 2/3) — The decomposable asset model in depth
• The Missing Safety Layer (Part 3/3) — Gaps, solutions, and roadmap

Get Started

Ready to bring i3X to your OPC UA infrastructure? Whether you need open-source flexibility or enterprise-grade support, we have you covered.

Contact Sterfive for Licensing & Support or visit sterfive.com for more information.