Open-Source Driver Kit

The Open-Source Driver Kit is a developer kit, not an instrument. There is no hardware on this page. What it gives you is the same driver interface every Revolution driver is written against, plus a worked example driver in the Revolution source tree that you can copy and cut down to the device you actually have.

A Revolution driver is a .NET class library. You write a class that derives from DeviceBase, decorate it with attributes, and Revolution does the rest: it discovers the class, lists it as a device class, renders your configuration properties in the device editor, and offers your operations as schedulable steps. There is no separate protocol to implement and no separate process to run — the driver is loaded by Revolution and runs inside it.

At a glance

Language	C# (.NET Framework 4.8.1)
Interface	UKRobotics.SystemInterfaces — derive from DeviceBase
Discovery	Revolution scans assemblies for device types; a matching DLL is picked up
Hosting	In-process by default; an out-of-process WCF host is available for SDKs that cannot share the Revolution process
Worked example	Devices/DriverTutorial1 — one driver class, four operations, one property, one unit test
Simulation	Every driver gets a simulation mode and can declare a 3D model for the simulator

What you declare

Revolution reads a driver by reflection, so the whole surface of a driver is declared with attributes on ordinary C# members.

Attribute	What it does
[DeviceClass("...")]	Names the device class as operators see it — a classification, not the C# class name
[DeviceProperty("...")]	Exposes a property as device configuration. The label is optional; without one the property name is used
[DeviceOperation]	Exposes a method as a schedulable operation
[DeviceOperationParameter]	Gives a parameter a display Name and Description, and optionally a DefaultValue, MinValue and MaxValue
[ScheduleParameter]	Declares a schedule parameter the operation reads or writes, with its type and direction
[ModelFile]	Points at the mesh used to draw the device in the simulator

Rules for an operation method

Revolution’s introspector only accepts a method as an operation if it is public, an instance method, returns void, and carries [DeviceOperation]. Its first parameter must be the IDeviceOperationContext that Revolution supplies at runtime. Operation names must be unique within a driver — a duplicate is rejected at load time rather than silently shadowed.

Configuration that survives a restart

Device configuration is persisted as XML. A driver overrides FromXmlElement and ToXmlElement to read and write its own attributes, and calls FireDeviceConfigurationChanged() from a property setter so Revolution knows the configuration is dirty and needs saving.

Initialise() and Uninitialise() are the lifecycle hooks — open the connection in one, close it in the other.

Supported methods

The example driver, DriverExample1, declares four operations. They log their parameters rather than touching hardware: the point is the shape, not the behaviour.

• RunScript — takes a script name. The minimum viable operation: one parameter, no ceremony
• Spin — takes an rpm and a duration, and declares an integer output schedule parameter AchievedRPM. This is the pattern for an operation that returns a measured value to the schedule
• SetTempTarget — takes a target temperature and writes it into the schedule thread’s parameters, showing how a driver publishes a value the rest of the schedule can read
• ErrorHandlingDeviceOperationExample — raises an error through the schedule thread and acts on what the operator chose

It also declares a single configuration property, IP Address, which is read from and written to the device XML, and ships an NUnit test that round-trips that XML.

Two ways to fail

A driver can simply throw from an operation, and Revolution treats that as an operation failure. Handling the error inside the driver instead — building ErrorHandlerData and calling ScheduleThread.HandleError with the recovery actions that make sense for this fault, such as Retry or Ignore error and continue — costs more code but buys one thing back: the driver controls where the schedule resumes. The example driver demonstrates the second route.

Real and simulated

Operations are written to branch on the device’s operation mode. In Real mode you talk to the instrument; in Simulation mode you call WaitForSimulationDuration and return. Because simulation is part of the driver rather than a layer above it, a schedule using your device can be built and rehearsed before the hardware arrives.

Integration

Most drivers run in the Revolution process. Some vendor SDKs cannot: a COM or ActiveX SDK, a 32-bit only library, or an SDK with a static lifecycle and its own logging that you do not want inside the scheduler. For those, Revolution ships a generic WCF host — the driver’s device class stays in Revolution and talks over HTTP to a small service that owns the vendor SDK in a separate process. The host is available as an AnyCPU build and an x86 build, and can be dropped into a vendor’s own install folder without colliding with the vendor’s libraries. Several shipped drivers, including the VWorks and Tecan Spark drivers, are built this way.

Prerequisites

• A Windows build toolchain for .NET Framework 4.8.1. Drivers are Windows components; that is where the instrument SDKs live.
• The Revolution interface assemblies — UKRobotics.SystemInterfaces and its dependencies — to compile against. Contact us for access.
• A documented control interface for the device. The kit gives you the Revolution side; the vendor has to give you a way in, whether that is a serial protocol, a TCP command set, a file interface or an SDK.
• Where a vendor SDK is involved, that SDK must be installed on the machine the driver runs on, under whatever licence the vendor requires.

If you need more of this instrument driven from a schedule, get in touch — the driver is extended on demand.