XCSoar in VR
Adding XCSoar PDA software to your Oculus Virtual Reality cockpit - in the Condor 2 soaring simulator
External PDA devices are not really an option in VR! Another solution is required if you want anything other than the standard PDA in Condor 2.
The solution offered here is the sum of efforts to get XCSoar into VR, then make interaction as easy as possible. XCSoar is run as a process on the same PC as Condor.
This guide covers use of the Oculus Rift / Rift S, but much of it will apply to other VR hardware.
Key features of XCSoar in your VR cockpit
XCSoar is run as a separate ‘pinned’ window within the VR environment. This remains visible, despite you being in another VR application (i.e. Condor). It stays in the place where you put it, visible in front of your virtual surroundings. It seems best positioned as a ‘virtual kneeboard’ (but you can put it wherever you like - at a size that suits you).
Full control of the XCSoar screen is achieved by use of the hat switch and two buttons on the joystick.
Full interaction is possible, with only minimal time away from full control of your glider.
Your cockpit always remains in view even when making complex interactions during flight. When familiar with the controls, any XCSoar action can be made in a similar time to that needed on an external tablet.
How to make it work in VR
What you need to do
This is a summary of what you need to do to get XCSoar inside your VR cockpit.
Download and install a little program called ‘Antimicro’. This enables you to use the joystick ‘hat’ switch to zoom in/out and change pages on XCSoar, and also makes it work as a mouse. Details are here.
Assign the relevant actions in Antimicro for the joystick commands.
Download and install ‘Autohotkey’. This allows control of a number of things. It looks complex but it’s very straightforward to use. The details are here.
Add some relevant instructions to Autohotkey. This is the 'script' that interprets button combinations on your joystick and sends instructions to Condor 2. Details on the 'ManyButtons' script are here.
'Pin' the XCSoar window in your virtual enviroment.
Adjust the appearance of the XCSoar window if desired.
Turn off ‘show layers’ in VR settings. This stops display issues when the pinned window is too close.
Run Condor in VR and adjust the postion of the XCSoar window as required.
And what you get
When it's all done you will then have an XCSoar display visible in your cockpit. You can zoom in / out and change pages with the hat switch whilst flying.
For more complex interactions, you need to switch windows with your assigned button combination. Crucially this leaves your condor view open in VR (it does go quiet and Autopilot is advisable), but now the mouse is visible on your kneeboard XCSoar - for you to do what you need to.
The hat switch is used as a mouse - when XCSoar has focus, and a joystick button is used as a left mouse button ‘click’. It may not be quite as quick as a normal mouse, but you can do everything in XCSoar using only your joystick. When such interactions are completed, the assigned button combination makes the Condor window ‘active’ again.
The vast majority of interactions with XCSoar are map Zoom In/Out or change page actions - and these are very easy and intuitive in flight.
The code includes a Condor view control 'toggle' function - by default set to F1<>F2 (cockpit view to external view), but may be adjused to suit personal preference.
Detailed setup
Full details of these steps are as follows. This guide is written assuming no previous setup in VR, but it does assume that you can get XCSoar loaded and operational on your PC. More details on XCSoar are here.
The easiest way to get to grips with this is to start with the default configuration, then when you have everything working, consider how you need to change the assignments and script to suit your individual preferences.
Start by resetting the Condor controls to 'default' - via 'Setup, Input, Assign controls' (keep notes of your existing assignments before you do this). Things are much less confusing if you do it this way.
Then reassign 'axis' controls (pitch, bank, yaw + any others you may have) if required, as you normally would.
Antimicro
The first thing to do is to get Antimicro working using a joystick settings file - to correctly interpret button presses on your joystick.
For ‘button to key' mappings, Antimicro is really easy to set up. For setting it to use different ‘Sets’ and defining mouse controls it’s a little more involved.
The easiest way is to proceed is to download one of the Antimicro settings files (the 8 button or 12 button solution as required - get the one closest to your hardware).
Copy either the '8B.joystick.amgp' or '12B.joystick.amgp' settings file to your Documents folder.
Start Antimicro, then select load, then find this file.
Selecting ‘Save’ will keep it as the current one.
Note that most joystick buttons are mapped directly to a specific equivalent keyboard key.
The exception is that Button5 (or Button7) states ‘[Set 2 WH]’, meaning that when you hold B5 (/B7) down, things behave differently. (Here B5 refers to the 8 button solution, B7 to the 12 button one.)
If you select ‘Set 2’ at the bottom (click on it), you will see that the hat switch now controls the mouse, and Button1 and Button2 are now Left and Right mouse button clicks respectively.
To be clear - with these settings Antimicro ONLY sends these commands from the Joystick IF B5 (/B7) is held. Release it and Antimicro sends whatever is defined in Set 1 (above).
You can make these assignments yourself once you have worked out where to do it in Antimicro - but starting with the settings file is probably quicker.
Note: If you did click on 'Set 2' above to look at it, click back on Set 1 again before you try to use Antimicro.
AutoHotkey
With the settings loaded in Antimicro, the next step is to run the associated AutoHotkey (AHK) script. If you follow the preassigned settings then the AHK script will work straightaway.
This is simply done by copying the script to your desktop, then double clicking it. It will run in the background until you stop it (via the system tray), or shut down the PC.
Select ManyButtons8.ahk or ManyButtons12.ahk according to your joystick, from the ManyButtons page.
The script uses 2 fundamental buttons that are used as modifiers - think of them as ‘Shift’ or ‘Control’ keys on the keyboard - when you hold them, the other keys will produce a different instruction.
In the default setup these two buttons are, conveniently, Button1 and Button2. And this is where the basic function you select for these is important; you want to to be useful, harmless and also ‘not annoying’.
The selections used in the default solution are “.” (wheelbrake) for B1 and “Tab” (show classification) for B2. These are functions that you (probably) want, but won’t spoil your flight if they are pressed routinely. Imagine that you have “R” (release) assigned to B1 - it will not harm your flight, but the clunking of the release being pulled many times could get quite annoying.
So whilst it’s possible to change these assignments, as they are they do work well, and the AHK code is written in this basis. Let’s proceed accepting the current assignments for B1 and B2 for now.
So, if you start a VR Condor flight, things will happen in the cockpit according to what you have set in Antimicro and the AHK script.
The AHK script will launch the ‘ManyButtons8.txt' or ManyButtons12.txt' controls guide text file for your reference - this will work if the correct .txt file is in the 'Documents\Condor' folder.
If the path is different it will need to be edited in the script - but this is a straightforward process.
Anyway, you can now experiment with the controls - just run through them all (as shown in the text file) - first those specified in Antimicro, then the combinations that are interpreted by Autohotkey.
Those that operate on XCSoar obviously need that to be running - which we will come to next.
To learn the new key combinations you have, you can 'pin' this text file in your cockpit initially.
Getting XCSoar into VR
You can pin any ‘Window’ into the Oculus environment quite easily - when you know how. It's easy and intuitive when you do.
First make sure the Window already exists on the PC, then enter VR. If you don't see the curved panel of controls, press the flat button (O) under your thumb on the right hand controller.
On the curved panel, find the button with the “+” on it on the right end, this allows you to 'Add Desktop Panel'.
Select it using the pointer and the trigger on the right hand controller.
On the list that appears, select the application and window that you want to ‘pin’; again with the trigger.
The window will appear - now you need to move it.
You can ‘grab’ the window - to do this press and hold the button ('grip') under your right second finger. You will find that as you move your hand around, the window follows, according to the position in 3D space you move it to. If you release your 'grip' it will stay put - where you released it.
So now you just need to bring it closer, and resize it, in your preferred location.
You do this by continuing to hold the button under your second finger, then moving the little joystick on top of the controller - left and right to change the window’s size, and down and up to move the window towards or away from you.
When it’s roughly where you want it, you need to select the ‘pin’ icon on the bottom right corner of the window - the pin will become white. When this is done, the window will stay in view when you change applications.
An alternative method to pin a window is accessed via the 'B' key on the top of the right hand controller - whilst pointing at the window, pressing B will bring up a menu from which you can select ‘Pin’. It has exactly the same effect.
With a little practice you will be able to place the window very close to where you want it in a few seconds.
The placement requires a little repetition as you will most likely need to re-centre the view in Condor as you go, as well as get the window aligned properly in your cockpit. In practice this is actually the most fiddly part of the whole procedure.
When you have XCSoar ready (with the appropriate map and task files), go to the VR home and add XCSoar as this pinned window. You can position it roughly correctly on your ‘knee’ and adjust it after seeing where it appears in your cockpit.
Start the Condor flight from Windows and re-enter VR. Adjust the size / position of the pinned window view as required in the VR Home, then switch back to Condor and recentre the view using small head movements until it's where you want it. You can change into and out of Condor using the flat ‘O’ button under your thumb on the VR controller.
Note - for other VR HMDs this window pinning function can be achieved using ‘OVRDrop’ software.
Once you have XCSoar there in your Condor cockpit, you can check your new control of it.
When B1 is held, the hat switch allows zoom in and out on the XCSoar map, and page changes left and right. This is possible when flying with complete control of your glider in Condor - the Condor window has ‘focus’; but you are able to send these simple commands to XCSoar.
MC changes are synchronised with the button commands sent to Condor, and water ballast will toggle in both Condor and XCSoar when you operate the button combination that operates the valve. These controls in XCSoar require that the '.xci' input file is included in your XCSoar installation.
Mousetime
To use the mouse on XCS, you need to do two things:
Select XCSoar as the active window (noting that you then temporarily lose control of Condor, and all goes quiet), and,
You need to HOLD DOWN B5 (/B7) to send the correct mouse commands (Set 2) via Antimicro.
It may take a few moments for the mouse to appear. When it does, you can move the mouse smoothly with the hat switch, and click or double click with Button1. Remember to hold B5 (/B7) until you have finished with the mouse!
When you have finished interacting with XCSoar, you can either deselect XCSoar with the same button combination, OR toggle Autopilot - either will bring Condor back into focus.
Note it will take a few seconds for the sound to return in Condor - this is normal, but control returns straightaway (occasionally you may need to repeat the command). You might want to engage autopilot before switching focus like this.
When you have switched focus to XCSoar, you can use your desktop mouse instead if you wish, it works just the same. After a little practice you will likely find it’s easier to just keep your hand on the stick and use the hat switch.
There is a need to build up muscle memory / intuitive memory for the controls that are assigned - this gets to be familiar after a little time. Ultimately you need to learn this - or you need to fiddle around with keys on the keyboard or find another alternative.
Display modifications
You may find that if you bring the XCSoar window too close within your Condor cockpit it may just go black whatever you do. This is to do with the way that different ‘layers’ in VR interact.
The solution is in the settings in the Oculus environment.
Open this using the 'Settings' gear wheel, the select Graphics, and set the 'Enable VR Layers' toggle to On.
The only downside of this is that some text (chats, Flap positions etc) may become harder to read, however it's a small price to pay.
In the same settings menu, you can if you wish reduce the real estate XCSoar takes up by trimming the window controls off the bottom of the window.
You do this via Settings, Experiments, Hide Panel Controls.
Note - if you do remove the window controls in this way, you will need to use the 'B' key and menu to 'pin' the window - as described earlier.
The special code for the exceptions
Antimicro is a very clever little application, but it does have one drawback. To get the mouse controls working, you need to activate a different ‘Set’ - Set 2 in our case. The drawback is that when you ask a button to perform this set change, it is not able to do the thing you want it to any more (by default these functions are R (release) for B5 or Space (start flight) for B7). The only way round this is some code in Autohotkey, to keep all the other functions working as normal key combinations - when B5 (/B7) is used. So, if you want to reassign controls that involve these buttons, there may be a lot of code manipulation to do to keep all this working. An alternative is to lose some functionality and ONLY use B5 (/B7) to activate Set 2. But this obviously loses up to 3 valuable buttons/combinations.
Having noted the above exception, most of the associations in the AHK script are very straightforward - Hold A, press B, and the output to Condor will be C.
It’s straightforward enough to recalibrate this as ‘Hold A, press C and output B to Condor.’ And in this case think of ‘C’ as G (gear), R (release), A (toggle auto rudder) or whatever you want.
How to modify the control assignments
It's very likely you will want to use different controls to the default ones. If so, the suggested way forward is to edit a copy the controls guide text file - decide what controls you want where - then see what you will need to modify in the script to make it work.
Once you have a template for 'what you want where', first modify a copy of the Antimicro settings file for the key changes and save it. That part is very quick.
Then you can edit the AHK script using Notepad.
For every changed item, find the appropriate part of the script and change out the input or output ‘keys’. You need to be quite methodical when you do this, but it’s quite achievable.
When you are done - test it all in flight, and obviously revisit anything that doesn't work as you expect. The effort in getting it set up the way you want is definately worthwhile.
As a very simple example, simply changing the 'P' to an 'A' in both the controls guide text file and the AHK script file would redefine this key combination as 'toggle Autorudder'.
The AHK script
The code is in 6 sections - after some preliminary parts.
Part 0 is the code which fixes the behaviour of the Set 2 selector button.
Part 1 is the part which defines what happens when you hold B1 (“.” - brake by default) with another key.
Part 2 is the part which defines what happens when you hold B2 (“Tab” - show classification by default) with another key.
Part 3 defines some useful Windows commands.
Part 4 defines commands for individual control of MC settings - in Condor only.
Part 5 defines an alternative way to close the flight window if the Exit menu will not appear.
Note that there are some keys that give Condor indigestion when you attempt to send them from Autohotkey - Condor just does not see the instruction. One example of this is “NumpadMult” (show labels). In the 12 Button default setup this is assigned as B10 in Antimicro - and this works. But all attempts to get this (*) to send from Autohotkey would not work.
If you want this function via Autohotkey you can just change this one key in the Condor key assignments to an available letter. The “=“ and “-“ and 'Numpad +' commands also have this issue, there may be some others too.
There are some functions contained in the code (e.g. Vario volume adjustments) which are not active, but can be with a simple editing process.
If required, you can find further information on special key assignments in AutoHotkey here.
Obviously those who already have things running in VR can just pick up any useful parts of the code and add it to their setup.
The script looks for a copy of the controls guide text file ManyButtons8(/12).txt in your \Documents\Condor folder. You will need to place a copy there, or edit the path in the script.
You can edit the file path (/name) for the controls guide file at this point in the script.
This text file is left available for your reference as a minimised Notepad window (which can be temporarily 'pinned' in your cockpit whilst learning control combinations).
MacCready
MacCready setting changes are easy - synchronised between Condor and XCSoar (there may be a small difference due rounding errors - if calibrated in knots ). If these become unsynchronised you can resync them by using the 'Condor only' MC adjustments. Then they will both move together using the standard control.
Switching between MC manual and MC Auto in XCSoar is available. If MC Auto is used you will again need to use the individual 'Condor only' MC adjustments.
Note the ‘safety MC’ in XCSoar needs to be set to zero - to start with the MC in both systems synchronised at 0.0.
Development notes
The solution here has been developed and tested within the DSGC club environment.
Inevitably some issues will arise and improvements may be obvious to others. Feedback is welcome - goldenhawk77v@gmail.com .
Improvements
For simplicity, in developing this solution every effort has been made to leave the key assignments per the ‘Default’ assignments in Condor settings.
This has worked successfully for the current set of assignments; however as noted above Condor does not accept some characters output from Autohotkey. The "."(Full stop/period) character (controlling the wheel brake) and conveniently assigned to the trigger button generates an unusual behaviour. To still work as a wheelbrake, the button needs to be set to ‘passthrough’.
For all the Autohotkey control interactions this works fine within Condor. However if you use key combinations to change windows, Button1 will try to send multiple "." Characters to the selected window. This will happen in XCSoar also if you don’t hold B5 (/B7) first - XCSoar will complain audibly.
Having said that, whilst it’s not perfect, this solution is probably better than changing the wheel brake assignment. In any case people can edit the script as they wish.
Clearly the pinned window that you get is pinned relative to your environment rather than your cockpit. Condor does subtly move the cockpit around to generate a feeling of flight - but the pinned window does not move with it. Unless there is deeper integration into Condor I don’t see a way around this.
It would be great if we could simply run a script which takes your prepared XCSoar window and places it into your cockpit! OVRDrop does something like this, but is not perfect. Using OVRDrop would also add another layer of complexity, so it has not been included here. Perhaps at some point we will be able to add window positioning instructions to Oculus directly.
It would also be great if there was more information available on direct inputs to XCSoar - but information on this and syntax that works is very hard to find. Some of the functions included here are elaborate workarounds.
It’s difficult to see how the ‘typed chat’ function in Condor can be interfaced via the joystick. A voice based solution may be best for this in VR.
Acknowledgements
This solution builds on the contributions of others in the condorsoaring forum.
Many thanks to: edwalker, GlenBecker, Jeffchristope, Bruce D, miguez, janjansen , Pit_R, Vlovs, Tailspin, h.kresco, jorjemarmor, Xavier, k6chris