Sampling

Strategies for sampling sensor values.

class katcp.sampling.SampleAuto(inform_callback, sensor, *params, **kwargs)

Bases: katcp.sampling.SampleStrategy

Strategy which sends updates whenever the sensor itself is updated.

Methods

SampleAuto.attach()	Attach strategy to its sensor and send initial update.
SampleAuto.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SampleAuto.cancel_timeouts()	Override this method to cancel any outstanding ioloop timeouts.
SampleAuto.detach()	Detach strategy from its sensor.
SampleAuto.get_sampling()
SampleAuto.get_sampling_formatted()	The current sampling strategy and parameters.
SampleAuto.get_strategy(strategyName, ...)	Factory method to create a strategy object.
SampleAuto.inform(reading)	Inform strategy creator of the sensor status.
SampleAuto.start()	Start operating the strategy.
SampleAuto.update(sensor, reading)

class katcp.sampling.SampleDifferential(inform_callback, sensor, *params, **kwargs)

Bases: katcp.sampling.SampleStrategy

Differential sampling strategy for integer and float sensors.

Sends updates only when the value has changed by more than some specified threshold, or the status changes.

Methods

SampleDifferential.attach()	Attach strategy to its sensor and send initial update.
SampleDifferential.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SampleDifferential.cancel_timeouts()	Override this method to cancel any outstanding ioloop timeouts.
SampleDifferential.detach()	Detach strategy from its sensor.
SampleDifferential.get_sampling()
SampleDifferential.get_sampling_formatted()	The current sampling strategy and parameters.
SampleDifferential.get_strategy(...)	Factory method to create a strategy object.
SampleDifferential.inform(reading)	Inform strategy creator of the sensor status.
SampleDifferential.start()	Start operating the strategy.
SampleDifferential.update(sensor, reading)

class katcp.sampling.SampleDifferentialRate(inform_callback, sensor, *params, **kwargs)

Bases: katcp.sampling.SampleEventRate

Differential rate sampling strategy.

Report the value whenever it changes by more than difference from the last reported value or if more than longest_period seconds have passed since the last reported update. However, do not report the value until shortest_period seconds have passed since the last reported update. The behaviour if shortest_period is greater than longest_period is undefined. May only be implemented for float and integer sensors.

Methods

SampleDifferentialRate.attach()	Attach strategy to its sensor and send initial update.
SampleDifferentialRate.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SampleDifferentialRate.cancel_timeouts()
SampleDifferentialRate.detach()	Detach strategy from its sensor.
SampleDifferentialRate.get_sampling()
SampleDifferentialRate.get_sampling_formatted()	The current sampling strategy and parameters.
SampleDifferentialRate.get_strategy(...)	Factory method to create a strategy object.
SampleDifferentialRate.inform(reading)
SampleDifferentialRate.start()
SampleDifferentialRate.update(sensor, reading)

class katcp.sampling.SampleEvent(inform_callback, sensor, *params, **kwargs)

Bases: katcp.sampling.SampleEventRate

Strategy which sends updates when the sensor value or status changes.

Since SampleEvent is just a special case of SampleEventRate, we use SampleEventRate with the appropriate default values to implement SampleEvent.

Methods

SampleEvent.attach()	Attach strategy to its sensor and send initial update.
SampleEvent.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SampleEvent.cancel_timeouts()
SampleEvent.detach()	Detach strategy from its sensor.
SampleEvent.get_sampling()
SampleEvent.get_sampling_formatted()	The current sampling strategy and parameters.
SampleEvent.get_strategy(strategyName, ...)	Factory method to create a strategy object.
SampleEvent.inform(reading)
SampleEvent.start()
SampleEvent.update(sensor, reading)

class katcp.sampling.SampleEventRate(inform_callback, sensor, *params, **kwargs)

Bases: katcp.sampling.SampleStrategy

Event rate sampling strategy.

Report the sensor value whenever it changes or if more than longest_period seconds have passed since the last reported update. However, do not report the value if less than shortest_period seconds have passed since the last reported update.

Methods

SampleEventRate.attach()	Attach strategy to its sensor and send initial update.
SampleEventRate.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SampleEventRate.cancel_timeouts()
SampleEventRate.detach()	Detach strategy from its sensor.
SampleEventRate.get_sampling()
SampleEventRate.get_sampling_formatted()	The current sampling strategy and parameters.
SampleEventRate.get_strategy(strategyName, ...)	Factory method to create a strategy object.
SampleEventRate.inform(reading)
SampleEventRate.start()
SampleEventRate.update(sensor, reading)

class katcp.sampling.SampleNone(inform_callback, sensor, *params, **kwargs)

Bases: katcp.sampling.SampleStrategy

Sampling strategy which never sends any updates.

Methods

