Subscribe Parameters¶

// Request message for `SubscribeParameters`.
interface SubscribeParametersRequest {

  // Yamcs instance name
  instance: string;

  // Processor name
  processor: string;

  // Parameter identifiers. Each identifier takes the form of
  // a namespace and a name.
  //
  // For Yamcs-native naming only the name field is required and
  // should be the fully qualified name. The namespace is only
  // required when the name represents an alias of that parameter.
  id: NamedObjectId[];

  // Send an error message if any parameter is invalid.
  // Default: true
  abortOnInvalid: boolean;

  // Send parameter updates when parameters expire.
  // The update will have the same value and timestamp like
  // the preceding update, but with acquisition status set to
  // EXPIRED (instead of ACQUIRED)
  // Default: false
  updateOnExpiration: boolean;

  // If available, send immediately the last cached value
  // of each subscribed parameter.
  // Default: true
  sendFromCache: boolean;

  // How to interpret the submitted parameter ids. Default
  // is to replace an existing subscription with the newly
  // submitted list.
  action: Action;

  // If set, truncate binary values to the specified byte length.
  // This may be necessary when Yamcs contains large binary values.
  //
  // A negative value implies no truncating, which is the default.
  maxBytes: number;
}

interface SubscribeParametersData {

  // Mapping between numeric and subscribed identifier.
  // This information is provided only once, following a subscription.
  mapping: {[key: number]: NamedObjectId};

  // Mapping between numeric identifier, and matching parameter.
  // This information is provided only once, following a subscription.
  info: {[key: number]: SubscribedParameterInfo};

  // Parameter identifiers that were subscribed to, but that
  // cannot be matched against the Mission Database.
  invalid: NamedObjectId[];

  // Values of updated parameters.
  values: ParameterValue[];
}

// Used by external clients to identify an item in the Mission Database
// If namespace is set, then the name is that of an alias, rather than
// the qualified name.
interface NamedObjectId {
  name: string;
  namespace: string;
}

interface ParameterValue {

  // Parameter identifier
  id: NamedObjectId;

  // Raw value (uncalibrated)
  rawValue: Value;

  // Engineering value (calibrated)
  engValue: Value;

  // Time of Yamcs reception
  acquisitionTime: string;  // RFC 3339 timestamp

  // Time of generation (~ packet time)
  generationTime: string;  // RFC 3339 timestamp
  acquisitionStatus: AcquisitionStatus;

  // Deprecated: this field was originally introduced for compatibility
  // with Airbus CGS/CD-MCS system. It was redundant, because when false,
  // the acquisitionStatus is also set to INVALID.
  processingStatus: boolean;
  monitoringResult: MonitoringResult;
  rangeCondition: RangeCondition;

  // Context-dependent ranges
  alarmRange: AlarmRange[];

  // How long (in milliseconds) this parameter value is valid
  // Note that there is an option when subscribing to parameters to get
  // updated when the parameter values expire.
  expireMillis: string;  // String decimal

  // When transferring parameters over WebSocket, this value might be used
  // instead of the id above in order to reduce the bandwidth.
  // Note that the id <-> numericId assignment is only valid in the context
  // of a single WebSocket call.
  numericId: number;
}

// Union type for storing a value
interface Value {
  type: Type;
  floatValue: number;
  doubleValue: number;
  sint32Value: number;
  uint32Value: number;
  binaryValue: string;  // Base64
  stringValue: string;
  timestampValue: string;  // String decimal
  uint64Value: string;  // String decimal
  sint64Value: string;  // String decimal
  booleanValue: boolean;
  aggregateValue: AggregateValue;
  arrayValue: Value[];
}

// An aggregate value is an ordered list of (member name, member value).
// Two arrays are used in order to be able to send just the values (since
// the names will not change)
interface AggregateValue {
  name: string[];
  value: Value[];
}

interface AlarmRange {
  level: AlarmLevelType;
  minInclusive: number;
  maxInclusive: number;
  minExclusive: number;
  maxExclusive: number;
}

enum Action {

  // The parameter identifiers specified with ``id``, replace any that were
  // previously subscribed to on this call.
  REPLACE = "REPLACE",

  // The parameter identifiers specified with ``id`` are added to any
  // that were previously subscribed to on this call.
  ADD = "ADD",

  // The parameter identifiers specified with ``id`` are removed from those
  // that were previously subscribed to on this call.
  REMOVE = "REMOVE",
}

enum DataSourceType {
  TELEMETERED = "TELEMETERED",
  DERIVED = "DERIVED",
  CONSTANT = "CONSTANT",
  LOCAL = "LOCAL",
  SYSTEM = "SYSTEM",
  COMMAND = "COMMAND",
  COMMAND_HISTORY = "COMMAND_HISTORY",
  EXTERNAL1 = "EXTERNAL1",
  EXTERNAL2 = "EXTERNAL2",
  EXTERNAL3 = "EXTERNAL3",
  GROUND = "GROUND",
}

enum Type {
  FLOAT = "FLOAT",
  DOUBLE = "DOUBLE",
  UINT32 = "UINT32",
  SINT32 = "SINT32",
  BINARY = "BINARY",
  STRING = "STRING",
  TIMESTAMP = "TIMESTAMP",
  UINT64 = "UINT64",
  SINT64 = "SINT64",
  BOOLEAN = "BOOLEAN",
  AGGREGATE = "AGGREGATE",
  ARRAY = "ARRAY",

  // Enumerated values have both an integer (sint64Value) and a string representation
  ENUMERATED = "ENUMERATED",
  NONE = "NONE",
}

enum AcquisitionStatus {

  // OK!
  ACQUIRED = "ACQUIRED",

  // No value received so far
  NOT_RECEIVED = "NOT_RECEIVED",

  // Some value has been received but is invalid
  INVALID = "INVALID",

  // The parameter is coming from a packet which has not since updated although it should have been
  EXPIRED = "EXPIRED",
}

enum MonitoringResult {
  DISABLED = "DISABLED",
  IN_LIMITS = "IN_LIMITS",
  WATCH = "WATCH",
  WARNING = "WARNING",
  DISTRESS = "DISTRESS",
  CRITICAL = "CRITICAL",
  SEVERE = "SEVERE",
}

enum RangeCondition {
  LOW = "LOW",
  HIGH = "HIGH",
}

enum AlarmLevelType {
  NORMAL = "NORMAL",
  WATCH = "WATCH",
  WARNING = "WARNING",
  DISTRESS = "DISTRESS",
  CRITICAL = "CRITICAL",
  SEVERE = "SEVERE",
}