Subscribe Alarms¶

interface SubscribeAlarmsRequest {
  instance: string;
  processor: string;
}

// Summary of an alarm applicable for Parameter or Event (possibly
// other in the future) alarms.
// Contains detailed information on the value occurrence that initially
// triggered the alarm, the most severe value since it originally triggered,
// and the latest value at the time of your request.
interface AlarmData {
  type: AlarmType;
  triggerTime: string;  // RFC 3339 timestamp

  // For parameter alarms, this is the id of the parameters
  // For event alarms
  //   - the id.namespace is /yamcs/event/<EVENT_SOURCE>, unless
  //     EVENT_SOURCE starts with a "/" in which case the namespace
  //     is just the <EVENT_SOURCE>
  //   - the id.name is the <EVENT_TYPE>
  id: NamedObjectId;

  // Distinguisher between multiple alarms for the same id
  seqNum: number;
  severity: AlarmSeverity;

  // Number of times the object was in alarm state
  violations: number;

  // Number of samples received for the object
  count: number;
  acknowledgeInfo: AcknowledgeInfo;
  notificationType: AlarmNotificationType;

  // Additional detail in case the alarm is of type PARAMETER
  parameterDetail: ParameterAlarmData;

  // Additional detail in case the alarm is of type EVENT
  eventDetail: EventAlarmData;

  // Whether the alarm will stay triggered even when the process is OK
  latching: boolean;

  // if the process that generated the alarm is ok (i.e. parameter is within limits)
  processOK: boolean;

  // triggered is same with processOK except when the alarm is latching
  triggered: boolean;

  // if the operator has acknowledged the alarm
  acknowledged: boolean;

  // Details in case the alarm was shelved
  shelveInfo: ShelveInfo;
  clearInfo: ClearInfo;

  // Time when the alarm was last updated
  updateTime: string;  // RFC 3339 timestamp
}

// 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 AcknowledgeInfo {
  acknowledgedBy: string;
  acknowledgeMessage: string;
  acknowledgeTime: string;  // RFC 3339 timestamp
}

interface ParameterAlarmData {
  triggerValue: ParameterValue;
  mostSevereValue: ParameterValue;
  currentValue: ParameterValue;
  parameter: ParameterInfo;
}

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;
}

interface ParameterInfo {
  name: string;
  qualifiedName: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];
  type: ParameterTypeInfo;
  dataSource: DataSourceType;
  usedBy: UsedByInfo;
  ancillaryData: {[key: string]: AncillaryDataInfo};

  // Operations that return aggregate members or array entries
  // may use this field to indicate the path within the parameter.
  path: string[];
}

interface ParameterTypeInfo {
  name: string;
  qualifiedName: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];

  // Engineering type
  engType: string;
  dataEncoding: DataEncodingInfo;
  unitSet: UnitInfo[];

  // Default Alarm, effective when no contextual alarm takes precedence.
  defaultAlarm: AlarmInfo;
  enumValue: EnumValue[];
  absoluteTimeInfo: AbsoluteTimeInfo;

  // Contextual alarms
  contextAlarm: ContextAlarmInfo[];
  member: MemberInfo[];
  arrayInfo: ArrayInfo;
  ancillaryData: {[key: string]: AncillaryDataInfo};

  // Provides hints on how to format the engineering
  // value as a string.
  numberFormat: NumberFormatTypeInfo;

  // True if the engineering type supports signed representation.
  // (only used by integer parameter types)
  signed: boolean;

  // Hint about the range of allowed engineering values
  sizeInBits: number;

  // String representation of a boolean zero (only used by boolean types)
  zeroStringValue: string;

  // String representation of a boolean one (only used by boolean types)
  oneStringValue: string;

  // Which parameters this type is used by. This field is only
  // populated when requesting directly a single parameter type.
  usedBy: ParameterInfo[];
}

interface DataEncodingInfo {
  type: Type;
  littleEndian: boolean;
  sizeInBits: number;
  encoding: string;
  defaultCalibrator: CalibratorInfo;

  // Deprecated, use ``contextCalibrators`` instead
  contextCalibrator: ContextCalibratorInfo[];
  contextCalibrators: ContextCalibratorInfo[];
}

