HexapodCsc¶

class lsst.ts.mthexapod.HexapodCsc(index, config_dir=None, initial_state=<State.OFFLINE: 4>, settings_to_apply='', simulation_mode=0)¶

Bases: lsst.ts.hexrotcomm.base_csc.BaseCsc

MTHexapod CSC.

Parameters

indexSalIndex or int

SAL index; see SalIndex for the allowed values.

config_dirstr, 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_statelsst.ts.salobj.State or int (optional)

The initial state of the CSC. Must be lsst.ts.salobj.State.OFFLINE unless simulating (simulation_mode != 0).

settings_to_applystr, optional

Settings to apply if initial_state is State.DISABLED or State.ENABLED.

simulation_modeint (optional)

Simulation mode. Allowed values:

0: regular operation.
1: simulation: use a mock low level controller.

Raises

ValueError: If initial_state != lsst.ts.salobj.State.OFFLINE and not simulating (simulation_mode = 0).

Notes

Error Codes

1: invalid data read on the telemetry socket

This CSC is unusual in several respect:

It acts as a server (not a client) for a low level controller (because that is how the low level controller is written).
The low level controller maintains the summary state and detailed state (that’s why this code inherits from Controller instead of BaseCsc).
The simulation mode can only be set at construction time.

Attributes Summary

`compensation_mode`	Return True if moves are compensated, False otherwise.
`config_dir`	Get or set the configuration directory.
`default_initial_state`
`disabled_or_enabled`	Return True if the summary state is `State.DISABLED` or `State.ENABLED`.
`domain`
`enable_cmdline_state`
`require_settings`
`simulation_help`
`simulation_mode`	Get the current simulation mode.
`summary_state`	Return the current summary state as a salobj.State, or OFFLINE if unknown.
`valid_simulation_modes`
`version`

Methods Summary

`add_arguments`(parser)	Add arguments to the parser created by `make_from_cmd_line`.
`add_kwargs_from_args`(args, kwargs)	Add constructor keyword arguments based on parsed arguments.
`amain`(index, **kwargs)	Make a CSC from command-line arguments and run it.
`assert_commandable`()	Assert that CSC is connected to the low-level controller and can command it.
`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`(*allowed_states, isbefore)	Assert that the current summary state is as specified.
`basic_run_command`(command)	Acquire the write_lock and run the command.
`begin_disable`(data)	Begin do_disable; called before state changes.
`begin_enable`(data)	Begin do_enable; called before state changes.
`begin_exitControl`(data)	Begin do_exitControl; called before state changes.
`begin_standby`(data)	Begin do_standby; called before the state changes.
`begin_start`(data)	Begin do_start; configure the CSC before changing state.
`close`([exception, cancel_start])	Shut down, clean up resources and set done_task done.
`close_tasks`()	Shut down pending tasks.
`compensation_loop`()	Apply compensation at regular intervals.
`compensation_wait`()	Wait until it is time to apply the next compensation update.
`compute_compensation`(uncompensated_pos)	Check uncompensated and, if relevant, compensated position and return compensation information.
`config_callback`(server)	Called when the low-level controller outputs configuration.
`configure`(config)	Configure the CSC.
`connect_callback`(server)	Called when the server’s command or telemetry sockets connect or disconnect.
`disable_compensation`()	Cancel compensation and report compensationMode.enabled=False.
`do_clearError`(data)	Reset the FAULT state to STANDBY.
`do_configureAcceleration`(data)	Specify the acceleration limit.
`do_configureLimits`(data)	Specify position and rotation limits.
`do_configureVelocity`(data)	Specify velocity limits.
`do_disable`(data)	Go from ENABLED state to DISABLED.
`do_enable`(data)	Go from DISABLED state to ENABLED.
`do_enterControl`(data)	Go from OFFLINE state, AVAILABLE offline substate to STANDBY.
`do_exitControl`(data)	Go from STANDBY state to OFFLINE state, AVAILABLE offline substate.
`do_move`(data)	Move to a specified position and orientation.
`do_offset`(data)	Move by a specified offset in position and orientation.
`do_setAuthList`(data)	Update the authorization list.
`do_setCompensationMode`(data)
`do_setLogLevel`(data)	Set logging level.
`do_setPivot`(data)	Set the coordinates of the pivot point.
`do_standby`(data)	Go from DISABLED state to STANDBY.
`do_start`(data)	Go from STANDBY state to DISABLED.
`do_stop`(data)	Halt tracking or any other motion.
`end_disable`(data)	End do_disable; called after state changes but before command acknowledged.
`end_enable`(data)	End do_enable; called after state changes but before command acknowledged.
`end_exitControl`(data)	End do_exitControl; called after state changes but before command acknowledged.
`end_standby`(data)	End do_standby; called after state changes but before command acknowledged.
`end_start`(data)	End do_start; called after state changes but before command acknowledged.
`fault`(code, report[, traceback])	Warning: the fault method is not support in this class.
`get_compensation_inputs`()	Return the current compensation inputs, or None if not available.
`get_config_pkg`()	Get the name of the configuration package, e.g.
`handle_summary_state`()	Called when the summary state has changed.
`implement_simulation_mode`(simulation_mode)	Implement going into or out of simulation mode.
`make_command`(code[, param1, param2, param3, …])	Make a command from the command identifier and keyword arguments.
`make_from_cmd_line`(index, **kwargs)	Construct a CSC from command line arguments.
`make_mock_controller`(initial_ctrl_state)	Construct and return a mock controller.
`put_log_level`()	Output the logLevel event.
`read_config_dir`()	Set `self.config_label_dict` and output `evt_settingVersions`.
`report_summary_state`()	Report a new value for summary_state, including current state.
`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.
`set_simulation_mode`(simulation_mode)	Set the simulation mode.
`start`()	Finish constructing the CSC.
`stop_motion`()	Stop motion and wait for it to stop.
`telemetry_callback`(server)	Called when the low-level controller outputs telemetry.
`wait_n_telemetry`([n_telemetry])	Wait for n_telemetry telemetry messages since the most recent low-level command.
`wait_stopped`([n_telemetry])	Wait for the current motion, if any, to stop.

Attributes Documentation

compensation_mode¶: Return True if moves are compensated, False otherwise.

config_dir¶

Get or set the configuration directory.

Parameters

config_dirstr, bytes, or pathlib.Path: New configuration directory.

Returns

config_dirpathlib.Path: Absolute path to the configuration directory.

Raises

ValueError: If the new configuration dir is not a directory.

default_initial_state = 4¶

disabled_or_enabled¶

Return True if the summary state is State.DISABLED or State.ENABLED.

This is useful in handle_summary_state to determine if you should start or stop a telemetry loop, and connect to or disconnect from an external controller

domain¶

enable_cmdline_state = False¶

require_settings = False¶

simulation_help = None¶

simulation_mode¶

Get the current simulation mode.

0 means normal operation (no simulation).

Raises

ExpectedError: If the new simulation mode is not a supported value.

summary_state¶: Return the current summary state as a salobj.State, or OFFLINE if unknown.

valid_simulation_modes = [0, 1]¶

version = '?'¶

Methods Documentation

classmethod add_arguments(parser)¶

Add arguments to the parser created by make_from_cmd_line.

Parameters

parserargparse.ArgumentParser: The argument parser.

Notes

If you override this method then you should almost certainly override add_kwargs_from_args as well.

classmethod add_kwargs_from_args(args, kwargs)¶

Add constructor keyword arguments based on parsed arguments.

Parameters

argsargparse.namespace: Parsed command.
kwargsdict: Keyword argument dict for the constructor. Update this based on args. The index argument will already be present if relevant.

Notes

If you override this method then you should almost certainly override add_arguments as well.

async classmethod amain(index, **kwargs)¶

Make a CSC from command-line arguments and run it.

Parameters

indexint, enum.IntEnum, True, or None

If the CSC is indexed, do one of the following:

Specify True to make index a required command-line argument that accepts any nonzero index.
Specify an enum.IntEnum class to make index a required command-line argument that only accepts the enum values.
Specify a non-zero integer to use that index. This is rare; if the CSC is indexed then the user should usually be allowed to specify the index.

If the CSC is not indexed, specify None or 0.

**kwargsdict, optional

Additional keyword arguments for your CSC’s constructor.

assert_commandable()¶: Assert that CSC is connected to the low-level controller and can command it.

assert_enabled()¶

Assert that the CSC is enabled.

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

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

substatelsst.ts.idl.enums.MTHexapod.EnabledSubstate: Substate of low-level controller.

assert_summary_state(*allowed_states, isbefore)¶

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

allowed_statesList [lsst.ts.salobj.State]: Allowed summary states.
isbeforebool: Determines the error message prefix. Set True if checking initial conditions before commanding the low-level controller. Message is “Rejected: initial state …”. Set False if checking the state after commanding the low-level controller. Message is “Failed: final state …”

async basic_run_command(command)¶

Acquire the write_lock and run the command.

Parameters

commandCommand: Command to run, as constructed by make_command.

async begin_disable(data)¶

Begin do_disable; called before state changes.

Parameters

dataDataType: Command data

async begin_enable(data)¶

Begin do_enable; called before state changes.

Parameters

dataDataType: Command data

async begin_exitControl(data)¶

Begin do_exitControl; called before state changes.

Parameters

dataDataType: Command data

async begin_standby(data)¶

Begin do_standby; called before the state changes.

Parameters

dataDataType: Command data

async begin_start(data)¶

Begin do_start; configure the CSC before changing state.

Parameters

datacmd_start.DataType: Command data

Notes

The settingsToApply field must be one of:

The name of a config label or config file
The name and version of a config file, formatted as <file_name>:<version>, where the version is a git reference, such as a git tag or commit hash. This form does not support labels.

async close(exception=None, cancel_start=True)¶

Shut down, clean up resources and set done_task done.

May be called multiple times. The first call closes the Controller; subsequent calls wait until the Controller is closed.

Subclasses should override close_tasks instead of close, unless you have a good reason to do otherwise.

Parameters

exceptionException, optional: The exception that caused stopping, if any, in which case the self.done_task exception is set to this value. Specify None for a normal exit, in which case the self.done_task result is set to None.
cancel_startbool, optional: Cancel the start task? Leave this true unless calling this from the start task.

Notes

Removes the SAL log handler, calls close_tasks to stop all background tasks, pauses briefly to allow final SAL messages to be sent, then closes the dds domain.

async close_tasks()¶: Shut down pending tasks. Called by close.

async compensation_loop()¶

Apply compensation at regular intervals.

The algorithm is to repeat the following sequence:

Wait until it is time to apply compensation (see compensation_wait for details).
Compute the compensation offset and apply it if large enough.

If a compensation update fails then compensation is disabled.

async compensation_wait()¶

Wait until it is time to apply the next compensation update.

Wait for motion to stop, then wait for self.compensation_interval seconds (a configuration parameter). Warn and repeat if the axes are moving again (very unlikely).

Raises

asyncio.CancelledError: If the CSC is no longer enabled.
asyncio.TimeoutError: If waiting for motion to stop takes longer than self.max_move_duration.

compute_compensation(uncompensated_pos)¶

Check uncompensated and, if relevant, compensated position and return compensation information.

Parameters

uncompensated_posPosition: Target position (without compensation applied).

Returns

compensation_infoCompensationInfo: Compensation information.

Raises

salobj.ExpectedError: If uncompensated or compensated position is out of bounds.

config_callback(server)¶

Called when the low-level controller outputs configuration.

Parameters

serverlsst.ts.hexrotcomm.CommandTelemetryServer: TCP/IP server.

async configure(config)¶

Configure the CSC.

Parameters

configobject: The configuration as described by the schema at schema_path, as a struct-like object.

Notes

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

connect_callback(server)¶

Called when the server’s command or telemetry sockets connect or disconnect.

Parameters

serverCommandTelemetryServer: TCP/IP server.

disable_compensation()¶: Cancel compensation and report compensationMode.enabled=False.

async do_clearError(data)¶: Reset the FAULT state to STANDBY.

async do_configureAcceleration(data)¶: Specify the acceleration limit.

async do_configureLimits(data)¶: Specify position and rotation limits.

async do_configureVelocity(data)¶: Specify velocity limits.

async do_disable(data)¶: Go from ENABLED state to DISABLED.

async do_enable(data)¶: Go from DISABLED state to ENABLED.

async do_enterControl(data)¶: Go from OFFLINE state, AVAILABLE offline substate to STANDBY.

async do_exitControl(data)¶: Go from STANDBY state to OFFLINE state, AVAILABLE offline substate.

async do_move(data)¶

Move to a specified position and orientation.

Check the target before and after compensation (if applied). Both the target and the compensated position (if compensating) should be in range, so we can turn off compensation at will. If compensation mode is off we do not test compensated position, as it allows running with invalid compensation coefficients or inputs.

async do_offset(data)¶

Move by a specified offset in position and orientation.

See note for do_move regarding checking the target position.

do_setAuthList(data)¶

Update the authorization list.

Parameters

datacmd_setAuthList.DataType: Authorization lists.

Notes

Add items if the data string starts with “+”, ignoring duplicates (both with respect to the existing items and within the data string). Remove items if the data string starts with “-“, ignoring missing items (items specified for removal that do not exist). Ignore whitespace after each comma and after the +/- prefix.

async do_setCompensationMode(data)¶

do_setLogLevel(data)¶

Set logging level.

Parameters

datacmd_setLogLevel.DataType: Logging level.

async do_setPivot(data)¶: Set the coordinates of the pivot point.

async do_standby(data)¶

Go from DISABLED state to STANDBY.

Note: use the clearError command to go from FAULT to STANDBY.

async do_start(data)¶

Go from STANDBY state to DISABLED.

Notes

This ignores the data, unlike the vendor’s CSC code, which writes the supplied file name into a file on an nfs-mounted partition. I hope we won’t need to do that, as it seems complicated.

async do_stop(data)¶: Halt tracking or any other motion.

async end_disable(data)¶

End do_disable; called after state changes but before command acknowledged.

Parameters

dataDataType: Command data

async end_enable(data)¶

End do_enable; called after state changes but before command acknowledged.

Parameters

dataDataType: Command data

async end_exitControl(data)¶

End do_exitControl; called after state changes but before command acknowledged.

Parameters

dataDataType: Command data

async end_standby(data)¶

End do_standby; called after state changes but before command acknowledged.

Parameters

dataDataType: Command data

async end_start(data)¶

End do_start; called after state changes but before command acknowledged.

Parameters

dataDataType: Command data

fault(code, report, traceback='')¶

Warning: the fault method is not support in this class.

The problem is that the summary state is maintained by the low-level controller and the CSC has no way to reliably send the low-level controller to FAULT state.

get_compensation_inputs()¶

Return the current compensation inputs, or None if not available.

Log a warning if inputs are missing and the missing list does not match the previous warning.

Returns

compensation_inputsCompensationInputs or None: The compensation inputs, if all inputs are available, else None.

static get_config_pkg()¶: Get the name of the configuration package, e.g. “ts_config_ocs”.

async handle_summary_state()¶

Called when the summary state has changed.

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

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().

async implement_simulation_mode(simulation_mode)¶

Implement going into or out of simulation mode.

Deprecated. See simulation mode for details.

Parameters

simulation_modeint: Requested simulation mode; 0 for normal operation.

Raises

ExpectedError: If simulation_mode is not a supported value.

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

Make a command from the command identifier and keyword arguments.

Used to make commands for run_multiple_commands.

Parameters

codeCommandCode: Command to run.
param1, param2, param3, param4, param5, param6double: Command parameters. The meaning of these parameters depends on the command code.

Returns

commandCommand: The command. Note that the counter field is 0; it is set by CommandTelemetryServer.put_command.

classmethod make_from_cmd_line(index, **kwargs)¶

Construct a CSC from command line arguments.

Parameters

indexint, enum.IntEnum, True, or None

If the CSC is indexed, do one of the following:

Specify True to make index a required command-line argument that accepts any nonzero index.
Specify an enum.IntEnum class to make index a required command-line argument that only accepts the enum values.
Specify a non-zero integer to use that index. This is rare; if the CSC is indexed then the user should usually be allowed to specify the index.

If the CSC is not indexed, specify None or 0.

**kwargsdict, optional

Additional keyword arguments for your CSC’s constructor.

Returns

csccls: The CSC.

Notes

To add additional command-line arguments, override add_arguments and add_kwargs_from_args.

make_mock_controller(initial_ctrl_state)¶

Construct and return a mock controller.

Parameters

initial_ctrl_stateint: Initial controller state.

put_log_level()¶: Output the logLevel event.

read_config_dir()¶

Set self.config_label_dict and output evt_settingVersions.

Set self.config_label_dict from self.config_dir/_labels.yaml. Output the settingVersions event (if changed) as follows:

recommendedSettingsLabels is a comma-separated list of labels in self.config_label_dict, truncated by omitting labels if necessary.
recommendedSettingsVersion is derived from git information for self.config_dir, if it is a git repository, else “”.

report_summary_state()¶

Report a new value for summary_state, including current state.

Subclasses may wish to override for code that depends on the current state (rather than the state transition command that got it into that state).

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

Run one command.

Parameters

codeCommandCode: Command to run.
param1, param2, param3, param4, param5, param6double: Command parameters. The meaning of these parameters depends on the command code.

async run_multiple_commands(*commands, delay=None)¶

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

Parameters

commandsList [Command]: Commands to run, as constructed by make_command.
delayfloat (optional): Delay between commands (sec); or no delay if None. Only intended for unit testing.

async set_simulation_mode(simulation_mode)¶

Set the simulation mode.

Await implement_simulation_mode, update the simulation mode property and report the new value.

Parameters

simulation_modeint: Requested simulation mode; 0 for normal operation.

async start()¶

Finish constructing the CSC.

If initial_summary_state is State.DISABLED or State.ENABLED then call configure.
Run BaseCsc.start

async stop_motion()¶

Stop motion and wait for it to stop.

Raises:: asyncio.CancelledError if not in enabled state.

telemetry_callback(server)¶

Called when the low-level controller outputs telemetry.

Parameters

serverlsst.ts.hexrotcomm.CommandTelemetryServer: TCP/IP server.

async wait_n_telemetry(n_telemetry=4)¶

Wait for n_telemetry telemetry messages since the most recent low-level command.

Parameters

n_telemetryint, optional: Minimum number of telemetry messages since the most recent low-level command. Must be positive. A value of 3 is necessary to reliably allow stop or move to interrupt another move.

Raises

asyncio.CancelledError: If the system goes out of enabled state.

async wait_stopped(n_telemetry=4)¶

Wait for the current motion, if any, to stop.

Parameters

n_telemetryint, optional: Minimum number of telemetry messages since the most recent low-level command. Must be positive. A value of 3 is necessary to reliably allow stop or move to interrupt another move.

Returns

is_stoppedbool: Is motion stopped? Always True unless max_nstatus is not None.
Raises:: asyncio.CancelledError if not in enabled state.

Navigation

HexapodCsc¶