lsst.ts.salobj

Object-oriented Python interface to Service Abstraction Layer (SAL) components that uses asyncio for asynchronous communication. ts_salobj SAL communication uses Kafka.

Using lsst.ts.salobj

• Configuring ts_salobj
  • Environment Variables
• Installation
  • Install ts_salobj
  • Run a Local Kafka Server
  • Additional Configuration
• salobj CSCs
  • Writing a CSC
  • Basic Development
  • CSC Details
  • Indexed CSCs
  • Configurable CSC Details
  • Standard State Transition Commands
  • Unit Testing your CSC
  • Externally Commandable CSCs
  • Running a CSC
  • Simulation Mode
  • External Connections
  • Telemetry Loop Example
• SAL Scripts
• Script Packages
• Python SAL Scripts
  • Python Script File
  • Python Script Implementation
  • Python Unit Test

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 origin (for the private_origin field of topics), default identity and weak links to all SalInfo objects that use the domain. 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.

Fine Tunning the Read Loop

It is possible to fine tune the read loop by a combination of two arguments in the Remote class; num_messages and consume_messages_timeout. By default these parameters are set to work for the majority of use cases, e.g.; normal CSC and SAL Script operations. However, in some applications, it might be necessary to tune the read loop to improve handling of high throughput topics.

If dealing with a high volume of data one might want to increase num_messages and reduce consume_messages_timeout. This allows the read loop to batch process a higher number of messages at each loop. However, when increasing the number of messages processed at every loop, this might increase the read latency as the loop only processes the messages if it received the number of messages requested or consume_messages_timeout has passed. When trying to optimize the read loop it is import to test a combination of values for these parameters.

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. You may also close Remotes directly, if you like, and if you close all Remotes then there is no need to also close the Domain.

Controller, Domain, and Remote can all 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_expected_summary_states(initial_state, ...)	Return all summary states expected when transitioning from one state to another.
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].
run_test_csc()	Run the Test CSC from the command line.
set_random_lsst_dds_partition_prefix()	A deprecated synonym for set_test_topic_subname.
set_summary_state(remote, state[, override, ...])	Put a CSC into the specified summary state.
set_test_topic_subname([randomize])	Set a test value for environment variable LSST_TOPIC_SUBNAME
stream_as_generator(stream[, exit_str])	Await lines of text from stdin or another text input stream.

Classes

AckCmdDataType([private_sndStamp, ...])	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_sndStamp, ...])	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()	Information common to all SalInfo instances.
ExpectedError	Report an error that does not benefit from a traceback.
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, ...])	Information for one SAL component and index.
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.
WildcardIndexError(name)	Custom exception to signify that the index is a wildcard ('*').

Class Inheritance Diagram

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

Version History

• Version History