interface CalibratorInfo {
  polynomialCalibrator: PolynomialCalibratorInfo;
  splineCalibrator: SplineCalibratorInfo;
  javaExpressionCalibrator: JavaExpressionCalibratorInfo;
  type: Type;
}

interface PolynomialCalibratorInfo {

  // Deprecated, use ``coefficients`` instead
  coefficient: number[];
  coefficients: number[];
}

interface SplineCalibratorInfo {

  // Deprecated, use ``points`` instead
  point: SplinePointInfo[];
  points: SplinePointInfo[];
}

interface SplinePointInfo {
  raw: number;
  calibrated: number;
}

interface JavaExpressionCalibratorInfo {
  formula: string;
}

interface ContextCalibratorInfo {
  comparison: ComparisonInfo[];
  calibrator: CalibratorInfo;

  // This can be used in UpdateParameterRequest to pass a context
  // that is parsed on the server, according to the rules in the
  // excel spreadsheet. Either this or a comparison has to be
  // used (not both at the same time)
  context: string;
}

interface ComparisonInfo {
  parameter: ParameterInfo;
  operator: OperatorType;
  value: string;
  argument: ArgumentInfo;
}

interface ArgumentInfo {
  name: string;
  description: string;
  initialValue: string;
  type: ArgumentTypeInfo;
}

interface ArgumentTypeInfo {
  engType: string;
  dataEncoding: DataEncodingInfo;
  unitSet: UnitInfo[];

  // Enumeration states (only used by enumerated arguments)
  enumValue: EnumValue[];

  // Minimum value (only used by integer and float arguments)
  rangeMin: number;

  // Maximum value (only used by integer and float arguments)
  rangeMax: number;

  // Member information (only used by aggregate arguments)
  member: ArgumentMemberInfo[];

  // String representation of a boolean zero (only used by boolean arguments)
  zeroStringValue: string;

  // String representation of a boolean one (only used by boolean arguments)
  oneStringValue: string;

  // Minimum character count (only used by string arguments)
  minChars: number;

  // Maximum character count (only used by string arguments)
  maxChars: number;

  // True if the engineering type supports signed representation.
  // (only used by integer arguments)
  signed: boolean;

  // Minimum byte count (only used by binary arguments)
  minBytes: number;

  // Maximum character count (only used by binary arguments)
  maxBytes: number;

  // Length of each dimension (only used by array arguments)
  dimensions: ArgumentDimensionInfo[];

  // Type of array entries (only used by array arguments)
  elementType: ArgumentTypeInfo;

  // Name of the parameter type
  name: string;
}

interface UnitInfo {
  unit: string;
}

interface EnumValue {
  value: string;  // String decimal
  label: string;
  description: string;
}

interface ArgumentMemberInfo {
  name: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];
  type: ArgumentTypeInfo;
  initialValue: string;
}

interface ArgumentDimensionInfo {

  // Use a fixed integer value. If set, no other options are applicable.
  // This value describes the length.
  fixedValue: string;  // String decimal

  // Use the value of the referenced parameter.
  // The value describes the zero-based ending index (length - 1)
  //
  // For a value ``v``, the dimension's length is determined
  // as: ``(v * slope) + intercept``.
  parameter: ParameterInfo;

  // Use the value of the referenced argument.
  // The value describes the zero-based ending index (length - 1)
  //
  // For a value ``v``, the dimension's length is determined
  // as: ``(v * slope) + intercept``.
  argument: string;

  // Scale the value obtained from a parameter or argument reference.
  slope: string;  // String decimal

  // Shift the value obtained from a parameter or argument reference.
  intercept: string;  // String decimal
}

interface AlarmInfo {
  minViolations: number;

  // Deprecated, use ``staticAlarmRanges`` instead
  staticAlarmRange: AlarmRange[];
  staticAlarmRanges: AlarmRange[];

  // Deprecated, use ``enumerationAlarms`` instead
  enumerationAlarm: EnumerationAlarm[];
  enumerationAlarms: EnumerationAlarm[];
}

interface EnumerationAlarm {
  level: AlarmLevelType;
  label: string;
}