SampleNone.attach()	Attach strategy to its sensor and send initial update.
SampleNone.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SampleNone.cancel_timeouts()	Override this method to cancel any outstanding ioloop timeouts.
SampleNone.detach()	Detach strategy from its sensor.
SampleNone.get_sampling()
SampleNone.get_sampling_formatted()	The current sampling strategy and parameters.
SampleNone.get_strategy(strategyName, ...)	Factory method to create a strategy object.
SampleNone.inform(reading)	Inform strategy creator of the sensor status.
SampleNone.start()
SampleNone.update(sensor, reading)	Callback used by the sensor’s notify() method.

class katcp.sampling.SamplePeriod(inform_callback, sensor, *params, **kwargs)

Bases: katcp.sampling.SampleStrategy

Periodic sampling strategy.

Methods

SamplePeriod.attach()	Attach strategy to its sensor and send initial update.
SamplePeriod.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SamplePeriod.cancel_timeouts()
SamplePeriod.detach()	Detach strategy from its sensor.
SamplePeriod.get_sampling()
SamplePeriod.get_sampling_formatted()	The current sampling strategy and parameters.
SamplePeriod.get_strategy(strategyName, ...)	Factory method to create a strategy object.
SamplePeriod.inform(reading)	Inform strategy creator of the sensor status.
SamplePeriod.start()
SamplePeriod.update(sensor, reading)	Callback used by the sensor’s notify() method.

class katcp.sampling.SampleStrategy(inform_callback, sensor, *params, **kwargs)

Bases: object

Base class for strategies for sampling sensors.

Parameters:

inform_callback : callable, signature inform_callback(sensor_obj, reading)

Callback to receive inform messages.

sensor : Sensor object

Sensor to sample.

params : list of objects

Custom sampling parameters.

Methods

SampleStrategy.attach()	Attach strategy to its sensor and send initial update.
SampleStrategy.cancel()	Detach strategy from its sensor and cancel ioloop callbacks.
SampleStrategy.cancel_timeouts()	Override this method to cancel any outstanding ioloop timeouts.
SampleStrategy.detach()	Detach strategy from its sensor.
SampleStrategy.get_sampling()	The Strategy constant for this sampling strategy.
SampleStrategy.get_sampling_formatted()	The current sampling strategy and parameters.
SampleStrategy.get_strategy(strategyName, ...)	Factory method to create a strategy object.
SampleStrategy.inform(reading)	Inform strategy creator of the sensor status.
SampleStrategy.start()	Start operating the strategy.
SampleStrategy.update(sensor, reading)	Callback used by the sensor’s notify() method.

OBSERVE_UPDATES = False

True if a strategy must be attached to its sensor as an observer

attach()

Attach strategy to its sensor and send initial update.

cancel()

Detach strategy from its sensor and cancel ioloop callbacks.

cancel_timeouts()

Override this method to cancel any outstanding ioloop timeouts.

detach()

Detach strategy from its sensor.

get_sampling()

The Strategy constant for this sampling strategy.

Sub-classes should implement this method and return the appropriate constant.

Returns:

strategy : Strategy constant

The strategy type constant for this strategy.

get_sampling_formatted()

The current sampling strategy and parameters.

The strategy is returned as a string and the values in the parameter list are formatted as strings using the formatter for this sensor type.

Returns:

strategy_name : string

KATCP name for the strategy.

params : list of strings

KATCP formatted parameters for the strategy.

classmethod get_strategy(strategyName, inform_callback, sensor, *params, **kwargs)

Factory method to create a strategy object.

Parameters:

strategyName : str

Name of strategy.

inform_callback : callable, signature inform_callback(sensor, reading)

Callback to receive inform messages.

sensor : Sensor object

Sensor to sample.

params : list of objects

Custom sampling parameters for specified strategy.

Keyword Arguments:  

ioloop : tornado.ioloop.IOLoop instance, optional

Tornado ioloop to use, otherwise tornado.ioloop.IOLoop.current()

Returns:

strategy : SampleStrategy object

The created sampling strategy.

inform(reading)

Inform strategy creator of the sensor status.

start()

Start operating the strategy.

Subclasses that override start() should call the super method before it does anything that uses the ioloop. This will attach to the sensor as an observer if OBSERVE_UPDATES is True, and sets _ioloop_thread_id using thread.get_ident().

update(sensor, reading)

Callback used by the sensor’s notify() method.

This update method is called whenever the sensor value is set so sensor will contain the right info. Note that the strategy does not really need to be passed a sensor because it already has a handle to it, but receives it due to the generic observer mechanism.

Sub-classes should override this method or start() to provide the necessary sampling strategy. Sub-classes should also ensure that update() is thread-safe; an easy way to do this is by using the @update_in_ioloop decorator.

Parameters:

sensor : Sensor object

The sensor which was just updated.

reading : (timestamp, status, value) tuple

Sensor reading as would be returned by sensor.read()

katcp.sampling.update_in_ioloop(update)

Decorator that ensures an update() method is run in the tornado ioloop.

Does this by checking the thread identity. Requires that the object to which the method is bound has the attributes _ioloop_thread_id (the result of thread.get_ident() in the ioloop thread) and ioloop (the ioloop instance in use). Also assumes the signature update(self, sensor, reading) for the method.