Configuration - RoystonS/BetterBravoLights GitHub Wiki

Important note:

This page describes how you can configure the way in which Better Bravo Lights (BBL) takes what's happening in Flight Simulator and reflects that via lights on your Bravo Throttle.

If all you want to do is to get BBL working, you don't need to read any of this page; you only need the content here if you need to configure an aircraft that BBL doesn't know about or want to change how a light works.

If you make some useful configuration entries, please share it with us on GitHub and we'll look at adding them to the default configuration for others to use!

Configuration Files

BBL has two configuration files for controlling the behaviour of lights:

  1. an internal Config.Builtin.ini file which contains the configuration entries that BBL ships with; this lives in the Program folder and you should not modify it.
  2. a user-modifiable Config.ini file which you can edit to add your own personal configuration to override the built-in configuration or add new aircraft.

Whenever BBL looks up a configuration value, entries in the user Config.ini file override those of the built-in Config.Builtin.ini file.

The intention is that you should carry your Config.ini file from one release of BBL to another, and that file should contain as little as possible. If you find yourself maintaining a large set of configuration, please contact the BBL authors to see if you can get some of that configuration adopted and maintained in the product so that others can share your work.

Configuration Syntax

The configuration file Config.ini is a standard .ini file.

Comments

  • Lines starting with a semicolon (;) are treated as comments and are ignored

Settings

The bulk of a BBL configuration file consists of 'settings' lines which typically indicate how individual lights are controlled. They're of the form:

setting = expression

Some examples:

  1. LowVolts = A:ELECTRICAL MAIN BUS VOLTAGE, volts < 26
  2. AUTOPILOT = L:A32NX_AUTOPILOT_1_ACTIVE == 1 OR L:A32NX_AUTOPILOT_2_ACTIVE == 1

We'll cover these in great detail shortly, but informally you can read these as:

  1. The LOW VOLTS light on the Bravo should be on if the main bus voltage is less than 26 volts.
  2. The AUTOPILOT light on the Bravo should be on if either of the two A320 autopilots are active.

Light Names

The light names used in settings lines largely match those found on the Bravo itself:

  • Autopilot buttons
    • HDG, NAV, APR, REV, ALT, VS, IAS, AUTOPILOT
  • Gear lights; 3 pairs of green and red lights
    • GearLGreen, GearLRed
    • GearCGreen, GearCRed
    • GearRGreen, GearRRed
    • If you're reading this and thinking "Cool, I can make amber gear lights", please read the amber gear lights page before doing that!
  • Annunciator lights
    • MasterWarning, EngineFire, LowOilPressure, LowFuelPressure, AntiIce, StarterEngaged, APU
    • MasterCaution, Vacuum, LowHydPressure, AuxFuelPump, ParkingBrake, LowVolts, Door

(BBL is case-sensitive, so you need to write AUTOPILOT, not AutoPilot or AuToPiLOT.)

As well as controlling lights, settings lines can also control some other settings; these are described in the 'Advanced settings' section below.

Expressions

The 'expression' part of a setting (e.g. A:ELECTRICAL MAIN BUS VOLTAGE, volts < 26) can be made up of many different parts:

Variables

The most common item found in a light expression is some sort of simulator variable which represents a particular piece of the state of the simulator. For instance, the state of the landing gear, the oil pressure in engine 3 or whether autopilot 2 is enabled.

BBL supports both of the main types of simulator variables found in Flight Simulator: "A: variables" and "L: variables".

A: Variables

You may also see these referred to as 'simulation variables' ('simvars') or 'simconnect vars'. These are standard variables that are built into Flight Simulator.

The official Microsoft SDK documentation provides details of most simvars: https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Simulation_Variables.htm

Simvar names are always prefixed with an A:, and they must always be followed by the units you want to read the variable in.

For example, A:GENERAL ENG OIL PRESSURE:1, bar and A:GENERAL ENG OIL PRESSURE:1, psi both read the GENERAL ENG OIL PRESSURE:1 variable, but with automatic conversion into the specified units.

