ska_oso_scripting.api

The ska_oso_scripting.api module provides the unified scripting interface for SKA telescope control.

This module re-exports functional API symbols from the devicecontrol, environment, messages, and sb submodules, providing a single entry point for the functional API.

Functional API: Import functions from ska_oso_scripting.api

• Device control functions (allocate, configure, scan, etc.)

• Environment helpers (get_telescope_state, wait_for_observation_state)

• Message builders (build*, make* functions)

• SBD helpers (prepare_sbd)

• Execution block helpers (create_eb, capture_request_response, mark_execution_block_observed, mark_execution_block_failed)

Objects API: Import classes from ska_oso_scripting.api.objects

• SubArray class for object-oriented subarray control

• Telescope class for object-oriented telescope control

exception ska_oso_scripting.api.ExecutionEnvironmentError(expected_env, msg='Telescope environment required by script does not match deployment')

Error raised when execution environment does not match the targeted telescope.

ska_oso_scripting.api.abort(subarray_id: int)

Send the ‘abort’ command to the SubArrayNode, halt the subarray activity.

Parameters:

subarray_id – the subarray to command

Returns:

ska_oso_scripting.api.assign_resources_from_cdm(subarray_id: int, request: ska_tmc_cdm.messages.central_node.assign_resources.AssignResourcesRequest, timeout: float = None)

Allocate resources to a sub-array using a CDM object.

Parameters:

• subarray_id – the id of the sub-array to allocate the resources

• request – the CDM AssignResourcesRequest object

• timeout – custom timeout provided while execution of assign resource command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.assign_resources_from_file(subarray_id: int, request_path: str, with_processing: bool = True, timeout: float = None)

Allocate resources to a sub-array using a JSON file.

Parameters:

• subarray_id – the ID of the sub-array to control

• request_path – JSON file path

• with_processing – False if JSON should be passed through to CentralNode directly without any validation or processing

• timeout – custom timeout provided while execution of assign resource command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.assign_resources_from_json(subarray_id: int, request: str, with_processing: bool = True, timeout: float = None)

Allocate resources to a sub-array using a JSON string representation of AssignResources request. Validity of given JSON string will be checked by default unless with_processing is explicitly set to False. In this case the string will be passed directly to central node without any processing.

This function will block until the sub-array with the given ID has been allocated the resources and has transitioned to obsState IDLE.

Parameters:

• subarray_id – the id of the sub-array to allocate the resources

• request – the JSON string to AssignResources with

• with_processing – False if JSON should be passed through to CentralNode directly without any validation or processing

• timeout – custom timeout provided while execution of assign resource command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.check_environment_for_consistency(request_json: str) → None

Confirm that the request is correct for the current environment, raising an ExecutionEnvironmentError if there is a mismatch.

Parameters:

request_json – The JSON control string to be tested

ska_oso_scripting.api.configure_from_cdm(subarray_id: int, request: ska_tmc_cdm.messages.subarray_node.configure.ConfigureRequest, timeout: float = None)

Configure a sub-array using the supplied CDM configuration.

This method does not make any changes to the configuration. It is the responsibility of the caller to ensure that all IDs, etc. are consistent.

Parameters:

• subarray_id – the ID of the sub-array to configure

• request – the CDM configuration to set custom timeout provided while execution of assign resource command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.configure_from_file(subarray_id: int, request_path: str, with_processing: bool = True, timeout: float = None)

Load a CDM ConfigureRequest from disk and use it to perform sub-array configuration.

This function blocks until the sub-array is configured and has an obsState of READY.

JSON processing is disabled when with_processing is set to False.

Parameters:

• subarray_id – the ID of the sub-array to configure

• request_path – path to CDM file

• with_processing – False if JSON should be passed through to SubArrayNode directly without any validation or processing

• timeout – custom timeout provided while execution of scan command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.configure_from_json(subarray_id: int, request: str, with_processing: bool = True, timeout: float = None)

Configure a sub-array using a JSON string representation of a ConfigureRequest.

This method does not make any changes to the configuration. It is the responsibility of the caller to ensure that all IDs, etc. are consistent.

Parameters:

• subarray_id – the ID of the sub-array to configure

• request – the JSON string of Configuration to set

• with_processing – False if JSON should be passed through to SubArrayNode directly without any validation or processing

• timeout – custom timeout provided while execution of configure command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.configure_subarray_quality_monitor(subarray_id: int, sbd: ska_oso_pdm.SBDefinition)

Configure the TMC Subarray Quality Monitor for readyToScan evaluation.

ska_oso_scripting.api.create_sbi(sbd: ska_oso_pdm.sb_definition.SBDefinition) → ska_oso_pdm.sb_definition.SBDefinition

Create a Scheduling Block Instance from a Scheduling Block Definition.

