plane icon Welcome to Microsoft Flight Simulator’s SDK Q&A Platform!

You have questions regarding the SDK? DevMode Tools? SimConnect? You would like to submit an idea for future improvements, seek help or exchange knowledge? You’re in the right place.


Please take a moment to read the platform’s guidelines before you get started!


article

Arzop avatar image
Arzop posted virtuali commented

SU12 Jetway API: Feedback

Hello there,


As you may know, we're going to expose Jetway's data through SimConnect.

During the last SDK Q&A, we said that we'll expose them through the NavData API but in the end, we're going to separate this feature in another API.

Indeed, NavData are "global" data available everywhere for every airports, waypoints... whereas jetway are linked to SimObject which are spawned next to your current location.

That's why we won't make this Jetway API a part of the NavData API even if both of them are linked.


This is how the Jetway API should be used (keep in mind that every functions name, variables name, tokens, flow... might change):


1. To get data from (a) jetway(s), you will need to use a new SimConnect function:


// C++
SimConnect_RequestJetwayData(HANDLE hSimConnect, const char* szAirportIcao, DWORD dwArrayCount, int* pIndexes)

// C#
void RequestJetwayData(string szAirportIcao, ICollection<int> pIndexes)


Using this function, you will be able to request one, multiple or all jetway(s) of an airport.

// Request data from a single jetway
int index = 123;
SimConnect_RequestJetwayData(hSimConnect, "LFPG", 1, &index);

// Request data from jetways 123, 456 and 789
int indexes[3] = { 123, 465, 789 };
SimConnect_RequestJetwayData(hSimConnect, "LFPG", 3, indexes);

// Request all jetways
SimConnect_RequestJetwayData(hSimConnect, "LFPG", 0, nullptr);


2. A jetway is linked to a ParkingSpace, so if you want to request a specific jetway you will have to get the parkingIndex using the NavData API.

// ...

SimConnect_AddToFacilityDefinition(hSimConnect, FACILITY_DATA_DEF_AIRPORT, "OPEN JETWAY");
SimConnect_AddToFacilityDefinition(hSimConnect, FACILITY_DATA_DEF_AIRPORT, "PARKING_GATE");  // Might want to filter using this field
SimConnect_AddToFacilityDefinition(hSimConnect, FACILITY_DATA_DEF_AIRPORT, "PARKING_SUFFIX"); // Might want to filter using this field
SimConnect_AddToFacilityDefinition(hSimConnect, FACILITY_DATA_DEF_AIRPORT, "PARKING_INDEX"); // Index of the Jetway (not the same as PARKING_SPOT)
SimConnect_AddToFacilityDefinition(hSimConnect, FACILITY_DATA_DEF_AIRPORT, "CLOSE JETWAY");

// ...

3. This call might send an exception (SIMCONNECT_EXCEPTION_JETWAY_DATA) if the icao is wrong, if one the given indexes is wrong...

Otherwise, this call will send a SIMCONNECT_RECV_JETWAY_DATA message which is an array of SIMCONNECT_JETWAY_DATA


SIMCONNECT_REFSTRUCT SIMCONNECT_RECV_JETWAY_DATA : public SIMCONNECT_RECV_LIST_TEMPLATE
{
    SIMCONNECT_FIXEDTYPE_DATAV(SIMCONNECT_JETWAY_DATA, rgData, dwArraySize, U1 /*member of UnmanagedType enum*/, SIMCONNECT_JETWAY_DATA /*cli type*/);
};

SIMCONNECT_REFSTRUCT SIMCONNECT_JETWAY_DATA : public SIMCONNECT_RECV
{
    char AirportIcao[8];                        // Icao of the airport (the one you used to request)
    int ParkingIndex;                            // Index of the parking space linked to this jetway (the one you used to request)
    SIMCONNECT_DATA_LATLONALT Lla;                // LLA of the jetway
    int Status;                                    // Enum: Current status of the jetway
    int Door;                                    // Index of the door attached to the jetway
    SIMCONNECT_DATA_XYZ ExitDoorRelativePos;    // Door position relative to aircraft
    SIMCONNECT_DATA_XYZ MainHandlePos;            // Relative position of IK_MainHandle (world pos, in meters)
    SIMCONNECT_DATA_XYZ SecondaryHandle;        // Relative position of IK_SecondaryHandle (world pos, in meters)
    SIMCONNECT_DATA_XYZ WheelGroundLock;        // Relative position of IK_WheelsGroundLock (world pos, in meters)
    DWORD JetwayObjectId;                        // ObjectId of the jetway (used by SimConnect_RequestDataOnSimObject for example)
    DWORD AttachedObjectId;                        // ObjectId of the object (aircraft) attached to the jetway (used by SimConnect_RequestDataOnSimObject for example)
}

enum JetwayStatus
{
    JETWAY_STATUS_REST = 0,
    JETWAY_STATUS_APPROACH_OUTSIDE,
    JETWAY_STATUS_APPROACH_DOOR,
    JETWAY_STATUS_HOOD_CONNECT,
    JETWAY_STATUS_HOOD_DISCONNECT,
    JETWAY_STATUS_RETRACT_OUTSIDE,
    JETWAY_STATUS_RETRACT_HOME,
    JETWAY_STATUS_FULLY_ATTACHED,
};


If you have any feedback (missing data, flow, ideas...), please share it here so we can improve this API and release it in the best state possible.


Best Regards

Maxime / Asobo

simconnect
12 comments
10 |10000

