BaseCsc

class lsst.ts.hexrotcomm.BaseCsc(*, name, index, CommandCode, ConfigClass, TelemetryClass, config_schema=None, config_dir=None, initial_state=State.STANDBY, override='', simulation_mode=0, extra_commands={})

Bases: ConfigurableCsc

Base CSC for talking to Moog hexpod or rotator controllers.

Parameters:

• name (str) – Name of SAL component.

• index (int or None (optional)) – SAL component index, or 0 or None if the component is not indexed. A value is required if the component is indexed.

• CommandCode (enum) – Command codes supported by the low-level controller. Must include SET_STATE and ENABLE_DRIVES, the two command codes used by this class.

• ConfigClass (ctypes.Structure) – Configuration structure.

• TelemetryClass (ctypes.Structure) – Telemetry structure.

• config_schema (dict or None, optional) – Configuration schema, as a dict in jsonschema format.

• config_dir (str, optional) – Directory of configuration files, or None for the standard configuration directory (obtained from _get_default_config_dir). This is provided for unit testing.

• initial_state (lsst.ts.salobj.State or int (optional)) – The initial state of the CSC.

• override (str, optional) – Configuration override file to apply if initial_state is State.DISABLED or State.ENABLED.

• simulation_mode (int (optional)) –

  Simulation mode. Allowed values:

  • 0: regular operation.

  • 1: simulation: use a mock low level controller.

• extra_commands (set [str]) – List of commands that can be defined in the CSC but be missing from the interface.

Notes

Error Codes

• ErrorCode.CONTROLLER_FAULT: The low-level controller went to fault state.

• ErrorCode.CONNECTION_LOST: Lost connection to the low-level controller.

Subclasses may add additional error codes.

Configuration

The configuration for subclasses must include the following fields, or, for host and port, the subclass may override the host and port properties (needed for MTHexapod):

• host (string):

  TCP/IP host address of low-level controller.

• port (integer):

  TCP/IP port of low-level controller.

• connection_timeout (number):

  Time limit for connection to the low-level controller

Both host and port are ignored in simulation mode; the host is lsst.ts.tcpip.LOCALHOST_IPV4 and the ports are automatically assigned.

Attributes Summary

connected
host	Get the TCP/IP address of the low-level controller.
port	Get the port of the low-level controller.

Methods Summary

assert_commandable()	Assert that CSC is connected to the low-level controller and can command it.
assert_connected()	Assert that the CSC is connected to the low-level controller.
assert_enabled()	Assert that the CSC is enabled.
assert_enabled_substate(substate)	Assert that the CSC is enabled and that the low-level controller is in the specified enabled substate.
assert_summary_state(state[, isbefore])	Assert that the current summary state is as specified.
basic_run_command(command)	Acquire the write_lock and run the command.
basic_telemetry_callback(client)	Called when the TCP/IP controller outputs telemetry.
begin_disable(data)	Begin do_disable; called before state changes.
begin_enable(data)	Begin do_enable; called before state changes.
begin_standby(data)	Begin do_standby; called before the state changes.
close_tasks()	Shut down pending tasks.
config_callback(client)	Called when the TCP/IP controller outputs configuration.
configure(config)	Configure the CSC.
connect()	Connect to the low-level controller.
connect_callback(client)	Called when the client socket connects or disconnects.
disconnect()	Disconnect from the low-level controller.
enable_controller()	Enable the low-level controller.
get_config_pkg()	Get the name of the configuration package, e.g. "ts_config_ocs".
handle_summary_state()	Called when the summary state has changed.
make_command(code[, param1, param2, param3, ...])	Make a command from the command identifier and keyword arguments.
make_mock_controller()	Construct and return a mock controller.
run_command(code[, param1, param2, param3, ...])	Run one command.
run_multiple_commands(*commands[, delay])	Run multiple commands, without allowing other commands to run between them.
standby_controller()	Standby the low-level controller.
telemetry_callback(client)	Called when the TCP/IP controller outputs telemetry.
wait_controller_state(state[, max_telem])	Wait for the controller state to be as specified.

Attributes Documentation

connected

host

Get the TCP/IP address of the low-level controller.

The default implementation returns self.config.host. This is not sufficient for the hexapods, which have a different host for each of the two hexapods.

port

Get the port of the low-level controller.

The default implementation returns self.config.port. This is not sufficient for the hexapods, which have a different port for each of the two hexapods.

Methods Documentation

assert_commandable()

Assert that CSC is connected to the low-level controller and can command it.

Return type:

None

assert_connected()

Assert that the CSC is connected to the low-level controller.

Raises:

lsst.ts.salobj.ExpectedError – If one or both streams is disconnected.

Return type:

None

assert_enabled()

Assert that the CSC is enabled.

First check that CSC can command the low-level controller.

Return type:

None

assert_enabled_substate(substate)

Assert that the CSC is enabled and that the low-level controller is in the specified enabled substate.

First check that CSC can command the low-level controller.

Parameters:

substate (EnabledSubstate) – Substate of low-level controller.

Return type:

None

