Cauldron KTL API

The Cauldron KTL API mimics the real KTL API for clients and DFW API for server-side components. A brief introduction to using each component is below.

Using a Cauldron KTL Client

To use a client, you must first select a backend via use():

import Cauldron

In this example, we use the “mock” backend, as it doesn’t require a dispatcher to be running. All dispatchers will be filled in with caching dispatchers at runtime.

Then, import the ktl library and create a service clinet:

from Cauldron import ktl
service = ktl.Service("MYSERVICENAME")

To access a keyword, you can index the service object like a dictionary:

keyword = service["AKEYWORD"]
keyword.write("some value")
value =

Using a Cauldron DFW dispatcher

Dispatchers are little more tricky in real-world use, as they respond to arbitrary requests from ktl clients. In the simplest implementation, you only need a dispatcher (instance of Service), from which you can access keyword objects, and attach callbacks to them. For example:

import Cauldron
from Cauldron import DFW
service = DFW.Service("MYSERVICENAME", config=None)
keyword = service["AKEYWORD"]
keyword.callback(lambda kwd : print("Hello"))

A more sophisticated (and correct) use of a dispatcher is to provide custom implementation for keywords which can validate keyword values as they are written, and which can respond with proper values as they are read. Imagine that you have a hardware widget with two functions and you wish to expose the widget via the keyword system:

def get_widget_value():
    return 5

def set_widget_value(value):
    print("Widget set to {0}".format(value))

Lets pretend that the widget only accepts integer values, and that negative numbers will cause an error for the widget. We can implement a custom keyword class for this widget using the following:

from Cauldron.types import DispatcherKeywordType

class WidgetKeyword(DispatcherKeywordType):

    def __init__(self, service):
        super(WidgetKeyword, self).__init__(service=service, name="MYWIDGET", initial=5)

    def read(self):
        return get_widget_value()

    def write(self, value):
        value = int(value)
        if value < 0:
            raise ValueError("Widget can't be less than zero.")
        return str(value)

Now we’d normally set up the keyword during the service’s setup function (see Service):

def setup(service):

service = DFW.Service("WIDGETSERVICE", setup=setup, config=None)

API Implementation Status

A brief summary of major KTL API features is provided in the table below. API features marked as Planned are ones that I do intend to implement at some point in support of ShadyAO. API features marked as Not Implemented would require more work.

Feature Status Comments
Synchronous read/write Implemented  
Asynchronous read/write Implemented KTL calls are still serial on most backends.
Heartbeats Planned  
Callbacks Implemented  
Polling Not Implemented  
Scheduling Not Implemented  
Expressions Not Implemented  
XML Keyword Validation Implemented  
Operator Overloading Not Implemented  

When Cauldron does not implement a feature, using that feature will raise an CauldronAPINotImplemented error, which is a subclass of NotImplementedError.

ktl Reference/API

Cauldron.ktl Package

This is the Cauldron implementation of ktl, the clinet side of the KTL keyword system. Don’t import this module if you haven’t called use() to set the backend yet, this module is not importable. It is set up to match ktl as closely as possible.

Cauldron.ktl.Keyword Module

The implementation of the KTL Keyword module which contains the implementations of the Keyword class for this KTL client.


Integer An integer value keyword.
Boolean A boolean-valued keyword.
Numeric A numerical value keyword.
String An ASCII valued keyword, implemented identically to Basic.
Keyword An alias for Basic

Class Inheritance Diagram

Inheritance diagram of Cauldron.ktl.Keyword.Integer, Cauldron.ktl.Keyword.Boolean, Cauldron.ktl.Keyword.Numeric, Cauldron.ktl.Keyword.String, Cauldron.ktl.Keyword.Keyword

Cauldron.ktl.Service Module

The Service will be added here by the runtime backend selection utilties.


Service A client-side KTL service object.

Class Inheritance Diagram

Inheritance diagram of Cauldron.ktl.Service.Service

Cauldron.ktl.procedural Module


write(service, keyword, *args, **kwargs) Perform a KTL write for this keyword.
read(service, keyword, *args, **kwargs) Perform a ktl_read() operation for this keyword.
wait(service, keyword, *args, **kwargs) Wait for the Keyword to receive a new value, or if sequence is set, wait for the designated write operation to complete.
monitor(service, keyword, *args, **kwargs) Subscribe to broadcasts for this KTL keyword.
subscribe(service, keyword, *args, **kwargs) Subscribe to broadcasts for this KTL keyword.
heartbeat(service, *args, **kwargs) Identify keyword (either a keyword name, or a Keyword instance) as a heartbeat keyword for this Service.
callback(service, keyword, *args, **kwargs) Request that a callback function be invoked whenever a KTL broadcast is received for this keyword.

DFW Reference/API

Cauldron.DFW Package

Cauldron.DFW.Service Module

The Service will be added here by the runtime backend selection utilties.


Service A dispatcher is a KTL service server-side.

Class Inheritance Diagram

Inheritance diagram of Cauldron.DFW.Service.Service

Cauldron.DFW.Keyword Module

No keywords are defined here, because this module is populated at runtime.


DoubleArray The base class for KTL and DFW keywords.
String An ASCII valued keyword, implemented identically to Basic.
Keyword An alias for Basic
FloatArray The base class for KTL and DFW keywords.
Double A numerical value keyword.
Float A numerical value keyword.
Mask The base class for KTL and DFW keywords.
Boolean A boolean-valued keyword.
Enumerated An enumerated keyword, which uses an integer as the underlying datatype.
Basic The base class for KTL and DFW keywords.
Integer An integer value keyword.
IntegerArray The base class for KTL and DFW keywords.

Class Inheritance Diagram

Inheritance diagram of Cauldron.DFW.Keyword.DoubleArray, Cauldron.DFW.Keyword.String, Cauldron.DFW.Keyword.Keyword, Cauldron.DFW.Keyword.FloatArray, Cauldron.DFW.Keyword.Double, Cauldron.DFW.Keyword.Float, Cauldron.DFW.Keyword.Mask, Cauldron.DFW.Keyword.Boolean, Cauldron.DFW.Keyword.Enumerated, Cauldron.DFW.Keyword.Basic, Cauldron.DFW.Keyword.Integer, Cauldron.DFW.Keyword.IntegerArray