Ground Tests Commanding Manual

This document describes the usage of the PLATO Common-EGSE to command the PLATO camera (SUT) and the ground support equipment (GSE) during the PLATO camera ground testing.

Throughout this document, we use the following notation:

The user interface to the PLATO camera EGSE is a software application developed at KU Leuven in collaboration with the test houses for site specific components. It provides graphical user interfaces to control the software processes in the system, monitor telemetry parameters, provide the operator with quick-look analysis images of the camera detectors, etc. It also features a commanding interface in Python. The commanding logic is entirely defined in Python. The hardware interfaces have been implemented in Python (possibly accessing a library written in the C programming language), and the user is accessing these by executing higher-level Python functions in a Python interpreter.

Typical flow of events and responsibilities:

This commanding manual is mainly targeted at the test developers, the test operators and the analysts. The site-operators and site-developers will find most of the information they need in the Common-EGSE installation manual and user manual.

This repository contains the background infrastructure to interface with the actual hardware in the test housess. The complete documentation can be found in the link above, and in RD-02, see Reference Documents.

In a nutshell, it provides access to all the necessary functions to

The THs are expected to contribute to this repository, to implement the interfaces to their own environment and devices, so they should fork this repository in order to be able to create pull requests.

The test-operators are not expected to contribute to this repository, so they should clone the repository.

This repository contains the Python scripts

The commanders and the THs are expected to contribute to this repository, so everyone should fork it.

This repository holds the setups saved during the tests under configuration control. The concept of setup is explained in Chapter 6.

No one is expected to contribute directly to this repository as it is maintained by the Common-EGSE. The repository can be cloned for inspection.

Operators use the software installation at the test house on the operational machine. The installation is read only and under configuration control. Only official releases shall be installed on the operational machines. The installation is maintained by the site-operator. Please refer to the on-line documentation of the Common-EGSE for full installation details.

The test-developer uses an installation that is more suited for development of scripts and can be changed. The test-developer has forked the repo on the GitHub website to her personal GitHub account and clones the repo from that account. She works in a virtual environment. Please refer to the Common-EGSE on-line docs for full details.

Please note that the installation examples above are simplified and serve as a reminder. The full installation process is detailed in the on-line Common-EGSE documentation.

The table below summarises the coding style that we have adopted for this project. More detailed information can be found in the on-line documentation at github.io: Development notions: Style Guide

At the user level, the PLATO commanding resides upon a few key concepts

More information on some of these elements are given in the next sections. The figure below describes the generic software architecture in place for the PLATO commanding:

The execution of a test is triggered by the Python function execute(). Like @building_block, it is a core functionality implemented by plato-test-scripts. It can be used with the following syntax:

All parameters must be specified by their name. No positional argument is allowed; hence the order of the parameters is not important. Note that the building block name does not have the paranthesis '()', only the name of the building block is given.

The execute command will start an observation and end the observation when the building block returns. Starting and ending an observation is an expensive operation in the sense that it notifies underlying mechanisms like the configuration and storage manager of the observation so they can take action. Therefore, although any building block can be executed using the execute(..) command, this should really only be used for higher level building blocks and from the Python prompt. Never use the execute(..) function inside a building block.

It is possible to perform a dry-run of a building-block by running generate_command_sequence() instead of execute(), with the same syntax. Be aware that the duration of the dry run may be as long as the execution itself!

This feature will execute all building blocks and functions without actually sending command strings to the test equipment. The current implementation does not take return values from device queries into account which makes it less suited for test scripts that need this feedback for conditional processing, e.g., waiting until a temperature is reached.

Note that execute and generate_command_sequence will only work under a set of restrictive conditions

The execute command will trigger the creation of an obsid and an associated data stream. In the case were the operator (e.g. while setting up and testing the TH environment) want to execute short commands or building blocks outside of the scope of a test-script, this is an overkill and will make the analysis of the resulting data very cumbersome, because the data will be distributed over many very very short obsids.

To work around this, it is possible to manually start and stop an observation

Will start an observation, attribute it an obsid and the associated data stream, just like what happens at the start of an execute.

After that any command passed (individually or within a function/building block) and any data generated will be recorded as part of the running obsid:

Finally

Will close the observation (or do nothing if none is running).

The acquisition of housekeeping telemetry is automatically started by the egse-server. In practice that means that the telemetry from all devices connected to the active egse-server is automatically, and constantly recorded (see the Common-EGSE documentation for further details).

The housekeeping telemetry is structured this way

The csv filenames have the following structure:

Where:

For example, the daily file at CSL for the Hexapod PUNA housekeeping on June 8th, 2023 is 20230608_CSL_PUNA.csv. The header of the CSV files contains explicit column-names. The complete information on the content and format of the telemetry files is contained in the ICD (RD-04, see Reference Documents).

Image data are usually only generated during a test execution. In order to facilitate the selection of data pertaining to a particular test execution, we are using the concept of ‘observation’ interchangeably with the name “test”.

An observation corresponds to a single execution of a given test, i.e. a single use of the execute() command, or all commands executed between a start_observation and an end_observation.

A unique obsid is automatically attributed to every observation. The filenames of housekeeping files are constructed from the unique obsid and a limited set of useful metadata about the test execution, with the following structure:

where:

The first three items in the above list form the full OBSID. The OBSID can be abbreviated to the TEST-ID and the SITE-ID thereby omitting the SETUP-ID which can be automatically recovered from the meta data.

For instance, CSV files for observation 00757 performed at CSL could be:

(PUNA points to a hexapod controller and CM refers to the Configuration Manager of the Common-EGSE).

For FITS files with the camera image data, the naming convention is similar (though we leave out the timestamp), with a sequencing number when the data volume justifies splitting of the data over multiple files.

Note that we used to have two types of FITS files: FITS files in which the data is organised in a flat structure, and FITS files in which the data is organised in cubes (with filenames as described above). The former will have "image" in their names (rather than "cube") but will be removed once the corresponding cube-structure FITS file has been created.

All data corresponding to the obsid are gathered in a dedicated directory named ‘obs’. That means that the fraction of the regular housekeeping data acquired during the execution of the observation is duplicated in that directory, keeping the same format as in the “daily” directory.

The data is hence stored in two different directories:

Image data are saved for each test execution as FITS files, with the corresponding housekeeping in csv files (see above).

Images are saved in FITS format, as UNSIGNED integers. You will have to cast them to float explicitly in python to avoid negative numbers to be wrongly interpreted.

Splitting: The DPU monitors a set of "crucial parameters" (see further) and each time at least one of these changes, a new FITS file will be created, provided the FEE is in full-image mode (or full-image pattern mode). Additionally, a maximum number of extensions is specified in the configuration (TBD). When that number is achieved, the image data are split, i.e. a new FITS file is opened to store the next block of image data.

Slicing: In a future version of the software, it will be possible to insert a given command in the test scripts in order to force the creation of a new FITS file. This will allow for a more flexible slicing of the data, i.e. enforce a clearer structure of the data, matching the commanding logic, and will facilitate the data analysis and interpretation.

Crucial parameters: As mentioned before, the DPU monitors (for changes in) crucial parameters. These are:

The complete telecommand history is not yet saved but can be reconstructed from the setup_id (see below) and the obsid-table. The obsid-table.txt is a text file located at the root of the data storage location. The file contains one entry per observation, associating

The following lines are examples taken from the obsid-table.txt file at CSL:

The obsid-table.txt file is explained in more detail in the Interface Control Document (ICD) [RD-04].

A snippet of a setup file is shown below. It shows the tree structure of the YAML file. At the top level are the main components: gse (devices), camera (fpa, tou, fee), telemetry, etc. The snippet only shows part of the Setup. Under the gse branch we have hexapod and stages and many more that are not shown. All ground equipment that is part of the test setup shall have an entry under the gse branch. The information that shall go into these entries is device identification, calibration information, specific device settings, etc.

Everything that is connected to the Camera, i.e. SUT, shall go under the camera branch. This is e.g. identifiers for the TOU, FEE, FPA, DPU, CCD, …​, calibration information, defaults, numbering, avoidance information, etc.

The users are allowed to modify or add items and branches to the setup and save a new version of it. As an example, the stages branch in this example contains calibration values defining metrology of the rotation and translation stages used to position the light beam at CSL.

You can check the version of the Setup with the following command:

The number printed on your system will be different.

Setups will be available in the form of YAML files that are stored in the plato-cgse-conf repository and are located (probably) at ~/git where the repos are kept.

Browsing through the available setups can either be done in Python or via a GUI.

After inspection of the available setups, a specific setup can be loaded, based on the identifier.

Ideally, the Setup will be loaded one single time at the start of a test phase, with a setup reflecting the HW present in the test environment. The preferred way to do so is via the setup GUI. That can be launched via

In python:

The above command will load the Setup in the configuration manager and also in the Python console you used to execute the load_setup() command.

You can check which Setup is loaded in the core services using the status parameter:

Also the process manager (pm_ui) and the Operator GUI (e.g. csl_ui) indicate which Setup is loaded, but keep in mind that this is only true for that particular process and is not necessarily propagated to all processes running in this distributed environment.

First, make sure a Setup is already loaded in the system, and that you have a variable attached to a setup in your Python session. Here we call it setup.

You can get a Setup with the following command

This will read the content of Setup "00007" for the site you are currently at and assign it to a variable called setup.

The setups are stored under configuration control in the plato-cgse-conf repository. The EGSE is taking care of the interface with that repository when a user is submitting a new setup, with no additional action necessary than:

The new setup receives a unique setup_id, and a new entry is created in the list of setups. The new Setup is then loaded and made active in the configuration manager. When the Setup is processed by the system, brought under configuration control and no errors occurred, the new Setup is returned and will be assigned to the setup variable. In case of a error, the response contains information on the cause of the Failure and is printed.

The following states have been defined for the EGSE system, as depicted in Figure 4:

The transitions between these states are all handled by the Process Manager GUI. Under the hood, the Process Manager queries the setup (from the Configuration Manager) for information on the relevant processes. A distinction is made between core and devices processes.

The following processes are considered as Common-EGSE core processes (depicted in the left panel of Figure 5]) and should always be running:

These processes are started automatically when the egse-server is booted. They cannot be re-started nor shut down via the Process Manager GUI; they can only be monitored there.

The device processes (depicted in the middle panel of Figure 5) are the so-called Control Servers that talk to the hardware Controllers (depicted in the right panel of Figure 5), for commanding and monitoring the devices.

These processes can be (re-)started and shut down individually from the Process Manager GUI. They will be running on the same machine as the Process Manager itself, which is the egse-server during normal operations.

A desktop icon will be provided to start the Process Manager GUI. Alternatively, it can be started from the terminal command line with the following command:

This will fire up the GUI shown in Figure 6.

On the top left, an overview of the core services will be given. When a (new) Setup is loaded (see Section 6.3]), the content of the right part (with the device control servers) will be updated. Only the processes for the devices that are included in the current Setup will be shown.

A led in front of the process name will give you a quick impression of the state of the process. It can have the following colour for device processes:

For the core processes, the led should always be green (indicating the process is running). In case one of them turns red, the corresponding core process is no longer alive, and the system may have to be re-started. Consult your site-operator in this case.

For the processes for which a "GUI" button is present, a GUI for the corresponding device can be opened in a separate window by pressing this button. A GUI for any device can be opened only once.

In contrast to the core processes, the device processes can be started from the Process Manager GUI, either in operational mode (when a hardware Controller is available) or in simulator mode (when no hardware Controller is available; for testing purposes).

Errors, warnings, general debugging or any useful information can be logged using the logging infrastructure. The logging infrastructure will take care that the messages you generate are stored in the log files associated with the measurement. It also takes care of visualising the messages to the operator.

Log levels: CRITICAL, ERROR, WARNING, INFO, DEBUG

To log a message in your script:

This will print a log message in the REPL and send a log record with the message to the Logger. Messages for any of the above levels will end up in the Common-EGSE log file, but only messages of level INFO and above will also be printed in the terminal. So, if you need to check any debugging messages, make sure you check the log file at $PLATO_LOG_FILE_LOCATION.

Inevitably, the code other developers write will generate error and exceptions. Whenever you expect an exception and you know what to do with it or how to handle it, catch it with the following construct:

If you cannot handle the error, just let it pass to the next level in you script and eventually to the top building_block.

There is a fully detailed description of exception handling in the on-line Common-EGSE documentation in the section Exception Handling of the developer manual.

Figure 7 below shows the schematic overview of the focal plane with the four CCDs. The focal-plane reference frame (x_FP, y_FP, z_FP) is associated with the focal plane of one camera. Its origin is in the middle of the four CCDs (indicated by the blue dot in the figure) and the z_FP–axis coincides with the optical axis (pointing towards the reader). The coordinates in the (x_FP, y_FP) reference frame are typically expressed in mm.

Each of the four CCDs has its own CCD reference frame (x_CCD, y_CCD) assigned to it (indicated with the small arrows in the figure). When keeping the readout register of a CCD at the bottom, the origin of the associated CCD reference frame is at the lower left corner of the CCD. The parallel charge transfer happens in the negative y_CCD direction; the serial charge transfer in the readout register happens in the negative x_CCD direction for the left detector half and in the positive x_CCD direction for the right detector half. The coordinates in the (x_CCD, y_CCD) reference frame are typically expressed in pixels (where a pixel measures 18µm in both directions)

Alternatively, the position in the focal plane can be expressed in field angles (θ, φ), as shown in Figure 8. The angular distance to the optical axis (marked with a blue dot in the figure) is denoted by angle θ, whereas φ represents the in-field angle, measured in counter-clockwise direction from the x _FP axis.

The following coordinate conversions can be imported from egse.coordinates:

The setup file is a configuration file, part of the CGSE, describing all components and calibrations of the actual test article, test equipment, and test environment. In addition to holding some information like the ensemble of reference frame definitions (in CSL) or the history, it consists of two main components: a first describing the GSE and gathering the information over the test environment (devices control and calibration, temperature sensors, …), and a second describing the camera, i.e. gathering all the information over the description and calibration of the test articles (TOU, FPA, FEE…).

The setup is a YAML file, i.e. a hierarchical “dictionary” (in the python sense of the word). Items can be referred to by a [key, value] pair, where the key refers to their location in the hierarchy and consists of the full path to that location, e.g. setup.gse.stages.calibration.phi_correction_coefficients: [-0.0014, -0.003]. The value can be a built-in type (int, float, str, …), a serialized object, a list, or the path to another calibration file. A more detailed explanation of the Setup is in Chapter 6.

The setup is under configuration control in the GitHub repository plato-cgse-conf and new setup versions are created exclusively on the server or client machine of the cleanroom for which the setup is intended.

This chapter describes the values susceptible to change when the components of a new camera are integrated on a test setup in CSL. The goal of this chapter is to provide a step-by-step procedure for the creation of the new setup, including the source of information for every item to update.

At the time of writing, several setups do already exist that include the calibration of the GSE components on both test setups in CSL (“CSL1” and “CSL2”). So this document assumes their pre-existence rather than creating them from scratch every time again.

Setups exist and are maintained in different configuration directories (and in GitHub) for every test environment, so every test chamber has its own numbering for the setups SETUP_<SITE>_<NUMBER>_<date>_<time>, e.g. SETUP_CSL1_00065_230407_091711.yaml (the date and time are automatically included at creation time). The <NUMBER> is sequentially incremented for each new version of a setup and is not reset for each new camera.

TBW

Camera configuration & ABCL:

CAM ID : from PLATO-CSL-PL-PR-0019 version 1.1

TOU is the usual reference FM#n.

DEAD : from AD01 (original reference: PTO-EST-PL-TN-1369 version 1.0)

Metrology

TODO: link the TOU & FPA Ref. to their EIDP in Eclipse ?

To be allocated to the right camera:

This section describes what is done during the Camera Switch ON procedure, i.e. by running the task 'Camera Switch ON' in the Operator GUI. Although the individual steps are explained in detail, you should still run the Camera Switch ON task instead of each step separately. Only use the individual commanding when in a contingency.

The AEU Test EGSE shall be on StandBy mode before we start. You can check that in the AEU GUI where the Stand-by LED in the left panel (EGSE mode) shall be green.

Step 1. Send commands to the AEU to power on the camera and enable the sync signals

The AEU Test EGSE is now ready to power the camera and enable the synchronisation. This is the first step in the procedure. The individual task is: Task GUI > Camera TAB > 2 — AEU > Switch ON. From the Python REPL^[1], you can execute these commands:

The camera shall now be in ON mode (check this in the DPU GUI) and the AEU GUI should have the following LEDs turned green: 'Functional check & TVAC', 'N-CAM', all power lines

At this point, the Camera Switch ON procedure will perform a few additional tasks that are not done when you execute the individual steps:

Step 2. Send the FPGA defaults to the N-FEE

Each camera N-FEE requires a update of a number of FPGA parameters in the register map. That is what we call the FPGA defaults. Please note that these settings are camera specific and influence the proper readout of the CCDs, so it’s important that this step is executed at the right time in the procedure. The individual task is: Task GUI > Camera TAB > 3 — N-FEE > Set FPGA defaults. From the REPL you can execute these commands:

The user will be prompted to confirm the values have been correctly applied in the N-FEE FPGA.

The FPGA defaults are read from the current Setup. In the Setup there is an entry setup.camera.fee.fpga_defaults that loads the YAML file with the correct values for the camera. The values are expressed as registers (32bit values) and not as individual parameters. You can inspect the values as follows:

Step 3. Go to STANDBY mode

Now, the camera will be brought into STANDBY mode. This means the CCDs will be powered and start accumulating flux. The individual task is: Task GUI > Camera TAB > 3 — N-FEE > To STANDBY mode. From the REPL, the command is:

In the Camera Switch ON procedure, the user will be prompted to confirm the N-FEE is actually in STANDBY mode.

