OA RxJS API

WebSocket API client for WinCC Open Architecture backend communication.

Overview

This library provides a reactive (RxJS) interface for web applications to communicate with WinCC OA backends via WebSocket. It handles:

• Real-time data subscriptions (dpConnect, dpQueryConnect)
• Read/query datapoint values and metadata (dpGet, dpQuery, dpNames)
• Write datapoint values (dpSet)
• Authentication and session management
• Shared Worker support for multi-tab scenarios

Installation

npm install @etm-professional-control/oa-rx-js-api

Package Exports

| Export | Description | | ------------------------------------------------------ | ------------------------------------- | | @etm-professional-control/oa-rx-js-api | Main API client | | @etm-professional-control/oa-rx-js-api/worker | Shared Worker implementation | | @etm-professional-control/oa-rx-js-api/serviceworker | Service Worker for offline support | | @etm-professional-control/oa-rx-js-api/loader | Dynamic loader for API initialization |

Basic Usage

Initialization

The API requires a SharedWorker factory function:

import { OaRxJsApi, SharedWorker } from '@etm-professional-control/oa-rx-js-api';

// Create SharedWorker factory
const sharedWorkerFactory = () =>
  new SharedWorker(new URL('@etm-professional-control/oa-rx-js-api/worker', import.meta.url), {
    type: 'module',
    name: 'WinCCOA oa-rx-js-api worker'
  });

// Initialize the API
const api = new OaRxJsApi(sharedWorkerFactory);

Connection

Connect to the WinCC OA backend with authentication:

api
  .connect(
    'wss://localhost:8449/websocket', // WebSocket URL
    token, // Authentication token from /WebUI_Token
    {
      serviceType: 'b1733f6d-0075-47ab-9bcc-71b464ed2fda', // Role UUID
      heartbeatSeconds: 10
    },
    'https://localhost:8843', // HTTP API URL
    'en_US.utf8' // Locale
  )
  .subscribe({
    next: (connectData) => console.log('Connected:', connectData),
    error: (err) => console.error('Connection failed:', err)
  });

Subscribe to Datapoint Changes

api.dpConnect(['System1:ExampleDp.value'], true).subscribe((data) => {
  console.log('Value:', data.value[0]);
});

Set Datapoint Values

api.dpSet(['System1:ExampleDp.value'], 42).subscribe({
  next: () => console.log('Value set successfully'),
  error: (err) => console.error('Error:', err)
});

Get Datapoint Metadata

// Get description
api.dpGetDescription(['System1:ExampleDp'], 2).subscribe((description) => console.log('Description:', description));

// Get unit
api.dpGetUnit(['System1:ExampleDp']).subscribe((unit) => console.log('Unit:', unit));

Custom Commands

api
  .customCommand<{ min: number; max: number }>('etm.core.ext.dpGetPvRange', {
    dpName: ['System1:ExampleDp']
  })
  .subscribe((result) => {
    console.log('Range:', result.min, '-', result.max);
  });

Documentation

For comprehensive usage information, see the WinCC OA Documentation.

License

MIT