interface AbsoluteTimeInfo {
  initialValue: string;
  scale: number;
  offset: number;
  offsetFrom: ParameterInfo;
  epoch: string;
}

interface ContextAlarmInfo {
  comparison: ComparisonInfo[];
  alarm: AlarmInfo;

  // This can be used in UpdateParameterRequest to pass a context
  // that is parsed on the server, according to the rules in the
  // excel spreadsheet. Either this or a comparison has to be
  // used (not both at the same time)
  context: string;
}

interface MemberInfo {
  name: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];
  type: ParameterTypeInfo;
}

interface ArrayInfo {
  type: ParameterTypeInfo;
  dimensions: ParameterDimensionInfo[];
}

interface ParameterDimensionInfo {
  fixedValue: string;  // String decimal
  parameter: ParameterInfo;
  slope: string;  // String decimal
  intercept: string;  // String decimal
}

interface NumberFormatTypeInfo {
  numberBase: string;
  minimumFractionDigits: number;
  maximumFractionDigits: number;
  minimumIntegerDigits: number;
  maximumIntegerDigits: number;
  negativeSuffix: string;
  positiveSuffix: string;
  negativePrefix: string;
  positivePrefix: string;
  showThousandsGrouping: boolean;
  notation: string;
}

interface UsedByInfo {
  algorithm: AlgorithmInfo[];
  container: ContainerInfo[];
}

interface AlgorithmInfo {

  // Algorithm name
  name: string;
  qualifiedName: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];
  scope: Scope;

  // Type of algorithm
  type: Type;

  // Language if this is a custom algorithm
  language: string;

  // Code if this is a custom algorithm
  text: string;
  inputParameter: InputParameterInfo[];
  outputParameter: OutputParameterInfo[];
  onParameterUpdate: ParameterInfo[];
  onPeriodicRate: string[];  // String decimal

  // Operands and operators in Reverse Polish Notation if type ``MATH``.
  mathElements: MathElement[];
}

interface InputParameterInfo {
  parameter: ParameterInfo;
  inputName: string;
  parameterInstance: number;
  mandatory: boolean;
  argument: ArgumentInfo;
}

interface OutputParameterInfo {
  parameter: ParameterInfo;
  outputName: string;
}

interface MathElement {

  // Type of element, either an operand kind or an operator.
  type: Type;

  // Operator symbol if type ``OPERATOR``.
  operator: string;

  // Constant if type ``VALUE_OPERAND``.
  value: number;

  // Parameter whose value is used if type ``PARAMETER``.
  parameter: ParameterInfo;

  // Parameter instance specifier
  parameterInstance: number;
}

interface ContainerInfo {
  name: string;
  qualifiedName: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];
  maxInterval: string;  // String decimal
  sizeInBits: number;
  baseContainer: ContainerInfo;
  restrictionCriteria: ComparisonInfo[];
  restrictionCriteriaExpression: string;
  entry: SequenceEntryInfo[];
  usedBy: UsedByInfo;
  ancillaryData: {[key: string]: AncillaryDataInfo};
  archivePartition: boolean;
}

interface SequenceEntryInfo {
  locationInBits: number;
  referenceLocation: ReferenceLocationType;

  // For use in sequence containers
  container: ContainerInfo;
  parameter: ParameterInfo;

  // For use in command containers
  argument: ArgumentInfo;
  fixedValue: FixedValueInfo;
  repeat: RepeatInfo;
  indirectParameterRef: IndirectParameterRefInfo;
}

interface FixedValueInfo {
  name: string;
  hexValue: string;
  sizeInBits: number;
}

interface RepeatInfo {
  fixedCount: string;  // String decimal
  dynamicCount: ParameterInfo;
  bitsBetween: number;
}

interface IndirectParameterRefInfo {
  parameter: ParameterInfo;
  aliasNamespace: string;
}

interface EventAlarmData {
  triggerEvent: Event;
  mostSevereEvent: Event;
  currentEvent: Event;
}

interface Event {
  source: string;
  generationTime: string;  // RFC 3339 timestamp
  receptionTime: string;  // RFC 3339 timestamp
  seqNumber: number;
  type: string;
  message: string;
  severity: EventSeverity;

