L-3 Integrated Optical Systems- Brashear Proprietary Information L-3 Communications Corporation, Brashear Division, reserves all rights in connection with this document and in the subject matter represented herein. The recipient hereby acknowledges these rights and shall not, without permission in writing, disclose or divulge this document in whole or in part to third parties or use it for any purpose other than that for which it was delivered to recipient. This technical data is controlled under the Export Administration Regulations (EAR) and may not be exported to a Foreign Person, either in the U.S. or abroad, without proper authorization by the U.S. Department of Commerce. DESTRUCTION NOTICE: Destroy by any method that will prevent disclosure of contents or reconstruction. 615 Epsilon Drive Pittsburgh, PA 15238 Phone: 412-967-7700, Fax: 412-967-7973 www.L-3Com.com/Brashear Software Design Document for the ATST Top End Optical Assembly SDD-32506 23 Oct 2012 Approval Name Signature Date Software Engineer Raymond Balister Project Engineer Steve Mix Systems Engineer Sandra Bader Program Manager Craig Peton
152
Embed
Software Design Document for the ATST Top End Optical ...
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
L-3 Integrated Optical Systems- Brashear Proprietary Information
L-3 Communications Corporation, Brashear Division, reserves all rights in connection with this document and in the subject matter represented
herein. The recipient hereby acknowledges these rights and shall not, without permission in writing, disclose or divulge this document in whole or in part to third parties or use it for any purpose other than that for which it was delivered to recipient.
This technical data is controlled under the Export Administration Regulations (EAR) and may not be exported to a Foreign Person, either in the U.S. or abroad, without proper authorization by the U.S. Department of Commerce.
DESTRUCTION NOTICE: Destroy by any method that will prevent disclosure of contents or reconstruction.
4.17 FAILURE MODES ............................................................................................... 23 4.17.1 RESPONDING TO INVALID DATA .............................................................................. 23
4.17.2 RESPONDING TO INVALID TRAJECTORY DATA ......................................................... 23 4.17.3 INTERNAL FAILURES ............................................................................................. 24
4.17.4 FAILURES OF TEOA HARDWARE ........................................................................... 24
5. USE CASES ..................................................................................... 25
5.1 TEOA MANAGEMENT CONTROLLER .............................................................. 25 5.1.1 USE CASE: SET TEOA TRACKING MODE ....................................................... 26 5.1.2 USE CASE: SET M2 HEXAPOD CORRECTION SOURCE ............................... 26
5.1.3 USE CASE: SET M2 HEXAPOD POSITION ...................................................... 27 5.1.4 USE CASE: SET M2 FTT POSITION ................................................................. 27
5.1.5 USE CASE: SET LYOT STOP POSITION .......................................................... 28 5.1.6 USE CASE: SEND LOG MESSAGE .................................................................. 28 5.1.7 USE CASE: TEOA MANAGER DETECT GLOBAL INTERLOCK ...................... 28
5.2 M2 HEXAPOD CONTROLLER ........................................................................... 29 5.2.1 USE CASE: RECEIVE AZ/ALT POSITION ........................................................ 29
5.2.2 USE CASE: SEND M2 HEXAPOD CONTROLLER STATUS ............................. 30 5.2.3 USE CASE: SEND M2 HEXAPOD LOG MESSAGE .......................................... 30
5.2.4 USE CASE: RECEIVE M2 HEXAPOD CORRECTIONS .................................... 31 5.2.5 USE CASE: M2 HEXAPOD CONTROLLER DETECT GLOBAL INTERLOCK .. 31
5.3 M2 FAST TIP-TILT CONTROLLER .................................................................... 31 5.3.1 USE CASE: SEND M2 FAST TIP-TILT CONTROLLER STATUS ...................... 32 5.3.2 USE CASE: SEND M2 FAST TIP-TILT LOG MESSAGE ................................... 32
Software Design Document SDD-32506 Rev A
v L-3 Communications PROPRIETARY
The information contained in this document is subject to the restrictions found on the title page.
5.3.3 USE CASE: M2 FAST TIP-TILT DETECT GLOBAL INTERLOCK ..................... 33
5.4 LYOT STOP CONTROLLER .............................................................................. 33 5.4.1 USE CASE: SEND LYOT STOP CONTROLLER STATUS ................................ 34 5.4.2 USE CASE: SEND LYOT STOP LOG MESSAGE ............................................. 34 5.4.3 USE CASE: LYOT STOP DETECT GLOBAL INTERLOCK ............................... 35
5.5 ENGINEERING USE CASES .............................................................................. 35
6.1 TEOACS TO TEOA COMMUNICATION ............................................................ 36
6.2 INFORMATION IN THE PROPERTY DB ............................................................ 36
6.3 IMPLEMENTING THE COMMUNICATION BETWEEN THE TEOACS AND TEOA HARDWARE CONTROLLERS .......................................................................... 39
The software described in this document is designed to control the operation of the Top End Optical
Assembly (TEOA) for the Advanced Technology Solar Telescope (ATST). This assembly consists of the
secondary mirror (M2) and the required support equipment. This equipment positions the mirror and
conditions the incoming beam. In addition it provides cooling to both the mirror and heat stop device.
For illustrative purposes, the system block diagram is shown in Figure 2.1-1.
TEOA Management
Controller
Hexapod Controller Fast Tip/Tilt ControllerLyot Stop Controller
Heat Stop Shutter
Acutator and position
sensors.
Physik Instrumente
M-850 Hexapod
Controller
Physik Instrumente
E-712 Digital Piezo
Controller
M2 Cell Cooling
Temperature, pressure and
flow sensors. Flow control
for output.
Lyot Stop actuator
and position sensors
TEOA Thermal
Management System Reads temp, pres, and flow
for HS, Lyot, and M2. Sets
pos of safety shutter.
Implemented as a PLC.
GigaBit Ethernet
Discrete
I.O
WFC Limb Tracker
WCCS
Wavefront Correction
Control System
TCS
Telescope Control System
TEOA Engineering
Graphical User
Interface
Common
Services
Framework
SPEC-0022
FMS
Facility Managementl
System
System DB
PIO Interface
Cable
GIS
Global Interlock System
Lyot Stop
Temperature, pressure and
flow sensors. Flow control
for output.
Heat Stop
Temperature, pressure and
flow sensors. Flow control
for output.
Discrete
GIS Outputs
ICD-1.3-4.5
TEOA-GIS
ICD-1.3-2.3
TEOA-WCCS
ICD-1.3-4.4
TEOA-TCS
ICD-1.3-2.5
TEOA-
WFC-LTDiscrete I/O from PLC
to physical sub-systems
Customer
Equipment
Legend
L3B
Supplied
Discrete I/O
Ethernet
Discrete
Fault Inputs
Acromag 983EN
Digital I/O Ethernet
Module
Hexapod ConnectionFast Tip/Tilt
ConnectionLyot Stop Connection
JNI/Acromag Library
Hexapod Hardware
Discrete
I.O
Fast Tip-tilt Stage
Discrete
I.O
Figure 2.1-1 ATST/TEOA Block Diagram
In general, the functions of the TEOA are divided into two categories, mechanical and thermal/safety.
The mechanical operations are controlled by a Linux based computer while the thermal/safety systems are
managed by a programmable logic controller (PLC). The exception to this division is the operation of the
Software Design Document SDD-32506 Rev A
3 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
heat stop shutter which is controlled by the PLC. While mechanical in operation, this item is deemed to
be integral to the safety systems. The majority of this document is concerned with the design description
of the TEOACS as it relates to the mechanical positioners.
The TEOACS must respond to positioning demands received from the TCS. These demands control the
absolute positioning of the M2 hexapod and FTT stage. Furthermore, with corrections enabled, the
hexapod position shall track corrections derived from the data received from the Wavefront Condition
Control System (WCCS). These corrections are in the form of delta positions and must be accumulated
and summed with the absolute positions received from the TCS. The FTT stage in addition to responding
to TCS position demands can be put into a state where it will respond directly to high rate absolute
position demands transmitted directly to the FTT control electronics from the Wavefront Control –
Adaptive Optics (WFC) limb tracker. In this mode, the TEOACS is not a participant in the control, but
merely monitors the FTT position.
The TEOACS implements the control for the Lyot stop and positions it according to data received from
the TCS. The position of the Lyot stop is monitored and compared to the requested position and faults
are generated as appropriate.
All command, control, and monitoring functions for the TEOACS are implemented over Ethernet. The
interface protocols to subordinate equipment are implemented in either Java or the native protocols as
implemented by the various vendors of said equipment. The interfaces to the TCS and other telescope
subsystems are implemented using the Common Services Framework (CSF) as developed by Association
of Universities for Research in Astronomy (AURA). This framework consists of an extensive set of
services that provide for health and alarm notifications, logging features, and persistent parameter data
storage. In addition, this framework implements the transport and communications protocol between the
various system components in a near seamless manner. As the TEOACS shall be implemented using CSF
the TEOACS application will be running on a control computer running CentOS 6 Linux and support
packages as specified in SPEC-0022. Furthermore, all communications will be unencrypted. The
TEOACS shall assume that all communications are already secured. It will not implement any firewalls
or other security measures.
In typical operation, all TEOACS communications shall be over Ethernet. This includes communications
with the PI E-710 and M-850 controllers. The TEOACS shall accept hardware configurations from the
TCS and return appropriate responses. In addition, the TEOACS shall transmit, on a regular basis, status,
health and logging information.
The primary role of the TEOACS is to control the hardware present on the TEOA. This hardware
consists of:
M2 Hexapod and PI M-850 hexapod controller
M2 Fast Tip-Tilt stage and PI E-710 Piezoelectric actuator controller
Lyot stop
This hardware is used to accurately and efficiently control the position of the M2 mirror. The Lyot stop is
used as an aperture stop as required during some experiments as defined by SPEC-0001.
Prior to examining the details of the TEOACS software design, it is necessary to gain an understanding of
the overview of the system to be developed and how it relates to the infrastructure required by ATST.
Software Design Document SDD-32506 Rev A
4 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
The infrastructure, or CSF, contains the base classes from which the TEOACS is constructed. All of the
controllers contained within the TEOACS are derived from one of the base classes contained within this
framework. This framework also includes base classes to support communications and I/O devices. In
accordance with the CSF specification, controllers are contained within containers and are managed by
the Container Manager. The Container Manager is responsible for the deployment and lifecycle
management of the controllers from which the TEOACS is constructed. Another integral part of the
entire system is the DB software toolset which supports the databases. The CSF architecture is dependent
on the DB tools to supply persistent storage for the initial data required by the TEOACS, and for the
purpose of logging several types of messages. From the point of view of the TEOACS, the interfaces to
the databases are encapsulated in classes supplied by the CSF infrastructure and utilized by the TEOACS.
An engineering graphical user interface (GUI) is required for the TEOACS. This engineering GUI is
built on top of the Java Engineering Screens (JES) toolset. The JES toolset is an extension of the CSF
and relies heavily on the classes contained therein. The JES contains tools and classes that facilitate
graphical layout of GUI objects to construct a GUI interface. Behind the interface, it is capable of
communicating, via CSF, to the TEOACS. This enables a user to submit configurations, manage
parameters and exchange events with the TEOACS via a GUI interface for test and diagnostics.
Complete details regarding the JES and related tools can be found in TN-0089.
The Container Manager is used to load, initialize and startup the several controllers implemented in the
TEOACS. Startup of these is accomplished through the CSF and appropriate entries in the application
database. Upon startup, the container manager queries the database and starts up the controllers in
accordance with the returned data. This operation occurs automatically upon boot of the TEOACS
hardware and requires no intervention on the part of the operator.
The TEOACS package, teoacs, comprises four distinct controllers and several other support classes:
TeoaManager is the class implementing the top level management controller atst.tcs.teoacs.
M2Hexapod is the class implementing the hexapod controller atst.tcs.teoacs.m2pos.
M2TT is the class implementing the fast tip-tilt controller atst.tcs.teoacs.mtt.
LyotStop is the class implementing the Lyot stop position controller atst.tcs.teoacs.lyot.
Each of these controllers is based on classes contained within the CSF base class package. Furthermore,
each of the controllers contained within the TEOACS communicates with other controllers via CSF.
Additionally, the TEOACS package contains several other classes used to support communications with
the actual hardware contained in the TEOA as previously enumerated. These classes, through a JNI
interface, support the creation of the communications channel and the actual device driver that
communicates with the hardware. It just prior to the JNI level that the TEOACS control software
implements the simulator. When properly configured, the driver software will refrain from sending
commands to the hardware. Instead it will hold a simulated state for the real hardware and use this to
emulate the actual devices intended to be controlled.
Communications between the TCS and the TEOACS can be classified into two major categories,
configurations and events. Configurations are handled by the top level TEOACS management controller
and typically take the form of attribute value pairs. The configurations are received by the management
controller and automatically routed to the proper lower level controller via code inherited through the
manager controller class. The worker controllers will then attempt to match their state to the received
configuration. Responses to the configuration requests, as well as status and health information are
relayed back to the TCS via events. These events, in addition to being sent to the TCS are also
accumulated by the system database and archived for later reference.
Software Design Document SDD-32506 Rev A
5 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
For the purpose of fault notification, the GIS communicates with the TEOACS. This communication is in
the form of fault events received via the CSF event service. Should the GIS determine that a fault is
present, it will broadcast that information and it will be received by any controllers which have subscribed
to that event. The TEOACS will be one of those subscribers and will use this event to trigger a transition
to a default, unpowered, non-moving state. In this state, all actuators shall be unpowered.
For the purpose of position adjustments, the WCCS will communicate with the TEOACS. This
communication is in the form of events and contains information necessary for position adjustment of the
M2 hexapod. It consists of delta measurements from the wavefront correction system. These deltas will
be accumulated and used to adjust the demanded hexapod position by simply adding them to the demand
current demand position.
2.2 TEOCS DEPLOYMENT
The TEOACS package is expected to be deployed on a single, CentOS based, CSF client. The hardware
requirements for the TEOACS hardware are similar to the typical CSF client. This controller does not
require any special hardware to be installed. All interaction with the actual TEOA hardware is expected
to occur over Ethernet. This hardware has been enumerated in a previous section. The software that is
installed will include CentOS 6 and the current version of the CSF client software. The TEOACS
application shall be deployed as a package that will be run by the CSF Container Manager. A single
Container Manager is capable of running several CSF controllers. This package shall contain all of the
required software controllers and interfaces needed to successfully accomplish the tasks necessary to meet
the requirements of the TEOACS.
Figure 2.2-1 TEOACS Deployment Diagram
Software Design Document SDD-32506 Rev A
6 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
In the diagram above, the TEOA controller artifact is the package that is running on the TEOA controller
and contains the code needed to control the TEOA. This code is written in Java and conforms to the
requirements of the CSF architecture. There is a requirement to deliver an engineering interface for the
TEOACS. This interface is written using the Java Engineering Screens CSF package and is deployed as a
separate package. The implementation of these screens is expected to be deployed on a separate
computer.
Upon startup of the TEOA controller, the CSF Container Manager will load the TEOACS controllers and
place them in the loaded state. Upon request of the TCS or other subsystems, they will transition to the
init and running states. Only once they have reached the running state will the TEOACS be operational.
Should a critical fault occur at any time, the affected controllers will transition to the default state, turn off
any hardware, and cease any motion. Should it be necessary to shut down the TEOACS, the controllers
may be commanded to uninit and to unload. This will shut down the TEOA hardware, place them in a
default state, and release all allocated resources.
2.3 IMPLEMENTATION LANGUAGE
[CUS-1246] [CUS-1247]
All TEOACS controllers/components and associated software are implemented in Java. However, the
library selected to provide communication with the Physik Instrumente (PI) controllers is written in C,
calls to this library will be made from Java using Java Native Interface (JNI) C code. The C code will
provide a wrapper enabling calls and return of data to and from the PI C communications library in Java.
Prior to use, all libraries shall be submitted to AURA for approval before they are used to implement the
functionality of the TEOACS.
Java is used as the language of choice as previous prototyping carried out using Java containers and
controllers has demonstrated there is no compelling reason to write CSF applications in C++. In fact
some of the base classes (including specialized management controllers) will only be supported in Java,
and it is therefore desirable to use Java in the TEOACS controllers to utilize the functionality already
provided.
2.4 SOURCE CODE
[CUS-1246]
All source code used by and implemented as part of the TEOACS contract will be provided. As the code
is developed it will be committed to a code source repository (Perforce) at the Contractor’s location. At
the various TEOACS delivery stages the code constituting the delivery shall be tagged (labeled) in the
repository and delivered to ATST. The code then can be extracted, inserted into the ATST code
repository, and reviewed. All implemented source code shall be documented in a manner consistent with
good software practices, using tools such as Javadoc and doxygen.
All implemented source files shall contain a header including the author(s), and functional description.
All functions within a source file shall have a description of the interface and operation of the function,
and shall be clearly commented.
All third-party software will be delivered as part of the regular release cycle. Third-party software will be
approved by ATST before its inclusion in the design and construction.
Software Design Document SDD-32506 Rev A
7 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
2.5 OVERALL USE OF THE ATST COMMON SERVICES
[CUS-1246]
The TEOACS, as one of the systems of the ATST, must work seamlessly with the other systems that
make up the overall ATST control system. In particular it must accept and act on configurations sent by
the TCS. To accomplish this, the TEOACS is built using the ATST CSF, which in turn constrains its
design.
At the highest level the TEOACS will consist of a collection of CSF Java class files. The TEOACS
container will hold a number of controllers that will be initialized and started by the container manager
via the init and startup command methods. During this phase the TEOACS controllers will attempt to
make connections to the other ATST components with which they need to communicate and will retrieve
their initial state from the runtime database through the use of the property service.
The workers of the system will be implemented as ATST controllers (deriving from
atst.base.HardwareController) providing the command/action/response behavior needed to handle the
submission of configurations. Details of the controller model in general and the particular controllers and
components that will be derived by the TEOACS can be found in the CSF User Manual (SPEC-0022-1)
and Base Software for Control Systems (TN-0088).
Software Design Document SDD-32506 Rev A
8 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
3. SYSTEM CONTEXT
This section describes the context of the TEOACS with respect to other systems of the ATST with which
it must communicate. Successive sections describe what functions the TEOACS must perform; however
the details of these functions are discussed in later sections.
The TEOACS context is bounded above it by the TCS and the WCCS and below it by the actual TEOA
hardware. The TEOACS receives configurations from the TCS and correction event data from the
WCCS. The TEOACS also receives information from the GIS with regards to observatory wide interlock
conditions and safety events.
3.1 CONTEXT DIAGRAM
The TEOACS context diagram is shown in Figure 3.1-1. The node at the top of the diagram represents
the TCS. The configuration and event interface used between the TCS and the TEOACS is defined in
ICD 1.3-4.4. The node at the bottom of the diagram represents the various bits of hardware resident on
the TEOA. All control of these hardware items are implemented over Ethernet with the various ICDs
dictated by the equipment vendors and are not CSF compliant.
The other systems to which the TEOACS communicates are the GIS and WCCS. These links are via CSF
events and are governed by ICDs ICD 1.3-4.5 and ICD 1.3-2.1 respectively.
Figure 3.1-1 TEOACS Context Diagram
3.2 TCS RELATIONSHIP
[CUS-1241]
The relationship between TCS and TEOACS is defined in ICD 1.3-4.4. The TEOACS must accept the
configurations defined, and subscribe to and generate the specified events of this ICD. Configurations
will contain the current mode required of M2 e.g. off, passive, active, or AO, and other parameters used to
define how the Lyot stop, M2 hexapod, and M2 fast tip-tilt stage should be moved. The TEOACS
subscribes to a MCS event from which it extracts Az and Alt information. This information is used as
lookup indices for corrections that are added to the M2 demand position when M2 is in either passive or
Software Design Document SDD-32506 Rev A
9 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
active modes. When in AO mode, these corrections are not used as the WFC limb tracker is directly
controlling the M2 fast tip-tilt stage.
The current status of the M2 is broadcast on the events atst.tcs.teoacs.cStatus,
atst.tcs.teoacs.m2pos.cStatus, atst.tcs.teoacs.m2tt.cStatus, and atst.tcs.teoacs.lyot.cStatus. These
events and their frequencies are described in greater detail in ICD 1.3-4.4. The TCS or any other
interested systems may subscribe to these events.
3.3 WCCS RELATIONSHIP
When the TEOACS is in passive mode, the M2 hexapod is getting position data from the TCS and error
correction data from lookup tables. When in active mode, the hexapod gets additional data from the
WCCS. This data is received in the form of events and contains delta correction information as defined
by ICD 1.3-2.3. This data must be accumulated by the TEOACS and added to the demand position
received from the TCS. This WCCS event is generated at the rate of 1 Hz. This data is used to make
corrections to the M2 hexapod position when the M2 is in an active mode.
3.4 WFC RELATIONSHIP
Although there is no direct relationship between the WFC and the TEOACS, there is nonetheless a
connection between the WFC and the TEOA M2 fast tip-tilt controller. When the TEOACS is in the AO
mode the TEOACS no longer controls the position of the M2 fast tip-tilt stage. Instead, the FTT stage is
controlled directly by the WFC system via a direct digital connection. The TEOACS is still able to
monitor the FTT position and continues to report the cStatus events. The TEOACS still maintains the
ability to control the source of position data through the Ethernet interface to the M2 FTT controller.
3.5 GIS RELATIONSHIP
[CUS-1306]
At all times the TEOACS monitors events from the GIS as specified by ICD 1.3-4.5. Should the GIS
alert the TEOACS of a fault condition, the TEOACS will respond by entering a default state. In this
state, the actuators will be in a safe, unpowered state. The TEOACS shall remain in the default state until
it is notified by the GIS that the fault has been cleared. At no time will the TEOACS be required to
participate in safety critical operation. Ensuring the safety of the equipment and/or personnel is the sole
responsibility of the GIS. The TEOACS shall only react so far as has been indicated within the
specification requirements.
Software Design Document SDD-32506 Rev A
10 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
4. SYSTEM DESIGN
This section describes the system design of the TEOACS and in particular its use of the ATST CSF. The
TEOACS design is constrained by the need to interact seamlessly with the rest of the ATST systems and
to use the CSF in its operations. The first subsections of this section therefore recap and summarize the
CSF design with regard to the use of configurations, and in particular the controller model. Subsection 4.7
then describes the controller model as applied to the TEOACS. Subsequent subsections then describe
other operations of the TEOACS that rely heavily on the CSF.
4.1 CONFIGURATIONS
Configurations lie at the heart of the ATST CSF. Configurations consist of a list of attributes and values
that the system receiving the configuration must match. CSF controllers do the matching of the
configuration’s attributes to the system’s attributes. The internal configuration of a controller can be set
up by issuing a series of set commands (section 4.4.12) or more usually by sending a complete
configuration with a submit command (section 4.4.7).
A configuration is a specialized form of an AttributeTable class that also contains a unique configuration
ID and header tag. An AttributeTable consists of a collection of Attribute objects each of which has a
name and value. Internally an Attribute value is stored as a string representation of the actual value, and
so multiple attributes of different types can be stored in the same AttributeTable.
Configurations go through a set of states during their lifecycle as illustrated in Figure 4. The controller
depending sets the state on which command the controller receives relating to the configuration. The
controller also sets the state when the action relating to the configuration completes (either successfully or
unsuccessfully). The commands are Submit, Cancel, Pause, Resume and Abort. The completion
possibilities are Done, Cancelled or Aborted.
A configuration is submitted to a controller using the submit() method. The controller then performs a
quick check of the attributes in the configuration to make sure the attributes are valid. The controller then
passes the attributes to the doSubmit() method to make sure that the combination of attributes make a
valid configuration. If the attributes do make a valid configuration the configuration is scheduled, and the
submit method returns OK. The acceptance or rejection of a command shall occur within 0.1 seconds. If
the configuration is not valid the submit method returns with a problem code. When the configuration’s
action starting time is reached (the default is for immediate execution) then the doCanRun() method is
called, providing a hook for final checking that the configuration can be executed at the current time. If
the doCanRun() method returns true then the doSerialAction() method is called followed by the starting
of an action thread. The action thread calls the doAction() method that does the required work to match
the component attributes to those of the configuration. Once the work is completed the method and action
thread complete. Three events are usually generated for a configuration action:
An event is generated when the actions is scheduled.
Another event is generated when the action is started.
A final event is generated when the action completes.
Configurations can be Cancelled/Aborted, which will lead to additional events being generated.
Software Design Document SDD-32506 Rev A
11 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Figure 4.1-1 Configuration States
When a configuration is cancelled using the Cancel command the TEOACS will take the following
actions:
1. If the configuration is queued then it will be removed from the queue and an abort event sent for it.
CSF provides this behavior.
2. If the configuration is running then the action thread propagates the cancel command to all the sub-
controllers involved in the configuration and then aborts and destroys the configuration. The propagation
of cancel commands is handled automatically when using the Base ManagementController. Action
threads must check for the abort status at regular intervals and then enforce the abort by terminating their
thread.
4.2 EVENTS
As well as providing configurations that can be sent from one controller to another, CSF also provides
events that can be used to signal changes of state or status. Although both configurations and events can
be used to pass data between controllers, they do so by different mechanisms.
Configurations require there to be a connection maintained between the two communicating controllers.
Events on the other hand use a publish-subscribe mechanism. The source of the data publishes it and then
any number of clients can subscribe. The publisher does not care how many, or who the subscribers are,
and there is no permanent connection between the two. If a publisher is not present then a subscriber
receives no events until the publisher is started.
In the CSF the data sent with events is encoded as an attribute table, i.e. the same data format used in
configurations. Arbitrary amounts of data can therefore be sent as an event; all a subscriber needs to
know is the name of the event so that it can register (subscribe) to receive it. Events are used internally
by the CSF to signal the matching of configurations and will be used extensively by the TEOACS to
report status, and also to receive the WCCS correction data for positioning the M2 hexapod.
Aborted Cancelled
Done
Paused
Aborted
Cancelled
Running
Queued
Initialized
Unknown
Cancel
Resume
Resume
Pause
Pause
Cancel
AbortMatched
Abort
Failed
Cancel
AbortReady
Submit
Create
Software Design Document SDD-32506 Rev A
12 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
To ensure the status of TEOACS items that change in a non-periodic or low frequency fashion are readily
available to other systems as events, these items, e.g. position of the Lyot stop, will be published by
controllers at 1Hz in a cStatus event. Every TEOACS controller will publish a cStatus event containing
its current status. The contents (attributes) of the cStatus event of each controller are defined in the TCS
to TEOACS ICD (ICD-1.3/4.4).
4.3 THE CONTROLLER MODEL
[CUS-1257]
An ATST CSF Controller implements what is called the command/action/response model. In this model
commands are separated from the actions they trigger. In this way many commands may be sent to a
controller resulting in many simultaneous actions, and in particular a controller is not blocked whilst
waiting for a previous command/action to complete. In the CSF commands are passed to controllers as
configurations; the configuration’s attributes describe the command in the form of values that must be
matched by the controller for the command to complete.
On receipt of a configuration describing the command’s values, the controller will send an immediate
response to the sender saying whether the attributes sent with the configuration are accepted or rejected
(within 0.1 seconds). It will then queue the configuration for either immediate or later action. Once
queued, the controller is ready to accept another command contained in another configuration. Separate
threads under the control of an action manager handle the actions started by configurations. Configuration
actions can complete as either Done, Cancelled or Aborted. Normal completion for a configuration action
is Done, but if an error occurs then it will be Aborted. This response is advertised by the posting of a
configuration action status event, which is automatically monitored by the CSF. Controllers can attach a
callback to perform processing on receipt of the action’s status event, if no further processing is required
the callback can be null. The action status event’s name is prefixed with the name of the controller
posting the event, as is the name of the attribute containing the event’s status value. The event name is
made up of this prefix and the text status. For example, if the controller atst.tcs.teoacs posts an action
status event, the name of this event is atst.tcs.teoacs.cStatus and this matches the name of the action status
attribute containing the event’s value.
Controllers accept a configuration as a parameter in the submit command. It is important for the
TEOACS to distinguish between the completion of an action and the state of an underlying piece of
hardware. A CSF configuration action is in the Running state until it is Done, Cancelled or Aborted.
This may or may not coincide with an underlying piece of hardware being physically stationary or not.
For example, if the Lyot stop is moved from the closed to open position, when the hardware reaches the
open position a signal must be sent to the action thread to tell the configuration it is Done. In this case the
hardware device stopping coincides with the configuration being Done. However, in the case of slewing
the mount, the action is Done when the mount first matches the position and velocity tolerances. The
mount will continue to track (move) and it would be incorrect to consider the configuration as still
Running because of this. Instead the configuration is considered Done when the mount is moving within
specified tolerance.
4.4 CONTROLLER LIFECYCLE AND COMMANDS
[CUS-1246] [CUS-1251]
During processing an ATST CSF controller moves through a well-defined lifecycle, as illustrated in
Figure 4.4-1.
Software Design Document SDD-32506 Rev A
13 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Figure 4.4-1 ATST CSF Controller Lifecycle
To trigger a transition between controller lifecycle states the commands Load, Init, Startup, Shutdown,
Uninit and Remove are used, these are described below. For configuration operations a controller
provides the commands Submit, Pause, Resume and Cancel. For low-level access to individual and
groups of attributes, the commands Get and Set are provided.
4.4.1 Load
This is not a command to the controller itself but the action of a container (or container manager) that
loads the controller from disk. This creates the controller by invoking the controller’s default constructor,
which places it in the Loaded state. During transition from Unknown to the Loaded state none of the CSF
services are available to the controller. For this reason a controller should do very little at load time and
constructors should be kept to an absolute minimum. The ideal constructor is empty. Once loaded, the
controller will be connected to the CSF. A controller should execute no functional behavior nor allocate
any resources in this state. If it is responsible for control of hardware, it must not attempt to connect to it
or move it.
4.4.2 Init
Initialization is the process of preparing a controller for operation, but stops short of starting that
operation. Typical steps taken during initialization include:
Metadata about the controller’s attributes is loaded.
Any special memory needs (fixed buffers, memory maps, etc.) are satisfied.
The CSF performs the first of these automatically. The latter is an action based upon the functional
behavior required of the controller and so is done by the individual controller.
No connections to hardware shall be made during initialization or while in the Initialized state.
4.4.3 Startup
Once in the Initialized state the startup command is used to progress to the Running state. The Running
state is the state for operational use. Only in the Running state is the controller able to accept functional
directives, checking if configurations are valid, and queuing them for actions. Whether the controller
actually acts on a submitted configuration will depend on whether any errors were encountered on
reaching the Initialized and then Running state. It may be that due to problems some or all configurations
will be rejected.
During startup, controllers responsible for hardware will make connections to hardware and read back
status. Controllers will avoid unexpected hardware movements during startup, particularly those that
might be hazardous. For example, it is not appropriate to automatically home hardware during startup.
Final
RunningInitializedLoaded
Initial
remove uninit shutdown
startupinitload
Software Design Document SDD-32506 Rev A
14 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Reaching the Running state is a necessary condition for a controller to be operational but for some
controllers it may not be fully sufficient. For example, a controller responsible for a tracking mechanism
will not begin tracking operations until specifically told to do so by the submission of a configuration.
4.4.4 Shutdown
Shutdown is essentially the reverse process of startup so any actions undertaken as part of startup should
be undone during the processing of the shutdown command, e.g., close hardware connections. Once
shutdown has completed the component state will return to the Initialized state and its capabilities must
reflect this. While in the Running state the controller may have executed many configurations that leave
mechanisms active, these shall be halted as part of the shutdown. For example if the azimuth carousel is
tracking it shall be stopped, motors powered down, and brakes applied.
Besides restarting the component, using the startup command, the only other operation available on an
Initialized component is the un-initialization of the component using the uninit command.
4.4.5 Uninit
This command is the reverse of init and will undo any actions that resulted from init command
processing. As a result of the uninit command the controller will return back to the Loaded state as if it
had just been loaded from disk.
4.4.6 Remove
As with the load command, the remove command is not a command to the controller itself but rather an
action of the container (or container manager). The action of remove is to remove the controller’s
instance from memory.
4.4.7 Submit
Once a controller is in the Running state it is ready to act on any configurations sent to it. Configurations
are sent using the submit command. On receipt of a submit command the controller will verify that the
configuration is valid. Once the verification is complete, the command thread queues the configuration
and signals the action manager. At this point a response is returned to the external source of the
command. The response is an integer representing the result of the submission; its value will be one of
the following:
OK (0) – The configuration has been accepted for action. This is the only code that will result in
the configuration being scheduled for action.
BUSY (-1) – The configuration has been rejected because the controller cannot perform any
additional simultaneous actions and cannot queue the submitted configuration.
BAD_PARAM (-2) – The configuration has an invalid parameter value.
MISSING_PARAM (-3) – The configuration is missing a parameter value that is required.
INCONSISTENT_PARAM (-4) – A parameter of the configuration is inconsistent with the other
parameters submitted in the configuration.
EXCEPTION (-5) – There is a runtime error in the submit code for the target controller.
NOT_RUNNING (-6) – The target controller is not in the Running state.
DUPLICATE (-7) – The configuration ID matches one already being acted upon.
NO_CONFIG (-8) – There was no configuration submitted.
Software Design Document SDD-32506 Rev A
15 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
SIMULATED (-9) – The request came from a component running in simulation mode.
Within the TEOACS, validation will consist of a number of stages:
The name of the attribute will be checked to ensure it is a valid attribute name. If any attribute
name is not a valid TEOACS attribute name then the configuration will be rejected with return
value BAD_PARAM. The alternative of simply ignoring invalid attribute names could lead to a
situation where a complex configuration is submitted with one of the attribute names spelt
incorrectly. The user might not notice that the configuration had been accepted but with one
attribute discarded in the process.
The value of the attribute will be range checked. Range checking is provided through the CSF
(property database) and is done by the CSF submit() method (see 4.1). If the value is out of
range then the whole configuration is rejected with the return value BAD_PARAM.
Conflict checking. This is a check that the configuration as sent contains no conflicting demands
and is done in the component’s doSubmit() method (see 4.1). For example setting the
hexapod power to off and also setting the position would conflict as the hexapod would
simultaneously be asked to move and to power it off. The configuration is rejected with return
value INCONSISTENT_PARAM.
If all validation checks are passed then the configuration is handed to an action thread for execution and
the OK value is returned from the submit command.
4.4.8 Pause
This command pauses the actions associated with an earlier submit command. During action processing
the action thread will check for the arrival of a pause command and if feasible, in the restraints of possible
hardware operations, the action will be paused. The action will be resumed on receipt of a resume
command.
The TEOACS does not accept Pause.
4.4.9 Resume
The resume command restarts actions previously paused using the pause command. The action thread
associated with the paused action will recommence its processing at the stage reached prior to arrival of
the pause command.
The TEOACS does not accept Resume.
4.4.10 Cancel/Abort
The cancel/abort command will remove a configuration from the queue if it has not yet been started. If the
configuration is already active then an abort signal is sent to the action thread and the configuration is
destroyed.
The actual operation carried out when a cancel command is received will depend upon the abilities
provided to stop ongoing hardware operations.
Software Design Document SDD-32506 Rev A
16 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
4.4.11 Get
This is a low-level command that can be issued to a controller once the controller is in the Initialized
state; it does not have to be Running for this command to be accepted. The get command can be used to
fetch the value of any attributes from the current internal configuration of the controller. If a get is called
without any specified attributes then the values of all attributes will be returned.
4.4.12 Set
This is a low-level command that can be issued to a controller once the controller is in the Initialized
state; it does not have to be Running for this command to be accepted. The set command can be used to
set the value of any attributes of the current internal configuration of the controller. These values will be
overridden if they are subsequently specified in a configuration that is submitted to the controller for
execution using the submit command.
4.5 ATST BASE CONTROLLERS
[CUS-1247]
The ATST application base is a suite of software that extends the ATST CSF beyond the technical
architecture. The application base includes controllers that provide generally useful functional behavior
that is not specific to a particular ATST system. Details of controllers contained in base can be found in.
TEOACS controllers are implemented by extending the following base controllers:
atst.base.management.action.ManagementController
atst.base.hardware.HardwareComponent
atst.base.hardware.HardwareController
atst.base.hardware.motion.MotionController
4.6 ATST BASE TECHNICAL ARCHITECTURE BLOCKS
Technical Architecture Blocks (TABs) are used to add technical code to a controller. A large portion of
the code in many of a controller’s methods is bookkeeping and error checking that needs to be done regardless of other operations. TABs are standalone objects that have some close relation to a controller
and are constructed in the controller’s namespace, i.e. TABs belonging to one controller cannot interfere
or corrupt another controller’s TABs.
The purpose of TABs is to remove the necessity to duplicate code that duplicates operations across
different controllers. The only duplicated code is registering the TAB with the superclass. Since TABs
are standalone and are iterated through, there is no fear of overriding methods from a superclass and
forgetting to call the superclass’s method. Since TABs are standalone objects they can be mixed and
matched as needed and there are no issues with multiple inheritances. Since each TAB only has to do one
thing it makes it easier to track down bugs, and modify behavior; bug fixes and modifications are made
once in the TAB not in every component using the TAB.
4.6.1 PropertyTAB
The PropertyTAB allows get and set calls to a controller to query or set the controller’s property
metadata. Every time that a controller’s get method is called the controller will iterate through a list of all
Software Design Document SDD-32506 Rev A
17 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
TABs that implement get()and call each of their get methods. In the case of the PropertyTAB, its get
method will look for queries of property metadata and fill in the appropriate values in the attribute table.
The PropertyTAB is automatically added to all controllers and so every TEOACS controller will contain
this functionality.
4.6.2 PostingTAB
The PostingTAB continually posts information from a controller that implements the IPoster interface. It
is configured using properties to setup its event channel name and posting rate. It can also be enabled and
disabled. This TAB simplifies the posting of regular attribute tables from controllers by taking care of
setting up the task, managing the timing of the task and ensuring it is created at init, started at startup,
stopped at shutdown and destroyed at uninit. Each TEOACS controller will use a PostingTAB to post its
cStatus event, and if applicable, its cPos event.
4.7 TEOACS CONTROLLERS
[CUS-1246]
The ATST controller model imposes a strict hierarchy on the control flow through the ATST control
system. This means that any attribute destined for a sub-controller must pass through a parent. This
means that attributes map directly on to the controller hierarchy. For example, the attribute
atst.tcs.teoacs.m2pos.aoMode may be sent from the TCS to the top-level TEOACS MangementController
atst.tcs.teoacs, which in turn will forward the attribute to the atst.tcs.teoacs.m2pos sub-controller. This
will be handled automatically as the top-level TEOACS MangementController is implemented as an
extension of the CSF base ManagementController class that provides this functionality.
A controller in the hierarchy may intercept an attribute and as a result generate its own configuration.
This will occur in the top-level TEOACS ManagementController, allowing multiple subsystem mode
changes by issuing just a few (or maybe one) attribute tables. An example of this would be the
atst.tcs.teoacs.mode attribute; when the top-level TEOA controller receives this attribute in a
configuration it will generate new configurations containing mode attributes for its subordinate
controllers, e.g. atst.tcs.teoacs.m2pos.mode and atst.tcs.teoacs.m2tt.mode. Whenever new configurations
are generated they are done so using the original configuration as a starting point. This ensures the
configuration ID is preserved (appended to) and consequently all configurations can be traced from the
originating configuration.
The TEOACS controller hierarchy is shown in Figure 4.7-1. This shows that all configurations flow
through the atst.tcs.teoacs ManagementController. The hierarchy and names used to identify the
controllers are defined in the TCS to TEOA ICD 1.3-4.4.
Software Design Document SDD-32506 Rev A
18 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Figure 4.7-1 TEOACS Controller Hierarchy
The roles of the TEOACS controllers are defined as:
atst.tcs.teoacs – This is the top-level controller for the TEOA. It is implemented using a class
that extends atst.base.management.action.ManagementController. It is responsible for managing
the lifecycles of the subordinate controllers and components of the TEOACS. All configurations
for the TEOACS pass through this controller.
atst.tcs.teoacs.m2pos – This controller is responsible for all operations on the PI hexapod
controller. It also maintains state, health, and status for the hexapod controller and forwards this
information to the TCS in event messages. This is implemented as an extension of the
atst.base.hardware.motion.MotionController class.
atst.tcs.teoacs.m2tt – This controller is responsible for all operations on the PI piezoelectric
controller which controls the fast tip tilt stage. The fast tip tilt assembly is implemented as a
hexapod. However, in practice only tip and tilt will be controlled. Therefore we reserve the
keyword ‘Hexapod’ to refer to the m2pos controller. The m2tt controller also maintains state,
health, and status for the piezoelectric controller and forwards this information to the TCS in
event messages. This is implemented as an extension of the
atst.base.hardware.motion.MotionController class.
atst.tcs.teoacs.lyot – This controller is responsible for all operations on the Lyot stop. It also
maintains state, health, and status for the Lyot stop and forwards this information to the TCS in
event messages. This is implemented as an extension of the
atst.base.hardware.HardwareController class.
4.8 PROPERTIES
[CUS-1246]
The property service maintains metadata about attributes in a persistent store (property DB). It provides a
mechanism that allows controllers access to this metadata as application-specific attributes. An example
of its use is the automatic range checking of attributes submitted to a controller within a configuration.
When a configuration is submitted, if a property exists for an attribute, the attribute’s value is range-
checked. Its read-only value is also checked. If either of these checks fails, the submission will be
rejected, e.g. if the value is out of range and/or the value is read-only.
This is provided as standard in the CSF and the TEOACS will complement this functionality with
additional use of the property service. In particular the TEOACS will use the property service to store
atst.tcs.teoacs
TEOA
Controller
atst.tcs.teoacs.m2pos
Hexapod Controller
atst.tcs.teoa.m2ftt
M2 Fast Tip-tilt
Controller
atst.tcs.teoacs.lyot
Lyot Stop Controller
Software Design Document SDD-32506 Rev A
19 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
saved values for many of its attributes. These saved values can then be restored after a reboot to bring the
TEOACS back into a fully operational state. The saved values will include (but not be limited to):
1. Correction lookup table values
2. IP and port numbers for actual hardware controllers
3. Named position data
At CDR, a more extensive list of properties to be stored in the property database shall be presented.
4.9 DEFAULT STATE
[CUS-1249]
All TEOA hardware shall have a defined default state. The default state of all hardware will be an inert,
non-moving condition. The TEOACS shall ensure all hardware enters this state on startup, shutdown or
on the assertion of an interlock condition. The startup command always asserts the default hardware state
and may be used at any time to re-assert the default state.
For the TEOA, the default hardware state will consist of simply powering down the controllers, where
possible. As required by specifications, entering the default state will not cause any motion to occur, nor
can motion be commanded while in this state.
4.10 HEALTH
[CUS-1246] [CUS-1253]
Every controller within the TEOACS will implement health categories. The health of a given category is
changed when needed. A health category does not necessarily need to be checked on a regular interval
but many of the health categories will be checked at a regular interval. The ATST health service takes all
the categories of a given controller and reports the health of the controller as the worst case of its’
categories. A health category is to UNKNOWN, ILL or BAD health, as appropriate, via a call to the
Health.set() method, giving an informative reason. If no reasons for poor health are found then the
health will be set to GOOD.
Health categories will usually be tied to hardware concepts. In computing health, the following set of
criteria will be used:
GOOD if hardware status is showing hardware can be fully controlled as required for operational
purposes, e.g. no interlocks and no failures are present.
ILL if hardware status is showing state of the hardware will enable control but not using its full
capabilities, e.g. no correction messages received within a set time period from the WCCS.
BAD if hardware status is showing hardware will be unable to operate and observing will be
unable to occur, e.g. interlock is present.
UNKNOWN if the hardware status hasn’t been checked yet.
In accordance with CSF guide lines, the health of TEOACS components will NOT depend on the health
of any components lower in the hierarchy e.g. the TEOACS ManagementController atst.tcs.teoacs will
not set its health to BAD if any of its sub-controllers set their health to BAD.
Software Design Document SDD-32506 Rev A
20 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
4.11 ALARMS
[CUS-1246]
The CSF alarm service provides a facility for raising alarms. Controllers can raise alarms in response to
exception conditions that require immediate operator intervention. The TEOACS may use the alarm
system provided by the CSF to notify the operator of any errors or problems that are detected. Examples
of alarms that the TEOACS may generate are:
1. TEOACS loss of communication with E-712, M-850 or digital I/O controller.
2. Management controller loss of communication with the sub-controllers.
Note: the implementation of Alarms in the CSF as of the date of the final design review (11/6) is not
finalized.
4.12 LOGGING
[CUS-1246] [CUS-1255] [CUS-1262] [CUS-1279]
The TEOACS will use the ATST CSF Log Service to log its system activity. In accordance with the CSF
the TEOACS will recognize messages of two types:
1. Status messages are messages that are always logged
2. Debug messages are only logged during diagnostic checks.
Both types of messages will be stored in a relational database. Messages generated through the log
service are automatically time stamped and tagged with the name of the component that generated them.
The ATST Log Service enumerates a number of different message categories. All TEOACS status
messages will be placed in the default category whereas debug messages will be placed into the most
appropriate category as defined in SPEC-0022-1.
4.12.1 Status Messages
The specifications require that the TEOACS controllers generate status messages at regular intervals. The
controllers shall use CSF to generate these messages. The messages and their contents are contained in
ICD 1.3-4.4. In addition, the CSF automatically generates other messages under the following
circumstances:
Lifecycle changes
Health changes
Connection changes
Commands and responses
Alarms
Software Design Document SDD-32506 Rev A
21 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
4.12.2 Debug Messages
When generating debug messages the TEOACS will make use of both message categories and debug
levels.
The category used will be taken from the list of categories provided in the CSF User Manual SPEC-0022-
1. The debug level of a controller is set through the lifecycle interface and applies to all code within that
controller. Unless used carefully this can lead to excessive numbers of debug messages. The TEOACS
will adopt the guide lines described in SPEC-0022-1 and in particular will only use level 4 messages
when absolutely necessary.
4.13 ENGINEERING SCREENS
[CUS-1284]
Several engineering screens will be available to implement independent (from the TCS) control of the
TEOACS. These screens will be developed using the JES package provided as part of the CSF. As the
JES is part of the CSF, this will ensure that the engineering GUI is fully integrated with the CSF platform.
The engineering screens will be capable of fully exercising the TEOACS. It will receive status messages
and send configurations so that all operations of the TEOACS can be tested. Although the engineering
GUI is capable of controlling the TEOACS, this interface shall not be required during normal operating
conditions
4.14 CONTROLLING DEVICES THAT TRACK
[CUS-1287] [CUS-1295] [CUS-1297] [CUS-1299]
The TEOACS is responsible for managing and controlling the position of the M2 mirror. The position of
the M2 is required to be dependent upon:
Demand position from the TCS (or engineering GUI)
Lookup table corrections based on temperature and gimbal position
WCCS data stream
WFC limb tracker data via PIO interface
All of these sources are used for commanding the M2 position, however, some are discarded depending
on the operational mode. The TEOACS can be placed in one of the following mirror control modes or
AO modes:
off – Hexapod and fast tip-tilt mechanisms are unpowered
passive – Hexapod and fast tip-tilt follow commanded positions. Hexapod uses lookup tables for
corrections
active – Hexapod and fast tip-tilt follow commanded positions. Hexapod uses lookup tables and
WCCS data for corrections.
The state diagram shown in Figure 4.14-1 illustrates the various tracking states of the TEOACS and the
possible state transitions.
Software Design Document SDD-32506 Rev A
22 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Figure 4.14-1 TEOACS AO Mode Transitions
4.14.1 WCCS Tracking
When the TEOACS is using the WCCS as an error correction source, the correction data received by the
TEOACS is interpreted as delta data. This data is accumulated and added to the last demand
configuration. This gives a new demand position that is then sent to the hexapod controller. This error
data is only used to correct the hexapod position. The accumulated error signal is not filtered or
processed in any way prior to adding it to the last demand position. None of these corrections are applied
to the fast tip-tilt stage. Regardless of whether the WCCS data is in use or not, corrections are still
computed from the lookup tables based on temperature and mount position. These are also added into the
offset summed with the demand position sent to the hexapod controller.
4.14.2 WFC Tracking
When the TEOACS is using the WFC as a tracking source, the absolute position of the fast tip-tilt stage is
controlled by the WFC through the PIO interface. When in this mode, the TEOACS will only monitor
the fast tip-tilt position. All configurations that modify the position are rejected. Note that no corrections
or lookup tables are implemented on the fast tip-tilt stage.
When the WFC is not in control of the fast tip-tilt stage, position commands are received from the TCS or
other CSF source and sent to the fast tip-tilt controller. When in this mode, the WFC does not need to
halt position data transmission since the position source is controlled via registers accessible from the
TEOACS. Continued data transmission does not affect the controller when in this mode.
4.15 POSITION FEEDBACK FOR THE TCS
The TEOACS shall provide position feedback of the systems contained on the TEOA. This position
feedback will be in the form of events that inform the TCS and other CSF systems of their status,
included in that is position. In addition to the status information is the transition of the controllers from
Running to Done. This transition signals that the condition specified in the configuration has been met.
The frequency and content of the status feedback events is detailed in ICD 1.3-4.4.
ao
active
passive
off
passive
active
shutdownstartup
off
ao
passive
active
ao
off
active
ao
off
passive
Software Design Document SDD-32506 Rev A
23 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
4.16 HARDWARE LIMITS
As much as possible, the TEOACS shall make use of any and all safety features of the base hardware
controllers (supplied by Physik Instrumente). When available, the following limits will be use to
maintain safe operation within the operational range.
Hardware Limits – Limit switches that remove power from the motors to prevent operation of the
actuator beyond design limits.
Software Limits – Limits in software that are imposed on the controllers and are intended to
maintain operation within safe limits. The software limits are programmable and shall be stored
in the property database.
The Lyot stop has two limit switches indicating the two positions of travel. Should both switches become
activated at the same time (indicating both open and closed), the TEOACS will flag this condition as an
error, disable the Lyot stop, and change its health to BAD.
4.17 FAILURE MODES
This section describes possible failure modes of the TEOACS, how the failures are handled, and potential
consequences.
4.17.1 Responding to Invalid Data
Attributes sent to the TEOACS are automatically range checked using the property DB. Configurations
consisting of multiple attributes are checked for consistency. If either of these checks fails, the
configuration is rejected.
The first of these checks could fail if the property DB were incorrectly configured and allowed a value to
be entered outside of a normal range. The second check could fail if the coding was done incorrectly and
allowed an inconsistent configuration to be executed. In either case, the hardware would not be at risk of
damage due to the limits imposed on the system by the actual hardware. The actuators cannot be driven
past their physical limit switches without the actuators being disabled.
Should the invalid data cause the CSF controller to crash, it is presumed that the loss of the cStatus
message from the controller would be noticed by the recipient and an alarm would be raised or it would
change its health status.
4.17.2 Responding to Invalid Trajectory Data
Should the TEOACS receive invalid data from the WCCS, it will be range-checked prior to being sent to
the hexapod. Should the range check succeed (i.e. bad property ranges) and the data is used, the internal
limits on the hexapod will prevent the actuators from moving beyond their normal operating range.
In the case of the WFC, that data is sent directly to the fast tip-tilt controller and is not range checked by
the TEOACS. Should this data be outside of the operational range, the fast tip-tilt controller will limit the
motion and maintain it inside of a safe range.
Software Design Document SDD-32506 Rev A
24 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
4.17.3 Internal Failures
The TEOACS is required to monitor the state of its sub-controllers and reflect any failures of these sub-
controllers. Failure here is in respect to a failure in sub-controller processing, not a failure of an actual
hardware controller, hardware failures are coved in section 4.17.4.
The TEOACS top-level ManagementController atst.tcs.teoacs is responsible for maintaining a record of
the state of its sub-controllers and for maintaining open connections to them for submission of
configurations. Each sub-controller present in the TEOACS system will post a cStatus event at 1Hz.
This will contain status specific to its operations, e.g. position of hardware, etc. The atst.tcs.teoacs top-
level controller will subscribe to these events and, if they do not arrive, it will attempt to determine the
cause. If communications with the sub-controller can no longer be established, the atst.tcs.teoacs
controller will set its health BAD with a message explaining the cause.
4.17.4 Failures of TEOA Hardware
The TEOACS can only control the M2 hardware through its connection to the hexapod and fast tip-tilt
controllers. If these connections fail or the hardware controllers report an internal failure, the appropriate
TEOA sub-controller will set its health to BAD with a message explaining the cause.
If a connection failure occurs, the sub-controller using that connection will discover this when it attempts
to write data to the hardware controller or read status.
Software Design Document SDD-32506 Rev A
25 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
5. USE CASES
The use cases presented in the following sections are based on information derived from the TEOA
specifications, statement of work, and CSF documentation. These use cases are intended to document
operations that would be executed during routine, normal operation. When inspecting the following use
cases, it is important to remember that the incoming messages can also be generated by the Engineering
GUI for a test scenario. The use cases are presented in groups by Controllers. Each controller has a
group of use cases that are documented.
Universal to all use cases are the possible actors that can be used:
1. TCS – The TCS may originate configurations or it could be the subscriber to events.
2. System Database – The system database or the CSF server may originate configurations or be the
recipient of TEOACS events.
3. GIS – The TEOACS subscribes to events from the GIS so that it may properly respond to
x:namedPos String choice see below Named demand x position
y:namedPos String choice see below Named demand y position
z:namedPos String choice see below Named demand z position
tip:namedPos String choice see below Named demand tip position
Software Design Document SDD-32506 Rev A
38 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
tilt:namedPos String choice see below Named demand tilt position
rot:namedPos String choice see below Named demand rotation position
x:stowPos Float mm ?range Value of the x stow named
position
y:stowPos Float mm ?range Value of the y stow named
position
z:stowPos Float mm ?range Value of the z stow named
position
tip:stowPos Float arcsec ?range Value of the tip stow named
position
tilt:stowPos Float arcsec ?range Value of the tilt stow named
position
rot:stowPos Float arcsec ?range Value of the rotation stow named
position
x:posTol Float mm ?range Position x tolerance
y:posTol Float mm ?range Position y tolerance
z:posTol Float mm ?range Position z tolerance
tip:posTol Float arcsec ?range Position tip tolerance
tilt:posTol Float arcsec ?range Position tilt tolerance
rot:posTol Float arcsec ?range Position rotation tolerance
Name Type Units Range Comment
atst.tcs.teoacs.m2tt
power boolean boolean off | on Turn system power off or on
namedPos string choice see below Named demand position
statusRate Float Hz ?range Rate of status event updates
eventGIS String ? ? String of GIS fault event to subscribe
portTiptilt String ? ? Device name for tip-tilt
communications
tip:pos Float arcsec ?range Demand tip position
tilt:pos Float arcsec ?range Demand tilt position
tip:namedPos string choice see below Named demand position
tilt:namedPos string choice see below Named demand position
tip:stowPos Float arcsec ?range Value of the stow tip position
tilt:stowPos Float arcsec ?range Value of the stow tilt position
tip:posTol Float arcsec ?range Position tip tolerance
tilt:posTol Float arcsec ?range Position tilt tolerance
Name Type Units Range Comment
atst.tcs.teoacs.lyot
pos string choice in | out Demand position
powered boolean Boolean on | off Power state
statusRate Float Hz ?range Rate of status event updates
Software Design Document SDD-32506 Rev A
39 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
eventGIS String ? ? String of GIS fault event to subscribe
portIO String ? ? Device name for digital I/O
communications
6.3 IMPLEMENTING THE COMMUNICATION BETWEEN THE TEOACS AND TEOA
HARDWARE CONTROLLERS
The software used to communicate with the hardware controllers is designed to be implemented in Java
for the Hexapod and Fast tip-tilt controllers. For the Lyot Stop controller the communication layer is
designed to be implemented using the JNI with the Acromag ESW-MBLIB Modbus C library. However,
since the Acromag ESW-MBLIB library is provided as C source code and not a compiled library, it is
possible that equivalent code could be written in Java much like the strategy for the Hexapod and Fast tip-
tilt. The pros and cons of each method will be weighed at the time of purchase of the Acromag library.
The Java communication implementation for Hexapod and Fast tip-tilt will consist of making a class that
extends the CSF base Connection class and a channel class which implements the IChannel interface.
The connection class is the interface the controller level class has to specific hardware related activities.
The channel class will hold the implementation where messages go out on the communication physical
layer.
The connection and channel classes will implement the producer/consumer pattern for communication
where messages are fed into and out of a message queue. This pattern has been successfully implemented
on other L-3 products. There will be producer and consumer threads on the read side and a consumer
thread on the send side. The send side producer thread is implemented in the controller level class whose
behavior is based on the state of the controller.
On the send side the controller level class, inside the producer thread, will call public methods in the of
the connection class. In each of these public methods a message is placed into the message send queue.
If the queue is full the connection class method shall not block. The send queue size shall be optimized
for the particular application and a health category will be implemented to indicate issues with the queue
itself. If public method is related to a query the message will be placed into an additional query queue.
The send consumer thread is implemented on the channel side. This thread will empty the send queue
and send messages over the physical communication layer (Ethernet in this case). The send consumer
thread will have the ability to be optimized for hardware specific timing limitations. Often
communication firmware on the target device cannot handle messages that come in too frequently. In this
design the optimization of spacing between messages is decoupled from the higher level software to
enable smooth communication. The programmer must be cognizant of the rate at which messages are
going into the queue at the higher level and the rate at which it is being emptied to not cause a back up in
the send queue.
On the read side, the channel class has the read producer thread. The read producer thread simply sits on
a blocking read of the physical communications layer. When bytes come in they are put through a
framing algorithm to determine the conditions for end of message. When an end of message has been
detected then the message is compared with the message that was supposed to be coming. This is done by
popping off the head of the query queue and using message validation to ensure the type of message.
When the message has been validated it is put in to the read queue. If message validation is not
implemented efficiently enough, the consequences would be not reading the physical layer
communications fast enough. If that occurs the alternate scheme will be to do minimal validation of the
Software Design Document SDD-32506 Rev A
40 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
message and place the message into a generic container message. Further validation and query queue
related logic would be done on the read consumer side.
The read consumer thread is implemented on the connection side. This thread will empty the read queue
and call an appropriate message handler for each message.
The overall architecture is illustrated in Figure 6.3-1.
Container Namespace
Hexapod Controller
Namespace
Fast Tip-tilt Controller
Namespace
Lyot Stop Controller
Namespace
Hexapod Controller Fast Tip/Tilt ControllerLyot Stop Controller
Physik Instrumente
M-850 Hexapod
Controller
Physik Instrumente
E-710 Digital Piezo
Controller
Acromag 983EN
Digital I/O Module
Hexapod ConnectionFast Tip/Tilt
ConnectionLyot Stop Connection
JNI
Acromag Library
TEOACS Management
Controller Namespace
TEOACS
Management
Controller
Figure 6.3-1 TEOACS Namespace Overview
6.4 TEOACS JAVA PACKAGES
[CUS-1278]
Table 6.4-1 below shows the Java packages that implement the TEOACS.
Software Design Document SDD-32506 Rev A
41 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Table 6.4-1 Java packages for TEOACS
Java Package Name CSF Controller Supported Description
atst.teoacs atst.tcs.teoacs This package contains the classes that implement the TEOACS management controller.
atst.teoacs.m2pos atst.tcs.teoacs.m2pos This package contains the classes that implement the TEOACS M2 Hexapod controller.
atst.teoacs.m2pos.connections atst.tcs.teoacs.m2pos This package contains the classes that implement the communications layer of the TEOACS M2 Hexapod controller.
atst.teoacs.m2tt atst.tcs.teoacs.m2tt This package contains the classes that implement the TEOACS M2 tip tilt controller.
atst.teoacs.m2tt.connections atst.tcs.teoacs.m2tt This package contains the classes that implement the communications layer of the TEOACS M2 tip tilt controller.
atst.teoacs.lyot atst.tcs.teoacs.lyot This package contains the classes that implement the TEOACS M2 lyot stop controller.
atst.teoacs.lyot.connections atst.tcs.teoacs.lyot This package contains the classes that implement the communications layer of the TEOACS M2 lyot stop controller.
atst.teoacs.interfaces ALL This package contains interfaces that are used throughout the TEOACS.
atst.teoacs.TFault ALL This package contains the implementation of the fault handling system used throughout the TEOACS. Each fault is actually a health category.
atst.teoacs.TMessage ALL This package contains the implementation of the hardware messaging used for communicating with TEOACS hardware controllers. Each message is a Java class with it’s own unique handler and callback context.
atst.teoacs.util ALL This package contains the support classes that are used throughout the TEOACS. Java enumerations, thread abstractions and other utilities are there.
The Java packages seen in Table 6.4-1 above contain the TEOACS application specific classes used to
create the TEOACS controllers. These classes contain the logic of how to translate received
configurations into operations using the communication software layer to the various hardware
controllers. Representative top-level class diagrams are shown in following sections. To see full class
diagrams documenting the interactions of all classes please see Appendix A.
Software Design Document SDD-32506 Rev A
42 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Table 6.4-1 shows which TEOA related CSF controller is supported by the Java package listed in the left
column. The names of packages and CSF controllers seen in this table are very similar. Since Java
enforces a folder layout according to the package name it is important not to confuse Java package name
with controller name. Class name and controller name are linked in the App database when a Container is
defined. In this design document we will be referring to the CSF controller names almost exclusively.
Specific customer direction has been given on the location of TEOACS Java files within the larger ATST
folder hierarchy. The Java package names seen in Table 6.4-1 reflect the appropriate place in the folder
hierarchy to place TEOACS code.
Note that the *.interfaces, *.[controller Name].connections, and *.util package names (where ‘*’ is
atst.teoacs) seen in Table 6.4-1 loosely follow an organizational convention that the customer has for Java
code.
6.4.1 Management Controller atst.tcs.teoacs
The TeoaManager class extends the CSF ManagementController class and implements the IPoster and
ITeoaManager interfaces among others. This class forms the implemention of the atst.tcs.teoacs
controller. A full class diagram for the TeoaManager can be seen below in Figure 6.4-1.
Figure 6.4-1 The full TeoaManager class diagam
TEOA Manager Class Summary
Software Design Document SDD-32506 Rev A
43 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.
Table 6.4-2 Table caption here
Name Documentation Type Type Modifier Multiplicity
m_mode TEOA Management Controller
Mode of operation int
Unspecified
m_statusRate Rate for status update messages to
the TCS. double
Unspecified
m_eventGIS Name of event to use as the source
for GIS fault events. string
Unspecified
6.4.2 Sub-controller atst.tcs.teoacs.m2pos
The M2Hexapod class is an extension of the CSF MotionController class and implements the IHexapod
and IThreadContext intefaces. This class forms the implementation of the atst.tcs.teoacs.m2pos
controller.
M2Hexapod Class Summary
Name Documentation Type Type Modifier Multiplicity
m_altitude Last altitude value received from
TCS. double
Unspecified
m_aoOffset HexapodPos
Unspecified
m_aoZero Clear all built-up errors on M2 boolean
Unspecified
-m_InUse : boolean
-m_Entries : int
-m_Position : HexapodPos
-m_luEntry : double
+AddEntry(LookupEntry : double, Position...
+GetEntry(Value : double) : HexapodPos
+InitTable(Entries : int) : int
LookupTable-x : double
-y : double
-z : double
-tip : double
-tilt : double
-rot : double
+SetPosition(x : double, y : double, z : dou...
++() : HexapodPos
+-() : HexapodPos
+Zero()
HexapodPos
Hexapod
-m_altitude : double
-m_aoOffset : HexapodPos
-m_aoZero : boolean
-m_azimuth : double
-m_demandPos : HexapodPos
-m_eventGIS : string
-m_eventTCS : string
-m_hexapodPos : HexapodPos
-m_lutAlt : LookupTable
-m_lutAz : LookupTable
-m_lutStatic : LookupTable
-m_lutTemp : LookupTable
-m_M2Hexapod : M2Hexapod
-m_namedPos : string[]
-m_offset : HexapodPos
-m_port : string
-m_powered : boolean
-m_state : int
-m_statusRate : double
-m_stowPos : HexapodPos
-m_tolerance : HexapodPos
+EnableCorrections()
+GetStatus() : long
+M2Hexapod()
+SetState(NewState : int)
+SetPosition(NewPosition : HexapodPos) : int
+SetCorrection()
+SetOffset()
M2Hexapod
Software Design Document SDD-32506 Rev A
44 L-3 Communications PROPRIETARY
This page is subject to the restrictions on the title page.