Skip to content

Part 4 : Automation Services and Process Values

Service BaseFunctions

mtppy.part4.automation_services.base_functions.service_operation_mode.ServiceOperationMode()

Bases: DataItemCollection

Operation mode selection per PNO MTP 2.0 Part 4, Section 8.2.2.3.

Represent the operation mode BaseFunction for a service part.

add_enter_automatic_callback(callback)

Register a callback invoked when entering automatic mode.

Parameters:

Name Type Description Default
callback Callable[[], None]

Zero-argument callable invoked on enter-automatic.

 required

add_enter_offline_callback(callback)

Register a callback invoked when entering offline mode.

Parameters:

Name Type Description Default
callback Callable[[], None]

Zero-argument callable invoked on enter-offline.

 required

add_enter_operator_callback(callback)

Register a callback invoked when entering operator mode.

Parameters:

Name Type Description Default
callback Callable[[], None]

Zero-argument callable invoked on enter-operator.

 required

add_exit_automatic_callback(callback)

Register a callback invoked when leaving automatic mode.

Parameters:

Name Type Description Default
callback Callable[[], None]

Zero-argument callable invoked on exit-automatic.

 required

add_exit_offline_callback(callback)

Register a callback invoked when leaving offline mode.

Parameters:

Name Type Description Default
callback Callable[[], None]

Zero-argument callable invoked on exit-offline.

 required

add_exit_operator_callback(callback)

Register a callback invoked when leaving operator mode.

Parameters:

Name Type Description Default
callback Callable[[], None]

Zero-argument callable invoked on exit-operator.

 required

allow_switch_to_offline_mode(allow_flag)

Allow or disallow switching to offline mode.

Parameters:

Name Type Description Default
allow_flag bool

When True the service may switch to offline mode.

 required

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

set_state_aut_aut(value)

Request automatic mode from the internal (automatic) side.

Parameters:

Name Type Description Default
value bool

When True request a transition to automatic mode.

 required

set_state_aut_op(value)

Request automatic mode from the operator (external) side.

Parameters:

Name Type Description Default
value bool

When True request a transition to automatic mode.

 required

set_state_channel(value)

Set the state channel flag.

Parameters:

Name Type Description Default
value bool

New value for the state channel.

 required

set_state_off_aut(value)

Request offline mode from the internal (automatic) side.

Parameters:

Name Type Description Default
value bool

When True request a transition to offline mode.

 required

set_state_off_op(value)

Request offline mode from the operator (external) side.

Parameters:

Name Type Description Default
value bool

When True request a transition to offline mode.

 required

set_state_op_aut(value)

Request operator mode from the internal (automatic) side.

Parameters:

Name Type Description Default
value bool

When True request a transition to operator mode.

 required

set_state_op_op(value)

Request operator mode from the operator (external) side.

Parameters:

Name Type Description Default
value bool

When True request a transition to operator mode.

 required

mtppy.part4.automation_services.base_functions.service_source_mode.ServiceSourceMode()

Bases: DataItemCollection

The Service Source Selection Mode is a concept that allows the service to select its source of operation based on the state of the service and the configuration parameters.

It is used to determine whether the service should operate in internal or external mode, and whether it should be in automatic or manual mode.

  • Manual Operations: Operator actions are conveyed via the Op variables.
  • Automatic Operation: PEA-internal actions made visible via the Aut variables.
  • Actual Operation: The actual state of the service is shown in the Act variables.

Note: The State Variables StateChannel, StateIntOp, a.s.o. are implemented in class ServiceOperationMode.

Assign callback functions after parent had set up internal structures.

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

set_src_channel(value)

Set the source channel flag.

Parameters:

Name Type Description Default
value bool

When True the source is internal, else external.

 required

set_src_ext_aut(value)

Request external source from the internal (automatic) side.

Parameters:

Name Type Description Default
value bool

When True and the channel is internal, select external source.

 required

set_src_ext_op(value)

Request external source from the operator (external) side.

Parameters:

Name Type Description Default
value bool

When True and the channel is external, select external source.

 required

set_src_int_aut(value)

Request internal source from the internal (automatic) side.

Parameters:

Name Type Description Default
value bool

When True and the channel is internal, select internal source.

 required

set_src_int_op(value)

Request internal source from the operator (external) side.

Parameters:

Name Type Description Default
value bool

When True and the channel is external, select internal source.

 required

mtppy.part4.automation_services.base_functions.service_operator_interaction.ServiceOperatorInteraction()

Bases: DataItemCollection

Represents the service interactions BaseFunction for service part.

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

ProcessValue BaseFunctions

mtppy.part4.process_values.base_functions.vqc.VQCBaseFunction()

Bases: DataItemCollection

Provide the VQC process value base function.

This base function stores the VQC value and exposes it through a read/write data item.

Initialize the VQC BaseFunction.

Sets up the VQC data item with the appropriate write callback.

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

get_vqc()

Return the current VQC value.

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

ServiceElements

mtppy.part4.automation_services.service_elements.service_element.ServiceElement(tag_name, tag_description)

Bases: DataAssembly

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

mtppy.part4.automation_services.service_elements.service_control.ServiceControl(tag_name, tag_description='', procedure_keys=None, execution_procedure=None)

Bases: ServiceElement

Service control data assembly per PNO MTP 2.0 Part 4.

Initialize service control with its sub-functions and callbacks.

Parameters:

Name Type Description Default
tag_name str

Tag name of the service.

 required
tag_description str

Human-readable description.

 ''
procedure_keys list[int] | None

Optional list of valid procedure IDs.

 None
execution_procedure Callable | None

Optional procedure executor callable.

 None

add_procedure_key(value)

Add a procedure key to the list of valid keys.

Parameters:

Name Type Description Default
value int

The procedure key to add.

 required

apply_config_param()

Apply configuration parameters if enabled.

apply_proc_param()

Apply procedure parameters if enabled.

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

dummy_procedure(value)

A dummy procedure for testing purposes.

Parameters:

Name Type Description Default
value int

Value to log during the dummy procedure call.

 required

get_procedure_cur()

Get the current procedure value.

Returns:

Type Description
int

The current procedure value.

remove_procedure_key(value)

Remove a procedure key from the list of valid keys.

Parameters:

Name Type Description Default
value int

The procedure key to remove.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

set_command_en(value)

Set the command enable value.

Parameters:

Name Type Description Default
value int

The value to set for the command enable.

 required

set_command_ext(value)

Set the external command.

Parameters:

Name Type Description Default
value int

The value to set for the external command.

 required

set_command_int(value)

Set the internal command.

Parameters:

Name Type Description Default
value int

The value to set for the internal command.

 required

set_command_op(value)

Set the operator command.

Parameters:

Name Type Description Default
value int

The value to set for the operator command.

 required

set_config_param_apply_en(value)

Set the configuration parameter apply enable.

Parameters:

Name Type Description Default
value bool

The value for the configuration parameter apply enable.

 required

set_config_param_apply_ext(value)

Set the external configuration parameter apply signal.

Parameters:

Name Type Description Default
value bool

The value for the external configuration parameter apply.

 required

set_config_param_apply_int(value)

Set the internal configuration parameter apply signal.

Parameters:

Name Type Description Default
value bool

The value for the internal configuration parameter apply.

 required

set_config_param_apply_op(value)

Set the operator configuration parameter apply signal.

Parameters:

Name Type Description Default
value bool

The value for the operator configuration parameter apply.

 required

set_proc_param_apply_en(value)

Set the procedure parameter apply enable.

Parameters:

Name Type Description Default
value bool

The value for the procedure parameter apply enable.

 required

set_proc_param_apply_ext(value)

Set the external procedure parameter apply signal.

Parameters:

Name Type Description Default
value bool

The value for the external procedure parameter apply.

 required

set_proc_param_apply_int(value)

Set the internal procedure parameter apply signal.

Parameters:

Name Type Description Default
value bool

The value for the internal procedure parameter apply.

 required

set_proc_param_apply_op(value)

Set the operator procedure parameter apply signal.

Parameters:

Name Type Description Default
value bool

The value for the operator procedure parameter apply.

 required

set_procedure_cur()

Set the current procedure based on the requested procedure.

set_procedure_ext(value)

Set the external procedure.

Parameters:

Name Type Description Default
value int

The value to set for the external procedure.

 required

set_procedure_int(value)

Set the internal procedure.

Parameters:

Name Type Description Default
value int

The value to set for the internal procedure.

 required

set_procedure_op(value)

Set the operator procedure.

Parameters:

Name Type Description Default
value int

The value to set for the operator procedure.

 required

set_procedure_req(value)

Set the requested procedure if it is a valid procedure id, else set the requested procedure parameter to 0 to indicate to the POL that the request was invalid.

Parameters:

Name Type Description Default
value int

The value to set for the requested procedure.

 required

set_report_value_freeze(value)

Set the report value freeze control.

Parameters:

Name Type Description Default
value bool

The boolean value to set for the report value freeze.

 required

valid_value(value)

Check if a value is a valid procedure id.

Parameters:

Name Type Description Default
value int

The value to check.

 required

Returns:

Type Description
bool

True if value is in list of procedure keys, else False

mtppy.part4.automation_services.service_elements.procedure_health_view.ProcedureHealthView(tag_name, tag_description)

Bases: ServiceElement

Procedure health view per PNO MTP 2.0 Part 4.

Initialize procedure health view.

Parameters:

Name Type Description Default
tag_name str

Tag name of the procedure health view.

 required
tag_description str

Human-readable description.

 required

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

set_command_info(value)

Set the command info bitmask.

Parameters:

Name Type Description Default
value int

The command info value to store.

 required

mtppy.part4.automation_services.service_elements.parameter_elements.parameter_element.ParameterElement(tag_name, tag_description)

Bases: DataAssembly

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

mtppy.part4.automation_services.service_elements.parameter_elements.ana_serv_param.AnaServParam(tag_name, tag_description='', *, v_min=0, v_max=100, v_scl_min=0, v_scl_max=100, v_unit=0)

Bases: ParameterElement

Analog Service Parameter implementation.

This class implements analog service parameters for service elements, inheriting from ParameterElement. It provides configurable boundaries (VMin, VMax) along with scaling parameters (VSclMin, VSclMax) for e.g. display purposes.

Initialize the Analog Service Parameter (AnaServParam).

Parameters:

Name Type Description Default
tag_name str

The name identifier for the parameter element

 required
tag_description str

A descriptive text for the parameter element

 ''
v_min float

Minimum value for the analog parameter (enforced)

 0
v_max float

Maximum value for the analog parameter (enforced)

 100
v_scl_min float

Scaled minimum value for the analog parameter (informative)

 0
v_scl_max float

Scaled maximum value for the analog parameter (informative)

 100
v_unit int

Unit identifier for the analog parameter

 0

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

is_valid_value(value)

Check if a value is within the valid range for this parameter.

Logs information about the validation process and returns whether the provided value is within the defined minimum and maximum bounds.

Parameters:

Name Type Description Default
value float

The value to validate

 required

Returns:

Name Type Description
bool bool

True if the value is within range, False otherwise

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

mtppy.part4.automation_services.service_elements.parameter_elements.bin_serv_param.BinServParam(tag_name, tag_description='', v_state_0='false', v_state_1='true')

Bases: ParameterElement

Binary Service Parameter (BinServParam).

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

mtppy.part4.automation_services.service_elements.parameter_elements.dint_serv_param.DIntServParam(tag_name, tag_description='', v_op=0, v_min=0, v_max=100, v_scl_min=0, v_scl_max=100, v_unit=0)

Bases: ParameterElement

Discrete Integer Service Parameter (DIntServParam).

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

mtppy.part4.automation_services.service_elements.parameter_elements.string_serv_param.StringServParam(tag_name, tag_description='')

Bases: ParameterElement

String Service Parameter implementation.

This class implements string service parameters for service elements. It inherits from ParameterElement and provides string-specific functionality for parameter handling with appropriate data types.

Initialize String Service Parameter (StringServParam).

Parameters:

Name Type Description Default
tag_name str

The name identifier for the parameter element

 required
tag_description str

A descriptive text for the parameter element

 ''

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

Service and Procedure

mtppy.part4.automation_services.service.Service(tag_name, tag_description='')

Bases: ABC

Abstract Base class implementing the Service specification.

This abstract base class provides the foundational structure for implementing services according to PNO MTP 2.0 Part 4 specifications. It handles state management, procedure execution, and configuration parameter handling through a state machine and thread control system.

It provides functions for all the defined states, such as idle, starting, ..., resetting, a.s.o, that shall be implemented by instantiable derivatives.

Attributes:

Name Type Description
thread_ctrl ThreadControl

Thread control manager for service operations.
configuration_parameters dict[str, ParameterElement]

Dictionary of configuration parameters.
procedures dict[int, Procedure]

Dictionary mapping procedure IDs to Procedure objects.
service_control ServiceControl

Service control instance managing operation modes.
state_machine StateMachine

State machine for service state transitions.
_cycle_time StateMachine

Time interval (in seconds) for cyclic state execution.

Initialize a service instance.

Parameters:

Name Type Description Default
tag_name str

Tag name of the service.

 required
tag_description str

Optional description of the service.

 ''

name property writable

Return the service tag name.

Returns:

Type Description
str

The current service tag name.

_get_procedures()

Return the service's procedure mapping.

Returns:

Type Description
dict[int, Procedure]

A mapping from procedure IDs to procedure objects.

_latch_procedure_if_idle()

Promote the requested procedure to the current procedure while idle.

PNO MTP 2.0 Part 4, Section 8.2.4.4 latches PROCEDURE_REQ into PROCEDURE_CUR on a START command. For an online service sitting in idle, selecting a procedure (writing PROCEDURE_OP) must likewise take effect immediately so that idle re-enters under the newly selected procedure (undefined.idle.exit -> auto.idle.entry).

This runs on the single run task (which owns all state mutation), so mutating service control state here is safe. It is a no-op unless the service is in idle and a valid, different procedure has been requested.

_lookup_procedure_cur_name()

Return the name of the currently selected procedure.

Returns:

Type Description
str

The current procedure name, or "undefined" when no procedure
str

is selected.

_publish_command_en()

Publish the effective CommandEn mask to external readers.

Per the clarified specification, the START bit is only advertised in the published CommandEn when, in idle, a valid non-zero ProcedureReq is present. This masks a local copy for publication only -- it must NOT mutate the persistent internal mask (command_en_ctrl). The internal gate (is_enabled) is therefore independent of this method having run since the last procedure change, which is required because the base Service executes commands immediately on the posted closure, potentially before the run loop has had a chance to re-publish the mask. Procedure validity for START is enforced separately by StateMachine.start, which re-checks PROCEDURE_REQ.

_state_change_handler()

Lightweight state-machine callback (no thread spawning).

The state machine (entry/do/exit) is driven by the single long-lived run task created in :meth:start; this handler only updates derived flags such as whether switching to offline mode is allowed.

add_configuration_parameter(configuration_parameter)

Add a configuration parameter to the service.

Parameters:

Name Type Description Default
configuration_parameter ParameterElement

Parameter to add, keyed by its tag name.

 required

add_procedure(procedure)

Add one or more procedures to the service.

Parameters:

Name Type Description Default
procedure Procedure | list[Procedure | None] | dict[str, Procedure | None] | None

A procedure, a list of procedures, a mapping of names to procedures, or None.

 required

Raises:

Type Description
ValueError

If any procedure has an ID of zero.

apply_configuration_parameters()

Apply all configuration parameters to the service.

Each parameter is updated through its update_v_out method.

apply_procedure_parameters()

Apply parameters for the currently selected procedure.

attach_loop(loop)

Attach the PEA's event loop to this service's run task.

Also binds the service's control-plane DataItem collections (service_control and its operation/source sub-assemblies) to the same loop so that every DataItem write and guarded transition funnels onto the single run task (the single-writer principle, see docs/architecture.md "Single-Writer Principle").

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the PEA.

 required

command_execution(value)

Forward a command to the service state machine on the task thread.

The command is delivered to the service's single run task via the thread-safe :meth:ThreadControl.post bridge, so that all state mutation happens on the run task rather than on a caller's thread.

Parameters:

Name Type Description Default
value int

Command value defined by the service control interface.

 required

get_base_interface(tag_name)

Return the data assembly with tag_name from the current procedure.

Parameters:

Name Type Description Default
tag_name str

Tag name of the data assembly to retrieve.

 required

Returns:

Type Description
DataAssembly

The matching data assembly.

Raises:

Type Description
RuntimeError

If the service has no current procedure.
KeyError

If no data assembly with that tag name is allocated to the current procedure.

get_current_procedure()

Return the currently selected procedure.

Returns:

Type Description
Procedure

The procedure selected by PROCEDURE_CUR.

Raises:

Type Description
RuntimeError

If no current procedure is selected.

idle() abstractmethod async

Execute idle state logic (entry/do*/exit).

is_state(state_str)

Check whether the service is in a specified state.

Parameters:

Name Type Description Default
state_str str

State name to compare with the current state.

 required

Returns:

Type Description
bool

True if the service is in state_str; otherwise, False.

run() async

The single long-lived task driving the service's lifecycle.

Repeatedly executes the state machine's current state (its entry/do*/exit application logic). A state change requested elsewhere only updates the state machine; this loop observes it, lets the current state's exit finish, then moves on to the new state's entry.

While in undefined, the loop checks whether the op-mode is online and activates the service (undefined → idle) if so. This reconciles the case where a service is constructed while already in Aut/Op (no offline→online event fires).

run_on_task(fn)

Run fn on the service's run task, deferring from other threads.

This is the single-writer entry point for any operation that mutates service state and may be invoked from an arbitrary thread (e.g. PEA startup) rather than from the run task itself. When the caller is already on the run task's event loop, fn runs inline (serialized with the run loop); otherwise it is scheduled onto that loop via call_soon_threadsafe (see :meth:ThreadControl.run_or_post).

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates service state.

 required

set_cycle_time(cycle_time)

Set the cycle time for this service.

Parameters:

Name Type Description Default
cycle_time float

Time interval (in seconds) for cyclic state execution.

 required

start()

Start the service's single long-lived run task.

Idempotent: if the task is already running this is a no-op. Uses the attached event loop when available, otherwise falls back to a single daemon thread running a private loop (useful for synchronous tests).

state_change()

Request a state change from a cyclic state to the next one.

stop()

Stop the service's run task.

mtppy.part4.automation_services.procedure.Procedure(procedure_id, tag_name, tag_description='', is_self_completing=False, required_equipment=None)

add_procedure_parameter(procedure_parameter)

Add one or more procedure parameter to the procedure.

Parameters:

Name Type Description Default
procedure_parameter ParameterElement | list[ParameterElement]

ParemeterElement or list of type ParameterElement.

 required

add_process_value_in(process_value_in)

Add one or more InputElements to the procedure.

Parameters:

Name Type Description Default
process_value_in InputElement | list[InputElement]

InputElement or list of InputElements.

 required

add_process_value_out(process_value_out)

Add one or more IndicatorElements to the procedure.

Parameters:

Name Type Description Default
process_value_out IndicatorElement | list[IndicatorElement]

IndicatorElement or list of IndicatorElement.

 required

add_report_value(report_value)

Add one or more IndicatorElements to the procedure as ReportValue.

Parameters:

Name Type Description Default
report_value IndicatorElement | list[IndicatorElement]

IndicatorElement or list of IndicatorElement.

 required

add_required_equipment(equipment)

Add one or more DataAssemblies to the procedure as Required Equipment.

Parameters:

Name Type Description Default
equipment DataAssembly | list[DataAssembly | None] | dict[str, DataAssembly | None] | None

DataAssembly or list of DataAssemblies.

 required

apply_procedure_parameters()

Apply ProcedureParameters.

Interprocess Communication

mtppy.part4.process_values.input_elements.input_element.InputElement(tag_name, tag_description)

Bases: DataAssembly

Base class for input elements in the process value framework.

Input elements provide data input capabilities with integrated quality control through WQC (Write Quality Control) and VQC (Validation Quality Control) functions. They inherit from DataAssembly and serve as the foundation for various input element types in the system.

Attributes:

Name Type Description
wqc WQCBaseFunction

Write Quality Control function instance for managing write operations
vqc VQCBaseFunction

Validation Quality Control function instance for validating data

Initialize an InputElement instance.

Parameters:

Name Type Description Default
tag_name str

The name identifier for the input element

 required
tag_description str

A descriptive text for the input element

 required

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

mtppy.part4.process_values.input_elements.ana_process_value_in.AnaProcessValueIn(tag_name, tag_description, v=0, scl_min_cur=0, scl_max_cur=100, unit_cur=1998, apply_en=False)

Bases: InputElement

Analog Process Value Input (AnaProcessValueIn).

Implements an analog process value input element according to MTP 2.0 specification.

Initialize the AnaProcessValueIn element.

Parameters:

Name Type Description Default
tag_name str

Name of the tag.

 required
tag_description str

Description of the tag.

 required
v float

Initial value for the V data item.

 0
scl_min_cur float

Current scale minimum value.

 0
scl_max_cur float

Current scale maximum value.

 100
unit_cur int

Current unit value.

 1998
apply_en bool

Apply enable flag.

 False

apply()

Apply the external values to current values.

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

set_apply_en(value)

Set the ApplyEn data item value.

Parameters:

Name Type Description Default
value bool

The boolean value to set for the ApplyEn data item.

 required

set_v(value)

Set the V data item value.

Parameters:

Name Type Description Default
value float

The value to set for the V data item.

 required

mtppy.part4.process_values.input_elements.bin_process_value_in.BinProcessValueIn(tag_name, tag_description, v=False, v_state_0='False', v_state_1='True')

Bases: InputElement

Binary Process Value Input (BinProcessValueIn).

Implements a binary process value input element according to MTP 2.0 specification.

Initialize the BinProcessValueIn element.

Parameters:

Name Type Description Default
tag_name str

Name of the tag.

 required
tag_description str

Description of the tag.

 required
v bool

Initial value for the V data item.

 False
v_state_0 str

Value for VState0 data item.

 'False'
v_state_1 str

Value for VState1 data item.

 'True'

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

set_v(value)

Set the V data item value.

Parameters:

Name Type Description Default
value bool

The boolean value to set for the V data item.

 required

mtppy.part4.process_values.input_elements.dint_process_value_in.DIntProcessValueIn(tag_name, tag_description, v=0, scl_min_cur=0, scl_max_cur=100, unit_cur=1998, apply_en=False)

Bases: InputElement

Discrete Integer Process Value Input (DIntProcessValueIn).

Initialize the DIntProcessValueIn element.

Parameters:

Name Type Description Default
tag_name str

Name of the tag.

 required
tag_description str

Description of the tag.

 required
v int

Initial value for the V data item.

 0
scl_min_cur int

Current scale minimum value.

 0
scl_max_cur int

Current scale maximum value.

 100
unit_cur int

Current unit value.

 1998
apply_en bool

Apply enable flag.

 False

apply()

Apply the external values to current values.

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

set_apply_en(value)

Set the ApplyEn data item value.

Parameters:

Name Type Description Default
value bool

The boolean value to set for the ApplyEn data item.

 required

set_scl_max_ext(value)

Set the SclMaxExt data item value.

Parameters:

Name Type Description Default
value int

The value to set for the SclMaxExt data item.

 required

set_scl_min_ext(value)

Set the SclMinExt data item value.

Parameters:

Name Type Description Default
value int

The value to set for the SclMinExt data item.

 required

set_unit_ext(value)

Set the UnitExt data item value.

Parameters:

Name Type Description Default
value int

The value to set for the UnitExt data item.

 required

set_v(value)

Set the V data item value.

Parameters:

Name Type Description Default
value int

The value to set for the V data item.

 required

mtppy.part4.process_values.input_elements.string_process_value_in.StringProcessValueIn(tag_name, tag_description, v='')

Bases: InputElement

attach_loop(loop)

Bind this collection to the run-task event loop of its service.

Once bound, every write made from a foreign thread is scheduled onto that loop so that all mutations happen on the single run task (the single-writer principle). Writes made from the run task itself execute inline. Collections that are never bound keep the legacy synchronous, inline behaviour.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running event loop owned by the service's run task.

 required

attach_wake(wake_fn)

Register the run-task wake callable for this collection.

When a guarded write (e.g. a service op-mode or command change) is scheduled onto the bound loop from a foreign thread, the owning service's run task may be parked in the offline undefined state. Registering its wake callable lets such a write release that wait immediately instead of waiting out the next poll interval.

Parameters:

Name Type Description Default
wake_fn Callable[[], None]

Zero-argument callable that signals the run task to wake.

 required

run_on_loop(fn)

Run fn on the bound loop, deferring from foreign threads.

This is the single-writer primitive. Three cases:

  • No bound loop -> run fn inline (unbound / test / offline).
  • Caller already on the bound loop -> run fn inline (avoids a re-post loop for nested / cascade writes fired inside a posted operation).
  • Caller on a foreign thread -> schedule fn via loop.call_soon_threadsafe so it runs on the run task.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable that mutates this collection.

 required

Definitions

mtppy.part4.definitions.command_codes.CommandCodes(string, code)

Bases: Enum

List of commands defined for MTP services

mtppy.part4.definitions.state_codes.StateCodes(string, code)

Bases: Enum

List of states defined for MTP services.

Store the string label and integer code.

Parameters:

Name Type Description Default
string str

Human-readable state name.

 required
code int

Numeric state code.

 required

from_code(code) classmethod

Look up a state name by its numeric code.

Parameters:

Name Type Description Default
code int

Numeric state code.

 required

Returns:

Type Description
str

The state name string.

Raises:

Type Description
ValueError

If the code does not match any state.

from_string(string) classmethod

Look up a state code by its name.

Parameters:

Name Type Description Default
string str

State name (case-insensitive).

 required

Returns:

Type Description
int

The numeric state code.

Raises:

Type Description
ValueError

If the string does not match any state.

list_of_codes() classmethod

Return all state codes in enum order.

list_of_strings() classmethod

Return all state names in enum order.

Helper

mtppy.part4.automation_services.helpers.command_en_control.CommandEnControl()

Manages the CommandEn bitmask for a service state machine.

The command enable mask is a single integer where each bit represents whether a particular command is currently permitted. The mask is recomputed on every state transition via :meth:execute.

Instantiate Command enable control.

command_en property

Return the legacy dict representation of the current mask.

Each entry has the shape {"default", "value", "bit_no", "int"} matching the pre-refactor format, so existing callers keep working.

disable_all()

Set False to all command enable flags.

enable_pause_loop(value)

Enable or disable the pause loop.

Parameters:

Name Type Description Default
value bool

True if the pause loop shall be enabled.

 required

enable_restart(value)

Enable or disable the restart command.

Parameters:

Name Type Description Default
value bool

True if the restart command shall be enabled.

 required

execute(state)

Compute the command enable mask for the given service state.

Parameters:

Name Type Description Default
state str

State string (e.g. "idle", "execute").

 required

get_command_en()

Return the current command enable bitmask.

Returns:

Type Description
int

Integer bitmask of all enabled command flags.

is_enabled(cmd)

Check if a given command is enabled right now.

Parameters:

Name Type Description Default
cmd str

Command name (e.g. "start").

 required

Returns:

Type Description
bool | None

True / False for a known command, None otherwise.

set_command_en(cmd, value)

Set or clear a specific command enable bit.

