From 9bd26e551f2138fe6086a0f4cac2c5bfeeca44f4 Mon Sep 17 00:00:00 2001 From: Jack Lavigne Date: Wed, 21 May 2025 16:46:36 +0200 Subject: [PATCH 1/5] docs: update readme to align with rewrite --- README.md | 49 ++++++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 3e4e8f72..bf339bc1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,16 @@ -# Navigraph Navigation Data Interface for MSFS +
+ + Logo + -The Navigraph Navigation Data Interface enables developers to download and integrate navigation data from Navigraph directly into add-on aircraft in MSFS. +
+

Navigraph Navigation Data Interface for MSFS

+
+ +

The Navigraph Navigation Data Interface enables developers to download and integrate navigation data from Navigraph directly into add-on aircraft in MSFS.

+ +
+
## Key Features @@ -14,15 +24,12 @@ The Navigraph Navigation Data Interface enables developers to download and integ Here's an overview on the structure of this repository, which is designed to be as simple as possible to use -- `examples/` - - Contains sample implementations for using the navigation data interface +- `example/` - `aircraft/` includes a base aircraft to test in the sim - `gauge/` includes a very simple TypeScript instrument to communicate with the WASM module - `src/` - - `database` Includes rust source code for interfacing with a DFD sqlite file (not WASM specific) - - `js` Includes source code for the JS interface for using the sdk - - `test` Includes code for testing the JS and Rust code using a Node runtime - - `wasm` includes the Rust source code for the WASM module which handles the downloading of the database file, and interfacing with the database implementation + - `ts` Includes source code for the JS interface for using the sdk + - `wasm` includes the Rust source code for the WASM module which handles the downloading of the database file, and interfacing with the database ## Including in Your Aircraft @@ -30,7 +37,7 @@ Here's an overview on the structure of this repository, which is designed to be 2. Add the WASM module into your `panel` folder in `PackageSources` 3. Add the following entry into `panel.cfg` (make sure to replace `NN` with the proper `VCockpit` ID): - ``` + ```ini [VCockpitNN] size_mm=0,0 pixel_size=0,0 @@ -60,34 +67,30 @@ If you bundle outdated navigation data in your aircraft and you want this module The default location for navigation data is `work/NavigationData`. -## Building the Sample Aircraft +## Building the Sample Aircraft (MSFS2020) Before building, make sure you have properly created and set an `.env` file in `examples/gauge`! An example can be found in the `.env.example` file in that directory. Replace with your credentials -1. [Download](https://nodejs.org/en/download) and install Node.js +1. Download and install [Bun](https://bun.sh/docs/installation) 2. Open the `msfs-navigation-data-interface` folder in a terminal -3. Run `npm i` the first time you build, in order to install dependencies -4. Change directory to `src/js` using `cd src/js` -5. Run `npm run build` to build the interface. -6. Change directory to `examples/gauge` using `cd ../../examples/gauge/` -7. Run `npm run build` to build into the `PackageSources` folder of the aircraft sample (or `npm run dev` to build into the `Packages` folder of the aircraft and listen to changes in the source). -8. Make sure the WASM module is included in the [`panel`](examples/aircraft/PackageSources/SimObjects/Airplanes/Navigraph_Navigation_Data_Interface_Aircraft/panel) folder! Look at either [Including in Your Aircraft](#including-in-your-aircraft) or [Building the WASM Module Yourself](#building-the-wasm-module-yourself) for info on that -9. Open the `examples/aircraft/NavigationDataInterfaceAircraftProject.xml` file in the simulator and build there +3. Run `bun i` the first time you build, in order to install dependencies +4. Change directory to `examples/gauge` using `cd example/gauge` +5. Run `bun run build` to build into the `PackageSources` folder of the aircraft sample (or `bun run dev` to build into the `Packages` folder of the aircraft and listen to changes in the source). +6. Make sure the WASM module is included in the [`panel`](examples/aircraft/PackageSources/SimObjects/Airplanes/Navigraph_Navigation_Data_Interface_Aircraft/panel) folder! Look at either [Including in Your Aircraft](#including-in-your-aircraft) or [Building the WASM Module Yourself](#building-the-wasm-module-yourself) for info on that +7. Open the `examples/aircraft/NavigationDataInterfaceAircraftProject.xml` file in the simulator and build there ## Building the WASM Module Yourself 1. [Install](https://github.com/navigraph/cargo-msfs) cargo-msfs -2. Run `npm run build:wasm` (must be on Windows) +2. Run `bun run build:wasm` at the root of the repository (requires Docker) - This will take a while to download and build the first time, but subsequent runs will be quicker -3. The compiled WASM module will be copied to `out` **and** `examples/aircraft/PackageSources/SimObjects/Airplanes/Navigraph_Navigation_Data_Interface_Aircraft/panel` +3. The compiled WASM module will be copied to `dist/wasm`. There will be two folders - `2020` and `2024`, for each sim version ## Interfacing with the gauge manually The navigation data interface acts as its own WASM gauge in sim, so in order to communicate with it, you must use the [CommBus](https://docs.flightsimulator.com/html/Programming_Tools/WASM/Communication_API/Communication_API.htm). -The gauge communicates using the following event names: - -(Any types referenced can be found in `wasm/src/json_structs.rs`) +The gauge communicates using the following event names (all types referenced can be found [here](src/ts)): - `NAVIGRAPH_CallFunction`: This event is received by the interface and is used to trigger one of the interfaces functions. It takes in arguments of type `CallFunction`. The available functions and their expected parameters can be found in the `json_structs.rs` file - `NAVIGRAPH_FunctionResult`: This event is sent by the interface as a response to a previously triggered function. Its result will have the type `FunctionResult`, with the data field containing the expected return type of the function. From ee191ea4895b8d3f2c3941b0f8f6366485e660a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Malte=20Hallstr=C3=B6m?= Date: Thu, 22 May 2025 14:36:32 +0200 Subject: [PATCH 2/5] docs: remove old key feature --- README.md | 58 +++++++++++++++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index bf339bc1..a621748f 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,6 @@ - Navigraph DFD Format: Leverage specialized support for Navigraph's DFD format, based on SQLite, which includes an SQL interface on the commbus for efficient data handling. - Javascript and WASM support: The navdata interface is accessible from both Javascript (Coherent) and WASM, providing flexibility for developers. -- Supports updating of custom data formats. - Xbox compatibility: Works on PC and Xbox. - Persistence: All data is persisted in the `work` folder of the aircraft. @@ -46,18 +45,19 @@ Here's an overview on the structure of this repository, which is designed to be ``` - Note that if you already have a `VCockpit` with `NO_TEXTURE` you can just add another `htmlgauge` to it, while making sure to increase the index + 4. **Optional**: Create a `Navigraph/config.json` file to assist with Sentry reports. This info will be reported to us should any error occur in the library. We will use this to directly reach out to you (the developer) for these errors. - - The file must look like + - The file must look like - ```json - { - "addon": { - "developer": "Navigraph", - "product": "Sample Aircraft" - } - } - ``` + ```json + { + "addon": { + "developer": "Navigraph", + "product": "Sample Aircraft" + } + } + ``` ## Dealing with Bundled Navigation Data @@ -101,30 +101,30 @@ The gauge communicates using the following event names (all types referenced can Below is an example of communicating with the interface in JS. (We provide a JS wrapper, the code below is just a basic example to show how it works). Please read the CommBus documentation to determine how to interface with CommBus in your chosen language. `src/js` contains our JS wrapper, it is also a useful example for implementing a fully fleshed out wrapper. ```js -const queue = [] +const queue = []; const listener = RegisterCommBusListener(() => { listener.on("NAVIGRAPH_FunctionResult", jsonArgs => { - const args = JSON.parse(jsonArgs) + const args = JSON.parse(jsonArgs); // When a FunctionResult is received, find the item in queue which matches the id, and resolve or reject it - const queueItem = queue.find(m => m.id === args.id) + const queueItem = queue.find(m => m.id === args.id); if (queueItem) { - queue.splice(queue.indexOf(queueItem), 1) - const data = args.data + queue.splice(queue.indexOf(queueItem), 1); + const data = args.data; if (args.status === FunctionResultStatus.Success) { - queueItem.resolve(data) + queueItem.resolve(data); } else { - queueItem.reject(new Error(typeof data === "string" ? data : "Unknown error")) + queueItem.reject(new Error(typeof data === "string" ? data : "Unknown error")); } } - }) -}) // RegisterCommBusListener is a function provided by sim + }); +}); // RegisterCommBusListener is a function provided by sim function getAirport(ident) { - const id = Utils.generateGUID() // Utils is a class provided by sim + const id = Utils.generateGUID(); // Utils is a class provided by sim const args = { function: "GetAirport", // The name of the function being called @@ -133,21 +133,21 @@ function getAirport(ident) { // The parameters of the function ident, }, - } + }; - listener.callWasm("NAVIGRAPH_CallFunction", JSON.stringify(args)) + listener.callWasm("NAVIGRAPH_CallFunction", JSON.stringify(args)); return new Promise((resolve, reject) => { queue.push({ id, resolve: response => resolve(response), reject: error => reject(error), - }) - }) + }); + }); } function executeSql(sql, params) { - const id = Utils.generateGUID() // Utils is a class provided by sim + const id = Utils.generateGUID(); // Utils is a class provided by sim const args = { function: "ExecuteSQLQuery", // The name of the function being called @@ -157,16 +157,16 @@ function executeSql(sql, params) { sql, params, }, - } + }; - listener.callWasm("NAVIGRAPH_CallFunction", JSON.stringify(args)) + listener.callWasm("NAVIGRAPH_CallFunction", JSON.stringify(args)); return new Promise((resolve, reject) => { queue.push({ id, resolve: response => resolve(response), reject: error => reject(error), - }) - }) + }); + }); } ``` From 079dc248c3c57b10d0cfbaaf8972aee555a8d9ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Malte=20Hallstr=C3=B6m?= Date: Thu, 22 May 2025 14:57:52 +0200 Subject: [PATCH 3/5] docs: broken links, formatting, improvements --- README.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a621748f..8f68fdd7 100644 --- a/README.md +++ b/README.md @@ -21,13 +21,11 @@ ## Repository Structure -Here's an overview on the structure of this repository, which is designed to be as simple as possible to use - - `example/` - `aircraft/` includes a base aircraft to test in the sim - `gauge/` includes a very simple TypeScript instrument to communicate with the WASM module - `src/` - - `ts` Includes source code for the JS interface for using the sdk + - `ts` includes source code for the JS interface for interfacing with the WASM module - `wasm` includes the Rust source code for the WASM module which handles the downloading of the database file, and interfacing with the database ## Including in Your Aircraft @@ -46,9 +44,9 @@ Here's an overview on the structure of this repository, which is designed to be - Note that if you already have a `VCockpit` with `NO_TEXTURE` you can just add another `htmlgauge` to it, while making sure to increase the index -4. **Optional**: Create a `Navigraph/config.json` file to assist with Sentry reports. This info will be reported to us should any error occur in the library. We will use this to directly reach out to you (the developer) for these errors. +4. **Optional**: Create a `Navigraph/config.json` file to provide additional metadata at runtime. This info will be reported to us should any error occur in the library, enabling us to directly reach out to you (the developer) to help track down the issue. - - The file must look like + - The file must follow this format: ```json { @@ -61,7 +59,9 @@ Here's an overview on the structure of this repository, which is designed to be ## Dealing with Bundled Navigation Data -If you bundle outdated navigation data in your aircraft and you want this module to handle updating it for users with subscriptions, place the navigation data into the `Navigraph/BundledData` directory in `PackageSources`. You can see an example [here](examples/aircraft/PackageSources/Navigraph/BundledData/) +If you bundle outdated navigation data in your aircraft and you want this module to handle updating it for users with subscriptions, place the navigation data into the `Navigraph/BundledData` directory in `PackageSources`. You can see an example [here](example/aircraft/PackageSources/Navigraph/BundledData/) + +The navigation data interface will automatically use this database by default, making it immediately available on startup. ## Where is the Navigation Data Stored? @@ -69,15 +69,15 @@ The default location for navigation data is `work/NavigationData`. ## Building the Sample Aircraft (MSFS2020) -Before building, make sure you have properly created and set an `.env` file in `examples/gauge`! An example can be found in the `.env.example` file in that directory. Replace with your credentials +Before building, make sure you have properly created and set an `.env` file in `example/gauge`! An example can be found in the `.env.example` file in that directory. Replace with your credentials 1. Download and install [Bun](https://bun.sh/docs/installation) 2. Open the `msfs-navigation-data-interface` folder in a terminal 3. Run `bun i` the first time you build, in order to install dependencies -4. Change directory to `examples/gauge` using `cd example/gauge` +4. Change directory to `example/gauge` using `cd example/gauge` 5. Run `bun run build` to build into the `PackageSources` folder of the aircraft sample (or `bun run dev` to build into the `Packages` folder of the aircraft and listen to changes in the source). -6. Make sure the WASM module is included in the [`panel`](examples/aircraft/PackageSources/SimObjects/Airplanes/Navigraph_Navigation_Data_Interface_Aircraft/panel) folder! Look at either [Including in Your Aircraft](#including-in-your-aircraft) or [Building the WASM Module Yourself](#building-the-wasm-module-yourself) for info on that -7. Open the `examples/aircraft/NavigationDataInterfaceAircraftProject.xml` file in the simulator and build there +6. Make sure the WASM module is included in the [`panel`](example/aircraft/PackageSources/SimObjects/Airplanes/Navigraph_Navigation_Data_Interface_Aircraft/panel) folder! Look at either [Including in Your Aircraft](#including-in-your-aircraft) or [Building the WASM Module Yourself](#building-the-wasm-module-yourself) for info on that +7. Open the `example/aircraft/NavigationDataInterfaceAircraftProject.xml` file in the simulator and build there ## Building the WASM Module Yourself @@ -92,13 +92,16 @@ The navigation data interface acts as its own WASM gauge in sim, so in order to The gauge communicates using the following event names (all types referenced can be found [here](src/ts)): -- `NAVIGRAPH_CallFunction`: This event is received by the interface and is used to trigger one of the interfaces functions. It takes in arguments of type `CallFunction`. The available functions and their expected parameters can be found in the `json_structs.rs` file +- `NAVIGRAPH_CallFunction`: This event is received by the interface and is used to trigger one of the interfaces functions. It takes in arguments of type `CallFunction`. The available functions and their expected parameters can be found in the [`src/ts`](src/ts) file - `NAVIGRAPH_FunctionResult`: This event is sent by the interface as a response to a previously triggered function. Its result will have the type `FunctionResult`, with the data field containing the expected return type of the function. - `NAVIGRAPH_Event`: This event is sent by the interface to give indications of progress or that the interface is running correctly. ### Example -Below is an example of communicating with the interface in JS. (We provide a JS wrapper, the code below is just a basic example to show how it works). Please read the CommBus documentation to determine how to interface with CommBus in your chosen language. `src/js` contains our JS wrapper, it is also a useful example for implementing a fully fleshed out wrapper. +Below is an example of communicating with the interface in JS. Please read the CommBus documentation to determine how to interface with CommBus in your chosen language. [`src/ts`](src/ts) contains our JS wrapper, it is also a useful example for implementing a fully fleshed out wrapper. + +> [!IMPORTANT] +> We provide a JS wrapper that handles this for you. The below is just a quick look at how it works. ```js const queue = []; From 0f76e76856a20ddba0187f7a2de6fe86bd19e55c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Malte=20Hallstr=C3=B6m?= Date: Thu, 22 May 2025 15:06:59 +0200 Subject: [PATCH 4/5] docs: update WASM build steps --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8f68fdd7..a1f4fe55 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ Before building, make sure you have properly created and set an `.env` file in ` ## Building the WASM Module Yourself -1. [Install](https://github.com/navigraph/cargo-msfs) cargo-msfs +1. Create a `.env` file in the root of this repository, containing a `SENTRY_URL` variable. Provide your own DSN, or leave it empty. 2. Run `bun run build:wasm` at the root of the repository (requires Docker) - This will take a while to download and build the first time, but subsequent runs will be quicker 3. The compiled WASM module will be copied to `dist/wasm`. There will be two folders - `2020` and `2024`, for each sim version From fcdf142489d785ed04db49970e2a6739730ce5b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Malte=20Hallstr=C3=B6m?= Date: Thu, 22 May 2025 16:06:26 +0200 Subject: [PATCH 5/5] docs: update aircraft build steps --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a1f4fe55..c8fae148 100644 --- a/README.md +++ b/README.md @@ -69,14 +69,18 @@ The default location for navigation data is `work/NavigationData`. ## Building the Sample Aircraft (MSFS2020) -Before building, make sure you have properly created and set an `.env` file in `example/gauge`! An example can be found in the `.env.example` file in that directory. Replace with your credentials +> [!NOTE] +> This project is only meant to be tested in MSFS2020. We will add an example for MSFS2024 in the future. + +> [!IMPORTANT] +> Before building, make sure you have properly created and set an `.env` file in `example/gauge`! An example can be found in the `.env.example` file in that directory. Replace with your credentials. 1. Download and install [Bun](https://bun.sh/docs/installation) -2. Open the `msfs-navigation-data-interface` folder in a terminal +2. Open this repository in a terminal 3. Run `bun i` the first time you build, in order to install dependencies -4. Change directory to `example/gauge` using `cd example/gauge` +4. Change directory to [`example/gauge`](example/gauge/) using `cd example/gauge` 5. Run `bun run build` to build into the `PackageSources` folder of the aircraft sample (or `bun run dev` to build into the `Packages` folder of the aircraft and listen to changes in the source). -6. Make sure the WASM module is included in the [`panel`](example/aircraft/PackageSources/SimObjects/Airplanes/Navigraph_Navigation_Data_Interface_Aircraft/panel) folder! Look at either [Including in Your Aircraft](#including-in-your-aircraft) or [Building the WASM Module Yourself](#building-the-wasm-module-yourself) for info on that +6. Make sure the WASM module is included in the [`panel`](example/aircraft/PackageSources/SimObjects/Airplanes/Navigraph_Navigation_Data_Interface_Aircraft/panel) folder! Look at either [Including in Your Aircraft](#including-in-your-aircraft) or [Building the WASM Module Yourself](#building-the-wasm-module-yourself) instructions 7. Open the `example/aircraft/NavigationDataInterfaceAircraftProject.xml` file in the simulator and build there ## Building the WASM Module Yourself