User:Zakharov/zkv1000 installation guide

Get the sources

the whole zkv1000 can be retrieved from https://seb.lautre.net/git/seb/zkv1000. You will have the choice with different ways (git, zip or tar.gz).

You have the choice of the destination of the source (in order of recommandation)

1. in $FGHOME/Aircraft/Instruments-3d
2. in your aircraft directory
3. in $FGDATA/Aircraft/Instruments-3d

We'll refer to the zkv1000 installation directory as $ZKV1000 later in this document

Installation in the cockpit

The glass cockpit and the material around are included in the sources, but you can provide yours. Please see the advanced installation below.

The zkv1000 provides files in order to let you choose if you want a PFD, a MFP, both of them, or two PFDs and one PFD.

So the installation depends on what you want. Place in your cockpit the following files in the XML definition files of your aircraft

Configuration	Files needed
PFD only	$ZKV1000/pfd-pilot.xml
MFD only	$ZKV1000/mfd.xml
1 PFD + 1 MFD	$ZKV1000/pfd-pilot.xml + $ZKV1000/mfd.xml
2 PFD + 1 MFD	$ZKV1000/pfd-pilot.xml + $ZKV1000/pfd-copilot.xml + $ZKV1000/mfd.xml

Here's an example from the Lancair 235, configuration with a PFD in front of the pilot's seat and a MFD between the pilot's seat and the copilot's seat, a bit inclinated in direction of the pilot. These lines take place in the dedicated file about the cockpit definition.

  <model>
    <path>Aircraft/Instruments-3d/zkv1000/pfd-pilot.xml</path>
    <offsets>
      <x-m> -0.023 </x-m>
      <y-m> -0.235 </y-m>
      <z-m> -0.028 </z-m>
    </offsets>
  </model>
  <model>
    <path>Aircraft/Instruments-3d/zkv1000/mfd.xml</path>
    <offsets>
      <x-m> 0.03 </x-m>
      <y-m>  0.06 </y-m>
      <z-m> -0.028 </z-m>
      <heading-deg> -15 </heading-deg>
    </offsets>
  </model>

make it work

Once your device is installed in your cockpit you may tell FligthGear where to find the underlying Nasal code. This is done in the <nasal> section of your aircraft definition. Obviously this is one of the manadatory step and value, the Nasal namespace must be zkv1000.

    <zkv1000>
      <file>Aircraft/Instruments-3d/zkv1000/zkv1000.nas</file>
    </zkv1000>

You have other options you can pass to the device in the <instrumentation> section of your aircraft definition

  <instrumentation>
...
    <zkv1000>
      <alerts>
        <Vx>15</Vx>
        <Vy>110</Vy>
        <Vr>65</Vr>
        <Vglide>80</Vglide>
        <stall-aoa>12</stall-aoa>
        <approach-aoa>4</approach-aoa>
      </alerts>
      <eis>
        <type>single-prop</type>
      </eis>
    </zkv1000>
...
  </instrumentation>

The available options are

Category	Option	Meaning	Values
alerts	Vspeed	default V-speed speed, displayed with a mark in the PFD's speed tape identified by the text after the uppercase V (Vfoobar, Vx, Vglide, etc.), no default value	a number in knots, it can be modified by user using zkv1000 UI except for Vne, no default value
	stall-aoa	The stalling angle of attack, if defined it is displayed in AOA widget	a number in degrees
	approach-aoa	The expected angle of attack at approach phase, if defined it is displayed in AOA widget
	warnings	Set of as simple as possible Nasal scripts to use the internal alerts system, internally the message identifies the alert so be careful not to use the same message for two different warnings. Indexing the warning space can be useful if some property has to be modified like message or level, letting you use only one definition of a kind of alert with multiple levels and messages. There are 3 alerts levels: 0 (information), 1 (warning), and higher values (begins with 2, decimal allowed) for really important alerts. The UI will sort the alerts in descendant order (highest level first). Only the triggered alerts are shown (i.e return true) An example may help a bit <warnings> <warning n="0"> <script><![CDATA[ var severity = getprop('/environment/icing/icing-severity'); if (severity) { setprop('/instrumentation/zkv1000/alerts/warnings/warning/level', severity); setprop('/instrumentation/zkv1000/alerts/warnings/warning/message', sprintf('%s ICING CONDITIONS', string.uc(getprop('/environment/icing/icing-severity-name')))); } return severity; ]]></script> <level>0</level> <!-- set by script --> <message>icing conditions</message> <!-- set by script --> </warning> <warning n="1"> <script><![CDATA[ getprop('/consumables/deice') / (getprop('/controls/deice/mode')+2) < 100; ]]></script> <level>1</level> <message>deice liquid low</message> </warning> ... </warnings>
eis	type or file	the type of EIS on MFD only, defaults to none	"none" means... none, the other possible values are the nasal definitions of file as in $ZKV1000/Nasal/eis (without the .nas extension) or the relative path to your definition specific to your aircarft

More options to come...

The zkv1000 Nasal code is loaded at the end of the FDM initialization. Knowing that if you want to automagically switch on the zkv1000 there is a function named zkv1000.powerOn(), otherwise there is a predefined multikey :zo witch will call the powerOn() function.

This should work and you and your aircraft's users should enjoy the instrument :)

Advanced installation

You may want to use your own 3D objects, this is not a problem.

Each component of the zkv1000 is created at the power on if a property exists : /instruments/zkv1000/<NAME>/status in wich NAME is a string with the pattern: (MFD|PFD)[optional identifier]

So there are 3 optional properties useful to create your own device (only screen-object is available for now)

Property	Role
/instruments/zkv1000/<NAME>/screen-object	The name of the 3D object
/instruments/zkv1000/<NAME>/screen-view	N/A The size of the view in Canvas context (defaults to [1024, 768])
/instruments/zkv1000/<NAME>/screen-size	N/A The value of the Canvas size (defaults to [1280, 1280]), this value should be a square and large enough to allow rotation of the view without a not included pixel

In the zkv1000 namespace API specific for one component will be available by the NAME:

zkv1000.flightdeck['PFD-example'].knobs.FmsInner(...)

API

softkeys

There are 12 softkeys, related to the twelve boxes along the bottom of the zkv1000 screen. They are accesible via the Class softkeys

SoftKey(number, pressed)

arguments:

 * number: the number of the softkey, from 0 on the left-side, to 11 at the most right
 * pressed: if the button is being pressed (1) or released (0), actually only pressed status is usable

buttons

.buttons.FMS .buttons.ENT .buttons.CLR .buttons.PROC .buttons.FPL .buttons.MENU .buttons.DirectTo .buttons.PAN .buttons.AsSwitchCOM .buttons.AsSwitchNAV .buttons.ALT

knobs

.knobs.FmsOuter(direction)

takes one argument which is the direction of the turn: cmdarg().getNode('offset').getValue()

.knobs.knobs.FmsInner(direction)

takes one argument which is the direction of the turn: cmdarg().getNode('offset').getValue()

.knobs.display.updateNAV({set:1})

set the value for standby frequency for the selected NAV radio

.knobs.display.updateCOMM({set:1})

set the value for standby frequency for the selected COMM radio

.knobs.display.updateHDG()

no argument, just refresh the HDG display when the knob is used

.knobs.display.updateCRS()

no argument, just refresh the CRS display when the knob is used

.knobs.display.updateALT()

no argument, just refresh the ALT display when the knob is used

.knobs.display.updateBARO()

no argument, just refresh the BARO display when the knob is used