Currently, an SBI is a snapshot of an SBD but with EB and PB IDs replaced.

ska_oso_scripting.api.end(subarray_id: int)

Send the ‘end’ command to the SubArrayNode, marking the end of the current observation.

Parameters:

subarray_id – the subarray to command

Returns:

ska_oso_scripting.api.init_qa_wait(initial_state: bool) → None

Initialise ADR-111 QA readiness waiting state and subscribe persistent handlers for operator enable/disable messages.

Parameters:

initial_state – initial enabled/disabled state for QA waiting

ska_oso_scripting.api.is_ska_low_environment() → bool

Return True if execution environment is identified as SKA LOW.

Returns:

True if SKA LOW

ska_oso_scripting.api.is_ska_mid_environment() → bool

Return True if execution environment is identified as SKA MID

Returns:

True if SKA MID

ska_oso_scripting.api.load_sbd(path: str | PathLike) → ska_oso_pdm.sb_definition.SBDefinition

Load an SBDefinition from a JSON file on disk.

Parameters:

path – path to SBD.

Returns:

SBDefinition object

ska_oso_scripting.api.obsreset(subarray_id: int)

Send the ‘ObsReset’ command to the SubArrayNode, which resets the SubArrayNode state to IDLE.

Parameters:

subarray_id – the subarray to command

Returns:

ska_oso_scripting.api.publish_event_message(topic=<class 'ska_oso_scripting.topics.user_topics.script.announce'>, **kwargs)

publish pypubsub event messages, OET scripts will be using this method to publish a freeform messages to an unknown listener.

Parameters:

• topic – message topic

• kwargs – any metadata associated with pypubsub message

ska_oso_scripting.api.release_all_resources(subarray_id: int, timeout: float = None)

Release resources on the sub-array with the given ID. If release_all is set to False, ReleaseResourcesRequest CDM object specified in request parameter will be sent to the sub-array. If release_all is set to True, the request will not be used.

This function blocks until resources have been released on the given sub-array and its obsState has transitioned to EMPTY.

Parameters:

• subarray_id – the sub-array to control

• timeout – custom timeout provided while execution of release resorce command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.release_resources(subarray_id: int, request: ska_tmc_cdm.messages.central_node.release_resources.ReleaseResourcesRequest, timeout: float = None)

Release resources on the sub-array with the given ID. If release_all is set to False, ReleaseResourcesRequest CDM object specified in request parameter will be sent to the sub-array. If release_all is set to True, the request will not be used.

This function blocks until resources have been released on the given sub-array and its obsState has transitioned to EMPTY.

Parameters:

• subarray_id – the sub-array to control

• request – CDM ReleaseResourcesRequest object specifying resources to release. Only required if release_all is False

• timeout – custom timeout provided while execution of release resource command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

ska_oso_scripting.api.restart(subarray_id: int)

Send the ‘restart’ command to the SubArrayNode which sets the SubArrayNode from ABORTED or FAULT state to EMPTY.

Parameters:

subarray_id – the subarray to command

Returns:

ska_oso_scripting.api.save_sbi(sbi: ska_oso_pdm.sb_definition.SBDefinition, path: str)

Save an SBI to disk. Saves an SBI (really, an SBD but with fixed IDs) the specified path. :param sbi: SBI to serialise :param path: output file to write

ska_oso_scripting.api.scan(subarray_id: int, timeout: float = None)

Execute a scan.

Parameters:

• subarray_id – the sub-array to control

• timeout – custom timeout provided while execution of scan command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

Returns:

the response from sending the command to configure sub-array

ska_oso_scripting.api.send_message(topic, **kwargs)

Helper function to send messages via pypubsub.

Parameters:

• topic – topic matching a topic in ska_oso_scripting.topics

• kwargs – kwargs to be included in message

ska_oso_scripting.api.telescope_off(final_state: tango.DevState = tango.DevState.STANDBY)

Instruct telescope devices to switch to STANDBY mode.

If expect_standby is True (default) then this function will wait for the telescope to reach STANDBY state. Otherwise, this function will wait for the OFF state to be reached.

Background: At the time of writing (PI15), CentralNode has new behaviour where it reports the aggregated state of the systems it controls. Hence. it is not yet clear which state CentralNode will reach when commanded to turn the telescope off, as this state could change dependning on what subsystems are connected to TMC. For instance, if CSP reports STANDBY, CentralNode will report STANDBY. If CSP was not present, CentralNode might report OFF.

Parameters:

final_state – Final Tango state to expect (default=STANDBY)

Returns:

ska_oso_scripting.api.telescope_on()

Start up the telescope.

This command powers up Dishes that are currently in standby.

Returns:

ska_oso_scripting.api.objects

The ska_oso_objects module holds the object-oriented scripting interface for SKA telescope and subarray control.

class ska_oso_scripting.api.objects.SubArray(identifier: int | str)

SubArray represents an SKA telescope subarray.

SubArrays are identified by a numeric ID, which is an integer between 1 and 16. This ID, accessible as SubArray.id, corresponds to the TMC SubArrayNode of the same ID that is controlled by invoking methods on a SubArray instance. SubArray objects with the same numeric ID are considered equal.

SubArrays are used to:

• allocate resources to a subarray

• configure a subarray

• instruct a subarray to commence scanning

• end an SB

• release subarray resources

assign_from_file(path: str, with_processing: bool = True, timeout: float | None = None) → None

Allocate resources to a subarray using a JSON file.

This method reads in a file, verifies that the file contents are a valid CDM resource allocation string, before using that JSON as the basis of a resource allocation control sequence. This method returns once the targeted subarray indicates that resources have been allocated or an error occurs.

Note that some JSON content will be replaced (Execution Block IDs, etc.) as required by the telescope control model, so what is sent to the telescope control system may not exactly match the contents of the file. To disable this JSON processing and send the raw contents of the file to the system, set with_processing to False. Note that you will be responsible for ensuring JSON correctness, Execution Block ID uniqueness, etc.

Parameters:

• path – path to the CDM JSON file

• with_processing – perform JSON validation and processing (default=True)

• timeout – custom timeout provided while execution of assign resource command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

assign_from_cdm(request: ska_tmc_cdm.messages.central_node.assign_resources.AssignResourcesRequest, timeout: float | None = None) → None

Allocate resources to this subarray using a CDM AssignResourcesRequest object.

Given a well-formed CDM AssignResourcesRequest object, this method will perform a resource allocation control sequence, returning once the targeted subarray indicates that resources have been allocated.

Parameters:

• request – CDM resource allocation request

• timeout – custom timeout provided while execution of assign resource command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

release(request: ska_tmc_cdm.messages.central_node.release_resources.ReleaseResourcesRequest | None = None, timeout: float | None = None) → None

Release subarray resources.

This method blocks until the subarray has released resources or an error occurs.

By default, all subarray resources will be released. To release some but not all of the subarray resources (partial release), give this method a CDM ReleaseResourcesRequest instance defining which resources should be deallocated.

Parameters:

• request – optional CDM request object for partial deallocation

• timeout – custom timeout provided while execution of release resource command’s if systems do not respond within reasonable timescales then method raised EventTimeoutError.

configure_from_cdm(request: ska_tmc_cdm.messages.subarray_node.configure.ConfigureRequest, timeout: float | None = None) → None

Configure subarray resources using a CDM ConfigureRequest object.

This method blocks when the subarray has completed resource configuration or when an error occurs.

Parameters:

• request – CDM configure request instance

• timeout – custom timeout provided while execution of configure command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

configure_from_file(cdm_file: str, with_processing=True, timeout: float | None = None) → None

Configure subarray resources using a JSON file.

This method reads in a file, verifies that the file contents are a valid CDM configuration JSON, before using that JSON as the basis of a subarray configuration control sequence. This method returns once the targeted subarray indicates that resources have been configured or an error occurs.

This method validates and processes the JSON before sending it downstream. To bypass JSON processing and validation, set the with_processing argument to False.

Parameters:

• cdm_file – path of the exported CDM

• with_processing – perform JSON validation and processing (default=True)

• timeout – custom timeout provided while execution of configure command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

scan(timeout: float | None = None) → None

Start a scan.

This method returns once the scan is complete or an error occurs.

The subarray should have resources allocated and configured before this command is called.

Parameters:

timeout – custom timeout provided while execution of scan command if systems do not respond within reasonable timescales then method raised EventTimeoutError.

end() → None

End Scheduling Block, marking the end of the active observing sequence.

This method returns once the underlying subarray becomes idle or if an error occurs.

abort() → None

Abort subarray activity.

This method returns once the underlying subarray state indicates that all activity has stopped or an error occurs.

reset() → None

Reset the subarray.

Reset the SubArray from ABORTED or FAULT state to IDLE.

restart() → None

Reset the SubArray from ABORTED or FAULT state to EMPTY.

class ska_oso_scripting.api.objects.Telescope

Telescope represents an SKA telescope.

Telescope methods will control the SKA telescope appropriate to the environment. That is, calling Telescope.on() inside an SKA MID environment will control the SKA MID devices, while calling the method inside an SKA LOW environment will control SKA LOW devices.

static on() → None

Power up all telescope devices.

static off(final_state: tango.DevState = tango.DevState.OFF) → None

Power down the telescope, setting all devices to off.

Parameters:

final_state – Final Tango state to expect (default=OFF)