Configurable Options

This reference document details the configurable settings available in MCS. The document is split between the MCS client and server.

The MCS client is located in the GNDSW/MCS_Display directory and the server is typically located in the GNDSW/MCS_Server directory.

MCS Server

Configurable MCS server files are located in the MCS_Sever/configs directory. Additionally, the MCS_Server/licence directory contains the licence.properties configurable text file which stores the licence code and other cloud licencing properties.

The `configs` Directory

By default, the configs directory should contain the following files:

File Purpose

calibrationsDefinitions.yaml

The calibration definition file. Used to store the Parameter calibration definitions. The default file contains example calibrations.

checkDefinitions.yaml

The check definition file. Used to store the Parameter check definitions. The default file contains example checks.

parmeterDefinitions.yaml

The Parameter associations file. Used to store Parameter calibration and Parameter check associations.

exampleSecurityAssociations.yaml

An example security associations file.

When using CCSDS Space Link security, a security associations file is used to configure security properties.

mcs.properties

The MCS property configuration file. Used to configure key-value properties that affect the behaviour of the MCS server.

Check Definition Properties

Checks are applied to both raw and calibrated Parameter values to determine if the value needs to be calibrated. Checks can also be used to indicate warnings or errors.

If the Parameter value is set outwith the range specified in the check definition file, the value can be calibrated and a warning, error, or information message can be logged.

In the following example:

A 'range' or 'chain' check is specified
The 'name' field assigns an identifier to the check
The 'label' field assigns a string to the check that will be logged if the value is outwith the specified range
The severity field represents the type of message that is logged if the value is outwith the specified range
The lower field represents the lower-limit of the check range
The upper field represents the upper-limit of the check range

Show example check definition file

- range:
    name: "small-range-HARD"
    label: HARD
    severity: ERROR
    lower: 1
    upper: 10

- range:
    name: "small-range-SOFT"
    label: SOFT
    severity: INFO
    lower: 2
    upper: 9

- range:
    name: "large-range-HARD"
    label: HARD
    severity: ERROR
    lower: -60
    upper: 100

- range:
    name: "large-range-SOFT"
    label: SOFT
    severity: WARNING
    lower: -20
    upper: 60

- chain:
    name: "small-range"
    checks:
      - "small-range-HARD"
      - "small-range-SOFT"

- chain:
    name: "large-range"
    checks:
      - "large-range-HARD"
      - "large-range-SOFT"

Calibration Definition Properties

Calibration functions are used to adjust Parameter values that fall outwith a check range.

In the following example:

The type of calibration (linear, range, text, time, chain, or polynomial) is specified
The name field assigns an identifier to the calibration
The m and c fields represent the coefficients in the equation result = mx + c
The precision field represents the number of decimal places the result value should be truncated to
The ranges field is used to specify multiple triple ranges
The from, to, and evalueTo represent the range checks. For example, if the value falls within the range, the evaluateTo value is returned.
The maps field is used to specify numeric to string maps
The offset field contains the offset to add to the input numeric value to adjust it to the January 1st 1970 GMT epoch
The scale field denotes whether the numeric value is in seconds or otherwise assumed to be milliseconds. It is assumed that the numeric value is offset from January 1st 1970 GMT
The calibrations field specifies multiple calibration identifiers (the name field)
The degrees field maps values to polynomial terms. In the following example, the values are mapped to the polynomial equation: :\(y = -1.67x^3 + 0.23x^2 + 245x - 32\).

Show example calibration definition file

- linear:
    name: linear-calibration-example
    m: 0.25
    c: 0.001
    precision: 2

- range:
    name: range-calibration-example
    ranges:
      -
        from: 0
        to: 10
        evaluateTo: 10
      -
        from: 11
        to: 100
        evaluateTo: 11

- text:
    name: text-calibration-example
    maps:
      10: "ten"
      11: "eleven"

- time:
    name: time-calibration-example
    offset: 0
    scale: seconds

- chain:
    name: chain-calibration-example
    calibrations:
      - "range-calibration-example"
      - "text-calibration-example"

- polynomial:
    name: polynomial-calibration-example
    degrees:
      0: -32
      1: 245
      2: 0.23
      3: -1.67
    precision: 2

Parameter Association Properties

The Parameter associations file assigns calibration and checks to Parameters.

In the following example:

The name field represents the full name of the Parameter instance in the SCDB
The calibrationId field represents the calibration name defined in the calibration definition file
The rawCheckId and calibratedCheckId fields represent the check names defined in the check definition file

Show example parameter associations file

- existing:
    name: "Target1:platform.DummySubsys1.dummyParam8"
    calibrationId: text-calibration-example
    rawCheckId: large-range
    calibratedCheckId: small-range

- existing:
    name: "Target1:platform.DummySubsys1.dummyParam16"
    calibrationId: linear-calibration-example
    rawCheckId: large-range
    calibratedCheckId: small-range-HARD

- existing:
    name: "Target1:cdh.DataPool.platform.DummySubsys1.dummyParam32"
    calibrationId: chain-calibration-example
    rawCheckId:
    calibratedCheckId: large-range

Security Association Properties

When using CCSDS Space Link security, a YAML file is used to configure the security associations. An example YAML configuration is provided in the configs folder.

The following table details the security association properties:

Security Association Properties
Property	Field type	Description
`securityParameterIndex`	Integer	The SDLS security parameter index.
`vcid`	Integer	The virtual channel to match on
`applyToTc`	Boolean	Should be `true` if this SA is to be applied to uplink, otherwise `false`.
`applyEncryption`	Boolean	Should be `true` encryption is to be applied, otherwise `false`.
`applyAuthentication`	Boolean	Should be true if authentication is used, otherwise `false`.
`authenticationKeyHexString`	String	The authentication string in Hex.
`encryptionKeyHexString`	String	The encryption key string in Hex.
`initialisationVector`	Integer	Provided as input to some cryptographic algorithms before processing user data. This serves to preload the cryptographic process and enhance its security by adding variability.

MCS Server Configuration Properties

General Configuration Properties
Configuration id	Field type	Default value	Description
`activityPersistenceDaemonDelay`	Integer	`10000`	The delay in milliseconds between the persistence of activities to disk
`activityPersistencePath`	String	`data/active_activities`	Path to the directory activities are stored.
`configurationStoreFilePath`	String	`data/mcsConfig.data`	Path to the file containing cached or imported Ground parameter values.
`groundSchedulePath`	Directory	`schedules`	Default directory to look for ground schedules
`maxLogFileRecords`	Integer	`30000`	The maximum number of records permitted inside the log archive CSV file. Exceeding this value will result in the current log being rotated to a separate file and further logs appended to a new file.
`missionRepository`	String	`data/missionFilestore`	Directory in which the MCS stores data about the current mission, such as assets and targets.
`remoteAccessPort`	Integer	`50051`	The TCP port to which MCS Display clients can connect.
`timezone`	String	`UTC`	Timezone for displayed date/time values. Format should be accepted by `java.time.ZoneId.of(String)`.

Transfer Configuration Properties
Configuration id	Field type	Default value	Description
`downlinkTempPath`	Directory	`data/ldt_parts`	Directory to store partial downlinks
`transferFilestorePath`	Directory	`cfdp_filestore`	Directory in which CFDP downlink data, of completed transfers, is stored.
`transferTempFilestorePath`	Directory	`data/cfdp_parts`	Directory where in-progress CFDP transfers are stored.

Archiving Configuration Properties
Configuration id	Field type	Default value	Description
`archivePath`	File	`data/missionArchive/`	The path to the archive
`archiveRetrieval_enabled`	String	`influxDbV2`	Which archive to use for retrievals, this value can be either `JPA` or `influxDbV2`
`minimum_activity_date`	String	`None`	An optional field which, if populated, will prune all archived activity data with a timestamp before the date specified in this field. For example, setting `minimum_activity_date=2023-01-01` in `mcs.properties` will prune all activity data from before 2023-01-01 on startup of the MCS. Depending on how large a data set is, this action might take some time to complete.

Influx DB Configuration Properties
`Configuration` id	Field type	Default value	Description
`influxDbV1_enabled`	Boolean	`false`	Whether to enable storage using the V1 implementation of the Influx database
`influxDbV1_url`	String		The URL for the Influx database
`influxDbV1_dbName`	String	`BAL_MCS`	The name of the Influx database
`influxDbV1_uname`	String		Username to use to connect to the Influx database
`influxDbV1_pword`	String		Password to use to connect to the Influx database
`influxDbV1_storeParams_AsAgnostic`	Boolean	`false`	Store parameters in the archive as `target.name`
`influxDbV2_store_enabled`	Boolean	`false`	Whether to enable storage using the V2 implementation of the Influx database
`influxDbV2_url`	String		The URL for the Influx database
`influxDbV2_orgId`	String		The organisation ID to use to connect to the Influx database
`influxDbV2_token`	String		The authentication token to use to connect to the Influx database
`influxDbV2_storeParams_AsAgnostic`	Boolean	`false`	Store parameters in the archive as `target.name`

Scripting Configuration Properties
Configuration id	Field type	Default value	Description
`scriptRoot`	Directory		Directory in which scripts are placed to run via MCS's `exectute script` functionality.
`groundScheduleIngesterPollingDelay`	Integer	`0`	Time in seconds to poll the watched ground schedule directory. 0 indicates it should never poll and effectively switches this functionality off.
`groundScheduleIngesterPollingDirectory`	String	`ground_schedule_watch`	The directory to watch for new ground schedules or entries, relative to the MCS installation directory.

The MCS Licencing File

The licence.properties file should be located in the MCS_Server/licence directory.

All configurable options detailed in the following table are optional unless otherwise specified.

Nalperion Cloud Licence Properties
Property	Description
`licenceCode`	The MCS licence code (required)
`provideSystemInfo`	Can be configured to submit system information to the licence manager for diagnostic purposes. Set to `false` by default
`proxyIP`	The IP address of an HTTP proxy
`proxyPort`	The IP port of an HTTP proxy
`proxyUsername`	The username to use for an HTTP proxy
`proxyPass`	The password to use for an HTTP proxy
`daemonIP`	The IP address of the Nalpeiron licence daemon when running in an air-gapped Deployment
`daemonPort`	The IP port of the Nalpeiron licence daemon when running in an air-gapped Deployment
`daemonUsername`	The username to use for the Nalpeiron licence daemon when running in an air-gapped Deployment
`daemonPass`	The password to use for the Nalpeiron licence daemon when running in an air-gapped Deployment

MCS Client

The MCS client can be configured using the display.properties file located in the MCS_Display/configs directory.

MCS maintains numerous properties in this file which should not be modified.

Don’t modify properties unless they’re present in the following table.

MCS Client Properties
Property	Field type	Default value	Description
`enableDeploymentIdCheck`	Boolean	`true`	Allows Deployment checking to be disabled, meaning the flight-side will not reject commands if the Deployment id on the flight and ground do not match.
`groundStations`	String		List of ground stations to display on the map. Formatted as a triple of name of the station followed by the latitude and longitude in degrees. To specify multiple stations, simply list multiple triples separated by a colon. For example: `Goonhilly, 50.0, -5.0: Inuvik, 68, -133`
`mapLatParameters`	String		Parameter representing spacecraft latitude. For example, `obsw.DataPool.platform.lat`
`mapLonParameters`	String		Parameter representing spacecraft longitude. For example, `obsw.DataPool.platform.lon`
`mapTimestampOffsetMs`	Integer	`0`	Parameter used to offset the map timestamp. Measured in milliseconds.
`mapTrailLength`	Integer	`100`	Maximum number of lat-long points in the trail of a spacecraft trail displayed on the map.
`scriptPath`	Directory	`scripts`	Default directory to look for script files.

Configurable Options

MCS Server

The configs Directory

Check Definition Properties

Calibration Definition Properties

Parameter Association Properties

Security Association Properties

MCS Server Configuration Properties

The MCS Licencing File

MCS Client

The `configs` Directory