Skip to content

Server Tutorials

These tutorials walk through the server side of o6 by building one server, one concept at a time. The Foundation band builds one continuous project — a small distillery exposing an object hierarchy, live variables, and methods — and that project is the same distillery the client tutorials ultimately connect to. Everything after Foundation applies the same domain, but as separate techniques you would reach for on a real deployment — Patterns, Composition, Behaviour, and Production are not folded back into that one running example.

The pages build on each other in ascending complexity. Each one introduces one concept and leaves the server runnable, so you can leave it running between pages and watch the address space grow.

Start from the first page

The project state at the top of each page is the project state at the bottom of the previous one. If you skip ahead, the imports and identifiers in the snippets will not match what you have.

Building a distillery server

Throughout the tutorials we build, one concept at a time, the same automated distillery: a still driven by a background simulation, exposing its state under Objects/DistillingSystem and accepting two writes — Operating (run / park) and Setpoint (target kettle temperature). On the way there we:

  • start with the smallest possible server, then grow the address space by hand — that's the whole Foundation band, and it's the one continuous project;
  • then work through the same handful of patterns the server examples walk through — an external data source, an asyncio server, and the declare/implement split for a Variable and for an ObjectType — each as its own small, self-contained aside rather than a further extension of the running distillery;
  • take a detour through the declarative alternative in depth — the same shapes as @o6.objecttype/@o6.variabletype/@o6.datatype classes, and custom ReferenceTypes — as a technique worth knowing once a model gets bigger than a handful of nodes;
  • attach write handlers, method implementations, events and timers once the hand-built data model is worth reacting to;
  • then take a second detour through access control, authentication, security policies, monitoring and history — everything a server needs before it is hosted on a real network, but not things this particular small distillery turns on.

The very last page — The distillery server — points back at Set the stage, which describes the two-file runnable project the Foundation band builds up to, and says plainly which bands are and aren't part of it.

Topics

The tutorials are organised around what you typically build on a server, moving from the smallest runnable program to a fully modelled, secured endpoint. The first two bands track the same order as the server examples, one page per example; everything after that goes further than the examples do.

Foundation

  1. Creating a server — create a Server, bind an endpoint, start it, stop it.
  2. Add a hierarchy — group nodes into a small hierarchy under Objects/.
  3. Add a variable — drop the first values into the right slots.
  4. Add a method — register a callable method, return values and StatusCode.

Patterns

The same shapes as the S07–S10 server examples, each as its own small aside rather than a further extension of the running distillery.

  1. Values from an external source — a Variable whose truth lives in a Python model, pushed in with server.write(...).
  2. Running on asyncio — async with server:, await asyncio.sleep(...), and asyncio.run(...).
  3. Declare and implement a Variable — declare a Variable as a contract, implement its read/write in a separate class.
  4. Declare and implement an ObjectType — the same declare/implement split, for a Method.

Composition

  1. Declare an object type — turn the hand-built hierarchy into a Python class with @o6.objecttype, define components, instantiate.
  2. Declare a variable type — @o6.variabletype for typed values with their own DataType, ValueRank, modelling rules.
  3. Declare a reference type — custom ReferenceTypes for relationships beyond HasComponent / HasProperty.
  4. Declare a data type — @o6.datatype for a custom Structure / Enum used by your variables and methods.

Behaviour

The data model is now in place; the next band is what makes it do something — the instance-level counterpart to the declare/implement classes in Patterns.

  1. Method implementations — install callbacks with Server.implement(method, call=...), sync vs async, error mapping.
  2. Variables with sources — install read and write callbacks with Server.implement(variable, read=..., write=...), validate, mirror.
  3. Server callbacks — startup, shutdown, periodic timers, retention cleanup.
  4. Events — the distillery's writable "event log" pattern, firing on state transitions, and when to graduate to real BaseEventType / emitEvent notifications.
  5. Timers and async loops — long-running background work, asyncio integration, cooperative cancellation.

Production

Take the distillery from "demo" to "ready for production".

  1. Access control — roles — Role / o6.roles, default-deny, granting reading / writing / calling per node, role mappings for built-in roles.
  2. Access control — authentication — session authentication, user token policies.
  3. Security policies and endpoints — SecurityPolicy selection, encrypted endpoints, certificate management.
  4. Subscribe monitoring on the server side — server-local monitored items for housekeeping.
  5. Historical data — historizing=True, server.config.setHistoryDatabase(...) + server._register_historizing(...), real HistoryRead against buffered values, and the allowHistoryUpdate / allowHistoryDelete hooks.

The distillery page that finishes the project — 500_distillery_server.md — defers to Set the stage, which is the same server in runnable form: the Foundation band, built incrementally, plus the plain write-loop pattern from Values from an external source. Patterns, Composition, Behaviour, and Production are separate techniques applied to the same distillery, not part of that one running file — 500_distillery_server.md says so explicitly.

Beyond the tutorials

The server manual collects the same topics as long-form narrative: