lsst.ts.salobj

https://img.shields.io/badge/GitHub-gray.svg https://img.shields.io/badge/Jira-gray.svg

Object-oriented Python interface to Service Abstraction Layer (SAL) components that uses asyncio for asynchronous communication. ts_salobj SAL communication uses the dds Python library, which is part of Vortex OpenSplice. You may use the free community edition or the licensed edition of OpenSplice.

Using lsst.ts.salobj

Important Classes

  • BaseCsc and ConfigurableCsc are subclasses of Controller that supports the standard CSC summary states and state transition commands. The latter also supports configuration via yaml files that are validated against a schema. See Writing a CSC for more information. It is important to call BaseCsc.close when done with the CSC; BaseCsc.amain does this automatically, but in other cases see Cleanup for more information.

  • Controller provides the capability to output SAL telemetry and event topics and receive SAL commands. Every Python SAL component that is not a Commandable SAL Component (CSC) should be a subclass of Controller. See Writing a Controller for more information. Note that it is important to close the Controller when you are finished. See Cleanup for more information.

  • Remote supports listening to other SAL components; it can receive events and telemetry and issue commands. If your SAL component needs to do this then it should create one Remote for each SAL component it wants to interact with. See the example above.

  • Domain contains the dds domain participant (which includes a cache of topic data) and quality of service objects for the various categories. There should be only one Domain per process or unit test method, if practical, though some unit tests create a few more. Controller creates and manages a Domain, but if you have no controller and wish to construct one or more Remotes then you will have to create and manage a Domain yourself. See Cleanup for more information.

  • BaseScript is a base class for Python SAL Scripts.

  • AsyncS3Bucket is a class for asynchronously uploading and downloading files to/from s3 buckets.

Examples:

  • TestCsc is an example of a fairly simple SAL CSC, though it is slightly unusual because it is intended for use in unit tests. In particular, it does not output telemetry at regular intervals.

  • TestScript is an example of a trivial Python SAL Script.

Cleanup

It is important to call Controller.close or Domain.close when done with any controller or domain you construct, unless your process is exiting. Note that closing a Domain automatically cleans up the resources used by all Remotes constructed using that domain.

Both Controller and Domain can be used as asynchronous context managers to call close automatically. For example:

# If you have a controller or CSC:
async with TestCsc(index=1) as csc:
    dome = Remote(domain=csc.domain, name="Test", index=0)

# If you don't have a controller or CSC:
async with Domain() as domain:
    dome = Remote(domain=domain, name="Test", index=1)

Contributing

lsst.ts.salobj is developed at https://github.com/lsst-ts/ts_salobj. You can find Jira issues for this module using project=DM and labels=ts_salobj.

Python API reference

lsst.ts.salobj Package

Functions

as_salRetCode(value)

Convert an int (or SalRetCode) to a SalRetCode.

as_state(value)

Convert an int (or State) to a State.

assertRaisesAckError([ack, error, ...])

Assert that code raises a salobj.AckError

assertRaisesAckTimeoutError([ack, error])

Assert that code raises a salobj.AckTimeoutError

command_test_csc()

Command the CSC Commander from the command line.

get_dds_version([dds_file])

Get the version of OpenSplice dds library.

get_expected_summary_states(initial_state, ...)

Return all summary states expected when transitioning from one state to another.

get_opensplice_version()

Get the version of OpenSplice as a string.

get_user_host()

Get the username and host as user@host

hierarchical_update(main, override, ...[, ...])

Hierarchically update one dict with values from another.

make_mock_write_topics(name, attr_names[, index])

Make a struct of mock write topics for unit testing data clients.

make_state_transition_dict()

Make a dict of state transition commands and states

name_to_name_index(name)

Parse a SAL component name of the form name[:index].

parse_idl(name, idl_path)

Parse the SAL-generated IDL file.

run_test_csc()

Run the Test CSC from the command line.

set_random_lsst_dds_partition_prefix()

Set a random value for environment variable LSST_DDS_PARTITION_PREFIX

set_summary_state(remote, state[, override, ...])

Put a CSC into the specified summary state.

stream_as_generator(stream[, exit_str])

Await lines of text from stdin or another text input stream.

Classes

AckCmdDataType([private_revCode, ...])

AckCmd topic data type, for type annotations.

AckError(msg, ackcmd)

Exception raised if a command fails.

AckTimeoutError(msg, ackcmd)

Exception raised if waiting for a command acknowledgement times out.

AsyncS3Bucket(name, *[, create, profile, domock])

Asynchronous interface to an Amazon Web Services s3 bucket.

BaseConfigTestCase()

Base class for testing configuration files.

BaseCsc(name[, index, check_if_duplicate, ...])

Base class for a Commandable SAL Component (CSC)

BaseCscTestCase()

Base class for CSC tests.

BaseDdsDataType

alias of BaseMsgType

BaseMsgType([private_revCode, ...])

Base DDS sample data type, for type annotations.

BaseScript(index, descr[, help])

Abstract base class for SAL Scripts.

ConfigurableCsc(name, index, config_schema)

Base class for a configurable Commandable SAL Component (CSC)

Controller(name[, index, do_callbacks, ...])

A class that receives commands for a SAL component and sends telemetry and events from that component.

CscCommander(name[, index, enable, exclude, ...])

Command a CSC from the command line.

DefaultingValidator(schema, typing.Any], ...)

A wrapper for jsonschema validators that applies default values.

Domain()

dds domain participant and quality of service information.

ExpectedError

Report an error that does not benefit from a traceback.

FieldMetadata(name, description, units, ...)

Information about a field.

IdlMetadata(name, idl_path, sal_version, ...)

Information about SAL topics in an IDL file.

QosSet(qos_path, profile_name)

QoS profiles for topic, reader and writer.

Remote(domain, name[, index, readonly, ...])

A class that issues commands to a SAL component and receives telemetry and events from that component.

SalInfo(domain, name[, index, write_only])

DDS information for one SAL component and its DDS partition

SalLogHandler(controller)

Log handler that outputs an event topic.

SalRetCode(value[, names, module, qualname, ...])

SAL return codes.

State(value[, names, module, qualname, ...])

CSC summaryState constants.

TestCsc(index[, config_dir, ...])

A simple CSC intended for unit testing.

TestCscCommander(index[, enable])

Control a Test CSC from the command line.

TestScript(index[, descr])

Test script to allow testing BaseScript.

TopicMetadata(sal_name, version_hash, ...)

Metadata about a topic.

Class Inheritance Diagram

Inheritance diagram of lsst.ts.salobj.type_hints.AckCmdDataType, lsst.ts.salobj.base.AckError, lsst.ts.salobj.base.AckTimeoutError, lsst.ts.salobj.async_s3_bucket.AsyncS3Bucket, lsst.ts.salobj.base_config_test_case.BaseConfigTestCase, lsst.ts.salobj.base_csc.BaseCsc, lsst.ts.salobj.base_csc_test_case.BaseCscTestCase, lsst.ts.salobj.type_hints.BaseMsgType, lsst.ts.salobj.type_hints.BaseMsgType, lsst.ts.salobj.base_script.BaseScript, lsst.ts.salobj.configurable_csc.ConfigurableCsc, lsst.ts.salobj.controller.Controller, lsst.ts.salobj.csc_commander.CscCommander, lsst.ts.salobj.validator.DefaultingValidator, lsst.ts.salobj.domain.Domain, lsst.ts.salobj.base.ExpectedError, lsst.ts.salobj.idl_metadata.FieldMetadata, lsst.ts.salobj.idl_metadata.IdlMetadata, lsst.ts.salobj.domain.QosSet, lsst.ts.salobj.remote.Remote, lsst.ts.salobj.sal_info.SalInfo, lsst.ts.salobj.sal_log_handler.SalLogHandler, lsst.ts.salobj.sal_enums.SalRetCode, lsst.ts.salobj.sal_enums.State, lsst.ts.salobj.testcsc.TestCsc, lsst.ts.salobj.testcsccommander.TestCscCommander, lsst.ts.salobj.testscript.TestScript, lsst.ts.salobj.idl_metadata.TopicMetadata

lsst.ts.salobj.topics Package

Classes

AckCmdReader(salinfo[, queue_len])

ackcmd (command acknowledgement) topic reader.

AckCmdWriter(salinfo)

ackcmd (command acknowledgement) topic writer.

BaseTopic(*, salinfo, attr_name)

Base class for topics.

CommandInfo(remote_command, seq_num, wait_done)

Struct to hold information about a command.

ControllerCommand(salinfo, name[, queue_len])

Read a specified command topic.

ControllerEvent(salinfo, name)

Write a specific event topic.

ControllerTelemetry(salinfo, name)

Write a specific telemetry topic.

MockWriteTopic(*, salinfo, attr_name[, ...])

A version of WriteTopic that records every message written instead of actually writing it.

QueueCapacityChecker(descr, log, queue_len)

Log warnings for a fixed-length queue that should contain no more than one item.

ReadTopic(*, salinfo, attr_name, max_history)

Base class for reading a topic.

RemoteCommand(salinfo, name)

Issue a specific command topic and wait for acknowldgement.

RemoteEvent(salinfo, name[, max_history, ...])

Read a specific event topic.

RemoteTelemetry(salinfo, name[, queue_len])

Read a specific telemetry topic.

SetWriteResult(did_change, was_written, data)

Result from set_write.

WriteTopic(*, salinfo, attr_name[, ...])

Base class for topics that are written.

Class Inheritance Diagram

Inheritance diagram of lsst.ts.salobj.topics.remote_command.AckCmdReader, lsst.ts.salobj.topics.controller_command.AckCmdWriter, lsst.ts.salobj.topics.base_topic.BaseTopic, lsst.ts.salobj.topics.remote_command.CommandInfo, lsst.ts.salobj.topics.controller_command.ControllerCommand, lsst.ts.salobj.topics.controller_event.ControllerEvent, lsst.ts.salobj.topics.controller_telemetry.ControllerTelemetry, lsst.ts.salobj.topics.mock_write_topic.MockWriteTopic, lsst.ts.salobj.topics.read_topic.QueueCapacityChecker, lsst.ts.salobj.topics.read_topic.ReadTopic, lsst.ts.salobj.topics.remote_command.RemoteCommand, lsst.ts.salobj.topics.remote_event.RemoteEvent, lsst.ts.salobj.topics.remote_telemetry.RemoteTelemetry, lsst.ts.salobj.topics.write_topic.SetWriteResult, lsst.ts.salobj.topics.write_topic.WriteTopic

Version History