M2 Common Code

https://img.shields.io/badge/GitHub-ts__m2com-green.svg https://img.shields.io/badge/Jenkins-ts__m2com-green.svg https://img.shields.io/badge/Jira-ts__m2com-green.svg

Overview

This module contains the common code for the main telescope M2 commandable SAL component (CSC) and graphical user interface (GUI) to operate the M2 mirror control system. The eups is used as the package manager. This package also supports the conda package manager.

The badges above navigate to the GitHub repository for the common code and Jira issues.

Dependencies

JSON String

The JSON string is used in the TCP/IP communication between the M2 CSC/GUI and hardware. The design here takes the following documents as references: TS JSON Message Format Proposal and TS JSON Message Format Proposal.

Algorithms

The followings are the algorithms used in the cell control system:

Architecture

The classes and files for each module are listed below.

m2com

        classDiagram
namespace tcpip {
    class Client
}

class SimpleDelayFilter
BiquadraticFilter "1" *-- "n" SingleBiquadraticFilter

Client <|-- TcpClient

Controller *-- ErrorHandler
Controller "1" *-- "2" TcpClient
Controller <|-- ControllerCell

Figure 14 Class diagram of M2 common code

  • ErrorHandler deals with the summary faults status from M2 cell controller.

  • Controller has the business logic to communicate with hardware by TCP/IP interface.

  • TcpClient is a TCP/IP client.

  • ControllerCell is a high-level class to integrate with the Controller class to communicate with the M2 cell controller.

  • SimpleDelayFilter is a simplified delay filter.

  • SingleBiquadraticFilter is the single biquadratic filter without the gain.

  • BiquadraticFilter is the compacted biquadratic filter with the gain.

m2com.mock

        classDiagram
namespace tcpip {
  class OneClientServer
}

namespace m2com {
  class ErrorHandler
  class SimpleDelayFilter
  class BiquadraticFilter
}

MockControlLoop "1" *-- "4" BiquadraticFilter
MockControlLoop "1" *-- "3" SimpleDelayFilter
MockControlLoop "1" *-- "2" MockDeadbandControl
MockControlLoop *-- MockGainSchedular
MockControlLoop *-- MockInPosition

ErrorHandler <|-- MockErrorHandler

MockServer "1" *-- "2" OneClientServer
MockServer *-- MockModel
MockServer *-- MockMessageTelemetry
MockServer *-- MockMessageEvent
MockServer *-- MockCommand

MockMessageEvent *-- OneClientServer
MockMessageTelemetry *-- OneClientServer

MockCommand --> MockMessageEvent
MockCommand --> MockModel

MockModel *-- MockScriptEngine
MockModel *-- MockControlOpenLoop
MockModel *-- MockControlClosedLoop
MockModel *-- MockErrorHandler
MockModel "1" *-- "2" MockPowerSystem
MockModel "1" *-- "84" MockInnerLoopController
MockModel *-- MockPlant

MockControlClosedLoop *-- MockControlLoop
MockControlClosedLoop --> MockPlant

MockControlOpenLoop ..> MockPlant

Figure 15 Class diagram of mock module in M2 common code

  • MockServer is a mock server of M2 to support the simulation mode.

  • MockModel simulates the hardware behavior to be used by MockServer.

  • MockScriptEngine simulates the execution of binary script.

  • MockControlOpenLoop simulates the open-loop control.

  • MockControlClosedLoop simulates the closed-loop control.

  • MockCommand simulates the execution of command in real hardware.

  • MockMessageEvent simulates the message of event from real hardware.

  • MockMessageTelemetry simulates the message of telemetry from real hardware.

  • MockErrorHandler manages the error codes to report.

  • MockPowerSystem simulates the behavior of power system.

  • MockInnerLoopController simulates the behavior of inner-loop controller.

  • MockPlant is the plant model of system.

  • MockControlLoop is the control loop of system.

  • MockDeadbandControl selects the force error of hardpoints.

  • MockGainSchedular tunes the gains for the slewing, settling, and imaging processes.

  • MockInPosition checks the mirror is in position or not.

APIs

This section is autogenerated from docstrings.

lsst.ts.m2com Package

Functions

camel_case(string_python)

Formate the string of Python style to camel case.

cancel_task_and_wait(task)

Cancel the asynchronous task (if not done) and wait for it to complete.

check_hardpoints(location_axial_actuator, ...)

Check the selected hardpoints are good or not.

check_limit_switches(actuator_forces, ...)

Check the limit switches are triggered or not.

check_queue_size(queue, log[, name])

Check the size of queue and log the information if needed.

collect_queue_messages(queue, name[, flush])

Collect the specific messages in queue.

correct_inclinometer_angle(angle[, offset])

Correct the inclinometer's value and make sure to limit the resulting value to the indicated range: (-270, 90).

get_config_dir([env_variable, relative_path])

Get the directory of configuration files.

get_forces_mirror_weight(angle)

Get the forces that bear the weight of mirror.

get_queue_message_latest(queue, name[, flush])

Get the latest message in queue.

is_coroutine(function)

Input function is a coroution or not.

read_error_code_file(filepath)

Read the error code file.

read_yaml_file(filepath)

Read the yaml file.

select_axial_hardpoints(...)

Select the axial hardpoints based on the specific axial hardpoint.

write_json_packet(writer, msg_input)

Write the json packet.

Classes

ActuatorDisplacementUnit(value[, names, ...])

Unit of the actuator displacement.

BiquadraticFilter(gain, coefficients, ...)

Biquadratic filter.

CommandActuator(value[, names, module, ...])

Action to command the actuators.

CommandScript(value[, names, module, ...])

Action to command the script execution.

CommandStatus(value[, names, module, ...])

Command status.

Controller([log])

Controller class.

ControllerCell([log, is_csc, host, ...])

Cell controller class.

DigitalInput(value[, names, module, ...])

Bit of digital input.

DigitalOutput(value[, names, module, ...])

Bit of digital output.

DigitalOutputStatus(value[, names, module, ...])

Digital output status to switch the individual bit value of digital output.

ErrorCodeWarning(value[, names, module, ...])

Error code of the warning message.

ErrorHandler([filepath])

Error Handler class to manage the errors.

LimitSwitchType(value[, names, module, ...])

Type of the limit switches on actuators.

MockCommand()

Mock command to simulate the execution of command in real hardware.

MockControlClosedLoop([is_mirror])

Mock closed-loop control.

MockControlLoop(gain_prefilter_axial, ...[, ...])

Mock control loop that implements the force control algorithm.

MockControlOpenLoop()

Mock open-loop control.

MockDeadbandControl(threshold_lower, ...)

Mock deadband control to select the force error of hardpoints.

MockErrorCode(value[, names, module, ...])

Mock error code used by the mock server.

MockErrorHandler([filepath])

Mock Error Handler class to manage the errors.

MockGainSchedular(min_gain_axial, ...)

Mock gain schedular to tune the gains for the slewing, settling, and imaging processes.

MockInPosition(window_size, ...)

Mock InPosition class that translates from the "InPosition.lvclass" in ts_mtm2_cell.

MockInnerLoopController()

Mock Inner-Loop Controller (ILC) to simulate the behavior of hardware.

MockMessageEvent(server)

Mock message of event to simulate the message from real hardware.

MockMessageTelemetry(server)

Mock message of telemetry to simulate the message from real hardware.

MockModel([log, inclinometer_angle, ...])

Mock Model class.

MockPlant(static_transfer_matrix, ...)

Mock plant model to simulate the actuator's force feedback.

MockPowerSystem(default_voltage, default_current)

Mock power system to simulate the behavior of hardware.

MockScriptEngine()

Mock script engine class to simulate the execution of binary script.

MockServer(host[, port_command, ...])

Mock server of M2.

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

Message type to the cell controller.

SimpleDelayFilter(coefficients, num_element)

Simple delay filter

SingleBiquadraticFilter(a11, a21, b11, b21, ...)

Single biquadratic filter.

TcpClient(host, port, ...[, log, ...])

TCP/IP client.

Build and Test

Using docker is highly recommended. The built docker image is develop_env.

To setup and test the code using Docker, enter:

docker run -it --rm -v ${repo_location}:/home/saluser/ts_m2com lsstts/develop-env:${tag}
cd ts_m2com
setup -k -r .

The environment shall be setup either from /home/saluser/.setup_dev.sh.

Version History

The version history is at the following link.

The released version is here.

Contributing

To contribute, please start a new pull request on GitHub. Feature requests shall be filled in JIRA with the ts_m2com or M2 label. In all cases, reaching out to the contacts for this CSC is recommended.

Contact Personnel

For questions not covered in the documentation, emails should be addressed to the developers: Tiago Ribeiro <tribeiro@lsst.org> and Te-Wei Tsai <ttsai@lsst.org>. The product owner is Sandrine Thomas <sthomas@lsst.org>.

This page was last modified 2025-06-09.