yaopcua

Implemented by AI under the supervision of Tallak Tveide.

Yet another OPC UA: an independent OPC UA stack in pure Elixir, for talking to PLCs, SCADA systems and HMIs without running C inside the BEAM.

It implements a subset of what open62541 does, written from the OPC UA specification (free to read at reference.opcfoundation.org) and the OPC Foundation's machine-readable definitions, not from another stack's code. It speaks the binary protocol over TCP only; the XML and JSON encodings are out.

Status: a client and a server that read, write, browse, call methods, subscribe to value changes and events, and handle alarms, over signed and encrypted channels; and PubSub over UDP for PLC to PLC. What's left is under What's missing.

Client

{:ok, client} = OPCUA.Client.start_link(url: "opc.tcp://10.0.0.5:4840")

{:ok, 1500} = OPCUA.Client.read(client, "ns=2;s=Pump1.Speed")
{:ok, [1.0, 2.0, 3.0]} = OPCUA.Client.read(client, "ns=2;s=Tank.Setpoints")
:ok = OPCUA.Client.write(client, "ns=2;s=Pump1.Speed", 1600)
{:ok, refs} = OPCUA.Client.browse(client, "ns=2;s=Plant")
{:ok, [42]} = OPCUA.Client.call(client, "ns=2;s=Plant", "ns=2;s=Multiply", [6, 7])

{:error, :bad_node_id_unknown} = OPCUA.Client.read(client, "ns=2;s=Nope")

Subscriptions send messages to the subscriber, the caller by default:

{:ok, sub} = OPCUA.Client.subscribe(client, ["ns=2;s=Pump1.Speed", "ns=2;s=Tank.Level"], interval: 100)

# first the current values, then each change
receive do
  {OPCUA.Client, ^sub, {:value, "ns=2;s=Pump1.Speed", %OPCUA.DataValue{value: %{value: speed}}}} -> speed
end

{:ok, alarms} = OPCUA.Client.subscribe_events(client, fields: ["Message", "Severity", "ActiveState/Id"])

receive do
  {OPCUA.Client, ^alarms, {:event, %{"Message" => message, "Severity" => severity}}} -> {message, severity}
end

Log in with user: {"operator", "secret"} or user: {:certificate, der, key}; anonymous is the default.

The client keeps the session alive and renews the secure channel before it expires. When the connection drops it stops with {:shutdown, reason}, so run it under a supervisor to reconnect.

Server

{:ok, server} = OPCUA.Server.start_link(port: 4840)
2 = OPCUA.Server.namespace(server, "urn:plant")

:ok = OPCUA.Server.add_object(server, "ns=2;s=Pump1", "Pump1")
:ok = OPCUA.Server.add_variable(server, "ns=2;s=Pump1.Speed", "Speed",
        parent: "ns=2;s=Pump1", type: :int16, value: 1500, writable: true)
:ok = OPCUA.Server.add_variable(server, "ns=2;s=Pump1.Temp", "Temp",
        parent: "ns=2;s=Pump1", type: :double, read: fn -> read_sensor() end)
:ok = OPCUA.Server.add_method(server, "ns=2;s=Pump1.Start", "Start",
        parent: "ns=2;s=Pump1", inputs: [{"speed", :int16}], outputs: [],
        call: fn [speed] -> start_pump(speed) && {:ok, []} end)

# from the application, whenever the value changes
:ok = OPCUA.Server.set(server, "ns=2;s=Pump1.Speed", 1510)

The server starts with all 5,500 standard nodes of namespace 0, and answers GetEndpoints, FindServers, sessions (anonymous and username logins), Read, Write, Browse and BrowseNext, TranslateBrowsePathsToNodeIds, Call, RegisterNodes, and the subscription services: value changes with deadbands and queues, keep-alives, lifetimes and Republish. Each client connection runs in its own process.

Alarms

An alarm is a condition (Part 9) on the node it's about. Clients see it through events, and acknowledge it through the server, which asks the application first:

:ok = OPCUA.Server.add_condition(server, "ns=2;s=Pump1.Overload", "Overload",
        source: "ns=2;s=Pump1", severity: 700, message: "Pump 1 overload",
        acknowledge: fn comment -> MyPlant.acknowledge(:pump_overload, comment) end)

:ok = OPCUA.Server.condition(server, "ns=2;s=Pump1.Overload", active: true)

Event filters take select clauses by browse path (including ConditionId) and where clauses with OfType, And, Or, Not, the comparisons, Between, InList and IsNull. Enable, Disable and AddComment work too; Confirm and shelving don't.

What the server doesn't do yet is listed under What's missing.

Security

Both the client and the server sign, or sign and encrypt, their channels with the current security policies, using only OTP's :crypto and :public_key:

# once, and keep the files: peers trust a certificate, not a name
{cert, key} = OPCUA.Certificate.self_signed("urn:plant:server", hostnames: ["plc1.local"])
OPCUA.Certificate.write("server.der", cert)
OPCUA.Certificate.write_key("server.pem", key)

{:ok, server} = OPCUA.Server.start_link(
  security: [:basic256sha256, :aes256_sha256_rsa_pss],
  certificate: cert, private_key: key,
  trust: [OPCUA.Certificate.read("scada.der")],
  users: %{"operator" => "secret"})

{:ok, client} = OPCUA.Client.start_link(
  url: "opc.tcp://plc1.local:4840",
  security: {:aes256_sha256_rsa_pss, :sign_and_encrypt},
  trust: [OPCUA.Certificate.read("server.der")],
  certificate: scada_cert, private_key: scada_key,
  user: {"operator", "secret"})

A secure client or server won't start without being told what to trust (:trust, a list of certificates or :any). See What's missing for the policies and certificate handling that aren't there.

PubSub

For controller-to-controller data: a publisher sends datasets over UDP every interval, to a multicast group or one host, and any number of subscribers pick out the ones they want. There are no sessions, and nothing to answer.

fields = [{"Speed", :int16}, {"Level", :double}, {"Running", :boolean}]

# on one PLC
{:ok, _} = OPCUA.PubSub.Publisher.start_link(
  url: "opc.udp://239.0.0.1:4840", publisher_id: 42, interval: 50,
  writers: [[id: 1, fields: fields, read: fn -> Pump.values() end]])

# on another
{:ok, _} = OPCUA.PubSub.Subscriber.start_link(
  url: "opc.udp://239.0.0.1:4840",
  readers: [[publisher_id: 42, writer_id: 1, fields: fields, timeout: 200]])

# which then gets, every 50 ms
{OPCUA.PubSub, {42, 1}, {:data, %{"Speed" => 1500, "Level" => 2.5, "Running" => true}}}
# and if the publisher goes quiet for 200 ms
{OPCUA.PubSub, {42, 1}, :timeout}

Messages are UADP (Part 14), checked against asyncua in both directions. See What's missing for what PubSub lacks.

Encoding

Every structure and enumeration of the spec is a module under OPCUA.Types, with the spec's field names in snake case:

alias OPCUA.Types.{ReadRequest, ReadValueId, RequestHeader}

request = %ReadRequest{
  request_header: %RequestHeader{request_handle: 1, timeout_hint: 5000},
  timestamps_to_return: :both,
  nodes_to_read: [
    %ReadValueId{node_id: OPCUA.NodeId.parse!("ns=3;s=Pump1.Speed"), attribute_id: OPCUA.AttributeId.id(:value)}
  ]
}

bytes = request |> ReadRequest.encode() |> IO.iodata_to_binary()
{:ok, ^request, ""} = OPCUA.Binary.decode(bytes, ReadRequest)

A structure field left nil, like a missing request_header, is sent as that structure's defaults, and comes back as the default struct.

The built-in types have their own structs and conventions:

OPCUA.Binary has the details, and OPCUA.NodeIds looks up the standard nodes by name: OPCUA.NodeIds.id("Server_ServerStatus") is 2256.

The spec version

The types are generated at compile time from the OPC Foundation's own files, copied unmodified into schema/ from one release of their UA-Nodeset repository:

So each yaopcua version builds against exactly one OPC UA release, and OPCUA.Schema.version/0 says which. To move to another release, give its tag:

mix opcua.schema UA-1.05.07-2026-07-30
mix test

The diff then shows the Foundation's own changes. The .bsd and the NodeSet are XML, read with OTP's xmerl while compiling; nothing reads XML at runtime.

What's missing

yaopcua is a subset of OPC UA. Beyond the XML and JSON encodings, which are out on purpose, this is what it doesn't do, by area.

Encoding

• Custom structures from a server's own namespaces stay undecoded OPCUA.ExtensionObjects; decoding them from their DataTypeDefinition is on the roadmap. Structures with optional fields or unions (spec 1.04+) aren't supported either.
• DateTime keeps microseconds, dropping the last 100 ns digit.
• A Variant with a built-in type id above 25 is a decoding error.
• XML bodies of ExtensionObjects are kept as text, never parsed.
• Option sets are integers; flags/1 on their module names the bits.

Connections

• UA-TCP over IPv4 only: no IPv6, HTTPS, WebSockets or reverse connect.
• Messages are capped at 16 MB and 4096 chunks.

Security

• The ECC policies, and the deprecated Basic128Rsa15 and Basic256.
• Certificate chains in the handshake: each side sends and expects a single certificate.
• Revocation lists, a rejected-certificate folder, and certificate management from a Global Discovery Server.
• The client trusts the server's certificate by the trust list alone; it doesn't compare the certificate's host names or URI with the endpoint.
• RSA-OAEP goes through functions OTP 27 deprecates (see OPCUA.SecurityPolicy).

