View source for CL650/Shared Cockpit

== Feature Overview ==
[[File:Shared ckpt 1.png|alt=Shared Cockpit model|thumb]]
Starting with [[CL650/Version History#1.7|version 1.7]], the Hot Start Challenger 650 includes support for multi-crew operations with two users, fulfilling the roles of pilot and copilot. This feature works by running two copies of the CL650 on two separate computers, connecting them over the Internet, and synchronizing every aspect of appearance and state of the flight. To the users this function is transparent, it simply appears that there is one aircraft with two pilots, each pilot being able to operate all controls and functions of the airplane.

Please note that starting with version 1.9, the shared cockpit feature has been significantly reworked and functions differently than in prior versions. This documentation describes the shared cockpit feature as of [[CL650/Version History#1.9|version 1.9]], and beyond.

== Prerequisites ==
To utilize the CL650 shared cockpit feature, the following prerequisites must be met:

* Each pilot must have purchased their own copy of the CL650 and X-Plane. '''<u>Account sharing is strictly forbidden.</u>'''
* Sufficient network bandwidth of at least 2 Mbit/s upload (on the host for each connected guest) and 2 Mbit/s download (on the guest). See below for details on which side is the host and which the guest.
* Mixing different X-Plane versions is ''technically'' possible, but '''not recommended''' due to differences in base scenery. The operating system running the simulator is not a limitation -- Linux, Windows, or macOS, all can be used by any participant.

== Principles of Operation ==
During operation, the computer of one user serves as the “host” for the shared cockpit session. Afterwards one or more computers of other users (known as "guests") can connect to the host's simulator.

On the host’s side, the simulator runs essentially as normal. The host can select either "Career" or "Non-persistent" mode during the initial aircraft startup screen. From then on, once it's been enabled in User Settings, the shared cockpit feature operates passively in the background until a guest connects. The host can leave the shared cockpit feature enabled indefinitely, even when not expecting to fly with another person.

To connect, a guest must select "Network Guest" mode from the initial aircraft startup screen. Upon connection, the guest’s simulator will move to the exact location of the host, and their aircraft will mirror the exact state of the host’s aircraft. To speed up simulator and scenery loading, it is recommended that the guest select the same airport as the host when setting up the flight in X-Plane's "New Flight" screen.
[[File:Shared ckpt 2.png|alt=Shared cockpit systems block model|thumb]]
Technically, there are not actually two aircraft operating at the same time. Instead, the aircraft is running entirely on the host’s computer. On the guest’s computer, there is only a minimal set of modules active, primarily the ones for the flight displays and sound generation. The simulator on the guest also forwards any user inputs (flight control movements, keyboard input, etc.) to the host, where they are processed, and the results are then sent back to the guest for display. As such, there’s almost no possibility of desynchronization between the two sides, since the guest doesn’t actually have a full aircraft operating. All the systems, physics, flight management, and avionics are only present on the host, with the guest being able to also interact with those systems remotely (if role permits, see later in this guide).

The practical implications of this technical arrangement are as follows:

* A guest’s simulator environment is entirely irrelevant to the physical state of the aircraft. Guests are encouraged to configure their weather identically to the host (using either real weather, manually set weather, or a 3rd party weather-injecting plugin), but this is only to facilitate a similar visual presentation to the guest.
* Environmental factors, such as the location of visible moisture, precipitation and cloud buildups will typically be identical '''only''' if the time, date, and weather are configured the same on the guest as on the host; using real-time and real-weather is most likely to result in identical conditions.
* The navigational database only matters on the host. The guest’s navigational database isn’t used for any functions of the aircraft avionics and systems simulation. The notable exception is external charts in the aircraft avionics (the "MFD CHARTS" function). This is downloaded and rendered independently by each user's avionics, therefore to achieve consistent results, all users should agree on the same chart provider option(s) (e.g. when the host is using [https://navigraph.com/ Navigraph] charts, all guests should be using that too).
* All users should be using the same scenery (whether customized or stock). Otherwise, visual differences in elements such as hangar building placement, taxiway layout, or airport markings can lead to confusion between the pilots.
* While the shared cockpit feature attempts to account for terrain height differences by utilizing a height blending model, this can lead to seemingly unnatural flight behavior of the aircraft for the guests. This blending starts at 500 ft [[wikipedia:Height_above_ground_level|AGL]] and gradually as the aircraft approaches the ground on the host, the guests will start to blend true elevation with height above local terrain. If there are significant terrain elevation differences between host and guest, the aircraft can appear to suddenly rise or sink in order to make sure it makes ground contact at the same point in time for both host and guest.
* While the aircraft can be hand flown by either host or guest (when assigned the "Pilot" role), network transmission time delay ("latency") can affect the feel and responsiveness of control inputs for the guest. This should be taken into account by the guest user in order to prevent overcontrolling or entering into pilot-induced oscillation due to excessive and rapid corrections. See [[CL650/Shared Cockpit#Operational Considerations|Operational Considerations]] for more information.

== Host Simulator Configuration ==
[[File:Host cfg.png|thumb|463x463px]]
To enable the shared cockpit hosting feature and allow remote access to the flight, go to the simulator menu under Challenger 650 > User Settings > Shared Cockpit and check "Allow others to connect to and control my aircraft." After checking this box, you should reload the aircraft using the "Reload Aircraft" button which appears. To disable the shared cockpit feature completely, simply uncheck the box and again reload the aircraft. Once enabled, shared cockpit preference is stored in the user preferences and automatically reapplied in future simulator sessions.

You should also give yourself a name in the "Your name" field. This is optional, but is the name by which shared cockpit guests will be able to identify your user avatar in the simulator. In addition, you can also customize your avatar's appearance. The button is labeled "My Avatar's Appearance", located the same "Shared Cockpit" user settings tab, under the "Appearance" section.
[[File:Copy to clipboard.png|thumb|244x244px]]
To allow a guest to connect, you must send them the <u>access key</u> generated for the simulator session. This key is regenerated every time the simulator is newly started, or whenever you manually click "Regenerate" on the Shared Cockpit Guest Management window. You can simply copy this access key from the simulator menu by selecting Challenger 650 > Shared Cockpit > Copy shared cockpit access key to clipboard, or by selecting "Copy to clipboard" from the Shared Cockpit Guest Management window.

=== Changes From Versions Prior To 1.9 ===
If you are used to the method of setting up shared cockpit hosting prior to version 1.9, the following aspects have changed:

* You no longer have to configure network port forwarding. Network configuration is now fully automated by default. See below for [[CL650/Shared Cockpit#Advanced Host Configuration|advanced configuration options]] and [[CL650/Shared Cockpit#Troubleshooting|troubleshooting]].
* You no longer configure a static access password. The access key works in its place, and is automatically regenerated each simulator session and can be simply copied from the Shared Cockpit menu, or from the new Shared Cockpit Guest Management window.

== Guest Connection Initiation ==
[[File:Netclient.png|thumb|456x456px]]
The guest can connect by selecting “Network Guest Mode” on the CL650 startup screen. This will show the screen shown on the right-hand side. You will need to enter the following pieces of information:

* A name for yourself. This is the name by which other participants in the shared cockpit session will know your user avatar.
* The access key sent to you by the host. Clicking on the field and pushing <code>Ctrl+V</code> will paste the key from your clipboard (or <code>cmd+V</code> on macOS). Clicking "Show" will reveal the access key, in case there is any doubt whether the correct key has been entered.
* In addition, you can customize your avatar's appearance at this time. This is how your avatar will appear to other shared cockpit participants.

Once all information has been entered, click "Connect." The system will attempt to initiate a connection to the host. In case of connection error, the error message will appear below the avatar customization box. See [[CL650/Shared Cockpit#Troubleshooting|Troubleshooting]] for guidance on how to proceed in case of connection problems.

== User Roles ==
The shared cockpit feature supports assigning participants one of the following roles:
{| class="wikitable"
|+
|[[File:Role pilot.png|none|thumb]]
|'''Pilot:''' this role is always held by the host of the shared cockpit session, and can optionally be assigned to up to one guest. These two participants together form the flight crew and have full access to all flight controls, cockpit switches, as well as external and service doors. When in career mode, these participants can freely move between the aircraft and the FBO, as in single-user mode.
When these shared cockpit participants move about the aircraft, their presence contributes to the aircraft's mass and CG.
|-
|[[File:Role jumpseater.png|none|thumb]]
|'''Jump-Seater:''' when a guest is assigned this role, they can access all cockpit switches, and external and service doors, but they are '''not''' allowed to manipulate the primary flight controls. This role also allows access to the failure manager to set and clear failures. This role also allows the guest to move freely between the aircraft and the FBO. When onboard the aircraft, their presence also contributes to the aircraft's mass and CG, as with the flight crew.
There can be only one jump-seater at any given time. Assigning the role to another user automatically demotes the existing jump-seater to either a passenger or spectator, depending on whether free passenger slots are available.
|-
|[[File:Role pax.png|none|thumb]]
|'''Passenger:''' this role allows the guest to only sit in the cabin and control the cabin environment (i.e. cabin lighting on the galley control panel). Access to the cockpit is restricted, unless given explicit permission by the host using the Shared Cockpit Guest Management window. Even when granted cockpit access, this guest cannot manipulate cockpit switches, flight controls, or external doors and service panels.
In addition, this user is restricted in their movement between the aircraft and FBO. On initial load-in, the guest is only allowed to move about in the FBO, until the flight crew instructs the FBO staff to bring the passengers to the aircraft. Passengers are then moved (in groups of 4) to the aircraft by the passenger transport van. Once at the aircraft, passengers can only move about near the boarding stairs and inside of the aircraft. Their presence contributes to the aircraft's mass and CG. There can be a maximum of 12 passengers onboard the aircraft at any one time.

Guests who join a shared cockpit session before the aircraft has departed are automatically assigned the passenger role, or the spectator role if no free passenger slots are available.
|-
|[[File:Role spectator.png|none|thumb]]
|'''Spectator:''' guests assigned the spectator role are restricted to only moving around the aircraft, with no ability to affect any controls, walk around, and other participants do not see their avatar. In a sense, they are completely passive, not even contributing to the aircraft's mass and CG.
Guests who join a shared cockpit session after the aircraft has departed are automatically assigned the spectator role.
|}
''Note: Guests can have their role reassigned at any time by the session host using the "Shared Cockpit Guest Management" window.''

=== Pilot Seat Assignments ===
For users assigned the Pilot role, the shared cockpit system keeps track of the left and right cockpit seat assignments. By default, the host is assigned the '''Left''' cockpit seat, and the guest with the Pilot role is assigned the '''Right''' cockpit seat. However this can be changed at almost any time. If a seat swap is desired, it can be performed while the aircraft is either stationary on the ground, or in flight, when at a height of greater than 1,300 ft AGL. To request a seat swap either:

* Select Challenger 650 > Shared Cockpit > Request to Swap Seats from the simulator’s main menu; or,
* Click on the seat cushion of the other pilot.

[[File:Seat swap.png|thumb|360x360px]]
When a seat swap is requested, the other pilot must agree to it by selecting “Accept” from the window shown on the right.

The currently active role and seat assignment is indicated using a status bar at the top of the screen. For pilots, it shows “L” on the screen of the currently active left-seater and “R” on the screen of the right-seater:
{| class="wikitable"
|+
|[[File:Left seater.png|none|thumb]]
|[[File:Right seater only.png|none|thumb]]
|}

=== Pilot Control Behavior ===
Either pilot can make control inputs at any time. There is no explicit handover of controls in the software. Therefore, correct cockpit [[wikipedia:Crew_resource_management|CRM]] should be observed, handing over control by standard verbal callouts such as “I have control” and “you have control.” Also, in shared cockpit mode, control inputs no longer follow the view position of the user. They are instead “pinned” to the respective control side, depending on the assumed cockpit seat -- left-seater always to the left controls, right-seater always to the right controls. Non-pilot participants cannot perform any primary flight control inputs.

Control inputs on the roll & pitch axis follow these rules:

*While the respective axis disconnect handle is stowed, inputs from the two pilots are summed up. You can think of this as the two pilots applying force to the control, and the resulting control position being the sum of the mechanical forces. For example, if both pilots are giving a 50% right roll input, the result is a 100% right roll command. Conversely, if one pilot is giving a 50% left roll input, and the other pilot a 50% right roll input, the result is a zero roll command (control wheel neutral).[[File:Shared ckpt 5.png|thumb|258x258px|center]]

*When the control axis disconnect handle is pulled, inputs from each of the pilots are simply applied directly to their respective control wheel and/or column.[[File:Shared ckpt 6.png|thumb|258x258px|center]]

Control inputs on the yaw axis are always summed up between the two pilots, since the yaw axis inputs are independent and only synchronized through springs that can be overcome with force.

Throttle input is somewhat special, since there’s only one set of throttles in the aircraft. The last crew member who made a significant throttle input (>5% axis movement) will have exclusive control of the throttle. If one of the pilots has a very noisy axis input which causes frequent throttle control takeover, they should recalibrate, disable (unassign), or disconnect their respective throttle controls, to avoid interfering with the pilot flying. Alternatively, they can increase the throttle takeover threshold in User Settings > Shared Cockpit using the "Throttle Takeover Threshold" slider, which increases the amount of needed displacement before the system assumed the user has taken over throttle control.

Please also note that the right-seater does '''not''' have control of the steering tiller, so taxiing of the aircraft can only be done by the left-seater.

== Interactions with Ground Handling ==
In Career mode, users assigned the Pilot role can enter and interact with the FBO. Typically it’ll be the responsibility of the fight’s commander to submit a handling request, but the copilot can do so as well. When calling to inform the crew of the passengers having arrived at the FBO, Jenny will only call the flight’s commander (left-seater). However, outgoing calls to the FBO and the passengers can be made by either a Pilot or Jump-Seater, using either the cellphone, or satellite phone.

When the fueler arrives and enters the aircraft, he will first look for the commander (left-seater). If that person is not present inside the aircraft at the time that the fueler attempts to enter, he will try to speak to the copilot (right-seater), if present. If neither crew member is currently inside the aircraft, the fueler will wait for one of them to enter the aircraft.

Either crew member can interact with the de-ice truck. To do so, the crew member wanting to place a call to the de-ice operator should tune to 1<u>36.925 MHz</u> on their respective radio set, and properly set up their audio control panel to be to transmit and receive radio calls.

== Flying with Online ATC ==
Online flying is fully supported in shared cockpit mode on both [https://vatsim.net/ VATSIM] and [https://www.pilotedge.net/ PilotEdge]. Each pilot’s radio reception and transmission is configured according to their own respective audio control panel settings. This will follow the left/right seat roles, as currently assigned.

''Note: Shared cockpit online flying on IVAO or POSCON has not been tested.''

=== PilotEdge ===
One of the pilots, typically the host, will connect to PilotEdge as normal. The second pilot (and optional jump-seater) should then connect using the same callsign with the ‘@’ character appended to the end of the callsign. No further special configuration is required. The PilotEdge server system prevents loopback of crew audio transmissions back to the other crew member, so while other users on the network can hear each crew member speaking, the crew members will not be hearing each other through their radios.

Passengers can optionally also connect to the PilotEdge network, using the same method as above. The PilotEdge pilot client is role-aware and will prevent radio transmissions from passengers.

=== VATSIM (xPilot client) ===
One of the pilots, typically the host, will connect to VATSIM as normal. The second pilot member should connect using the same callsign, but adding a single letter (A–Z) at the end of the callsign to differentiate the connection, and also check “Connect in Shared Cockpit/Observer Mode”. For example, if pilot 1 connected as <code>N123AB</code>, then pilot 2 should connect as <code>N123ABA</code> and check the box for shared cockpit.

Unfortunately VATSIM doesn’t properly implement audio loopback prevention. If pilot 1 transmits while pilot 2 is monitoring the same frequency (either on the same radio, or on another radio), VATSIM '''will not''' inhibit the audio being retransmitted to pilot 2. If the pilots are also using some kind of private voice chat system, such as Discord, this VATSIM audio loopback results in doubled audio being heard by pilot 2 (once through Discord and once through VATSIM). The suggested workaround is to assign <u>push-to-mute</u> in Discord to the same PTT key/button as xPilot is using. That way whenever they transmit on the radios they will be muted on Discord.

Jump-seater and Passenger audio hasn't been tested with the VATSIM network and might not function. It is recommended not to rely on it, or only connect as a passive listener.

== Operational Considerations ==
This section lists various operational considerations and aspects of the shared cockpit function, in no particular order:

* The performance impact of shared cockpit operation is negligible, although additional network traffic will occur. The typical data streaming load is as follows:

{| class="wikitable"
|+
!Side
!Upload
!Download
|-
|Host
|800 kbit/s per connected guest
|100 kbit/s per connected guest
|-
|Guest
|100 kbit/s
|800 kbit/s
|}

*Since user inputs are first sent from the guest to the host, where they are implemented, after which the resulting effects are sent to the guest, network latency can affect the control feel for the guest while hand-flying. The guest continuously monitors network latency and displays it in the status window at the top of the screen, as depicted on the right. The following table lists approximate "control feel" for the guest at various latency values:[[File:Right seater.png|thumb]]

{| class="wikitable"
|+
!Latency
!Rating
!Perceived control response
|-
|< 50ms
|Excellent
|Essentially imperceptible
|-
|50ms - 125ms
|Good
|Slightly perceptible, normal flying technique unaffected
|-
|125ms - 200ms
|Tolerable
|Perceptible, requires gentler inputs to avoid PIO in landing flare
|-
|> 200ms
|Poor
|Very perceptible, difficulty with control in turbulence or in the landing flare.
Hand-flying shouldn’t be attempted by the guest when network latency exceeds 200ms.
|}

* When the host pauses (explicitly or by opening an X-Plane menu), or enters replay mode, the simulators of all guests pause and wait for the host to resume normal flight.
* When the connection to the host is lost, the guest pauses and waits for the host connection to become available. In case the host simulator crashes, the host can restart the simulator and resume the last state save. The guest simulator(s) will automatically reconnect and resume flight alongside the host.
* The Failure Manager is available to any participant assigned either the Pilot or Jump-seater role, and is fully synchronized. This facilitates training, where either one of the pilots or the jump-seater can serve the role of training instructor.
* In shared cockpit mode, the automatic/virtual first officer (accessible via the “Checklist” menu) is no longer available, as its operation would clash with the real human copilot. To operate the checklists, please use the copilot’s CCP, just as the real one would be.

== Limitations ==

* It is not possible to use the "Reverse Detents" axis option in X-Plane to actuate reverse thrust as a Guest. This is due to a limitation in the handling of hardware input of the simulator itself. The workaround is to use a dedicated "Reverse" axis/axes, or button/key commands.

== Networking Technical Discussion ==
This section is intended for advanced users with networking knowledge, or who wish to configure the finer details of how the shared cockpit network connectivity functions. The intended purpose is to allow adapting the shared cockpit system to network environments with special requirements and/or troubleshooting issues. It is not an exhaustive protocol description, but merely a quick overview of how the shared cockpit system interacts with your network.

=== General Principles ===
The custom "net code" inside the addon is known as '''Netlink'''. This layer performs the message encoding, decoding, and network orchestration for the shared cockpit system. Netlink communications between host and guests use the [[wikipedia:QUIC|QUIC]] transport protocol, which runs on top of UDP. In addition, Netlink manages host auto-discovery and [[wikipedia:Hole_punching_(networking)|NAT hole punching]] by utilizing Hot Start's "Meet" server. This serves the purpose of peer discovery, as well as fallback message relaying when direct peer-to-peer connection is not possible.

In order to start a shared cockpit session, the host must be able to do the following:

* Listen on UDP port 8205. (The default port can be changed in User Settings > Shared Cockpit in the "Advanced Options" section.)
* Contact the Hot Start Meet server (<code>meet.hotstart.net</code>) on UDP port 8206 and receive responses.

There is generally no need to configure port forwarding on your router. When a guest enters an access key and clicks "Connect", the system attempts to contact the Hot Start Meet server and requests contact with host that matches the access key (the access key is '''not''' sent "in the clear", unencrypted, over the wire). The Meet server then contacts the host and also returns the host's external IP address and port to the calling guest. In most circumstances, the host and guest then exchange "Hello" messages and start to communicate directly, without involving the Meet server any further. This process is more commonly known as [[wikipedia:UDP_hole_punching|UDP hole punching]].

Rarely, either the guest or host will not be able to establish direct communications. This is typically a result of some form of [[wikipedia:Network_address_translation#Symmetric_NAT|symmetric NAT]] on one of the sides of the connection. In that case, Netlink automatically falls back to relayed operation through the Hot Start Meet server. This will result in increased latency, which may now no longer be acceptable.

When direct communications via UDP hole punching fails, and relayed communication is not acceptable, Netlink allows for another fallback. This involves manually configured direct communication between guest and host. In this case, the host must configure UDP port forwarding on their router, and notify the guest of the host's external IP address. An explanation of how this is done is beyond the scope of this article, but [[wikihow:Set-Up-Port-Forwarding-on-a-Router|this online resource]], as well as online searches, can generally provide reasonable guidance for this fallback mechanism. The host must enable UDP port forwarding of port 8205 on their router, to the machine on the internal network running the simulator, as well as enable inbound UDP traffic on port 8205 through the simulator machine's firewall (if one is active).

=== Advanced Host Configuration ===
The host allows advanced configuration options in the User Settings > Shared Cockpit section.

* Set a custom UDP listen port. This can be altered if the default UDP port of 8205 is used by some other service on the host machine.
* Enforce a connection mode:
** '''Automatic:''' this is the default. The host allows both direct connections from guests, as well as relayed communications via the Hot Start Meet server, preferring direct connections first.
** '''Only allow indirect connections:''' in this mode, the host will explicitly refuse direct connections from guests, and the Netlink Meet server will not even give out the host's IP address to guests. All communications are forced to be relayed through the Hot Start Meet server. This mode might be desirable for hosts who wish not to reveal their external IP address to guests, at the cost of added connection latency.
** '''Only allow direct connections:''' in this mode, the host will refuse relayed connections from guests. If a connection via direct communications is not possible, the connection attempt fails instead of reverting to the relayed mode.

=== Advanced Guest Configuration ===
Similar to the host, the guest can configure additional advanced options prior to the connection attempt:

* '''Hostname:''' this manually specifies the IP address or host name of the host machine, if known ahead of time. When this field is provided, the guest will not attempt to contact the Hot Start Meet server. Instead, it will attempt a direct connection (and only a direct connection, no fallback to relayed operation will be attempted) only to that specified host address.
* '''Port:''' this manually specifies the UDP port to contact on the host. If the host is using a port number other than the default 8205, it must be specified here.
* '''Connection Mode:'''
** '''Automatic:''' this is the default. The guest will first attempt a direct connection to the host. If a direct connection is not possible, the system automatically falls back to relayed connection via the Netlink Meet server (unless a "Hostname" was provided, in which case relayed operation will not be attempted).
** '''Only allow indirect connections:''' in this mode, the guest will explicitly refuse a direct connection to the host. Instead, all communications are forced to be relayed through the Hot Start Meet server. This mode might be desirable for guests who wish not to reveal their external IP address to host, at the cost of added connection latency.
** '''Only allow direct connections:''' in this mode, the guest will refuse relayed connections to the host. If a connection via direct communications is not possible, the connection attempt fails instead of reverting to the relayed mode.

== Troubleshooting ==
When a connection failure occurs, you should generally check the following items:

* Is the access key on the client entered correctly? You can click "Show" next to the key to verify entry.
* Does the guest's and host's firewall allow UDP traffic to port 8205 to pass?
* Verify that both the host and guest have their connection mode under Advanced Options set to either "Automatic" or a matching specific mode (either both direct, or both indirect).
* Can the host support more any more connections? Each guest connection requires up to 2Mbit/s (approx.) of streaming bandwidth from the host, so if too many guests connect, the host's uplink can become saturated.