Datapoint Connectivity

The WebUI Runtime connects to WinCC OA datapoints through the OaRxJsApi library, enabling live data display and control actions.

Reading datapoints (dpConnect)

dpConnect creates a reactive subscription to a datapoint value. The subscription receives the current value immediately (when the second parameter is true) and all subsequent changes. The WebUI Runtime wrapper mirrors the CTRL function dpConnect().

import { OaRxJsApi } from '@etm-professional-control/oa-rx-js-api';
import { container } from 'tsyringe';
import { map } from 'rxjs';

const oaRxJsApi = container.resolve<OaRxJsApi>(OaRxJsApi);

const subscription = oaRxJsApi
  .dpConnect('System1:MyDatapoint.Value', true)
  .pipe(map((data) => (data.value[0] as number) ?? 0))
  .subscribe((value) => {
    console.log('Current value:', value);
  });
  • Datapoint names in the browser always require the System1: prefix.
  • The second parameter (true) delivers the current value immediately on connect.
  • data.value[0] contains the datapoint value.
  • Subscriptions must be cleaned up in disconnectedCallback() to prevent memory leaks.

Writing datapoints (dpSet)

dpSet sends values to WinCC OA. The WebUI Runtime wrapper mirrors the CTRL function dpSet().

oaRxJsApi.dpSet(['System1:MyDatapoint.Value'], [42.5]).subscribe({
  next: (success) => { console.log('Value set:', success); },
  error: (err) => { console.error('Error:', err); }
});
  • dpSet accepts arrays for multiple datapoints: dpSet([name1, name2], [value1, value2]).
  • Returns an Observable that must be subscribed to execute the operation.
  • Use SuccessNotificationEvent and ErrorNotificationEvent for user feedback.

Using widgets with wui-context-generator

The wui-context-generator component binds Dashboard widgets to datapoints declaratively.

<wui-context-generator
  .component=${'wui-widget-gauge'}
  .config=${{
    value: {
      context: 'data-point',
      config: {
        dpName: 'System1:MyDatapoint.Value',
        definedConfigs: ['value']
      }
    }
  }}
  .properties=${{ min: 0, max: 100, label: 'Load', unit: 'MW' }}
></wui-context-generator>
Note:
For gauges and progress bars, direct property binding via @state() and OaRxJsApi is often more reliable than the datapoint context. The context generator is better suited for trend charts and complex widgets.

Additional OaRxJsApi methods

Beyond dpConnect and dpSet, the OaRxJsApi provides a comprehensive set of methods that mirror CTRL functions for datapoint access, querying, and system interaction. The following table lists the available method categories:

Category Methods
Datapoint subscriptions dpConnect, dpConnectList, dpConnectListAdd, dpConnectListGet, dpConnectListRemove
Datapoint read/write dpGet, dpGetAsynch, dpSet, getValue, setValue
Queries dpQuery, dpQueryConnect
Datapoint metadata dpNames, dpElementType, dpGetAlias, dpGetDescription, dpGetFormat, dpGetUnit
Historical data dpGetPeriod, alertGetPeriod
System and connection connect, disconnect, getConnectionState, connectToHeartbeat, systemInfoConnect, sysConnectDpDpt, prepareSysConnects
Custom commands and MSA customCommand, customCommandWithId, customCommandSharedId
Configuration setBaseParams, setLocale, cnsGetCompletions

All methods return RxJS Observables. For complete API documentation, see the OaRxJsApi reference.