Client

• No reconnecting: when the connection drops the client stops, and a supervisor must start a new one, with new sessions and subscriptions.
• Notifications lost on the way aren't asked for again (Republish), and subscriptions can't move to another session (TransferSubscriptions).
• History, Query, node management (AddNodes and so on), SetTriggering and discovery beyond GetEndpoints; the other services are there through request/3, without helpers.
• call/4 sends plain integers as Int32 and floats as Double; other types need an OPCUA.Variant.

Server

• Sessions end with their connection, so a client can't reactivate one, or its subscriptions, on a new connection.
• No history, Query, node management from clients, SetTriggering or TransferSubscriptions: they're answered with BadServiceUnsupported.
• No views, no DataTypeDefinition or RolePermissions attributes, and only the Value attribute can be written, without index ranges.
• Variables are of the 25 built-in types, scalar or one-dimensional arrays; no custom data types or enumerations.
• Most of namespace 0 has no values: ServerCapabilities, diagnostics and the like read as empty. Its methods, such as GetMonitoredItems, answer BadNotImplemented.
• No limits on connections, sessions, subscriptions or monitored items per client, and fixed ones elsewhere (10,000 operations per request, 1,000 references per browse, 16 continuation points per session).
• Subscriptions ignore max_notifications_per_publish and priority, and don't set the queue overflow bit. Items are sampled on a timer that ticks at the subscription's fastest sampling interval, so a slower item may be up to one tick late. Percent deadbands need an EURange, which isn't there.
• A renewed secure channel token is used for sending at once, rather than after the client first uses it.
• Events: the where-clause operators Like, Cast, InView, RelatedTo and the bitwise ones; AttributeOperand; index ranges in select clauses; overflow events for full queues. Events reach the Server object, their source and what's above the source by HasEventSource and HasNotifier.
• Alarms: no Confirm, shelving, suppression, silencing, latching or branches; no fields of specific alarm types (such as limits); and no Acknowledge method node on each condition, so clients call the one on the type.
• The address space isn't saved; the application builds it on each start.
• The server's certificate, if not given, is made anew on each start.
• No registration with discovery servers, and no mDNS.

PubSub

• Message security and the Security Key Service.
• Network messages chunked over several datagrams, discovery messages, and dataset metadata; promoted fields are skipped.
• Transports other than UDP: Ethernet (TSN), MQTT, AMQP; and the JSON message mapping.
• Configuration as nodes in the server, or from a configuration file.
• Event datasets: decoded, but not published or passed on.

Quality

• Tested against asyncua only, not against open62541, the OPC Foundation's .NET stack, real PLCs, or the Compliance Test Tool.
• Fuzzed in runs of hours, not continuously the way OSS-Fuzz fuzzes open62541, and without coverage guidance.
• Performance hasn't been measured.

Tests

yaopcua is tested against asyncua, a Python OPC UA stack written independently of this one, in two ways:

• test/vectors/asyncua.txt holds about 1,200 structures encoded by asyncua. yaopcua must decode each one and encode it back to the same bytes. These run with every mix test; test/vectors/generate_asyncua.py regenerates them.

• The interop tests run the client against an asyncua server, and asyncua's client against the server, as separate processes from test/support/, with and without every security policy and mode. They need a Python with asyncua, and are skipped without one:

  python3 -m venv ~/.venvs/asyncua && ~/.venvs/asyncua/bin/pip install asyncua
  ASYNCUA_PYTHON=~/.venvs/asyncua/bin/python mix test
  

Python only ever runs in tests, never inside yaopcua.

test/opcua/fuzz_test.exs fuzzes with StreamData, in the spirit of open62541's fuzzers. Random and mutated bytes go into:

• every decoder;
• the transport framing;
• the secure channel, with each policy and mode;
• UADP, and a running subscriber;
• a running server, on new connections and on open sessions.

Random requests go to the server too, for every service except Publish and those that manage the channel and session, and random arguments to its methods and alarm methods. Nothing may crash. The server must answer or refuse, and whatever decodes must encode and decode back to itself. Each property runs 100 cases with mix test. For more:

FUZZ_RUNS=10000 mix test test/opcua/fuzz_test.exs   # cases per property
FUZZ_SECONDS=600 mix test test/opcua/fuzz_test.exs  # or seconds per property

StreamData generates values from the types, where libFuzzer follows code coverage. It knows every structure's shape, but it won't work its way into a rare branch.

Roadmap

Out of scope on purpose: the XML and JSON encodings. Everything else not done is under What's missing.

License

Apache License 2.0; see LICENSE. The OPC Foundation's definition files in schema/ keep their own license, the OPC Foundation MIT License 1.00; see NOTICE.