/  Yamcs HTTP API  /  Alarms  /  Subscribe Alarms

Subscribe AlarmsΒΆ

Receive alarm updates

WebSocket

This method requires to upgrade an HTTP connection to WebSocket. See details on how Yamcs uses WebSocket.

Use the message type alarms.

Input Type

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

Output Type

// 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

  // 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;
  parameterDetail: ParameterAlarmData;
  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;
}

Related Types

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

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

interface ParameterValue {
  id: NamedObjectId;
  rawValue: Value;
  engValue: Value;
  acquisitionTime: string;  // RFC 3339
  generationTime: string;  // RFC 3339
  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;

  // Deprecated. Use ``acquisitionTime`` instead.
  acquisitionTimeUTC: string;

  // Deprecated. Use ``generationTime`` instead.
  generationTimeUTC: string;

  // 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 connection.
  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 {
  engType: string;
  dataEncoding: DataEncodingInfo;
  unitSet: UnitInfo[];
  defaultAlarm: AlarmInfo;
  enumValue: EnumValue[];
  absoluteTimeInfo: AbsoluteTimeInfo;
  contextAlarm: ContextAlarmInfo[];
  member: MemberInfo[];
  arrayInfo: ArrayInfo;
  ancillaryData: {[key: string]: AncillaryDataInfo};
}

interface DataEncodingInfo {
  type: Type;
  littleEndian: boolean;
  sizeInBits: number;
  encoding: string;
  defaultCalibrator: CalibratorInfo;
  contextCalibrator: ContextCalibratorInfo[];
}

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

interface PolynomialCalibratorInfo {
  coefficient: number[];
}

interface SplineCalibratorInfo {
  point: 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;

  //optional string type = 3;
  initialValue: string;

  // repeated UnitInfo unitSet = 5;
  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;
}

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

interface AlarmInfo {
  minViolations: number;
  staticAlarmRange: AlarmRange[];
  enumerationAlarm: 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 UsedByInfo {
  algorithm: AlgorithmInfo[];
  container: ContainerInfo[];
}

interface AlgorithmInfo {
  name: string;
  qualifiedName: string;
  shortDescription: string;
  longDescription: string;
  alias: NamedObjectId[];
  scope: Scope;
  language: string;
  text: string;
  inputParameter: InputParameterInfo[];
  outputParameter: OutputParameterInfo[];
  onParameterUpdate: ParameterInfo[];
  onPeriodicRate: string[];  // String decimal
}

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

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

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

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

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

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

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

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

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

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

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

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

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

enum Scope {
  GLOBAL = "GLOBAL",
  COMMAND_VERIFICATION = "COMMAND_VERIFICATION",
  CONTAINER_PROCESSING = "CONTAINER_PROCESSING",
}

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

enum EventSeverity {
  INFO = "INFO",
  WARNING = "WARNING",
  ERROR = "ERROR",
  WATCH = "WATCH",
  DISTRESS = "DISTRESS",
  CRITICAL = "CRITICAL",
  SEVERE = "SEVERE",
}