Skip to content

Positioning.md

Latest commit

 

History

History
326 lines (260 loc) · 12.8 KB

Positioning.md

File metadata and controls

326 lines (260 loc) · 12.8 KB
Raw

OPC UA Relative Spatial Location and Global Positioning

The Positioning libraries implement two OPC UA companion specifications:

The libraries use the released RSL 1.00.1 and GPOS 1.0.0 NodeSets. GPOS depends on RSL.

Contents

Packages

Package Purpose
OPCFoundation.NetStandard.Opc.Ua.Positioning Source-generated RSL and GPOS models plus frame, WGS84, ENU, and ground-control-point transformations.
OPCFoundation.NetStandard.Opc.Ua.Positioning.Server Standalone/composed node-manager hosting, address-space builders, providers, lifecycle, validation, and logging.
OPCFoundation.NetStandard.Opc.Ua.Positioning.Client Continuation-safe discovery, typed reads and streams, frame-chain resolution, and Zone transforms.

Generated model types remain in the specification namespaces:

  • Opc.Ua.Rsl
  • Opc.Ua.Gpos

The base package exposes generated NodeIds, NodeStates, encodeables, model loaders, and generated ObjectType clients. The hand-written APIs compose those generated basics instead of replacing or inheriting from them.

Minimal standalone server

AddPositioningServer owns an RSL/GPOS node manager. Configure the address space after the generated models are loaded:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Opc.Ua.Positioning.Server;
using Opc.Ua.Positioning.Server.Hosting;

HostApplicationBuilder host = Host.CreateApplicationBuilder(args);

IPositioningServerBuilder positioning = host.Services
    .AddOpcUa()
    .AddServer(options =>
    {
        options.ApplicationName = "PositioningServer";
        options.EndpointUrls.Add(
            "opc.tcp://localhost:4840/PositioningServer");
    })
    .AddPositioningServer();

positioning
    .AddGeoLocationProvider<MyGpsProvider>()
    .AddRelativeSpatialLocationProvider<MyRelativeLocationProvider>()
    .ConfigurePositioningFor<PositioningNodeManager>(async context =>
    {
        PositioningAddressSpaceBuilder model = context.AddressSpace;

        // Create a SpatialObjectsList, SpatialObject AddIns and concrete
        // Cartesian frames, then register each completed subtree.
        // Create Zones and attach GlobalPosition or GlobalLocation Variables
        // in the same callback.

        await ValueTask.CompletedTask;
    });

await host.Build().RunAsync();

For a server that already owns the companion address space, keep that manager as the single namespace owner:

IPositioningServerBuilder positioning = serverBuilder
    .AddNodeManager<MyNodeManagerFactory>()
    .AddPositioningFor<MyNodeManager>();

positioning.ConfigurePositioningFor<MyNodeManager>(
    context => ((MyNodeManager)context.Manager)
        .ConfigurePositioningAsync(context));

The owning composite manager must load the RSL model before GPOS and advertise both namespace URIs.

Server authoring

PositioningAddressSpaceBuilder creates instances through the generated factories and supports:

  • SpatialObjectsListType AddIns below the standardized RelativeSpatialLocations entry point.
  • SpatialObjectType AddIns attached to existing objects through HasAddIn.
  • Cartesian world, position, attach-point, internal, and alternative frames.
  • GPOS ZoneType instances defined by ground control points or a position/radius.
  • GlobalPositionType and GlobalLocationType Variables attached to tracked objects.
  • Coherent aggregate/component updates, optional-field status, NodeVersion, and model-change notifications.

Provider bindings publish an initial value and then consume a cancellation-aware async stream:

PositioningProviderSubscription subscription =
    await model.BindGlobalLocationAsync(
        globalLocation,
        provider,
        sourceId,
        cancellationToken: ct);

Dispose the subscription asynchronously during server shutdown. Provider failures retain the last value, set its status to BadCommunicationError, log the failure through ITelemetryContext, and fault Completion.

IGeoLocationProvider is intentionally technology-neutral, and lives in Opc.Ua.Server (namespace Opc.Ua) rather than in a companion-model assembly. Global Positioning System (GPS) and World Geodetic System 1984 (WGS84) coordinates are built-in use cases. Real-time location systems (RTLS), ultra-wideband (UWB), radio-frequency identification (RFID), local floor-plan coordinates, and other tracking systems can use the same contract. An RSL provider is also useful when a robot controller, metrology system, or kinematic service is authoritative for a relative frame rather than a global coordinate.

Because the contract is shared, one provider implementation serves every model that publishes location. The same instance can back GPOS GlobalLocation Variables here and OPC 10030 (ISA-95) GeoSpatialLocationType Variables — see ISA-95. A sample can include:

  • GeoPosition with latitude, longitude, optional height, accuracy, floor, and EPSG code
  • GeoOrientation
  • Text labels
public sealed class MyGpsProvider : IGeoLocationProvider
{
    public bool SupportsPush => true;

    public ValueTask<GeoLocationSample> ReadAsync(
        string sourceId,
        CancellationToken ct = default)
    {
        return new ValueTask<GeoLocationSample>(
            GeoLocationSample.Good(
                new GeoPosition(47.3769, 8.5417, 408.0, EpsgCode: 4326)));
    }

    public async IAsyncEnumerable<GeoLocationSample> WatchAsync(
        string sourceId,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        // Yield a sample whenever the receiver reports a new fix.
    }
}

Set SupportsPush to false when the source can only be polled; the binding layer then never calls WatchAsync and reads through ReadAsync at the Variable's sampling interval instead.