Some simvars are 'indexed'. For instance, A:ENG OIL PRESSURE:1 and A:ENG OIL PRESSURE:2 are the different oil pressures for engines 1 and 2.

Details of available units can be found in the Microsoft documentation, at: https://docs.flightsimulator.com/html/Programming_Tools/SimVars/Simulation_Variable_Units.htm

L: Variables

You may also see these referred to as 'lvars' or 'local simvars'. These are 'extension' variables that are added to Flight Simulator by addons. (In a few cases Microsoft have added their own lvars as standard.)

Their names are always prefixed with an L:, are always numeric, and don't support automatic units conversion. (You can use BBL to perform basic arithmetic to enable such conversion. See below.)

For example, L:Generic_Master_Warning_Active is a 'standard' lvar that Microsoft use to represent the state of the Master Warning light in some aircraft.

L: variables are frequently aircraft-specific and are rarely documented but a notable exception to this is the excellent documentation that FlyByWire provide for their A32NX aircraft, at https://docs.flybywiresim.com/pilots-corner/a32nx-briefing/a32nx_api/ and https://github.com/flybywiresim/a32nx/blob/master/docs/a320-simvars.md.

Fixed values

In light settings expressions you can use

  • decimal numbers, e.g. 0, 1, 2.5, -42
  • hexadecimal numbers, e.g. 0x56d8
  • fixed light values ON or OFF

Examples:

  • LowVolts = A:ELECTRICAL MAIN BUS VOLTAGE, volts < 26
  • LowHydPressure = OFF

Comparison operators

BBL supports the 6 standard comparison operators:

  • < (less than)
  • <= (less than or equal to)
  • == (equal to)
  • != (not equal to)
  • >= (greater than or equal to)
  • > (greater than)

Arithmetic operators

BBL supports:

  • + (add)
  • - (subtract)
    • As well as subtracting one value from another, BBL also supports a 'unary' minus, where a minus sign is applied to an entire expression; for example, -(X + Y)
  • * (multiply)
  • / (divide)
  • ( and ) (parentheses or brackets, to override operation order)

It also understands the standard BODMAS/BIDMAS/PEMDAS order of operations, meaning that BBL will correctly treat the expression a + b * c + d as if you'd written a + (b * c) + d.

Logical operators

BBL supports the standard logical operators:

  • AND (which can also be written as &&)
  • OR (which can also be written as ||)
  • NOT

Similar to the order of operations for arithmetic operators, AND binds more tightly than OR, so BBL will treat a OR b AND c OR d as if you'd written a OR (b AND c) OR d, and you can use parentheses/brackets to override this.

Note that both AND and OR are 'short-circuiting' operators as of BBL v0.6.0. This means that if one side of the value is enough to determine the overall result of the expression, the other side of the value is irrelevant. For example:

  • expr1 OR expr2 will evaluate to true if expr1 is true irrespective of the value or error state of expr2
  • expr1 AND expr2 will evaluate to false if expr1 is false irrespective of the value or error state of expr2.
  • This has an impact on how erroneous (e.g. missing) L: variables are handled. See the Error handling section of the advanced configuration page if you want to know more.

Examples:

  • AUTOPILOT = L:A32NX_AUTOPILOT_1_ACTIVE == 1 OR L:A32NX_AUTOPILOT_2_ACTIVE == 1
  • LowVolts = A:ELECTRICAL MAIN BUS VOLTAGE:1, volts < 25 AND (A:ELECTRICAL BATTERY LOAD:1, amps > 0 OR A:ELECTRICAL BATTERY LOAD:2, amps > 0)

Binary/bitwise operations

As of version 0.7.0, BBL supports some bitwise operators:

  • & (bitwise AND)
  • | (bitwise OR)

Note: The bitwise AND & operator works on binary numbers whereas the logical AND (AND / &&) operator works on true/false values.