assert_summary_state(state, isbefore=None)

Assert that the current summary state is as specified.

First check that CSC can command the low-level controller.

Used in do_xxx methods to check that a command is allowed.

Parameters:

• state (lsst.ts.salobj.State) – Expected summary state.

• isbefore (bool, optional) – Deprecated. The only allowed values are False (which raises a deprecation warning) and None.

Return type:

None

async basic_run_command(command)

Acquire the write_lock and run the command.

Parameters:

command (Command) – Command to run, as constructed by make_command.

Return type:

None

async basic_telemetry_callback(client)

Called when the TCP/IP controller outputs telemetry.

Call telemetry_callback, then check the following:

• If the low-level controller is in fault state, transition the CSC to FAULT state.

• IF the low-level controller is not in enabled state or if the CSC has lost the ability to command the low-level controller, move the CSC to DISABLED state.

Parameters:

client (CommandTelemetryClient) – TCP/IP client.

Return type:

None

async begin_disable(data)

Begin do_disable; called before state changes.

Parameters:

data (DataType) – Command data

Return type:

None

async begin_enable(data)

Begin do_enable; called before state changes.

Parameters:

data (DataType) – Command data

Return type:

None

async begin_standby(data)

Begin do_standby; called before the state changes.

Parameters:

data (DataType) – Command data

Return type:

None

async close_tasks()

Shut down pending tasks. Called by close.

Return type:

None

abstract async config_callback(client)

Called when the TCP/IP controller outputs configuration.

Parameters:

client (CommandTelemetryClient) – TCP/IP client.

Return type:

None

async configure(config)

Configure the CSC.

Parameters:

config (object) – The configuration, as described by the config schema, as a struct-like object.

Return type:

None

Notes

Called when running the start command, just before changing summary state from State.STANDBY to State.DISABLED.

async connect()

Connect to the low-level controller.

After starting the mock controller, if using one.

Return type:

None

async connect_callback(client)

Called when the client socket connects or disconnects.

Parameters:

client (CommandTelemetryClient) – TCP/IP client.

Return type:

None

async disconnect()

Disconnect from the low-level controller.

And shut down the mock controller, if using one.

Return type:

None

async enable_controller()

Enable the low-level controller.

Raises:

lsst.ts.salobj.ExpectedError – If the low-level controller is in fault state and the fault cannot be cleared. Or if a state transition command fails (which is unlikely).

Return type:

None

static get_config_pkg()

Get the name of the configuration package, e.g. “ts_config_ocs”.

Return type:

str

async handle_summary_state()

Called when the summary state has changed.

Override to perform tasks such as starting and stopping telemetry (example).

Return type:

None

Notes

The versions in BaseCsc and ConfigurableCsc do nothing, so if you subclass one of those you do not need to call await super().handle_summary_state().

make_command(code, param1=0.0, param2=0.0, param3=0.0, param4=0.0, param5=0.0, param6=0.0)

Make a command from the command identifier and keyword arguments.

Used to make commands for run_multiple_commands.

Parameters:

• code (CommandCode) – Command to run.

• param1 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param2 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param3 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param4 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param5 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param6 (double) – Command parameters. The meaning of these parameters depends on the command code.

Returns:

command – The command. Note that the counter field is 0; it is set by CommandTelemetryClient.run_command.

Return type:

Command

abstract make_mock_controller()

Construct and return a mock controller.

Return type:

None

async run_command(code, param1=0.0, param2=0.0, param3=0.0, param4=0.0, param5=0.0, param6=0.0)

Run one command.

Parameters:

• code (CommandCode) – Command to run.

• param1 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param2 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param3 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param4 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param5 (double) – Command parameters. The meaning of these parameters depends on the command code.

• param6 (double) – Command parameters. The meaning of these parameters depends on the command code.

Return type:

None

async run_multiple_commands(*commands, delay=None)

Run multiple commands, without allowing other commands to run between them.

Parameters:

• commands (List [Command]) – Commands to run, as constructed by make_command.

• delay (float (optional)) – Delay between commands (sec); or no delay if None. Only intended for unit testing.

Return type:

None

async standby_controller()

Standby the low-level controller.

Return type:

None

abstract async telemetry_callback(client)

Called when the TCP/IP controller outputs telemetry.

Parameters:

client (CommandTelemetryClient) – TCP/IP client.

Return type:

None

Notes

This method must set the following events:

• evt_controllerState

• evt_commandableByDDS

Here is a typical implementation:

await self.evt_controllerState.set_write(
    controllerState=int(client.telemetry.state),
    enabledSubstate=int(client.telemetry.enabled_substate),
)
await self.evt_commandableByDDS.set_write(
    state=bool(
        client.telemetry.application_status
        & ApplicationStatus.DDS_COMMAND_SOURCE
    )
)

async wait_controller_state(state, max_telem=5)

Wait for the controller state to be as specified.

Fails if the CSC cannot command the low-level controller.

Parameters:

• state (ControllerState) – Desired controller state.

• max_telem (int) – Maximum number of low-level telemetry messages to wait for.

Return type:

None