xp-command 1.3.2 → 1.5.0

package/README.md

@@ -46,11 +46,7 @@ This installs xp-command globally so you can run it from anywhere.
 
 ## 🛠 X-Plane setup
 
-You shouldn't need to perform any extra setup steps in X-Plane. There is no plugin that needs to be installed. If you still want to check if the Web API (which allows xp-command to communicate with X-Plane) is configured correctly, here is how you can do it:
-
-1. In X-Plane 12, go to **Settings → Data Output**
-2. Find **"Enable Web Server API"** and make sure it's enabled
-3. Note the **port number** (default is `8086`)
+You do not need to do anything inside X-Plane for xp-command to work. X-Plane 12 runs a local Web API automatically on `http://localhost:8086` as long as it is not started with the `--no_web_server` command-line option and the port is free. Just make sure X-Plane is running on the same machine as xp-command and that nothing (firewall or another process) is blocking or using port `8086`.
 
 ---
 
@@ -146,9 +142,11 @@ The first time you run xp-command in a new aircraft, it automatically creates a
 - **macOS/Linux:** `~/.xp-command/<Aircraft Name>.yml`
 - **Windows:** `%USERPROFILE%\.xp-command\<Aircraft Name>.yml`
 
+You can run the command `config` to open the aircraft configuration file in your system’s default YAML editor.
+
 ### Customizing commands
 
-You can edit these YAML files to add aircraft-specific commands or modify existing ones. Note that for changes to take effect you'll need to restart xp-command.
+You can edit these YAML files to add aircraft-specific commands or modify existing ones.
 
 **Example**: Add a command to set heading with 10-degree increments:
 
@@ -164,11 +162,12 @@ You can edit these YAML files to add aircraft-specific commands or modify existi
 - `pattern`: Regular expression matching your command (`hdg18`)
 - `type`: Either `get` (read value and copy to clipboard) or `set` (write value)
 - `dataref`: X-Plane dataref path (find these in X-Plane's DataRef Editor)
-- `transform`: Optional value conversions (multiply, divide, round, etc.)
+- `command`: X-Plane command path (find these in X-Plane's DataRef Editor)
+- `transform`: Optional value conversions (`mult<number>` to multiply or divide, `round`, `toFixed<number>` etc.)
 
 **Finding datarefs**: Use the [DataRefTool plugin](https://datareftool.com) or check [X-Plane datarefs documentation](https://developer.x-plane.com/datarefs/).
 
-#### Array Datarefs
+#### Array datarefs
 
 Many X-Plane datarefs are arrays (e.g., for multiple engines, generators, radios). You can access specific array elements using `[index]` notation:
 
@@ -192,11 +191,48 @@ Here is an example of a custom set command which sets multiple datarefs at once
     - sim/flightmodel2/gear/is_chocked[2]
 ```
 
-## 🔄 Resetting Aircraft Profiles
+#### Using commands
+
+In addition to reading/writing datarefs, you can trigger X-Plane commands. Commands are actions (like button presses) rather than values.
+
+**Command field**: Use `command` instead of or alongside `dataref` in `set` type operations.
+
+**Duration syntax**: Append `[duration]` to specify how long the command stays active (in seconds):
+- `command` or `command[0]`: Press and immediately release (default behavior)
+- `command[5]`: Hold for 5 seconds then release
+- Maximum duration: 10 seconds
+
+**Examples**:
+
+```yaml
+# Toggle anti-ice group on
+- pattern: "^i(1)$"
+  type: set
+  command:
+    - FJS/Q4XP/Knobs/prop_heat_up
+    - FJS/Q4XP/Knobs/Airframe_deice_mode_up
+  dataref:
+    - FJS/Q4XP/Manips/TwoSwitch_Anim[8]
+    - FJS/Q4XP/Manips/TwoSwitch_Anim[9]
+    - FJS/Q4XP/Manips/TwoSwitch_Anim[10]
+```
+
+Here is an example demonstrating the usage of the duration option: In the Dash 8 (Q4XP), in order to change the transponder mode, you must press a tiny button for at least two seconds! Not anymore:
+
+```
+# Toggle transponder mode
+- pattern: "^x$"
+  type: set
+  command: FJS/Q4XP/SoftKey/arcdu_1/skr4[2]
+```
+
+**Finding commands**: Use the [DataRefTool plugin](https://datareftool.com) to browse available commands.
+
+## 🔄 Resetting aircraft profiles
 
 If you've edited an aircraft configuration and xp-command crashes or stops working, you can reset to default settings by deleting the config files.
 
-### Profile Location
+### Profile location
 
 Aircraft profiles are stored in:
 

package/bin/index.js

@@ -11,16 +11,28 @@ import {
 import chalk from "chalk";
 import { program } from "commander";
 import ora from "ora";
+import { homedir } from "os";
+import { join } from "path";
 
-import { getDatarefValues, initAPI, setDatarefValues } from "../src/api.js";
+import packageJson from "../package.json" with { type: "json" };
+import {
+  activateCommands,
+  getDatarefValues,
+  initAPI,
+  setDatarefValues,
+} from "../src/api.js";
 import { copyToClipboard } from "../src/clipboard.js";
-import { getConfig } from "../src/config.js";
+import { editConfig, getConfig } from "../src/config.js";
 import { clearLine, hideCursor, showCursor } from "../src/console.js";
 import { isAPIError, isEconnRefused } from "../src/error.js";
 import history from "../src/history.js";
+import { Logger } from "../src/logger.js";
 import { sleep } from "../src/sleep.js";
 
-import packageJson from '../package.json' with { type: 'json' };
+const osHomedir = homedir();
+const logger = new Logger(join(osHomedir, ".xp-command", "log.txt"), {
+  clearOnStart: true,
+});
 
 const PREFIX = "🛩 ";
 
@@ -28,7 +40,7 @@ program
   .version(packageJson.version)
   .description(`${PREFIX} ${packageJson.name}\n${packageJson.description}`)
   .option("-p, --port <number>", "server port number")
-  .helpOption('-h, --help', 'display this help text');
+  .helpOption("-h, --help", "display this help text");
 
 /**
  * @param {string} command
@@ -42,6 +54,7 @@ const processCommand = async (command) => {
   try {
     config = await getConfig();
   } catch (error) {
+    logger.error(error);
     if (isEconnRefused(error) || isAPIError(error)) {
       spinner.fail(chalk.red(`${PREFIX} No connection - in aircraft?`));
       hideCursor();
@@ -51,9 +64,19 @@ const processCommand = async (command) => {
     }
   }
 
+  if (command?.toLowerCase() === "config") {
+    await editConfig();
+    spinner.succeed(chalk.green(`${PREFIX} config`));
+    hideCursor();
+    await sleep(1500);
+    clearLine();
+    return;
+  }
+
   /**
-   * @param {number|string} value
+   * @param {number|string|Array<number|string>} value
    * @param {import('../src/config.js').Transform} transform
+   * @return {number|string|Array<number|string>}
    */
   const getTransformedValue = (value, transform) => {
     if (Array.isArray(value)) return value.slice();
@@ -79,20 +102,48 @@ const processCommand = async (command) => {
 
   /** @type {Array<[RegExp, (regExpResult: Array<string> | null) => Promise<void>]>} */
   const matches = config.commands.map((c) => {
+    if (!c.type) {
+      return [
+        new RegExp(c.pattern),
+        async () => {
+          spinner.fail(
+            chalk.red(`${PREFIX} Missing type (must be get or set)!`),
+          );
+          hideCursor();
+          await sleep(1500);
+          clearLine();
+          return;
+        },
+      ];
+    }
+
     switch (c.type) {
       case "get":
         return [
           new RegExp(c.pattern),
           async () => {
+            if (!c.dataref) {
+              spinner.fail(chalk.red(`${PREFIX} Missing dataref!`));
+              hideCursor();
+              await sleep(1500);
+              clearLine();
+              return;
+            }
+
+            /** @type {number|string|Array<number|string>}*/
             let value = await getDatarefValues(c.dataref);
             c.transform?.forEach((t) => {
               value = getTransformedValue(value, t);
             });
-            const asString = String(value)
+            const asString = String(value);
             await copyToClipboard(asString);
-            const lines = asString.split('\n')
-            const firstLine = lines[0]
-            spinner.succeed(chalk.green(`${PREFIX} ${lines.length > 1 ? firstLine + '...' : firstLine}`));
+            const lines = asString.split("\n");
+            const firstLine = lines[0];
+            spinner.succeed(
+              chalk.green(
+                `${PREFIX} ${lines.length > 1 ? firstLine + "..." : firstLine}`,
+              ),
+            );
             hideCursor();
             await sleep(1500);
             clearLine();
@@ -102,16 +153,30 @@ const processCommand = async (command) => {
         return [
           new RegExp(c.pattern),
           async (regExpResult) => {
-            let value = String(regExpResult[1]);
-            
-            if (isNaN(Number(value))) {
-              const base64 = Buffer.from(value, 'utf-8').toString('base64');
-              await setDatarefValues(c.dataref, base64);
-            } else {
-              c.transform?.forEach((t) => {
-                value = String(getTransformedValue(value, t));
-              });
-              await setDatarefValues(c.dataref, Number(value));
+            if (!c.command && !c.dataref) {
+              spinner.fail(
+                chalk.red(`${PREFIX} Neither dataref nor command provided!`),
+              );
+              hideCursor();
+              await sleep(1500);
+              clearLine();
+              return;
+            }
+
+            if (c.command) {
+              await activateCommands(c.command);
+            }
+            if (c.dataref) {
+              let value = String(regExpResult[1]);
+              if (isNaN(Number(value))) {
+                const base64 = Buffer.from(value, "utf-8").toString("base64");
+                await setDatarefValues(c.dataref, base64);
+              } else {
+                c.transform?.forEach((t) => {
+                  value = String(getTransformedValue(value, t));
+                });
+                await setDatarefValues(c.dataref, Number(value));
+              }
             }
             spinner.succeed(chalk.green(`${PREFIX} ${command}`));
             hideCursor();
@@ -133,6 +198,7 @@ const processCommand = async (command) => {
 
         showCursor();
       } catch (error) {
+        logger.error(error);
         spinner.fail();
         hideCursor();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-command",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Quick cockpit commands for X-Plane 12 - set your radios, altimeter, autopilot, and more from the terminal while flying.",
   "keywords": [
     "xplane",

package/src/api.js

@@ -37,6 +37,22 @@ const parseDataref = (datarefString) => {
   return [match[1], match[2] ? parseInt(match[2]) : null];
 };
 
+/**
+ * @param {string} commandString
+ * @return {[string, number|null]}
+ */
+const parseCommand = (commandString) => {
+  // Regex pattern: captures base name and optional duration value
+  const pattern = /^(.+?)(?:\[(\d+)\])?$/;
+  const match = commandString.match(pattern);
+
+  if (!match) {
+    throw new CustomError("invalid_command");
+  }
+
+  return [match[1], match[2] ? parseInt(match[2]) : null];
+};
+
 /**
  * @param {string} datarefName
  * @return { Promise<number | null> }
@@ -65,6 +81,54 @@ export const initAPI = (options) => {
   port = options.port;
 };
 
+/**
+ * @param {string} commandName
+ * @return {Promise<number|string>}
+ */
+export const getCommandId = async (commandName) => {
+  const url = new URL(`http://localhost:${port}/api/v2/commands`);
+  url.searchParams.set("filter[name]", commandName);
+  url.searchParams.set("fields", "id");
+
+  const response = await fetch(url);
+  const json = /** @type { {data:[{id: number }]} | APIError } */ (
+    await response.json()
+  );
+
+  if ("error_code" in json) {
+    throw new CustomError(json.error_code);
+  }
+
+  return json.data[0]?.id ?? null;
+};
+
+/**
+ * @param {string} commandNameWithOptionalDuration
+ */
+export const activateCommand = async (commandNameWithOptionalDuration) => {
+  const [commandName, duration] = parseCommand(commandNameWithOptionalDuration);
+
+  const commandId = await getCommandId(commandName);
+
+  const url = new URL(
+    `http://localhost:${port}/api/v2/command/${commandId}/activate`,
+  );
+
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify({ duration: duration || 0 }),
+  });
+  const json = /** @type { {data: number|string } | APIError } */ (
+    await response.json()
+  );
+
+  if (json && "error_code" in json) {
+    throw new CustomError(json.error_code);
+  }
+
+  return json;
+};
+
 /**
  * @param {string} datarefNameWithOptionalIndex
  * @return {Promise<number|string>}
@@ -112,13 +176,18 @@ export const getDatarefValue = async (datarefNameWithOptionalIndex) => {
  */
 export const getDatarefValues = async (datarefNamesWithOptionalIndex) => {
   if (Array.isArray(datarefNamesWithOptionalIndex)) {
-    return Promise.all(datarefNamesWithOptionalIndex.map(dataref => getDatarefValue(dataref))).then(results => {
-      return results.map(v => String(v)).join('\n').trim()
-    })
+    return Promise.all(
+      datarefNamesWithOptionalIndex.map((dataref) => getDatarefValue(dataref)),
+    ).then((results) => {
+      return results
+        .map((v) => String(v))
+        .join("\n")
+        .trim();
+    });
   }
-  
-  return getDatarefValue(datarefNamesWithOptionalIndex)
-}
+
+  return getDatarefValue(datarefNamesWithOptionalIndex);
+};
 
 /**
  * @param {string} datarefNameWithOptionalIndex
@@ -154,14 +223,35 @@ export const setDatarefValue = async (datarefNameWithOptionalIndex, value) => {
 /**
  * @param {string|Array<string>} datarefNamesWithOptionalIndex
  * @param {number|string} value
- * @return {Promise<number|string>}
+ * @return {Promise<void>}
  */
-export const setDatarefValues = async (datarefNamesWithOptionalIndex, value) => {
+export const setDatarefValues = async (
+  datarefNamesWithOptionalIndex,
+  value,
+) => {
   if (Array.isArray(datarefNamesWithOptionalIndex)) {
-    return Promise.all(datarefNamesWithOptionalIndex.map(dataref => setDatarefValue(dataref, value))).then(results => {
-      return results[0]
-    })
+    await Promise.all(
+      datarefNamesWithOptionalIndex.map((dataref) =>
+        setDatarefValue(dataref, value),
+      ),
+    );
+  } else {
+    await setDatarefValue(datarefNamesWithOptionalIndex, value);
   }
-  
-  return setDatarefValue(datarefNamesWithOptionalIndex, value)
-}
+};
+
+/**
+ * @param {string|Array<string>} commandNamesWithOptionalDuration
+ * @return {Promise<void>}
+ */
+export const activateCommands = async (commandNamesWithOptionalDuration) => {
+  if (Array.isArray(commandNamesWithOptionalDuration)) {
+    await Promise.all(
+      commandNamesWithOptionalDuration.map((command) =>
+        activateCommand(command),
+      ),
+    );
+  } else {
+    await activateCommand(commandNamesWithOptionalDuration);
+  }
+};

package/src/config.js

@@ -1,4 +1,7 @@
+import { exec as rawExec } from "node:child_process";
 import { copyFile, mkdir, readFile } from "node:fs/promises";
+import { platform } from "node:process";
+import { promisify } from "node:util";
 
 import yaml from "js-yaml";
 import { homedir } from "os";
@@ -8,6 +11,8 @@ import { fileURLToPath } from "url";
 
 import { getDatarefValue } from "./api.js";
 
+const exec = promisify(rawExec);
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -21,6 +26,7 @@ const __dirname = dirname(__filename);
  * @property {RegExp} pattern - Regular expression pattern to match commands
  * @property {'get' | 'set'} type - Operation type
  * @property {string|Array<string>} dataref - X-Plane dataref path(s)
+ * @property {string|Array<string>} command - X-Plane command path(s)
  * @property {Transform[]} transform - Array of transformation operations to apply
  */
 
@@ -35,6 +41,15 @@ const __dirname = dirname(__filename);
 
 const osHomedir = homedir();
 
+const getAircraftConfigPath = async () => {
+  const aircraft = /** @type {string} */ (
+    await getDatarefValue("sim/aircraft/view/acf_ui_name")
+  )
+    .replaceAll(/[./\\]/g, " ")
+    .replace(/"/g, "");
+  return join(osHomedir, ".xp-command", `${aircraft}.yml`);
+};
+
 /**
  * @return {Promise<CommandConfig>}
  */
@@ -43,12 +58,7 @@ export const getConfig = async () => {
     recursive: true,
   });
 
-  /** @type {string} */
-  let aircraft;
-  aircraft = /** @type {string} */ (
-    await getDatarefValue("sim/aircraft/view/acf_ui_name")
-  ).replaceAll(/[./\\]/g, ' ');
-  const aircraftConfigPath = join(osHomedir, ".xp-command", `${aircraft}.yml`);
+  const aircraftConfigPath = await getAircraftConfigPath();
 
   let config;
   try {
@@ -67,3 +77,20 @@ export const getConfig = async () => {
 
   return /** @type {CommandConfig} */ (config);
 };
+
+export const editConfig = async () => {
+  const aircraftConfigPath = await getAircraftConfigPath();
+
+  const command =
+    platform === "win32"
+      ? `start "" "${aircraftConfigPath}"`
+      : platform === "darwin"
+        ? `open "${aircraftConfigPath}"`
+        : `xdg-open "${aircraftConfigPath}"`;
+
+  const { stderr } = await exec(command);
+
+  if (stderr) {
+    throw new Error(stderr);
+  }
+};

package/src/logger.js

@@ -0,0 +1,80 @@
+// logger.js
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {"debug" | "info" | "warn" | "error"} LogLevel
+ */
+
+/**
+ * @typedef {Object} LoggerOptions
+ * @property {boolean} [clearOnStart]
+ */
+
+export class Logger {
+  /**
+   * @param {string} filePath
+   * @param {LoggerOptions} [options]
+   */
+  constructor(filePath, options = {}) {
+    /** @private */
+    this.filePath = filePath;
+
+    /** @private */
+    this.options = options;
+
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    if (options.clearOnStart && fs.existsSync(filePath)) {
+      // clear file on app start
+      fs.truncateSync(filePath, 0);
+    }
+
+    /**
+     * @private
+     * @type {fs.WriteStream}
+     */
+    this.stream = fs.createWriteStream(filePath, { flags: "a" });
+  }
+
+  /**
+   * @private
+   * @param {LogLevel} level
+   * @param {string} msg
+   */
+  write(level, msg) {
+    const line = `${new Date().toISOString()} [${level.toUpperCase()}] ${msg}\n`;
+    this.stream.write(line);
+  }
+
+  /**
+   * @param {string} msg
+   */
+  debug(msg) {
+    this.write("debug", msg);
+  }
+
+  /**
+   * @param {string} msg
+   */
+  info(msg) {
+    this.write("info", msg);
+  }
+
+  /**
+   * @param {string} msg
+   */
+  warn(msg) {
+    this.write("warn", msg);
+  }
+
+  /**
+   * @param {string} msg
+   */
+  error(msg) {
+    this.write("error", msg);
+  }
+}