Bitwise operators are useful for checking variables which are masks, such as (A:LIGHT ON STATES for example).

Examples:

  • A:LIGHT ON STATES, mask & 0x0008 == 0x0008 would check for the taxi lights being on.

Examples of light settings

  • LowHydPressure = OFF

    Specifies that the 'LOW HYD PRESSURE' light should be permanently off. This could be used to override configuration from the [Default] section which isn't appropriate for some specific aircraft

  • LowVolts = A:ELECTRICAL MAIN BUS VOLTAGE, volts < 24.5

    Specifies that the 'LOW VOLTS' light should be on if the ELECTRICAL MAIN BUS VOLTAGE variable (measured in volts) is less than 24.5. Otherwise it should be off.

  • LowOilPressure = A:GENERAL ENG OIL PRESSURE:1, bar < 2.5

    Specifies that the 'LOW OIL PRESSURE' light should be on if the GENERAL ENG OIL PRESSURE for engine 1 (measured in bars) is less than 2.5.

  • LowOilPressure = A:GENERAL ENG OIL PRESSURE:1, psi < 10

    Specifies that the 'LOW OIL PRESSURE' light should be on if the GENERAL ENG OIL PRESSURE for engine 1 (measured in psi) is less than 10.

  • GearLRed = A:GEAR LEFT POSITION, percent over 100 > 0 AND A:GEAR LEFT POSITION, percent over 100 < 1

    Specifies that the left gear red light should be on if the GEAR LEFT POSITION (measured in percent/100) is between 0 and 1 (but isn't exactly 0 nor exactly 1); this is how we specify that a gear light should be red if the gear is partially down.

  • LowOilPressure = (A:GENERAL ENG OIL PRESSURE:1, psf > 0 AND A:GENERAL ENG OIL PRESSURE:1, psf < 15120) OR (A:GENERAL ENG OIL PRESSURE:2, psf > 0 AND A:GENERAL ENG OIL PRESSURE:2, psf < 15120)

    Specifies that the 'LOW OIL PRESSURE' light should be on if either of the two engine's oil pressures is between 0 and 15120. It will not be lit if the oil pressure is precisely 0 (which means it still works on a single-engine aircraft).

Sections

Whilst most of the configuration file consists of settings lines, these settings are applied to specific aircraft by being grouped together into 'sections'.

The beginning of a section is marked by a line starting with a section name in square brackets. For example [Aircraft.Asobo_Pitts].

Configuration for a specific aircraft is found in a section named [Aircraft.<aircraftname>].

Aircraft names need to be specified precisely and should be the internal name used inside Flight Simulator, such as Asobo_Pitts or Asobo_Savage_ShockUltra_Skis. You can find the exact name of your current aircraft by looking in the top right of the BBL lights debugging screen.

For example,

[Aircraft.Asobo_TBM930]
LowOilPressure = A:ENG OIL PRESSURE:1, psi < 105
LowVolts = A:ELECTRICAL MAIN BUS VOLTAGE, volts < 28

[Aircraft.Asobo_DA40_TDI]
LowOilPressure = A:GENERAL ENG OIL PRESSURE:1, bar <= 2.3
LowVolts = A:ELECTRICAL MAIN BUS VOLTAGE:3, volts < 14

would specify different configurations for the 'Low Oil Pressure' and 'Low Volts' lights for the TBM930 and DA40 aircraft.

Avoiding repetition

It's common for multiple aircraft to share some configuration. For instance, if an aircraft has floats and skis variants, then technically it's 3 different aircraft as far as Flight Simulator is concerned. We don't want to duplicate our configuration for that aircraft 3 times, so, in an extension to standard .inifile syntax, BBL allows you to target multiple sections at the same time, by comma-separating the section names. You can also use the same section name multiple times in a file.

For instance:

[Aircraft.Aircraft1, Aircraft.Aircraft2, Aircraft.Aircraft3]
Light1 = A:SOME VARIABLE, bool == 1
Light2 = A:OTHER VARIABLE, bool == 1

[Aircraft.Aircraft2]
Light3 = L:ANOTHER VARIABLE == 1

is the same as writing

[Aircraft.Aircraft1]
Light1 = A:SOME VARIABLE, bool == 1
Light2 = A:OTHER VARIABLE, bool == 1

[Aircraft.Aircraft2]
Light1 = A:SOME VARIABLE, bool == 1
Light2 = A:OTHER VARIABLE, bool == 1
Light3 = L:ANOTHER VARIABLE == 1

[Aircraft.Aircraft3]
Light1 = A:SOME VARIABLE, bool == 1
Light2 = A:OTHER VARIABLE, bool == 1

but without duplicating information.

'Default' section

Some pieces of lights configuration are so common that they should simply apply to all aircraft by default unless an aircraft specifically overrides that configuration. This is where the section named Default comes in.

For instance, it's pretty obvious that we should turn on the 'Auto Pilot' light if the simulator tells us that the auto pilot is enabled. So, instead of adding the setting

AUTOPILOT = A:AUTOPILOT MASTER, percent over 100 == 1

to every aircraft, we simply add it once to the Default section. And indeed, BBL ships with this exact rule in its built-in configuration.

Some more complex aircraft - with multiple autopilots or where an aircraft producer isn't using the standard AUTOPILOT MASTER variable - override this rule, but on the whole this rule works for almost every aircraft so it makes sense to put it in Default.

Note that if you're flying with an aircraft that BBL has no specific configured for, only the entries in the Default section will take effect.

How can I tell whether my lights expressions are working or not? How do I 'debug' my configuration?

Whilst Better Bravo Lights is running, it'll show a light-bulb icon in the system tray. Right-click that and click 'Debugger'. A diagnostics window will open up, showing the status of each light. Clicking on the radio button next to a light will show the configured expression and the current values of all the variables mentioned in the expression.

image

In the above picture we can see:

  • several autopilot and annunciator lights are lit: these are shown in red
  • all of the gear lights are green
  • we've selected the LOW OIL PRESSURE light to monitor it to find out why the light is lit
    • we can see the light is using the expression (A:ENG OIL PRESSURE:1, psi <= 60) OR (A:ENG OIL PRESSURE:2, psi <= 60)
    • we can see the current value of A:ENG OIL PRESSURE:1, psi is 37.18. This is less than or equal to 60, which is why the light is lit
    • (that is, engine 2's oil is fine but we have a leak on engine 1, so the light is correctly lit)

I have a new aircraft that Better Bravo Lights doesn't know about. How on earth do I go about configuring it?

It's a good idea not to guess at values such as the threshold for low oil pressure; instead, check the POH, or check in the actual aircraft module itself. The aircraft files panel.xml or cockpit.cfg are useful files to check as they describe the configurations for on-screen anunciators and/or the red/yellow/green ranges for panel gauges.

Some third-party aircraft manufacturers are incredibly helpful and provide complete lists of their custom variables. FlyByWire provide this list for the A32X, for instance: https://github.com/flybywiresim/a32nx/blob/master/docs/a320-simvars.md. Most, however, don't document their variables, so you're likely to have to poke around and figure things out the hard way.

BBL itself comes with an experimental 'Variable List' user interface. This shows all known variables currently available in the simulator, both A: and L: variables, which can provide significant help when tracking down the variables that determine whether your light should be on or off.

I want to do something more advanced

To keep this page from getting even longer we've moved some of more advanced concepts out to a separate page.

So, if you want to know about:

  • Inverting the behaviour of lights
  • Configuring a 'master enable' option to enable or disable all your lights based on a condition
  • The gory details of how aircraft, default, user and built-in configuration overrides interact
  • Error-handling when variables don't exist

head on over to the advanced configuration page.