docs

Tinkwell Documentation

What is Tinkwell?

Tinkwell is a .NET-based runtime for connected systems: you describe an ensemble in a single configuration file (.tw)—which processes (runners) start, which pluggable services (runlets) they host, and how measures (values you track), signals (conditions), actions (reactions to events), and protocol integrations (e.g. MQTT, CoAP) fit together. A coordinator process launches and supervises child runners; the tw CLI talks to the coordinator to inspect and control a running system. You do not need to write custom code to get started: reference the built-in runner and runlet assemblies and focus on configuration and plugins from the community or your organization.

Getting started

New to Tinkwell? Start here.

• Installation — Windows, Linux, and manual setup
• Quick start — From install to running in minutes
• Tutorial — End-to-end walkthrough: measures, signals, actions, and the CLI
• Running under systemd — Production-style Linux deployment with auto-start, restart, and journald logging
• Running under Docker — Bind-mount and derived-image patterns, ports, volumes, healthcheck, and docker-compose examples
• Glossary — Alphabetical reference of Tinkwell terminology

User guide

Configuration, CLI, and day-to-day usage.

• Configuration reference — Complete .tw language: blocks, properties, includes, templates, conditionals
• CLI reference — Every tw command, option, output format, and exit code
• Expressions — Operators, built-in functions, and evaluation contexts
• Units — Supported quantity types and unit abbreviations
• How-to recipes — Practical patterns: ensembles, measures, signals, custom runlets
• Services — gRPC services: Store, Measures, Events, Signals, Measure History RPCs
• Extending integrations — Custom CoAP routes, LwM2M resources, and middleware
• Troubleshooting — Common issues, error messages, and debugging

Protocol and subsystem reference

Standalone reference pages for each protocol and subsystem.

• MQTT — Broker connection, topic routing, bindings, publish actions
• CoAP — Server, resources, bindings, Observe
• LwM2M — Device management, object mapping, TLV/SenML
• Modbus — RTU/TCP polling, register types, data decoding
• I2C — Linux raw I2C bus polling
• TextQuery / SCPI — Text-based instrument queries over TCP, serial, file, or command
• Protobuf gateway — CoAP-to-gRPC tunneling for constrained devices
• Measures — Measure types, units, derived measures
• Measure history — Time-series persistence, TimescaleDB backend, query API
• Signals — Condition evaluation, firing, duration, hysteresis
• Events — Event bus, SVO model, subscriptions
• Plugins — Discovery, resolution, authoring, packaging, installation
• Packages — Secure package format, signing, verification
• HTTPS / TLS — Certificate configuration and TLS modes
• Telemetry — OpenTelemetry metrics, traces, and histograms

Architecture (contributors)

Internal design documentation for contributors and extension authors.

• Overview — Solution structure, project map, and design philosophy
• Coordinator-runner model — Process tree, IPC, service discovery
• Runner lifecycle — Build and run phases, crash recovery, sentinel pipes
• Configuration internals — Parser pipeline, block model, lax mode
• Services internals — Endpoint allocation, registration, discovery protocol
• Runlets catalog — All built-in runlets, dependencies, and ordering constraints
• Published libraries — NuGet packages: standalone, SDK, and tools

Contributing

• Code conventions — Naming, style, DI patterns, test conventions
• CI/CD pipelines — Workflows, change-detection gate, version bumping
• Roadmap — Planned features and exploration ideas
• Project README template — Minimum quality bar for per-project READMEs