  // Set by API when event was posted by a user
  createdBy: string;

  // Additional properties
  extra: {[key: string]: string};
}

interface ShelveInfo {
  shelvedBy: string;
  shelveMessage: string;
  shelveTime: string;  // RFC 3339 timestamp

  //when the shelving will expire (can be unset which means that it will never expire)
  shelveExpiration: string;  // RFC 3339 timestamp
}

interface ClearInfo {
  clearedBy: string;
  clearTime: string;  // RFC 3339 timestamp

  //if the alarm has been manually cleared, this is the message provided by the operator
  clearMessage: string;
}

enum AlarmType {
  PARAMETER = "PARAMETER",
  EVENT = "EVENT",
}

enum AlarmSeverity {
  WATCH = "WATCH",
  WARNING = "WARNING",
  DISTRESS = "DISTRESS",
  CRITICAL = "CRITICAL",
  SEVERE = "SEVERE",
}

enum AlarmNotificationType {
  ACTIVE = "ACTIVE",
  TRIGGERED = "TRIGGERED",
  SEVERITY_INCREASED = "SEVERITY_INCREASED",
  VALUE_UPDATED = "VALUE_UPDATED",
  ACKNOWLEDGED = "ACKNOWLEDGED",
  CLEARED = "CLEARED",
  RTN = "RTN",
  SHELVED = "SHELVED",
  UNSHELVED = "UNSHELVED",
  RESET = "RESET",
}

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",
}

enum Type {
  BINARY = "BINARY",
  BOOLEAN = "BOOLEAN",
  FLOAT = "FLOAT",
  INTEGER = "INTEGER",
  STRING = "STRING",
}

enum Type {
  POLYNOMIAL = "POLYNOMIAL",
  SPLINE = "SPLINE",
  MATH_OPERATION = "MATH_OPERATION",
  JAVA_EXPRESSION = "JAVA_EXPRESSION",
}

enum OperatorType {
  EQUAL_TO = "EQUAL_TO",
  NOT_EQUAL_TO = "NOT_EQUAL_TO",
  GREATER_THAN = "GREATER_THAN",
  GREATER_THAN_OR_EQUAL_TO = "GREATER_THAN_OR_EQUAL_TO",
  SMALLER_THAN = "SMALLER_THAN",
  SMALLER_THAN_OR_EQUAL_TO = "SMALLER_THAN_OR_EQUAL_TO",
}

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

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 Scope {
  GLOBAL = "GLOBAL",
  COMMAND_VERIFICATION = "COMMAND_VERIFICATION",
  CONTAINER_PROCESSING = "CONTAINER_PROCESSING",
}

enum Type {
  CUSTOM = "CUSTOM",
  MATH = "MATH",
}

enum Type {
  VALUE_OPERAND = "VALUE_OPERAND",
  THIS_PARAMETER_OPERAND = "THIS_PARAMETER_OPERAND",
  OPERATOR = "OPERATOR",
  PARAMETER = "PARAMETER",
}

enum ReferenceLocationType {
  CONTAINER_START = "CONTAINER_START",
  PREVIOUS_ENTRY = "PREVIOUS_ENTRY",
}

enum EventSeverity {
  INFO = "INFO",
  WARNING = "WARNING",

  // Legacy, avoid use.
  ERROR = "ERROR",
  WATCH = "WATCH",

  // Placeholder for future WARNING constant.
  // (correctly sorted between WATCH and DISTRESS)
  //
  // Most clients can ignore, this state is here
  // to give Protobuf clients (Python Client, Yamcs Studio)
  // the time to add a migration for supporting both WARNING
  // and WARNING_NEW (Protobuf serializes the number).
  //
  // Then in a later phase, we move from:
  // WARNING=1, WARNING_NEW=4
  //
  // To:
  // WARNING_OLD=1, WARNING=4
  //
  // (which is a transparent change to JSON clients)
  WARNING_NEW = "WARNING_NEW",
  DISTRESS = "DISTRESS",
  CRITICAL = "CRITICAL",
  SEVERE = "SEVERE",
}