# Part 16 State Machines This guide describes the generic, extensible OPC UA Part 16 state- machine support layered on top of the source-generated ObjectType proxies and the existing `FiniteStateMachineState` server base. For the formal model, see [OPC UA Part 16 — State Machines](https://reference.opcfoundation.org/specs/OPC-10000-16/full). ## Contents - [Two-mode unified builder](#two-mode-unified-builder) - [Quick reference](#quick-reference) - [Client side](#client-side) - [Read the current state](#read-the-current-state) - [Stream transitions](#stream-transitions) - [Wait for a target state](#wait-for-a-target-state) - [Enumerate states + transitions](#enumerate-states--transitions) - [Alarm shelving alignment](#alarm-shelving-alignment) - [Device Integration (DI) software-update alignment](#device-integration-di-software-update-alignment) - [Vendor extensibility](#vendor-extensibility) - [Server side — definition mode](#server-side--definition-mode) - [Server side — lifecycle mode](#server-side--lifecycle-mode) - [Stack-shipped state machine](#stack-shipped-state-machine) - [Inside a fluent node-manager build pipeline](#inside-a-fluent-node-manager-build-pipeline) - [Lifecycle ordering](#lifecycle-ordering) - [How the source-generator integrates](#how-the-source-generator-integrates) - [Guard clauses (fluent sugar)](#guard-clauses-fluent-sugar) - [Sub-state machines (hierarchical state)](#sub-state-machines-hierarchical-state) - [Server side — `WithSubStateMachine`](#server-side--withsubstatemachine) - [Server side — materialized state and transition nodes](#server-side--materialized-state-and-transition-nodes) - [Executable causes](#executable-causes) - [Client side — sub-SM observation](#client-side--sub-sm-observation) - [Client side — typed sub-SM accessors (generated)](#client-side--typed-sub-sm-accessors-generated) - [Fluent builder behavior — `HasSubStateMachine` is on the state node](#fluent-builder-behavior--hassubstatemachine-is-on-the-state-node) - [Extensibility recipes](#extensibility-recipes) - [Tests](#tests) - [See also](#see-also) ## Two-mode unified builder The server side ships **one** fluent builder — `StateMachineBuilder` — with two complementary modes that can be mixed in a single chain: | Mode | Entry point | Use when … | |------------------|--------------------------------------------------------|----------------------------------------------------------------------------| | **Definition** | `StateMachineBuilder.Create(parent, ctx, nodeId, name)` | You need a state machine that isn't already declared as a generator-emitted `*StateMachineState` subclass. Declare states, transitions, and cause mappings declaratively. | | **Lifecycle** | `StateMachineBuilder.For(stateMachine, ctx)` or `INodeBuilder.AsStateMachine()` | You already have a `FiniteStateMachineState` subclass (stack-shipped, generator-emitted, or vendor) and want to attach behavior (enter/exit/transition hooks, method-to-cause bindings, auto-transitions). | Both modes share the same lifecycle surface (`WithInitialState`, `OnEnterState`, `OnExitState`, `OnTransition`, `OnBeforeTransition`, `WithCause`, `WithTimedTransition`, `ConfigureStateMachine`). Async overloads — `OnEnterStateAsync`, `OnExitStateAsync`, `OnTransitionAsync` — accept `Func` (or the four-arg form for transition observers) and are invoked **fire-and-forget on the thread pool** from the synchronous transition path. The handler therefore runs on a fully-async path (no `GetAwaiter().GetResult()` / `Wait()` / `.Result` anywhere) without blocking the transition or the calling client. Exceptions thrown from an async handler are captured and logged via `Debug.WriteLine`. Pre-transition guards (`OnBeforeTransition`, `When*`) intentionally remain sync-only because they must veto the transition synchronously before the state-machine state mutation completes. The definition methods (`AddState`, `AddTransition`, `OnCause`, `UseElementNamespace`) are only available in definition mode. ## Quick reference | Concern | Client entry point | Server entry point | |----------------------------------------|------------------------------------------------------------------------|------------------------------------------------------| | Read the current state | `StateMachineTypeClient.GetCurrentStateAsync` | `FiniteStateMachineState.CurrentState` | | Read current state + last transition (finite) | `FiniteStateMachineTypeClient.GetCurrentFiniteStateAsync` | `FiniteStateMachineState.LastState/LastTransition` | | Observe transitions (stream) | `(Finite)StateMachineTypeClient.ObserveFiniteTransitionsAsync` | n/a | | Wait for a target state | `(Finite)StateMachineTypeClient.WaitForStateAsync` | n/a | | Enumerate states / transitions | `FiniteStateMachineTypeClient.GetAvailableStatesAsync` / `GetAvailableTransitionsAsync` | n/a | | Build a state machine declaratively | n/a | `StateMachineBuilder.Create` (definition mode) | | Attach behavior to an existing FSM | n/a | `StateMachineBuilder.For` / `INodeBuilder.AsStateMachine` (lifecycle mode) | ## Client side The source-generated `*TypeClient` proxies for state-machine types (`StateMachineTypeClient`, `FiniteStateMachineTypeClient`, `ShelvedStateMachineTypeClient`, `ExclusiveLimitStateMachineTypeClient`, `ProgramStateMachineTypeClient`, and any vendor subtypes) all inherit the generic API automatically — implemented as extension methods that hang off the proxy base. ### Read the current state ```csharp var proxy = new ShelvedStateMachineTypeClient(session, conditionId, telemetry); FiniteStateSnapshot snap = await proxy.GetCurrentFiniteStateAsync(ct); Console.WriteLine($"State: {snap.CurrentState} ({snap.CurrentStateId})"); Console.WriteLine($"Last transition: {snap.LastTransition} ({snap.LastTransitionId})"); ``` ### Stream transitions Pair the proxy with the session's [streaming subscription](Subscriptions.md#streaming-subscriptions): ```csharp ManagedSession session = ...; IStreamingSubscription streaming = session.DefaultStreaming; await foreach (FiniteStateSnapshot snap in proxy .ObserveFiniteTransitionsAsync(streaming, ct: ct)) { Console.WriteLine($"{snap.Timestamp:O} -> {snap.CurrentState}"); } ``` Each yielded snapshot is refreshed by reading the four state + transition variables in one round-trip, so consumers see consistent typed data per transition. ### Wait for a target state ```csharp FiniteStateSnapshot reached = await proxy.WaitForStateAsync( streaming, targetStateId: new NodeId(Objects.ShelvedStateMachineType_TimedShelved), timeout: TimeSpan.FromSeconds(30), ct: ct); ``` The wait composes `ObserveFiniteTransitionsAsync` with timeout and cancellation; an immediate match against the current state is short-circuited. ### Enumerate states + transitions ```csharp IReadOnlyList states = await proxy.GetAvailableStatesAsync(ct); IReadOnlyList transitions = await proxy.GetAvailableTransitionsAsync(ct); ``` Reads the optional `AvailableStates` / `AvailableTransitions` NodeId-array properties and then reads each referenced node's browse name and number. An absent or invalid availability property produces an empty result. ### Alarm shelving alignment `AlarmClient` exposes the same API for the `ShelvingState` child of every Part 9 alarm condition: ```csharp AlarmClient alarms = session.GetAlarmClient(telemetry); FiniteStateSnapshot snap = await alarms.GetShelvingStateAsync(conditionId, ct); await foreach (FiniteStateSnapshot s in alarms .ObserveShelvingTransitionsAsync(conditionId, streaming, ct: ct)) { // … } ``` Both methods delegate to `ShelvedStateMachineTypeClient` internally — same proxy-delegation pattern used by the rest of `AlarmClient`. ### Device Integration (DI) software-update alignment `SoftwareUpdateClient` (in `Opc.Ua.Di.Client`) wraps the same generic API for each of the four child state machines of OPC 10000-100 §10.3 (`PrepareForUpdate`, `Installation`, `Confirmation`, `PowerCycle`): ```csharp var su = new SoftwareUpdateClient(session, suNodeId, telemetry); FiniteStateSnapshot? state = await su.GetInstallationStateAsync(ct); await foreach (FiniteStateSnapshot snap in su .ObserveInstallationTransitionsAsync(streaming, options: null, ct)) { // … } await su.InstallSoftwarePackageAsync("urn:acme", "2.0.0", ArrayOf.Empty(), default, ct); ``` See [`SoftwareUpdate.md`](SoftwareUpdate.md) for the full SU facet — including the server-side `OnInstallationStateChanged` / `OnPrepareStateChanged` / `OnConfirmStateChanged` instrumentation hooks that the DI server attaches to its built-in FSM lifecycle. ### Vendor extensibility Vendor concrete state machines declared in a NodeSet (e.g. `MyVendor:FoodPreparationStateMachineType : FiniteStateMachineType`) automatically get the generic API. The proxy generator emits a `FoodPreparationStateMachineTypeClient` that inherits from `FiniteStateMachineTypeClient`, and every extension method (`GetCurrentFiniteStateAsync`, `ObserveFiniteTransitionsAsync`, `WaitForStateAsync`, …) applies through the inheritance chain transparently. Vendor-declared methods (e.g. `BeginPreparation`) are emitted as instance methods on the vendor client by the generator. ## Server side — definition mode Use `StateMachineBuilder.Create(...)` when you need a state machine that isn't already a generator-emitted subclass. The builder owns a `FluentFiniteStateMachineState` instance, populates its state / transition / cause tables from your declarations, and freezes the definition the moment you read `StateMachine` or attach the first lifecycle hook. ```csharp using Opc.Ua.Server.StateMachines; FluentFiniteStateMachineState sm = StateMachineBuilder .Create(parent, systemContext, nodeId: new NodeId(/*your numeric id*/, namespaceIndex), browseName: new QualifiedName("PowerSwitch", namespaceIndex)) .AddState(id: 1, "Off", isInitial: true) .AddState(id: 2, "On") .AddTransition(id: 10, "OffToOn", from: 1, to: 2) .AddTransition(id: 20, "OnToOff", from: 2, to: 1) .OnCause(causeId: 100, from: 1, transition: 10) .OnCause(causeId: 200, from: 2, transition: 20) .WithInitialState(1) .StateMachine; ``` The builder validates structural integrity at the freeze step (the first lifecycle method or `StateMachine` access): every transition's `from`/`to` must reference declared states, every cause mapping must reference a declared transition, and state / transition / cause ids must be unique within their tables. ## Server side — lifecycle mode Use `StateMachineBuilder.For(...)` (or `INodeBuilder.AsStateMachine()` inside a fluent node-manager build pipeline) when you already have a state-machine instance — stack-shipped (`ShelvedStateMachineState`, `ExclusiveLimitStateMachineState`, `ProgramStateMachineState`), generator-emitted (`MyVendor.FoodPreparationStateMachineState`), or the result of an earlier `StateMachineBuilder.Create(...)` chain. ### Stack-shipped state machine ```csharp // Existing ShelvedStateMachineState that lives under an alarm condition: ShelvedStateMachineState shelving = alarm.ShelvingState; StateMachineBuilder.For(shelving, systemContext) .OnEnterState( Objects.ShelvedStateMachineType_TimedShelved, (ctx, sm) => logger.LogInformation("Alarm timed-shelved")) .OnExitState( Objects.ShelvedStateMachineType_TimedShelved, (ctx, sm) => logger.LogInformation("Alarm un-timed-shelved")) .OnTransition((ctx, sm, from, to) => logger.LogDebug("Shelving {From} -> {To}", from, to)) .WithTimedTransition( fromStateId: Objects.ShelvedStateMachineType_OneShotShelved, timeout: TimeSpan.FromMinutes(15), transitionId: Objects.ShelvedStateMachineType_OneShotShelvedToUnshelved); ``` The lifecycle builder layers on top of any pre-existing `OnBeforeTransition` / `OnAfterTransition` delegates the state machine had — the stack-shipped behavior continues to run, with your handlers wrapping it. ### Inside a fluent node-manager build pipeline ```csharp [NodeManager] public partial class MyNodeManager { partial void Configure(INodeManagerBuilder builder) { builder .Node(BrowsePaths.SoftwareUpdate.Installation) .As() .AsStateMachine() .OnEnterState(StateNumbers.Installing, (ctx, sm) => StartInstall(ctx)) .OnTransition((ctx, sm, from, to) => _logger.LogInformation("Install: {From} -> {To}", from, to)) .WithTimedTransition( fromStateId: StateNumbers.Installing, timeout: TimeSpan.FromMinutes(10), transitionId: StateNumbers.InstallingToFailed, causeId: StateNumbers.TimeoutCause); } } ``` `AsStateMachine()` pulls the `ISystemContext` from `nodeBuilder.Builder.Context`. The `INodeBuilder` typed view ensures the underlying node is a `FiniteStateMachineState` subclass at compile time — no runtime casts. The fluent pipeline retries an expired timed cause on subsequent simulation ticks if a guard rejects it. It warns only once for an unchanged rejected state, state revision, and status code; changing the status or entering a new state revision permits another warning. `BadInvalidState` remains silent but resets the previous rejection, so a later different failure is reported. Warning suppression does not delay retries or prevent recovery when the guard starts allowing the transition. ### Lifecycle ordering For every transition the dispatcher fires handlers in this order: ``` DispatchBefore: builder guards (in registration order) ↓ veto on any failure [original OnBeforeTransition, if any] ↓ framework state update (LastState ← CurrentState, CurrentState ← newState) DispatchAfter: [original OnAfterTransition, if any] ↓ OnExitState(from) (each registered handler, in order) ↓ OnTransition(from, to) (each observer, in order) ↓ OnEnterState(to) (each registered handler, in order) ``` Builder guards run **before** any pre-existing `OnBeforeTransition` — so they can veto without the original side-effectful pre-handler running. Builder observers run **after** the original `OnAfterTransition` so stack-shipped audit / change notifications complete first. If multiple handlers are registered for the same state or transition, they fire in the order they were added. Exceptions thrown by an individual handler do not interrupt the dispatch — they are caught and logged via `Debug.WriteLine`. ## How the source-generator integrates * **Client**: every state-machine `*TypeClient` proxy (generated from the standard NodeSet *and* every vendor NodeSet you feed through the generator) inherits the streaming + read + browse API automatically. No hand-written client per state-machine type. * **Server**: when a NodeSet declares a concrete subtype of `FiniteStateMachineType` (vendor or standard), the generator emits a `*StateMachineState` server class with the hardcoded `StateTable` / `TransitionTable` / `TransitionMappings` / `CauseMappings` overrides. Hook behavior onto that instance via `StateMachineBuilder.For(...)` — no need to redeclare the tables. The unified builder gives you a clean migration path: * **Have a generator-emitted FSM type?** Lifecycle mode only. Build the instance the usual way, then attach behavior with `StateMachineBuilder.For(...)`. * **Need an ad-hoc state machine with no generated subclass?** Definition mode. `StateMachineBuilder.Create(...)` constructs a `FluentFiniteStateMachineState` and lets you chain definitions and lifecycle hooks in one expression. ## Guard clauses (fluent sugar) The lifecycle builder offers a coarse `OnBeforeTransition` that fires for every transition; the `When*` family provides per-trigger sugar that compiles down to the same pipeline but scopes the predicate automatically. ```csharp StateMachineBuilder.Create(parent, ctx, nodeId, browseName) .AddState(1, "Off", isInitial: true) .AddState(2, "On") .AddTransition(10, "OffToOn", from: 1, to: 2) .AddTransition(20, "OnToOff", from: 2, to: 1) .WhenTransition(10, (ctx, sm) => HasPermission(ctx)) .WhenCause(causeId: 100, (ctx, sm) => sm.SafetyInterlockClear) .WhenEnter(toStateId: 2, (ctx, sm) => sm.PreflightOk, denyStatus: StatusCodes.BadInvalidState) .WhenExit(fromStateId: 2, (ctx, sm) => sm.ShutdownComplete); ``` | Method | Scope | Available in | |---|---|---| | `OnBeforeTransition(Func)` | Every transition (caller filters) | Both modes | | `WhenTransition(transitionId, predicate[, denyStatus])` | Transition matches `transitionId` | Both modes | | `WhenCause(causeId, predicate[, denyStatus])` | Cause matches `causeId` | Both modes | | `WhenEnter(toStateId, predicate[, denyStatus])` | Transition would enter `toStateId` | Definition mode only | | `WhenExit(fromStateId, predicate[, denyStatus])` | Machine is leaving `fromStateId` | Both modes | Returning `false` from a predicate vetoes the transition with `BadUserAccessDenied` (or the caller-supplied `denyStatus`). Multiple guards on the same trigger AND together — the first predicate returning `false` wins, and its `denyStatus` flows through to `DoTransition`'s return. All guards (`On*` + `When*`) share one pipeline in registration order — the FIRST failing guard wins. This means a `When*` guard declared before an `OnBeforeTransition` guard runs first. `WhenEnter` is definition-mode-only because the builder needs the transition table to map `toStateId` to the matching transition ids. In lifecycle mode the table is protected on the FSM; use `WhenTransition` with the explicit transition id instead. ## Sub-state machines (hierarchical state) OPC UA Part 16 §5.2.3 supports nested state machines via the `HasSubStateMachine` reference. Standard alarms use this pattern (`ExclusiveLimitAlarmType.LimitState` is itself an `ExclusiveLimitStateMachineType` distinguishing `HighHigh / High / Low / LowLow` while the parent alarm is `Active`). Vendor process-control servers compose hierarchical state machines extensively. ### Server side — `WithSubStateMachine` The unified builder attaches a sub-state-machine to a parent state. The dispatcher auto-manages the lifecycle: parent enters → child activates (and resets to its initial state unless `preserveOnReentry: true` is supplied); parent exits → child is suspended and rejects subsequent transitions until the next parent re-entry. Child synchronization completes before the parent's builder lifecycle handlers run or asynchronous handlers are scheduled. A parent `OnEnterState` handler can therefore call the child's `DoCause` or `DoTransition` without seeing an inactive child or having its transition overwritten by deferred initialization. Synchronization and these parent handlers run outside the parent's transition lock; transition-local source/destination snapshots and lifecycle ordering are preserved. ```csharp FluentFiniteStateMachineState parent = StateMachineBuilder .Create(parentNode, ctx, parentNodeId, browseName) .AddState(1, "Active", isInitial: true) .AddState(2, "Inactive") .AddTransition(12, "ActiveToInactive", from: 1, to: 2) .AddTransition(21, "InactiveToActive", from: 2, to: 1) // Attach a sub-state-machine to the Active parent state. .WithSubStateMachine( parentStateId: 1, browseName: new QualifiedName("LimitState", ns), configure: child => child .AddState(10, "HighHigh", isInitial: true) .AddState(11, "High") .AddState(12, "Low") .AddState(13, "LowLow") .AddTransition(110, "HighHighToHigh", from: 10, to: 11), preserveOnReentry: false) .StateMachine; ``` Available in **definition mode only** — in lifecycle mode the parent FSM already declares its sub-state machines as part of the type definition. Observe them through the client-side sub-SM accessors below. `WithSubStateMachine` and `WithInitialState` are order-independent: whichever is called second brings the sub-SM in line with the parent's current state. (`WithInitialState` goes through `SetState`, which is not a transition and so still runs no user lifecycle handler — but it does re-arm timed transitions and synchronize sub-state machines.) A state declared with `isInitial: true` is applied automatically when the machine is created and its state node is materialized as an `InitialStateType` (OPC 10000-16 §4.4.10), so the minimal example above is fully functional without an explicit `WithInitialState` call; call `WithInitialState` to start in a different state. A sub-state machine's declared initial state is applied only while its parent is in the attached state. While suspended, the child FSM's `CurrentState` and `LastTransition` read with `Bad_StateNotActive` (per OPC 10000-16 §4.4.6), and its `DoTransition` / `DoCause` return `BadStateNotActive`. The flag is exposed publicly as `FluentFiniteStateMachineState.IsSuspended` for diagnostics. The resulting address space follows Part 16 §4.4.16 and the standard NodeSets: ``` LimitAlarm --HasComponent--> Active (StateType) Active --HasSubStateMachine--> LimitState LimitAlarm --HasComponent--> LimitState ``` `HasSubStateMachine` is a **non-hierarchical** reference, so it cannot double as the parent/child reference — the sub-SM is a `HasComponent` child of the state machine and the spec reference hangs off the parent *state* node. ### Server side — materialized state and transition nodes To give `HasSubStateMachine` a state node to hang off — and to make `CurrentState/Id` and `LastTransition/Id` resolve to something a client can actually browse — `FluentFiniteStateMachineState` materializes a node per declared state and transition when the machine is created. All of them are `HasComponent` children of the machine. **States** — one `StateType` node each, carrying a `StateNumber` property equal to the numeric state id. `CurrentState/Id` points at the node for the current state and tracks it across transitions, and the optional `AvailableStates` property lists them, so `GetAvailableStatesAsync` works against a fluent-built server. **Transitions** — one `TransitionType` node each, carrying a `TransitionNumber` property and the Part 16 §4.4.11 references: * `FromState` / `ToState` to the two state nodes; * `HasEffect` to `TransitionEventType`, unless the transition was declared with `hasEffect: false` — forward-only, matching how companion NodeSets declare it (the target is a standard node owned by another node manager, so no inverse edge is registered there); * `HasCause` to the method node, added by `WithCause(methodNodeId)` for every transition the cause can trigger. `AvailableTransitions` lists them, and the optional `LastTransition` variable is materialized too — without it the base class has nowhere to record a completed transition and `ObserveFiniteTransitionsAsync` has nothing to subscribe to. NodeIds are **per instance**, derived from the machine's own NodeId, so several machines built from one definition coexist in a single address space. Use `sm.GetStateId(nodeId)` / `sm.GetTransitionId(nodeId)` and their inverses `sm.GetStateNodeId(stateId)` / `sm.GetTransitionNodeId(transitionId)` to move between a NodeId and the numeric id used by `AddState` / `AddTransition` / `OnCause` and the lifecycle hooks — never parse the NodeId's identifier directly. Element nodes land in the namespace given to `UseElementNamespace`, or in the state machine's own namespace when that was not called or the URI is not registered with the server (the element namespace defaults to the OPC UA namespace, which must never host vendor nodes). Because element NodeIds are derived from browse names, browse names must be unique across states and transitions (and must not shadow the standard `CurrentState` / `LastTransition` / `AvailableStates` / `AvailableTransitions` children); the builder rejects duplicates when the definition freezes. Cost is one node plus one property per declared state and transition, per machine instance — worth weighing for servers that instantiate many machines. ### Executable causes A cause is a Method, and whether it may fire depends on the state the machine is in. Part 3 §5.7 defines `Executable` / `UserExecutable` as exactly that question, and Part 4 §5.11.2 has `Call` refuse a Method that is not executable with `Bad_NotExecutable`. `WithCause(methodNodeId)` therefore answers both attributes from `IsCausePermitted(context, causeId, checkUserAccessRights)` alongside installing the call handler — `Executable` ignoring user rights, `UserExecutable` running the machine's `OnCheckUserPermission` callback as well. A client can read them after every transition and offer only the causes that currently apply, instead of duplicating the server's state table or calling one to find out. Pass `reportExecutable: false` to opt out, for servers that deliberately keep their methods executable and answer at call time. The stack-shipped `ProgramStateMachineState` does the same for its own `Start` / `Suspend` / `Resume` / `Halt` / `Reset` methods when they are created, so a Program server no longer repeats the wiring per method. Those five are optional placeholders on the type, so only the ones an instance declares are wired, matched on browse name alone — a subtype that redeclares them puts them in its own namespace. Call `WireCauseMethods(context)` yourself if you add one to an already-created instance; `Create` rebuilds the child list from the type template, so children added by hand before it are not there when the automatic pass runs. ### Client side — sub-SM observation ```csharp FiniteStateMachineTypeClient parent = new FiniteStateMachineTypeClient(session, alarmId, telemetry); // The state NodeId comes from AvailableStates ... IReadOnlyList states = await parent.GetAvailableStatesAsync(ct); NodeId activeStateId = states.First(s => s.BrowseName.Name == "Active").NodeId; // ... or from a snapshot's CurrentStateId, to reach the sub-SM of // whatever state the machine is in right now. FiniteStateMachineTypeClient? limitSm = await parent.GetSubStateMachineAsync( parentStateNodeId: activeStateId, telemetry, ct); if (limitSm != null) { FiniteStateSnapshot snap = await limitSm.GetCurrentFiniteStateAsync(ct); Console.WriteLine($"Limit state: {snap.CurrentState}"); } // Observe combined parent + sub-SM transitions: await foreach (FiniteStateSnapshot snap in parent .ObserveEffectiveStateAsync(streaming, telemetry, ct: ct)) { Console.WriteLine($"Parent: {snap.CurrentState}"); if (snap.SubMachine != null) { Console.WriteLine($" Sub: {snap.SubMachine.CurrentState}"); } } ``` `FiniteStateSnapshot` gains an optional `SubMachine: FiniteStateSnapshot?` field carrying the snapshot of the parent's currently-active sub-SM (or `null` if none). `ObserveEffectiveStateAsync` yields a combined snapshot each time **either** the parent transitions **or** the parent's currently-active sub-SM transitions: * On every parent transition the yield carries the latest known snapshot of the sub-SM attached to the new state (or `null` if none). * On every sub-SM transition that occurs while the parent is in the state that owns the sub-SM, the yield carries the new sub-SM snapshot. Sub-SM transitions occurring while the parent is in a different state are silently discarded. Under the hood all discovered sub-SMs are subscribed once up-front and their notifications are multiplexed through a `Channel`; sub-SM events are filtered against the parent's currently-active state. If any source fails (including a follow-up state read), the combined stream surfaces that exception and cancels the other sources immediately. A healthy sub-state-machine stream does not keep a failed parent stream silently alive. ### Client side — typed sub-SM accessors (generated) For every `` child declared on a generator-emitted ObjectType, the source generator now emits a typed, lazily-resolved accessor on the parent type's client. For state-machine types, this gives ergonomic access to known sub-SMs without needing to know the state NodeId: ```csharp // Generated on AlarmConditionTypeClient: ShelvedStateMachineTypeClient? shelving = await alarm .GetShelvingStateAsync(telemetry, ct); // Generated on ExclusiveLimitAlarmTypeClient: ExclusiveLimitStateMachineTypeClient? limit = await alarm .GetLimitStateAsync(telemetry, ct); ``` Properties of the generated accessor: * **Typed** — returns the concrete sub-SM proxy type, not the generic `FiniteStateMachineTypeClient`. * **Lazy** — first call resolves the child NodeId via `TranslateBrowsePathsToNodeIds` against the parent's `ObjectId`. Optional children (`ModellingRule="Optional"`) that aren't exposed by the server yield `null`. * **Cached** — subsequent calls return the same instance without another browse round-trip. The cache is per-parent-instance. Vendor models that add their own `` children on a custom ObjectType benefit automatically; the generator emits the same shape for every Object child it encounters. ### Fluent builder behavior — `HasSubStateMachine` is on the state node Earlier fluent-builder implementations attached `HasSubStateMachine` to the state machine **root**, because the fluent builder did not materialize state nodes. It now sits on the parent **state** node per Part 16 §4.4.16, and the root reference is gone. Callers that passed the state machine's `ObjectId` to `GetSubStateMachineAsync` must pass a state NodeId instead — from `GetAvailableStatesAsync` or from a snapshot's `CurrentStateId`. ## Extensibility recipes * **Add convenience properties.** Subclass `FluentFiniteStateMachineState`, override `CreateChildren` if you need vendor-specific child variables, and call `StateMachineBuilder.For(instance, ctx)` to attach behavior. * **Bind a method node to a cause.** `WithCause(methodNodeId)` installs an `OnCallMethod2` handler that calls `DoCause(...)`. The cause id is derived from the method NodeId's numeric identifier (OPC UA convention); the cause→transition mapping is whatever the underlying FSM declared (`OnCause(...)` in definition mode or hardcoded in a stack/vendor subclass). It also answers the method's `Executable` / `UserExecutable` attributes from `IsCausePermitted` — see [Executable causes](#executable-causes). * **Drive auto-transitions.** `WithTimedTransition(fromStateId, timeout, transitionId, causeId)` uses the server's `TimeProvider` to arm one timer on entry into `fromStateId`, including the initial state. Re-arming disposes the previous timer. A queued callback cannot transition after reset, replacement, or exit/re-entry. `StopTimedTransitions()` permanently stops that builder's automatic transitions without removing the machine or its lifecycle observers. Timer-only causes emit transition events, not fabricated Method audit events; real Method calls retain their normal audit events. * **Escape hatch.** `ConfigureStateMachine(Action)` is invoked synchronously with the underlying state machine. Use it for properties or methods the builder doesn't surface directly. Transitions are serialized per machine. Before/after handlers retain per-invocation source and destination snapshots, including nested callbacks. If a before-handler changes the state, the stale outer transition is rejected with `BadInvalidState`. Transition events capture their state data before after-handlers run, so a nested transition cannot rewrite an earlier event. ## Tests * `tests/Opc.Ua.Server.Tests/StateMachines/StateMachineBuilderTests.cs` validates definition-mode chaining, validation, and freeze semantics. * `tests/Opc.Ua.Server.Tests/StateMachines/StateMachineBuilderLifecycleTests.cs` exercises every lifecycle method, including timed transitions and the layering behavior on top of pre-existing delegates. * `tests/Opc.Ua.Server.Tests/StateMachines/FluentFiniteStateMachineStateTests.cs` covers the table projections. * `tests/Opc.Ua.Server.Tests/StateMachines/StateMachineBuilderCauseExecutableTests.cs` and `tests/Opc.Ua.Core.Tests/Stack/State/ProgramStateMachineStateTests.cs` cover the `Executable` / `UserExecutable` reporting of causes. * The Part 9 conformance tests in `tests/Opc.Ua.History.Tests/AlarmsAndConditions*.cs` exercise `AlarmClient.GetShelvingStateAsync` and `ObserveShelvingTransitionsAsync` end-to-end against the reference server. ## See also - [Subscriptions and Monitored Items](Subscriptions.md#streaming-subscriptions) — the `IStreamingSubscription` surface the observation methods consume. - [Alarms and conditions](AlarmsAndConditions.md) — Part 9 alarm client that exposes the shelving-state-machine helpers. - [Device Integration (DI) software-update facet](SoftwareUpdate.md) — the four DI SU state machines, the typed `SoftwareUpdateClient.StateMachine` partial, and the server-side `On*StateChanged` instrumentation hooks. - [Source-generated NodeManagers](NodeManagers.md#source-generated-node-managers) — how vendor NodeSets get their `*TypeClient` proxies emitted.