Again, the procedure will check the AEU cRIO voltages and currents and print an overview table. Please note that the configured limits are different for ON mode, STANDBY mode and also DUMP mode. At each step the procedure will perform this check. The operator is asked to confirm or abort.

Step 4. Go to DUMP mode, external sync

The last step in the switch-on procedure is to bring the camera in DUMP mode (external sync). As explained in Chapter 12, DUMP mode is not a genuine FEE operation mode, but is defined in the CGSE as a state in which the N-FEE is in FULL IMAGE mode in which the dump gate is kept high, continuously resetting the readout register. No data is acquired or send to the DPU. The indicidual task is: Task GUI > Camera TAB > 3 — N-FEE > To DUMP mode. The command you can use in the REPL is:

The user will then be prompted to confirm that the N-FEE is actually in DUMP mode. After confirmation, the AEU cRIO voltages and currents will be checked against their limits and printed in an overview table asking the user for another confirmation.

One last step that is part of the Camera Switch ON procedure is to take a series of single images without the light source on. That is, it will be full frame darks with the dump gate enabled.

Finally, the AEU cRIO and PSU HK frequency is reset to their default values from the Settings, i.e. HK_DELAY.

This concludes the Camera Switch ON procedure as it is currently implemented and required to execute. The camera will be in DUMP mode after this switch-on which is the starting state for all the TVAC tests that will be executed.

Switching OFF the camera is much simpler and doesn’t require specific checks. The N-FEE should normally be in DUMP mode when you start this switch-off and is brought first to STANDBY mode, then to ON mode. Each of these steps require confirmation from the operator. Finally, the AEU Switch OFF is executed which disables the sync signals and powers off the camera. The individual tasks are Camera TAB > 3 — N-FEE > To STANDBY mode, Camera TAB > 3 — N-FEE > To ON mode, and Camera TAB > 2 — AEU > Switch OFF. From the REPL, the following commands accomplish the same result:

Every time you execute the Camera Switch ON procedure, the task will perform a short functional test using the acquire_and_dump command as shown below. This is a full-frame measurement of all four CCDs and both sides.

In the Operator Task GUI, Camera TAB (see Figure 9), there is a task button to execute the SFT analysis. In the arguments panel, you should provide the obsid of the Camera Switch ON as an integer, i.e. only the test id, not the site id. The data_dir is the parent folder where the observations are stored and the output_dir is where the result of the analysis will be saved.

The SFT analysis runs two different functions:

These functions produce several standard output files, consisting in

The HK checks produce the following files:

where <camera> is the camera.ID, e.g. 'duvel', and <obsid> is the observation id, e.g. ‘01234’.

The former is a plot of the HK, looking like this for an SFT measurement on Brigand:

The latter file is a text file and contains the limit-checks for currents and power consumption, and nominally ends with a message formatted like this:

If any of the checks are invalid it recommends to “STOP for analysis”.

The image analysis part produces the following files:

where <func> is the statistical function used to combine the results obtained from individual columns (default is ‘mean’).

The ‘raw’ image displays one full-frame image of the 4 CCDs (the layer is chosen at run-time of the analysis, and is reported in the image itself).

The offsetSubtracted image corresponds to the same data, after subtraction from the offset computed from the serial overscan columns.

The avg_rows_and_columns presents the average row and column profiles of the image area (including parallel overscan) of the 8 half-CCDs independently.

Examples of such images can be found below.

The text file contains the limit-checks for electronic offsets and readout noise, and nominally ends with a message formatted like this:

Here as well, if any of the checks are invalid it recommends to “STOP for analysis”.

On the spacecraft, the Ancillary Electronics Unit (AEU) is providing the FEE with the necessary stabilised secondary voltages and is also providing synchronisation signals to allow the different FEEs to synchronise their CCD readout cycle to the temperature control system (TCS) heater power switching.

On CAM level, we do not use a flight-like AEU. A dedicated AEU EGSE is providing the power supplies and synchronisation signals needed to operate a single N-type or single F-type camera.

The AEU EGSE supplies 6 voltages to the FEE:

Figure 16, Figure 17, Figure 18, and Figure 19 list the default voltage and current values for the N-AEU and F-AEU.

The AEU EGSE provides sync pulses to the N-FEE, F-FEE, TCS EGSE, and the EGSE (e.g. shutter controller of the OGSE). The following synchronisation signals can be configured:

The synchronisation output signal timings are shown in Figure 20.

The AEU is switched on by the operator by powering up the unit. During the first 3 minutes after powering up no AEU commanding shall take place. The front-panel leds stand-by, self-test, functional check & TVAC, and alignment will be blinking until the system is ready.

The AEU EGSE has 4 functional modes:

Stand-by:

Functional check & TVAC mode

(ambient) Alignment operating mode

Self-test

Switching modes:

Checking in which mode the AEU is:

To read the voltage and current setpoints, and the corresponding over-protection values (OVP and OCP) from the power supply units:

To read the measured voltages and currents from the power supply units:

To read the measured values for the voltages and currents, and the corresponding protection values (UVP, OVP, and OCP):

For the N-CAM:

For the F-CAM:

The AEU EGSE provides three memory positions to store default values for the FEE voltages: position A, B, C.

TBD: We store the nominal N-FEE values in memory position A, the nominal values for F-FEE in memory position B. + commands to store voltages, currents, protection values in the memory positions

To power on and off the N- or F-CAM, the following building blocks can be used:

Note that switching on the camera, will put the AEU in functional check and TVAC mode. Switching off, will put it back to stand-by mode.

For the N-CAM, the synchronisation signals must be configured according to the desired image cycle time. Allowed values for the image cycle time are: 25, 31.25, 37.50, 43.75, and 50s. Note that - for image cycle times longer than 25s - not all heater sync pulses are synchronised with a Clk_ccdread sync pulse.

The following building blocks enable and disable the clock sync signals that are sent to the N-FEE (i.e. Clk_50MHz, Clk_ccdread (here with an image cycle time of 25s), and Clk_heater (synchronised with Clk_ccdread)):

For the F_CAM, the following building blocks enable and disable the clock sync signals that are sent to the F-FEE (i.e.Clk_50MHz, Clk_F_ccdread, and Clk_heater (synchronised with Clk_F_ccdread); nominal clocks only):

To check the sync status of the clocks (i.e. whether or not they are enabled) and whether or not a synchronisation failure has been detected:

For the N-CAM:

For the F-CAM:

For the SVM/heater:

When the AEU is put in self-test mode (see Section 11.3), the loopback option can be set as follows:

At the start of a test day, the following two AEU building blocks must be executed (either independently or in another building block):

At the end of a test day, the following two AEU building blocks must be executed (either independently or in another building block):

A complete list of the N-FEE operating modes can be found in RD-06. The main modes for camera testing are:

The N-FEE Operating modes are described in more detail in the appendix attached to RD-14. The mode identifiers that you will probably see in Grafana screens or in housekeeping entries, are defined in the N-FEE Register Map and listed here for your convenience.

Readout timing: The AEU sends synchronization pulses to the FEE every 6.25 seconds. Every pulse triggers a CCD-readout. In nominal operations, the 4 CCDs in one camera are addressed sequentially, i.e. readout one at a time, delayed by one pulse period, i.e. 6.25 seconds.

Cycle time and FEE configuration: all sync-pulses trigger a CCD readout. During nominal operations, every fourth pulse is “long” (it lasts 400ms instead of 200ms). We define the long-pulse period as the “cycle-time”. The cycle-time is important in two respects. First, in nominal operations, it takes 4 pulses to cycle over the 4 CCDs, i.e. each CCD is readout every cycle-time seconds. Second, the FEEs, i.e. the operating mode of the CCDs can be reconfigured whenever, but only when the FEE receives a long pulse. The FEE-register (containing the configuration parameters) is read during the pulse and the new configuration is immediately applied to the subsequent readouts, i.e. to integrations that were already on-going. This is important to keep in mind for the timing of your tests (see the timing examples in Appendix).

Exposure time: the PLATO cameras have no shutter. Consequently, the CCDs integration never stops. In practice, the sync-pulses trigger the readout process, and the exposure time effectively corresponds to the cycle-time minus the readout time. That means for instance that for a given cycle-time, the effective exposure time will be longer when performing partial readout than when acquiring full-CCD images.

Modifying the exposure time: the exposure time itself cannot be commanded at the level of the FEE. There are nevertheless various ways to modify the exposure time:

N-FEE internal sync-pulses: to accommodate short exposure times, the FEE can generate its own sync-pulses. The source of the sync pulses and period of the internal pulses can be configured with the following EGSE commands to the DPU:

You shouldn’t use these commands directly but rather call the dedicated building block:

The following sections describe a collection of building blocks designed to configure and operate the FEEs and the CCDs. A list of the building blocks can also be found on the PLATO Confluence, in the PCOT space, by following links to the “On-Ground Testing”.

Examples of time-sequencing for some operational approaches are presented in Appendix 18.A.

In this section, for the sake of simplicity, the names of the building blocks directly appear at the python prompt (>>>), but remember that a commanding building block will exclusively be accepted either within another building block or function, or (hence generating an observation) by the execute command (see Section 4.1).

It may be beneficial to synchronize some commands with the CCD readouts. For instance small movements of the source on the detector (dithering) may be fast enough to occur entirely during the CCD readout. Synchronizing the movements on the readout hence alleviates the need to lose one image cycle or more to “let things happen”. This can be achieved with the following approach (e.g. in standard mode)

The first command sets the FEE into an infinite image-acquisition loop, and returns immediately. In the loop, the wait command “counts” the right number of cycles (images) before returning. Finally, the command on_long_pulse_do will wait until the next long synchronisation pulse and then trigger the embedded command, making sure it starts simultaneously with the CCD readout.

The on_long_pulse_do command will only execute the function passed as the argument to on_lon_pulse_do. If you want to execute several commands, or include a delay: use wait_cycles(1) to hold till the system sees the long pulse. The subsequent commands in your script will be executed after the long pulse.

Notes:

A complete list of the F-FEE operating modes can be found in RD-16. The main modes for camera testing are:

CCD In this section we assume that CCD refers to the half-CCD that is exposed to light. The 'bottom' half, i.e. the storage area is never discussed. The term 'half-CCD' here refers to either the F or the E side of (half) a detector, hence physically one fourth CCD, i.e. 2255 x 2255 pixels (+ pre- and over-scans).

The following sections describe a collection of building blocks designed to configure and operate the FEEs and the CCDs.

In this section, for the sake of simplicity, the names of the building blocks directly appear at the python prompt (>>>), but remember that a commanding building block will exclusively be accepted either within another building block or function, or (hence generating an observation) by the execute command (see Section 4.1).

To synchronize some commands with the CCD readouts, please refer to [sec-synchronisation-detector-mgse]

Switching between modes is done with just one command, set_operating_mode. The command takes one parameter that defines the mode.

You can use either the number or the name of the mode as the argument, but it is preferred to use the constants defined in the egse.tcs module.

The mode that will be used most during camera testing is the extended mode, which allows all parameters to be configurable.

The TCS EGSE has a set of commands at your disposal for remote commanding the device. These commands can only be used in Remote Control mode, i.e., when the button shows orange in the MMI. We can categorise these commands as follows:

Change the operating mode: as seen above, the command for changing the operating mode is tcs.set_operating_mode(…​) which takes one parameters that defines the mode.

Set configuration parameter: to change configuration parameters, use the command tcs.set_parameter(…​) which takes two arguments, the parameter name and its value. The following command changes the temperature set point for the PI controller on channel 1 to -40ºC.

A full list of parameters that can be configured is available in table 6.8 on page 61-68 of RD-09.

Please note that several parameters can form a group, e.g., to configure the PI controller for a certain channel. In this case the best approach is to set all the parameters needed for that configuration and switch to the proper mode, i.e., closed loop or open loop.

After your configuration is finished, the parameter set needs to be committed on the device. This is done by sending a tcs.commit() command.

Run the task: When you have properly configured the TCS EGSE, you need to run the task. This is needed to drive the controllers for the heaters and to execute the PID controller to reach and maintain the intended temperatures.

A task is run with the tcs.run_task() command and stopped with tcs.stop_task().

Retrieve Information: several commands are available to retrieve information from the TCS EGSE.

Convenience Functions: two convenience functions are available to show information in a nice colour table. If you need a quick overview of the configuration or the housekeeping in the REPL or in a Jupyter Notebook, use the following functions:

Monitoring TCS EGSE telemetry can best be done with the TCS data acquisition das. The das command is used from the terminal as follows:

The above command will retrieve TCS housekeeping telemetry every 10 seconds. The data is sent to the Storage Manager that saves the telemetry in a CSV file on the egse-server. The das also makes the temperatures of the TOU, FEE, and the ambient and internal temperatures available for Prometheus to be monitored by Grafana.

Please note that this command should preferably run on the egse-server and be started by the site-operator (see Section 1.3). The test-operator can inspect the metrics from the TCS EGSE data acquisition in the Grafana display.

TBW

TBW

TBW

TBW

TBW

TBW

The test houses implement the temperature control of 6 Temperature Reference points (TRP) of temperature interfaces to the camera: three temperatures of the Thermal Environment Box (TEB): the TEB_SKY, a shroud offering a cold radiative cooling sink to the TOU baffle, an upper segment TEB_TOU, offering the radiative environment seen by the TOU tube (covered in MLI) above the optical bench on the spacecraft, a lower segment TEB_FEE offering the radiative environment in the optical bench cavity seen by the FEE onboard the spacecraft, and the mounting points of the 3 TOU bipods on the manipulation ring (TRP2,3,4) which are representing the conductive interface of the optical bench as seen by the TOU bipods on the spacecraft.

All six TRPs are controlled independently, and we can check and change the temperature setpoints, and switch the control on / off for each TRP.

Changing the setpoints:

The effect of the last command (changing TRP234) is the same as setting TRP2, 3, 4 to the same setpoint.

Checking the setpoints:

Utility building block

The OGSE can be switched on with one simple command:

or the command ogse.ogse_swon() can be used in a test script.

Effect

Utility building block

Effect

The attenuation is set by a double filter wheel where specific combinations of the wheel positions define a predefined attenuation. The following commands can be used to set the attenuation:

Effect: changes filter wheel combination one attenuation step higher.

Effect: changes filter wheel combination one attenuation step lower.

Effect: will choose combination of ND filters that matches commanded factor of the full-well capacity as close as possible.

Effect: choose manual ND filters in the two wheels, note the argument is a tuple.

You can also read this back through the housekeeping:

Returns the actual attenuation factor realised with the ND filter combination

The CSL ambient alignment collimator provides the following attenuation factors:

For every facility, a calibration will be done to relate the attenuation factor (0…​1) to the fraction of the full well that will be filled in a nominal (25sec) integration near the center of the field.

Will set the OGSE attenuation factor that results in the brightest pixel in the PSF near the center of the field to be about 50% of the full well (which is roughly 1E6 for PLATO CCDs)

Only implemented at IAS (TBD)

The N-camera reads out a different CCD every 6.25 seconds. You want to synchronise the shutter open to the start of the new integration on the CCD you are interested in (where the collimator image is seen). Setting the exposure time allows to avoid exposing the CCD during readout (avoiding e.g. smearing) and/or attenuate the light source in finer steps than allowed by the neutral density filter wheels.

The readings of the power meters are store in OGSE housekeeping telemetry.

If you need access to the power, read the housekeeping parameters GOGSE_PM_CH1_PWR (light source monitor) or GOGSE_PM_CH2_PWR (light injected into the collimator)

Commanding: To keep notations light, the building blocks in the examples below are presented directly at the python prompt, but in operations they will be refused outside of either another function or building-block, or (if they by themselves constitute the entire test) an execute() command (see Section 4.1).

Timing: In all cases, our time reference starts at the pulse triggering

In most cases, as long as the cycle-time and the ccd_order remain unchanged by the configuration occurring at t = 0, the images read out during the first cycle can probably be used directly since, e.g. the just commanded partial readout would be applied. This must be assessed on a case-by-case basis. It will make a difference of one cycle wrt the first moment where a representative set of images corresponding to the new configuration has been recorded. This explains why an apparently redundant cycle is represented in all examples below.

Starting a GUI on the operator screen showing the FOV:

Then you can add the visited locations as follows:

At each of these locations, a red dot will appear on the plot. You can switch between coordinate system (used in the plot) with the combobox below the plot window (focal-plane coordinates, pixel coordinates, and field angles).

Alternatively, you can fire up this GUI with

and add the visited locations with the following commands:

These commands can be used in test scripts, to visualise visited positions, without having to pass on the GUI object (or checking for its existence). In case the GUI has been fired up, the positions will be marked in the GUI. If not, nothing will happen (no error will occur).

In camtest.commanding.csl_gse, there are a couple of building blocks to move the mechanisms (i.e. hexapod and stages) such that the point sources falls on a specified position:

When executing these building blocks, a red dot will be added to the GUI, marking that position (in case the GUI was fired up).

On the EGSE server:

On the EGSE client:

It sometimes happens that the FITS files need to be re-processed off-line for some observations. This can be done, based on the relevant HDF5 files that are stored in the daily folders for the OD(s) during which the observation took place. Preferably, this is done on the EGSE server of the TH, with the following command:

This will use the default data location from the PLATO_DATA_STORAGE_LOCATION environment variable. It is possible to use a different data location, as follows:

Note that it can be dangerous to run the off-line FITS generation on the client or server during testing, as it could overload the Storage Manager. In case you would do this on a dedicated machine (with the same commands), preferably over VNC (as some observation take a long time to be processed), you need:

Before you can go ahead, make sure that there are no FITS files in the folder for this observation (remove them if there would be any)!

In this section we explain what the difference is between a GitHub issue, a non-conformance report (NCR) and a procedure variation sheet (PVS). All three have their value and life cycle, but its important to understand when and where they have to be used, and how they are tracked.