|
| 1 | +# Specification for loading and persistence of Navigation Data packages in Microsoft Flight Simulator |
| 2 | + |
| 3 | +To be Reviewed By: Katlyn Courtade, Jack Lavigne, Markus Hamburger |
| 4 | + |
| 5 | +Authors: Alex Cutforth |
| 6 | + |
| 7 | +Status: In Progress |
| 8 | + |
| 9 | +## Definition of Terms |
| 10 | + |
| 11 | +- `developers` refers to any third party aircraft developer wishing to use Navigraph's in sim navigation data package loader |
| 12 | +- `sim`/`the sim` refers to Microsoft Flight Simulator specifically |
| 13 | +- `wasm-interface` refers to the WASM bundle that is run in sim by aircraft wishing to download or load Navigraph's navigation data. Aircraft developers can interface with this bundle through CommBus calls |
| 14 | + |
| 15 | +## Problem |
| 16 | + |
| 17 | +Shipping navigation data to aircraft is traditionally done by an external program, while the simulator is not running. This is inconvinent especially when users forget to update their navigation data before starting the simulator. This RFC will outline a system for storing navigation data packages in sim persistently, and outline a system for automatically loading bundled navigation data. |
| 18 | + |
| 19 | +# Solution |
| 20 | + |
| 21 | +## Storage |
| 22 | + |
| 23 | +Navigation Data packages shall be stored within a folder in the simulator `work` folder called `navigation-data`, so `/work/navigation-data`. Each package should be a folder containing all the data and metadata for that package. These folders should be given uuids as names to prevent collisions. The contents of these folders should match the contents of the ZIP folder provided from the Navigraph packages API, that is, the .zip is essentially transformed into a file system folder with a uuid name. |
| 24 | + |
| 25 | +The UUID of each folder should be seeded based on the [uniqeness properties](#package-uniqueness) of the `cycle.json` so that folder names can be used to check if two packages are the same without reading both `cycle.json`s. This also ensures that two packages that are the 'same' are not installed at the same time. |
| 26 | + |
| 27 | +Every package which is downloaded must contain exactly one `cycle.json` file placed at the root. This file shall follow the following structure: |
| 28 | + |
| 29 | +```ts |
| 30 | +{ |
| 31 | + cycle: string, // E.g.: "2311" Represents the AIRAC cycle number of this package |
| 32 | + revision: string, // E.g.: "2" |
| 33 | + name: string, // E.g.: "avionics_v1" (this is an arbitrary name that generally represents what/who this package is meant for) |
| 34 | + format: 'dfd' | 'dfdv2' | 'custom', // Represents the format of the data present. Note that further format types may be added if they are supported with custom wrappers in the `wasm-interface` |
| 35 | + validityPeriod: string, // E.g.: "2024-10-03/2024-10-30" Represents the time period through which this package is valid (generally matches the AIRAC cycle period) |
| 36 | + |
| 37 | + // Required for dfd_v1 and dfd_v2 |
| 38 | + databasePath?: string, // E.g.: "/e_dfd_2311.s3db" Provides the path to the dfd database file from the root of the folder |
| 39 | + |
| 40 | + // May contain any other neccessary metadata such as paths to certain files/folders |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +Any folder within the `navigation-data` folder which does not contain a `cycle.json` at the root, or contains more than one `cycle.json` will be regarded as an invalid package, and will not be recognised by the wasm-interface. |
| 45 | + |
| 46 | +### Example file structure: |
| 47 | + |
| 48 | +``` |
| 49 | +work |
| 50 | +| navigation-data |
| 51 | +| | bac9657d-36b8-4ffb-8052-7d88b13f6ff8 |
| 52 | +| | | cycle.json |
| 53 | +| | | e_dfd_2311.s3db |
| 54 | +| | | ... |
| 55 | +| | |
| 56 | +| | 27b1642c-7572-468a-b11a-be1b944c5e43 |
| 57 | +| | | cycle.json |
| 58 | +| | | Config |
| 59 | +| | | | .DS_Store |
| 60 | +| | | | |
| 61 | +| | | | NavData |
| 62 | +| | | | | airports.dat |
| 63 | +| | | | | apNavAPT.txt |
| 64 | +| | | | | ... |
| 65 | +| | | | |
| 66 | +| | | | SidStars |
| 67 | +| | | | | NZCH.txt |
| 68 | +| | | | | KJFK.txt |
| 69 | +| | | | | ... |
| 70 | +
|
| 71 | +``` |
| 72 | + |
| 73 | +## Package Uniqueness |
| 74 | + |
| 75 | +The `cycle.json` properties: `cycle`, `revision`, `name` and `format` shall be used to differentiate packages from one another. That is to say, the `navigation-data` folder shouldn't have multiple packages with the same set of said properties. |
| 76 | + |
| 77 | +## Bundled data |
| 78 | + |
| 79 | +**It is important to note that the package folder name is unrelated to the `name` field in `cycle.json`** |
| 80 | + |
| 81 | +Aircraft devlopers may bundle navigation data packages with their aircraft by placing them in `/PackageSources/bundled-navigation-data` in the same way packages are stored in `\work\navigation-data`. On initialisation of the wasm-interface, all packages in `bundled-navigation-data` that are not already in `/work/navigation-data` (see [Package Uniqueness](#package-uniqueness) for details on how to check if two packages are the same) shall be copied to `/work/navigation-data`. The packages in `bundled-navigation-data` may have any folder name, so when copying a package to `/work/navigation-data` the folder shall be renamed to the seeded uuid. If this was not the case, an aircraft update may bundle a newer cycle version package which would then have the same folder name as the previous package in `/work/navigation-data`, so to avoid having to check for clashes and delete the previous package, the package folder will be given seeded uuid name. This is to ensure developers to properly check that their desired package and format is present before tring to load it (This can be done using the function outlined in [Package Selection](#package-selection)). Packages which are copied over from `bundled-navigation-data` should not be deleted from `bundled-navigation-data`. |
| 82 | + |
| 83 | +## Download |
| 84 | + |
| 85 | +Navigation data can be downloaded using Navigraph's packages API. The wasm-interface shall provide a function `DownloadNavigationData` which will take in a download URL, and download it to the `\work\navigation-data`. The wasm-interface will unzip the contents of the download into a folder with a seeded uuid name in order to match the [required file structure](#example-file-structure). The wasm-interface should also provide a function `SetDownloadOptions` which allows the developer to specify the maximum file extraction/deletion rate to maintain sim performance. |
| 86 | + |
| 87 | +Note that the packages API may provide packages which are not valid navigation data packages, do not attempt to download these as they will not be recognised by the `wasm-interface` once installed. |
| 88 | + |
| 89 | +The DownloadNavigationData function shall provide an optional parameter to **explicitly** enable automatic selection of the package once it has been downloaded. |
| 90 | + |
| 91 | +## Package deletion |
| 92 | + |
| 93 | +The wasm-interface shall provide a function `DeletePackage` which shall delete a package from `/work/navigation-data` based on its uuid. |
| 94 | + |
| 95 | +## Package Cleanup |
| 96 | + |
| 97 | +The wasm-interface shall provide a function `CleanPackages` which shall delete all package from `/work/navigation-data` which do not have the same format as the currently active database. It shall accept an optional parameter `count` which will limit the number of matching format packages to retain. Any packages which are also present in the `bundled-navigation-data` folder will be retained regardless of `count` or format. |
| 98 | + |
| 99 | +## Package Selection |
| 100 | + |
| 101 | +The wasm-interface shall provide a function `ListAvailablePackages` which returns a list of valid packages present in the `/work/navigation-data` folder. |
| 102 | + |
| 103 | +### `ListAvailablePackages` Result type |
| 104 | + |
| 105 | +```ts |
| 106 | +[ |
| 107 | + { |
| 108 | + uuid: string, // E.g.: "bac9657d-36b8-4ffb-8052-7d88b13f6ff8" Provides the seeded uuid of the package (same as the folder name) |
| 109 | + path: string, // E.g. "/work/navigation-data/bac9657d-36b8-4ffb-8052-7d88b13f6ff8" Provides the absolute path in the wasm file system to the package folder. |
| 110 | + is_bundled: boolean, |
| 111 | + cycle: { |
| 112 | + // Provides all the data from the cycle.json |
| 113 | + ... |
| 114 | + } |
| 115 | + } |
| 116 | + ... |
| 117 | +] |
| 118 | +``` |
| 119 | + |
| 120 | +### Active package |
| 121 | + |
| 122 | +A package is said to be "selected" or "active" by having its folder renamed to `active`. This enables persistent selection and assurance that only one package is active at any one time. Developers can then find the currently selected package in `/work/navigation-data/active/`. |
| 123 | + |
| 124 | +The wasm-interface shall provide a function `SetActivePackage`. This function shall take in the uuid of the package to be selected, and that package folder shall then be renamed to `active`. If the active package `cycle.json` format field indicates the package is of a format that can be read by the `wasm-interface` database functionality, it will be automatically selected for use. When a package is "de-selected", that is, a different package is selected, it's folder shall be renamed to its seeded uuid. |
| 125 | + |
| 126 | +The wasm-interface shall also provide a function `GetActivePackage`. This function shall return information about the package which is currently active, in the same format as `ListAvailablePackages`. If no package is active, the function shall return null. |
0 commit comments