Up to 5 attachments (including images) can be used with a maximum of 4.8 MiB each and 23.8 MiB total.

virtuali avatar image virtuali commented ·

Hi Maxime @Arzop ,

The Jetway API proposal looks very nice and seems to provide all the info we needed. I just need a couple of clarifications:

What's is being returned exactly as ParkingIndex ? The definition use "PARKING_INDEX", but it's then commented to be the Index of the Jetway and not the same as the PARKING_SPOT so, it's just an value we pass to the RequestJetwayData and eventually check in the received structure which jetway we received ?

Does it mean we can't make a single call to get all jetways in the airport at once ?

Another question is about the two objects Id returned, while it seems clear the JetwayObjectId is the ID of the Simobject associated to the Jetway, what is the AttachedObjectId ? The Jetway Link ? But as far as I know, these are not Simobjects. Is anything attached to the Jetway using <ModelAttachments> ? But these can be more than one, so it's not very clear what is the AttachedObjectId refers to.


Also, do you think it might be possible to have additional variations of the JETWAY_TOGGLE Events ?

Something like JETWAY_TOGGLE_ON and JETWAY_TOGGLE_OFF, which might be handy to save a call each to check the Jetway docked status each time we wanted to either Dock or Undock the jetway, no matter the jetway state is in.


1 Like 1 ·
Arzop avatar image Arzop ♦♦ virtuali commented ·

Hi,

- It is now possible to request multiple/all jetways at once.

- A jetway is linked to a parking space. So, to request data from a jetway we need the index (id) of its parking space.

- AttachedObjectId refers to the aircraft attached to the jetway.

- TOGGLE_JETWAY event is not linked to this API so i suggest you to make a dedicated post (on DevSupport) for this request.


Best regards

Maxime / Asobo

0 Likes 0 ·
FlyingRaccoon avatar image FlyingRaccoon ♦♦ commented ·

Hello @Paavo @TheSecretStudio @WombiiActual as you've been involved in similar discussions...
Just wanted to make sure you don't miss the opportunity to provide feedback before the feature is released.

Regards,
Sylvain

1 Like 1 ·
virtuali avatar image virtuali FlyingRaccoon ♦♦ commented ·

I second the request to add, in addition to the jetway position, the insertion heading ( PBH ? )

0 Likes 0 ·
Paavo avatar image Paavo commented ·

I have two suggestions related to jetways:

1. Add heading to jetway struct.

Example use case: if a static jetway (doesn't move sideways; only extends to meet the airplane) is paired with a docking device, then to provide guidance we need to find the point where airplane door should meet the jetway. So we extend a line from jetway's origin along its axis towards the airplane to see where lines intersect. Knowing jetway heading is crucial, because even a small 3 degree placement offset from a perfect 90 deg angle over a 20 m long jetway to the airplane leads to more than 1 full meter of difference at the door.

2. Expose the same values as simvars.

The new XML templating is really good and I always try to use it instead of WASM if possible. It is more portable, easier to manage and better for performance. If a jetway needs simple status-based lights or stairs that extend based on jetway's angle, then shipping a full WASM module for that for every airport is an overkill, when a few trigonometric functions in a behaviour template could achieve the same.

Thus, please consider exposing the data in struct as simvars too:

A:JETWAY MAIN HANDLE X, meters
A:JETWAY MAIN HANDLE Y, meters
A:JETWAY MAIN HANDLE Z, meters

A:JETWAY SECONDARY HANDLE X, meters
A:JETWAY SECONDARY HANDLE Y, meters
A:JETWAY SECONDARY HANDLE Z, meters

A:JETWAY WHEEL GROUND LOCK X, meters
A:JETWAY WHEEL GROUND LOCK Y, meters
A:JETWAY WHEEL GROUND LOCK Z, meters

A:JETWAY STATUS, enum

We already have jetway hood and wheel related simvars, and these would complete the set.

1 Like 1 ·
FlyingRaccoon avatar image FlyingRaccoon ♦♦ Paavo commented ·

@Arzop FYI

0 Likes 0 ·
WombiiActual avatar image WombiiActual Paavo commented ·

Yes Please! Having those simvars would let us do so many fun things with normal simobject jetways!

0 Likes 0 ·
Simbol avatar image Simbol commented ·

Hi Maxime @Arzop ,

When is SU12 Beta planned? we received a beta last night, but Microsoft is calling it AAUI.. so this can cause confusions..

Can you help US to understand better what version is what?

Thanks
Raul

0 Likes 0 ·
FlyingRaccoon avatar image FlyingRaccoon ♦♦ Simbol commented ·

Hello @Simbol

We don't know yet when SU12 beta will begin.
AAU1 is the Aircraft & Avionics Update, featuring some avionics and aircraft packages update.

Regards,
Sylvain

0 Likes 0 ·
Simbol avatar image Simbol FlyingRaccoon ♦♦ commented ·

Hi Sylvain, @FlyingRaccoon

Got you.. thanks for letting US know and the clarification, it is getting tricky to track these updates now haha.. as we understand snow fixes were published with AAU1 so since it is not just avionics, it causes a confusion..

R.

0 Likes 0 ·
Arzop avatar image Arzop ♦♦ commented ·

This article has been updated (V2)

0 Likes 0 ·
virtuali avatar image virtuali Arzop ♦♦ commented ·

Thanks a lot, the API looks very much improved with the update, and it really seem to do everything we could ask for, related to jetways.

Looking forward to be able to test it.


2 Likes 2 ·

Article

Contributors

Arzop contributed to this article