Parameters:

Name Type Description Default
cmd str

Command name (e.g. "start").

 required
value bool

True to set the bit, False to clear it.

 required

set_default()

Apply default values to all command enable flags.

mtppy.part4.automation_services.helpers.state_machine.StateMachine(service_control, execution_routine)

Initialize the state machine for a service.

Parameters:

Name Type Description Default
service_control ServiceControl

ServiceControl.

 required
execution_routine Callable

Execution routine for state changing.

 required

mtppy.part4.automation_services.helpers.thread_control.ThreadControl()

Runs a service's single lifecycle task and accepts thread-safe posts.

Attributes:

Name Type Description
running_state

Name of the state currently active on the task.
requested_state

Name of the state most recently requested.

thread property

Backwards-compatible handle to the running executor.

Returns the asyncio.Task (loop backend) or the threading.Thread (fallback backend), or None if none is running.

attach_loop(loop)

Attach the event loop this runner's task will live on.

Must be called before the task is first started so that the long-lived task and the thread-safe wake-up event are created on the correct loop.

Parameters:

Name Type Description Default
loop AbstractEventLoop

The running (or to-be-run) event loop owned by the PEA.

 required

is_stopped()

Return True once the stop signal has been raised.

post(fn)

Schedule a synchronous callback to run on the runner's task thread.

This is the thread-safe bridge: synchronous callers (e.g. an OPC-UA ext_wrt_cb running on the server's callback thread) call this to deliver a command to the service's single task without spawning threads.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable to execute on the service task.

 required

reallocate_running_thread()

Start (or restart) the single long-lived task for the service.

If a loop is attached the task is created on that loop; otherwise a single daemon thread is started. Calling this when the same state is already running is a no-op.

request_state(state, cb_function=None)

Record the state to run (and, if given, the task coroutine).

For the single-task design the coroutine passed is the service's whole run loop; state is retained as the requested state name for introspection and backwards compatibility.

Parameters:

Name Type Description Default
state str

Name of the state to run.

 required
cb_function Callable[[], Coroutine[Any, Any, None]] | None

Optional coroutine function (async backend) or callable.

 None

run_or_post(fn)

Run fn on the run-task loop, deferring from other threads.

Enforces the single-writer principle for callers that may be invoked either on the run task's event loop or from a foreign thread:

  • If called on the loop thread, fn runs inline, immediately and serialized with the run task (no re-entrant scheduling).
  • If called from another thread with a loop attached, fn is scheduled onto the loop thread via call_soon_threadsafe.
  • If no loop is attached, fn runs inline (synchronous fallback, mirroring :meth:post).

Unlike :meth:post (which always defers when a loop is present), this lets an already-on-loop caller (e.g. a test driver coroutine) apply a sequence of state changes inline without a spurious deferral hop.

Parameters:

Name Type Description Default
fn Callable[[], None]

Zero-argument callable to execute on the service task thread.

 required

sleep_until_wake(fallback=0.0) async

Suspend the run task until woken, or a short fallback interval.

While a service sits offline (undefined) there is nothing for its run task to do, so instead of burning a cycle_time sleep per poll the task blocks here and is released exactly when a control-plane write is posted (see :meth:wake). A stop (see :meth:stop) also wakes the task; the run loop then continues, re-reads is_stopped() and exits. With no attached loop (synchronous test harness) it degrades to a short asyncio.sleep(fallback) so callers keep the previous polling cadence.

Parameters:

Name Type Description Default
fallback float

Seconds to sleep when no wake event is available.

 0.0

stop()

Signal the running task to stop (and cancel it if it is a task).

Also wakes a run task parked in the offline undefined state so it exits promptly on its own is_stopped() check, rather than only when the event loop later processes the task cancellation.

wake()

Signal that the run task should stop sleeping and re-check state.

Breaks the run task out of its indefinite wait while the service is offline (undefined) so that a control-plane write (a mode change or command) is acted on promptly rather than after the next poll interval. Safe to call from any thread: when off the loop thread the signal is delivered via call_soon_threadsafe.