lsst.ts.salobj¶
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
andConfigurableCsc
are subclasses ofController
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 callBaseCsc.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 ofController
. See Writing a Controller for more information. Note that it is important to close theController
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 oneRemote
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 oneDomain
per process or unit test method, if practical, though some unit tests create a few more.Controller
creates and manages aDomain
, but if you have no controller and wish to construct one or moreRemote
s then you will have to create and manage aDomain
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 Remote
s 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¶
|
Convert an int (or SalRetCode) to a SalRetCode. |
|
Convert an int (or State) to a State. |
|
Assert that code raises a salobj.AckError |
|
Assert that code raises a salobj.AckTimeoutError |
Command the CSC Commander from the command line. |
|
|
Get the version of OpenSplice dds library. |
|
Return all summary states expected when transitioning from one state to another. |
Get the version of OpenSplice as a string. |
|
Get the username and host as user@host |
|
|
Hierarchically update one dict with values from another. |
|
Make a struct of mock write topics for unit testing data clients. |
Make a dict of state transition commands and states |
|
|
Parse a SAL component name of the form name[:index]. |
|
Parse the SAL-generated IDL file. |
Run the Test CSC from the command line. |
|
Set a random value for environment variable LSST_DDS_PARTITION_PREFIX |
|
|
Put a CSC into the specified summary state. |
|
Await lines of text from stdin or another text input stream. |
Classes¶
|
AckCmd topic data type, for type annotations. |
|
Exception raised if a command fails. |
|
Exception raised if waiting for a command acknowledgement times out. |
|
Asynchronous interface to an Amazon Web Services s3 bucket. |
Base class for testing configuration files. |
|
|
Base class for a Commandable SAL Component (CSC) |
Base class for CSC tests. |
|
alias of |
|
|
Base DDS sample data type, for type annotations. |
|
Abstract base class for SAL Scripts. |
|
Base class for a configurable Commandable SAL Component (CSC) |
|
A class that receives commands for a SAL component and sends telemetry and events from that component. |
|
Command a CSC from the command line. |
|
A wrapper for jsonschema validators that applies default values. |
|
dds domain participant and quality of service information. |
Report an error that does not benefit from a traceback. |
|
|
Information about a field. |
|
Information about SAL topics in an IDL file. |
|
QoS profiles for topic, reader and writer. |
|
A class that issues commands to a SAL component and receives telemetry and events from that component. |
|
DDS information for one SAL component and its DDS partition |
|
Log handler that outputs an event topic. |
|
SAL return codes. |
|
CSC summaryState constants. |
|
A simple CSC intended for unit testing. |
|
Control a Test CSC from the command line. |
|
Test script to allow testing BaseScript. |
|
Metadata about a topic. |
|
Custom exception to signify that the index is a wildcard ('*'). |
Class Inheritance Diagram¶
lsst.ts.salobj.topics Package¶
Classes¶
|
ackcmd (command acknowledgement) topic reader. |
|
ackcmd (command acknowledgement) topic writer. |
|
Base class for topics. |
|
Struct to hold information about a command. |
|
Read a specified command topic. |
|
Write a specific event topic. |
|
Write a specific telemetry topic. |
|
A version of WriteTopic that records every message written instead of actually writing it. |
|
Log warnings for a fixed-length queue that should contain no more than one item. |
|
Base class for reading a topic. |
|
Issue a specific command topic and wait for acknowldgement. |
|
Read a specific event topic. |
|
Read a specific telemetry topic. |
|
Result from set_write. |
|
Base class for topics that are written. |