SimAPI Developer HowTo: Integrating SayIntentions.AI with ANY Flight Simulator

What is SimAPI

SayIntentions.AI uses our custom "SimAPI" implementation as the mechanism for integrating SayIntentions.AI into ANY flight simulation software.  Or put another way, SimAPI is used as a custom-built abstraction layer between SayIntentions.AI and any given flight simulator.

How does it work?

1. Input Integration: For feeding simulator data into SayIntentions.AI, a developer / integrator builds an "adapter" application which collects the telemetry and radio-stack data from the flight simulator, and writes that data to a JSON file, which SayIntentions.AI will read every 1-2 seconds. 
2. Output Integration: Secondarily (and optionally) there are times when SayIntentions.AI needs to be able to change the value of certain variables in the sim itself. (For example, when a pilot clicks on a frequency, expecting that the COM1 Active Frequency will change automatically to that frequency -- or when using Auto-Tune to automatically set the transponder code).  To facilitate this type of integration, SayIntentions.AI will write an "output" file any time a change is requested, and the developer should read this file, and set the variable values appropriately in the flight simulator.

How long does it take to build an adapter?

For a developer who is already familiar with the inner-workings of the API of a given simulator, it should take less than a day of work to build a complete input AND output adapter.

What language does the adapter need to be written in?

We are language agnostic. As long as the adapter can read and write JSON files from the local file system, it should work.

What operating systems are supported?

The SayIntentions.AI client application currently supports Windows 10 and Windows 11. No other operating systems are supported.

What features are NOT supported using the SimAPI Adapter?

The following features are not available to simulators that integrate with SayIntentions.AI using the SimAPI adapter:

• Pushback and ramp control.
• Traffic Injection and Traffic Awareness
• Anything that involves "injecting 3D objects" into the sim, which includes:
  
  • Lighted Taxi Paths
  • SkyOps Rescue Missions and SkyOps Fire Missions (there will be no smoke signals, incident scene, flares, or fires) -- all other mission types are supported.

Does the adapter need to run on the same computer as the simulator?

The adapter needs to be able to read and write to the file-system of whatever computer the SayIntentions.AI application is running on. However, these read and write operations could be done over a network connection.

What file should I write the simulator telemetry data to?

The INPUT file for telemetry data is %localappdata%\SayIntentionsAI\simAPI_input.json

What file should I read from, to interpret requests for variable changes, from SayIntentions.AI?

The OUTPUT file for variable change requests is %localappdata%\SayIntentionsAI\simAPI_output.jsonl

How often do I need to write the input file?

Every 0.75 to 1 second is more than enough.

How often do I need to read the output file?

Every 0.75 to 1 second is enough.  After the file has been read, don't forget to either delete the file, or clear it. 

Where can I find the list of "simvars" that are needed for the input file, and what each one is for?

The "input" simvar names are taken from MSFS 2020 / 2024, and a complete list of each simvar, and its purpose and expected data-type can be found here: 

https://portal.sayintentions.ai/simapi/v1/input_variables.txt 

Where can I find the list of "simvars" that are needed for the output file, and what each one is for?

The "output" simvar names are taken from MSFS 2020 / 2024 K-Vars, and a complete list of each simvar, and its purpose and expected data-type can be found here: 

https://portal.sayintentions.ai/simapi/v1/output_variables.txt 

For the input file, do I need to provide any data-fields besides the simvars listed in the specification above?

Yes, there are five additional fields required in the JSON:

• "name":  This is the plain-text name of your simulator (e.g. "SuperFunSim", "MobiSimNow", etc.). This serves no other purpose than to identify to us which sims are using our system, for reporting and debugging purposes. This should be a string.
• "version": This is the version of the sim itself. This serves no other purpose than to identify to us which sim version is using our system, for reporting and debugging purposes. This should be a string.
• "adapter_version": This is the version of the adapter. This serves no other purpose than to identify to us which adapter versions are using our system, for reporting and debugging purposes. This should be a string.
• "simapi_version": This is the version of SimAPI your code is built to work with. This tells us which variables and which data-format to expect to see in the input file, and which format you are expecting in the output file.
• "exe": This is the windows file executable name of the simulator. This is used by the SayIntentions.AI to determine whether or not the sim is running.  If the sim is running, it tells the app to read the input file (and write the output file) on a regular basis.

What am I expected to do with the simAPI_output.jsonl file?

This file is appended any time a new request to change the value of a variable comes in from the app. In most cases, these are requests to change frequencies, or change the transponder code.  Your job is to read this file roughly once per second and set the internal sim variables to match the values specified in the file.

The formal is "jsonl" (one JSON object per line).

SAMPLE LINE:  {"setvar": "COM_STBY_RADIO_SET_HZ" , "value" : "127950000" }

In the above example, it's your job to set the value of the COM1 standby radio to 127.95

Once the file had been read, you should clear the file, or delete it.

Where can I find a sample of simAPI_input.json ?

You can find a sample of simAPI_input.json here: https://portal.sayintentions.ai/simapi/v1/simapi_input.json

Where can I find a sample of simAPI_output.json ?

You can find a sample of simAPI_input.json here: https://portal.sayintentions.ai/simapi/v1/simapi_output.jsonl