A GPOS Variable requires coordinates. If a sample has Position set to null, the server rejects it with BadNoDataAvailable. If the position's EpsgCode differs from the Variable's configured CoordinateReferenceSystem, the binding fails rather than mis-georeference the value silently. Set EpsgCode to null to accept the Variable's configured coordinate reference system. InMemoryGeoLocationProvider ships as a reference implementation for tests and for servers whose positions are pushed in from elsewhere. Watching an unknown source does not create a sample: reads return BadNotFound until Update supplies one. Fault makes reads surface the supplied exception even for an unknown source; a subsequent Update clears the fault and publishes its sample.

Client

Register client factories over the managed-session registration:

services.AddOpcUa()
    .AddClient(options => { /* endpoint and application options */ })
    .AddPositioningClient();

Direct constructors are also available:

var rsl = new RelativeSpatialLocationClient(session, telemetry);
var gpos = new GlobalPositioningClient(session, telemetry);

await foreach (PositioningObjectEntry list in
    rsl.EnumerateSpatialObjectListsAsync(ct))
{
    await foreach (PositioningObjectEntry spatialObject in
        rsl.EnumerateSpatialObjectsAsync(list.NodeId, ct))
    {
        RelativeSpatialFrameValue frame =
            await rsl.ReadPositionFrameAsync(spatialObject.NodeId, ct);
    }
}

await foreach (PositioningObjectEntry zone in gpos.EnumerateZonesAsync(ct))
{
    GroundControlPointFitResult transform =
        await gpos.ReadZoneTransformAsync(zone.NodeId, cancellationToken: ct);
}

ResolveFrameToWorldAsync follows the RSL Base chain, composes each ThreeDFrame, and rejects missing nodes, bad status, cycles, and excessive depth. ObserveFrameAsync, ObservePositionFrameAsync, ObserveNodeVersionAsync, ObserveGlobalPositionAsync, and ObserveGlobalLocationAsync use IStreamingSubscription.

GPOS structured types are registered with both the session and message-context encodeable factories before reads, so binary ExtensionObject values decode to the generated types.

Use the read-options overloads to enable strict quality checks and resource limits. Constructors without read options use tolerant reads:

var limits = new PositioningClientReadOptions
{
    MaximumBrowseReferences = 1024,
    MaximumBrowsePages = 128,
    MaximumFrameChainLength = 64,
    MaximumReadArrayItems = 128
};
var rsl = new RelativeSpatialLocationClient(session, telemetry, limits);
var gpos = new GlobalPositioningClient(session, telemetry, limits);

The options also work with AddPositioningClient(limits). Strict reads reject bad/uncertain quality, malformed values, invalid geometry and excessive arrays. They read a frame and its Base together and bound continuation traversal. Continuation cleanup accepts an empty successful release response while still checking service quality; cleanup failure preserves the original read failure or cancellation. Unencoded optional geometry fields are not treated as supplied values. Array bounds are checked after decoding; the session's transport quotas bound incoming messages. The supplied session remains caller-owned.

Transform conventions

RSL uses a right-handed coordinate system:

  • A: roll about X
  • B: pitch about Y
  • C: yaw about Z
  • column-vector matrix: Rz(C) * Ry(B) * Rx(A)

RslFrameTransform supports conversion, composition, inversion, point transformation, and deterministic gimbal-lock handling.

The built-in coordinate-reference-system transformer supports WGS84 / EPSG:4326, ECEF, and local East-North-Up coordinates. Inject ICoordinateReferenceSystemTransformer for another CRS.

GroundControlPointFitter supports rigid, similarity, and affine fits. When elevation or rank is insufficient, it selects a horizontal 2D fit. It forces a proper rotation for rigid and similarity modes, and rejects affine reflections unless you enable them. The fitter reports residual, determinant, rank, dimension, and invertibility diagnostics.

UaLens Positioning tool

UaLens exposes these models through a dedicated read-only tool. It discovers spatial objects, global variables on those objects or their owners, and the GlobalLocations entry point. It does not require a renderer or external location service.

Raw inspection preserves declared units and value evidence. World resolution requires matching declared length units and the selected degrees/radians interpretation across the Base chain; the tool does not convert mixed units. It bounds chains to 64 frames and checks exposed spatial-list NodeVersions. These checks do not provide atomic telemetry snapshots.

Zone previews use a copied, bounded ground-control-point calibration and single-use preparation. A 2D fit requires local Z = 0; only a 3D fit produces elevation. Connection changes, changed calibration, cancellation or the fixed five-minute preparation deadline prevent publication. The preview never writes a device position.

Robot and OpenUSD sample

MinimalRobotServer composes RSL and GPOS into its Robotics node manager. Both robots publish GlobalLocation values and derived local RSL frames. Each robot independently selects Fixed, FigureEight, Circle, or Shuttle motion. RSL position/orientation drive OpenUSD double3 transform operators, while GPOS longitude, latitude, and elevation drive live custom attributes.

The generic OpenUSD connector has no Positioning dependency; it handles core ThreeDCartesianCoordinates, ThreeDOrientation, and ThreeDFrame values.

The server supports an explicit private PKI and finite managed run:

$pkiRoot = Join-Path $env:TEMP 'robot-positioning-pki'
dotnet run --project samples\Robotics\MinimalRobotServer -c Release -f net10.0 -- `
  --host 127.0.0.1 --port 62830 --pki-root $pkiRoot --autoaccept false --run-seconds 60

--pki-root must be absolute; --run-seconds accepts 1-3600 seconds. Without the runtime option, the server runs until stopped interactively. Standalone defaults bind all interfaces and automatically accept certificates; use explicit secure options for controlled runs.

UaLens supplies loopback binding, private PKI, disabled automatic trust and a finite lifetime. Its Positioning workflow does not authorize robot operation commands.