High level API

[EvenAR]

@Pomax's work on msfs-simconnect-api-wrapper has really inspired me to do something similar with node-simconnect. I want to make it clear that I'm not trying to copy Pomax's work. I've noticed that starting with node-simconnect can be a bit challenging. There's a bunch of basic code and technical stuff that assumes you're already familiar with the official SDK, as well as the older-style data types and byte structures. I believe it would be really useful if even newcomers to Node.js could easily use this library with any simulator (FSX, P3D or MSFS). I hope you can see where I'm coming from.

Pull request #84 introduces a new layer on top of the most commonly used features:

• simulation variables
• events
• facilities
• and potentially more

Currently, I'm working on finding the best "generic" API. It should be as independent from the specific simulator version as possible. It will still require users to look up details about simulation variables, but it should reduce a lot of the necessary boilerplate code, like defining data structures, structuring and de-structuring raw byte buffers and keeping track of different IDs. You can check out the work-in-progress samples to get an idea.

Feedback appreciated 🙏

Naming

What is a suitable name for the wrapper class. SimConnectApp, SimConnectAPI?

How to define data structures for reading/writing

The PR adds functions for requesting or observing a set of simulation variables and receive the same variables in a callback function.

What is the most intuitive way for specifying the requested variables, and on which format should they be received? I can think of two generic options:

1. The input is an object where the requested property names (keys) refer to the requested simulation variable. The received data will be an object with the same keys as the input object:

   apiHelpers.simulationVariables.observe({
       simulationVariables: {
           PLANE_LATITUDE: {
               dataType: SimConnectDataType.FLOAT32,
               units: 'Degrees',
           },
           PLANE_LONGITUDE: {
               dataType: SimConnectDataType.FLOAT32,
               units: 'Degrees',
           },
       },
       onData: data => {
           console.log(`Aircraft position: ${data.PLANE_LONGITUDE}, ${data.PLANE_LONGITUDE}`);
       },
   });

   Pros:

   • Most text editors will complain if you request a simulation variable twice
   • The keys of the input object and the output object are the same, which might be more intuitive

   Cons:

   • Reusing simulation variable definitions is easier with a list representation
   • It's not clear that the object cannot be nested

2. The input is a list of objects defining the requested variables. The received data will be an object where the keys come from the name-property in the simulationVariables list.

   apiHelpers.simulationVariables.observe({
       simulationVariables: [
           {
               name: "PLANE_LATITUDE",
               dataType: SimConnectDataType.FLOAT32,
               units: 'Degrees',
           },
           {
               name: "PLANE_LONGITUDE",
               dataType: SimConnectDataType.FLOAT32,
               units: 'Degrees',
           },
       ],
       onData: data => {
           console.log(`Aircraft position: ${data.PLANE_LONGITUDE}, ${data.PLANE_LONGITUDE}`);
       },
   });

   Pros:

   • Reusing simulation variable definitions is easier. Simply define a lot of definitions (could be automated by scraping online docs), pick the ones you want for a specific request and wrap them in a list.

Event triggering

I think I prefer the first option. For most events value is not used and onError could be made optional making it possible to just write apiHelpers.events.trigger('EVENT_NAME').

apiHelpers.events.trigger('COM_RADIO_SET_HZ', {
    value: 118.3 * 1_000_000,
    onError: err => console.log(err),
});

vs

apiHelpers.events.trigger('COM_RADIO_SET_HZ', 118.3 * 1_000_000, err => console.log(err));

vs

apiHelpers.events.trigger({
    name: 'COM_RADIO_SET_HZ',
    value: 118.3 * 1_000_000,
    onError: err => console.log(err),
});

[Pomax]

I'd go with SimConnectAPI, since this won't be a standalone application but an API.

Getting-vars-wise, I'm biased of course, but I'd advocate for not making people specify data types, since the data type is dictated by SimConnect. There's only one value it can be, so it would make for a better API if those values are simply stored in a mapping file, and looked up there instead.

And then you could add a separate "more advanced" function that lets users call variables with a datatype that are missing from the mapping file (e.g. as future-proofing as well as for working around potential bugs in var naming or straight up missing known vars).

I like the idea of using observe, to line up with the JS MutationObserver, but then I might suggest following the same pattern that the JS observer code does:

import { SIM_VAR_NAMES, SimulationVariablesObserver } from "simconnectapi/simulationvariables";

// Having known names somewhere means that linters can do a better job at informing users that
// they have a typo in their varname, or are trying to use a variable that doesn't even exist.
const { PLANE_LATITUDE, PLANE_LONGITUDE, PLANE_ALTITUDE } = SIM_VAR_NAMES;

// define an observation configuration
const config = {
  frequency: once,
  simulationVariables: {
    PLANE_LATITUDE: 'degrees', // have valid entries either be (case-insensitive) var:unit pairs, or...
    PLANE_LONGITUDE: 'degrees',
    PLANE_ALTITUDE, // ... use its own name as value, telling the code to use the default unit for this variable
    ...
  }
};

// define the callback for variable updates
const callback = (simulationValues, observer) => {
  Object.entries(simulationValues).forEach(([key, value]) => {
    ...
  });
};

// then create the observer, but don't actually start yet, just like MutationObserver
const observer = new SimulationVariablesObserver(callback)

// Then start...
observer.observe(config);

// ...and then (much) later on, stop again
observer.disconnect();

For event triggering, it might also be worth considering making it promise-based:

import { events } from "simconnectapi";
import { SIM_EVENT_NAMES } from "simconnectapi/simulationevents";

const { COM_RADIO_SET_HZ } = SIM_EVENT_NAMES;

// using the original Promise then/catch chain
events.trigger(COM_RADIO_SET_HZ, 118.3 * 1_000_000).then(() => ...).catch(console.error);

// or using the newer async/await
try {
  await events.trigger(COM_RADIO_SET_HZ, 118.3 * 1_000_000);
  ...
} .catch(err) {
  console.error(err);
}

[EvenAR]

Very valuable input. Thanks!

I'll go with the API-ending 👍

Ok, I will probably add a simulation variables index after all 😄 Having to look up variables manually is indeed cumbersome - I realise that. I will also add a more advanced/generic function like you suggest.

I like the observer-pattern you describe, and having the option to "disconnect". I'll look into that!

Promise based event triggering would indeed be very nice. My only concern is that the only feedback SimConnect gives on event triggering is an exception (if one occurs), and there is no acknowledgement from SimConnect when the event succeeds which would tell when the promise can be resolved (AFAIK). Resolving it after a certain fixed timeout is probably the best solution, although it might add unnecessary delay if someone needs to trigger a lot of events with await between each of them (although right now I don't see any cases where one would do this?). Another option would be to assume that SimConnect always sends an exception message before it sends anything else (which seems to be the case as far as I have tested). In that case the wrapper API could just run, say requestSystemState(), immediately after triggering the event and resolve the promise once the system state message is received. If an exception message is received before the system state message, the promise will be rejected instead. This will add some extra network traffic though, and possibly some SimConnect overhead - so a simple timeout is probably good enough as a start (for most users).

[Charlotte-br560]

Love the initiative and the direction you're taking with this! Your approach to simplifying the usage of node-simconnect is spot on. Regarding naming, I'd lean towards SimConnectWrapper for clarity and simplicity. As for defining data structures, I'm inclined towards the first option—it's more intuitive and cleaner, especially for newcomers. And for event triggering, I'm with you on preferring the first option as well. It provides clarity and flexibility. Keep up the great work!