Defining Aural Alerts Using panel.xml

Introduction

When using the Aural Alert System API, you may choose to support defining aural alerts and their activation criteria in panel.xml.

The Aural Alerts Syntax

To use this syntax, include any tag in panel.xml that has as its children a series of <Alert> tags. Each child <Alert> tag then defines a single alert:

<AuralAlerts>
  <!--
    Defines a non-repeating alert that plays the 'aural_autopilot' sound event when the AUTOPILOT MASTER simvar changes
    from 1 to 0.
  -->
  <Alert uuid="autopilot" queue="my-queue" priority="10" continuous="false" requeue="false">
    <Sequence>aural_autopilot</Sequence>
    <Condition>
      <Not>
        <Simvar name="AUTOPILOT MASTER" unit="Bool"/>
      </Not>
    </Condition>
  </Alert>

  <!--
    Defines a repeating alert that plays the 'aural_no_takeoff' sound event when the 'cas-no-takeoff' CAS alert is
    displayed with Warning priority in either the unacknowledged or acknowledged state.
  -->
  <Alert uuid="no-takeoff" queue="my-queue" priority="0" continuous="false" requeue="true">
    <Sequence>aural_no_takeoff</Sequence>
    <CAS uuid="cas-no-takeoff" type="warning" acknowledged="true" />
  </Alert>
</AuralAlerts>

note

The Aural Alerts syntax has some important limitations:

• Alerts cannot be triggered/untriggered.
• Alerts cannot be customized when activated.
• Aliases and suffixes are not supported.

To parse and use the alert definitions from panel.xml, you can use the DefaultXmlAuralAlertParser and AuralAlertSystemXmlAdapter classes.

The following is an example of how to configure an instrument to support alerts defined in panel.xml using the Aural Alerts syntax (it is assumed that AuralAlertSystem is already set up and initialized):

import { AuralAlertSystemXmlAdapter, CasSystem, EventBus, CompositeLogicXMLHost, DefaultXmlAuralAlertParser } from '@microsoft/msfs-sdk';

class MyInstrument extends BaseInstrument {

  private readonly bus = new EventBus();

  private readonly logicHost = new CompositeLogicXMLHost();

  // Can be either primary or non-primary
  private readonly casSystem = new CasSystem(this.bus);

  // ...

  public connectedCallback(): void {
    super.connectedCallback();

    // The second constructor argument sets the default queue to assign alerts that didn't explicitly define a queue in panel.xml.
    const parser = new DefaultXmlAuralAlertParser(this, 'xml-default-queue');

    // Get the parent element containing the alert tags
    const element = this.xmlConfig.getElementsByTagName('PlaneHTMLConfig')[0].querySelector('AuralAlerts');

    const adapter = new AuralAlertSystemXmlAdapter(this.bus, this.logicHost, this.casSystem, element, parser);

    adapter.start();
  }
}