Sigil

Sigil models one OPC UA variable with synchronized runtime surfaces across OPC UA, REST, and MCP.

Core behavior

• node_id is required and must be a valid OPC UA NodeId string.
• Sigil registration happens at construction time; declare Sigils before nexus.start().
• Each Sigil contributes generated REST and MCP endpoints:
  • Read endpoint/tool always.
  • Write endpoint/tool only when writable=True.
• minimum_value and maximum_value constrain writes; initial_value is validated against the same bounds.

Embedded vs external mode

• Embedded mode: omit opc_ua_url and the Sigil is hosted by Nexus on the embedded OPC UA server.
• External mode: set opc_ua_url to bind the Sigil to a node on another OPC UA server (for example, a PLC) while preserving REST/MCP access through Nexus.

External OPC UA attributes

Use these constructor attributes when a Sigil is linked to an external OPC UA server:

• opc_ua_url: external OPC UA endpoint URL.
• user_name: optional user for username/password authentication.
• password: optional password for username/password authentication.
• security_policy: optional asyncua security policy class.
• certificate: optional client certificate path/content accepted by your SDK setup.
• private_key: optional private key path/content paired with certificate.
• server_certificate: optional trusted server certificate path/content.
• message_security_mode: OPC UA message security mode (default is sign-and-encrypt in SDK behavior).

External behavior notes

• On startup, Nexus can initialize and connect external Sigil clients.
• read() on external Sigils refreshes from the remote node.
• write() on external Sigils writes to the remote node while preserving local value state.
• Read/write events are emitted as Sigil events for AWS IoT publishing when configured.
• If writable=False, REST/MCP write interfaces are omitted even though internal logic can still update values where your application permits.

Value and writable semantics

• initial_value: optional startup value.
• minimum_value / maximum_value: optional bounds enforced on writes.
• writable:
  • True (default): external and generated surfaces can write.
  • False: generated external write surfaces are disabled; use for operator-read telemetry variables.

Example: external PLC-linked Sigil

from asyncua import ua
from asyncua.crypto import security_policies

from aether.nexus import Nexus
from aether.sigil import Sigil

nexus = Nexus(opc_ua_url="opc.tcp://0.0.0.0:4840")

PLC_URL = "opc.tcp://192.168.1.100:4840"

process_value = Sigil(
    node_id="ns=3;i=1001",
    opc_ua_url=PLC_URL,
    user_name="opcuser",
    password="your_password",
    security_policy=security_policies.SecurityPolicyBasic256Sha256,
    certificate="certs/client-cert.pem",
    private_key="certs/client-key.pem",
    server_certificate="certs/plc-server-cert.der",
    message_security_mode=ua.MessageSecurityMode.SignAndEncrypt,
    initial_value=0.0,
    writable=False,
    description="Measured process value from PLC.",
)

if __name__ == "__main__":
    nexus.start()

Related

• Nexus, Sigils, and Weaves overview
• Nexus reference
• Weave reference
• PID loop on a real PLC