xp-command 1.4.0 → 1.6.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`.
 
 ---
 
@@ -77,15 +73,25 @@ If you changed the Web API port from 8086 to another port, you'll need to start
 xp-command --port 8090
 ```
 
+### One-shot mode
+
+Run a single command and exit immediately (useful for scripts or keybindings):
+
+```bash
+xp-command --run x7000
+```
+
+Exits with code `0` on success, `1` on failure.
+
 ### Exiting
 
 Type `exit` or press `Ctrl+C`
 
 ---
 
-## 📋 Pre-configured commands
+## 📋 Pre-configured triggers
 
-All pre-configured commands work well with most aircraft I currently fly, but you may want to adjust them for **your** aircraft (see _Aircraft-specific profiles_ section below).
+All pre-configured triggers work well with most aircraft I currently fly, but you may want to adjust them for **your** aircraft (see _Aircraft-specific profiles_ section below).
 
 ### Barometric pressure
 
@@ -166,11 +172,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:
 
@@ -194,11 +201,51 @@ 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
+
+**Repeat syntax**: Append `[repeatCount]` to specify how often the command should be repeated:
+- `command[0][3]`: Press and immediately release three times
+- `command[0][$]`: Press and immediately release as often as defined by captured value
+
+**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

@@ -15,7 +15,12 @@ import { homedir } from "os";
 import { join } from "path";
 
 import packageJson from "../package.json" with { type: "json" };
-import { getDatarefValues, initAPI, setDatarefValues } from "../src/api.js";
+import {
+  activateCommands,
+  getDatarefValues,
+  initAPI,
+  setDatarefValues,
+} from "../src/api.js";
 import { copyToClipboard } from "../src/clipboard.js";
 import { editConfig, getConfig } from "../src/config.js";
 import { clearLine, hideCursor, showCursor } from "../src/console.js";
@@ -35,10 +40,12 @@ program
   .version(packageJson.version)
   .description(`${PREFIX} ${packageJson.name}\n${packageJson.description}`)
   .option("-p, --port <number>", "server port number")
+  .option("-r, --run <command>", "run a single command and exit")
   .helpOption("-h, --help", "display this help text");
 
 /**
  * @param {string} command
+ * @returns {Promise<boolean>} true if command succeeded, false otherwise
  */
 const processCommand = async (command) => {
   const spinner = ora(`${PREFIX} ${chalk.cyan(command ?? "")}`).start();
@@ -55,7 +62,7 @@ const processCommand = async (command) => {
       hideCursor();
       await sleep(1500);
       showCursor();
-      return;
+      return false;
     }
   }
 
@@ -65,7 +72,7 @@ const processCommand = async (command) => {
     hideCursor();
     await sleep(1500);
     clearLine();
-    return;
+    return true;
   }
 
   /**
@@ -95,13 +102,36 @@ const processCommand = async (command) => {
     return value;
   };
 
-  /** @type {Array<[RegExp, (regExpResult: Array<string> | null) => Promise<void>]>} */
+  /** @type {Array<[RegExp, (regExpResult: Array<string> | null) => Promise<boolean>]>} */
   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 false;
+        },
+      ];
+    }
+
     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 false;
+            }
+
             /** @type {number|string|Array<number|string>}*/
             let value = await getDatarefValues(c.dataref);
             c.transform?.forEach((t) => {
@@ -119,27 +149,51 @@ const processCommand = async (command) => {
             hideCursor();
             await sleep(1500);
             clearLine();
+            return true;
           },
         ];
       case "set":
         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 false;
+            }
+
+            if (c.command) {
+              let value = String(regExpResult[1]);
+              if (isNaN(Number(value))) {
+                await activateCommands(c.command);
+              } else {
+                c.transform?.forEach((t) => {
+                  value = String(getTransformedValue(value, t));
+                });
+                await activateCommands(c.command, Number(value));
+              }
+            }
+            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();
             await sleep(1500);
             clearLine();
+            return true;
           },
         ];
     }
@@ -149,12 +203,15 @@ const processCommand = async (command) => {
     const regexpResult = regexp.exec(command);
     if (regexpResult !== null) {
       try {
-        await cb(regexpResult);
+        const success = await cb(regexpResult);
 
-        spinner.succeed();
+        if (success) {
+          spinner.succeed();
+        }
         hideCursor();
 
         showCursor();
+        return success;
       } catch (error) {
         logger.error(error);
         spinner.fail();
@@ -178,8 +235,8 @@ const processCommand = async (command) => {
 
         await sleep(500);
         showCursor();
+        return false;
       }
-      return;
     }
   }
 
@@ -188,6 +245,7 @@ const processCommand = async (command) => {
 
   await sleep(1500);
   showCursor();
+  return false;
 };
 
 const sayHello = () => {
@@ -249,17 +307,27 @@ const askForCommand = async () => {
   await askForCommand();
 };
 
-program.action(async (/** @type {{ port: number | undefined }} */ options) => {
-  initAPI({ port: options.port ?? 8086 });
+program.action(
+  async (
+    /** @type {{ port: number | undefined, run: string | undefined }} */ options,
+  ) => {
+    initAPI({ port: options.port ?? 8086 });
 
-  hideCursor();
-  clearLine();
-  sayHello();
-  await sleep(1000);
-  showCursor();
+    if (options.run) {
+      history.addCommand(options.run);
+      const success = await processCommand(options.run);
+      process.exit(success ? 0 : 1);
+    }
 
-  await askForCommand();
-});
+    hideCursor();
+    clearLine();
+    sayHello();
+    await sleep(1000);
+    showCursor();
+
+    await askForCommand();
+  },
+);
 
 program.parse(process.argv);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-command",
-  "version": "1.4.0",
+  "version": "1.6.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,31 @@ const parseDataref = (datarefString) => {
   return [match[1], match[2] ? parseInt(match[2]) : null];
 };
 
+/**
+ * @param {string} commandString
+ * @param {number|string} [value]
+ * @return {[string, number|null, number|null]}
+ */
+const parseCommand = (commandString, value) => {
+  // Regex pattern: captures base name and optional duration and repeat count values
+  const pattern = /^(.+?)(?:\[(\d+)\])?(?:\[(\d+|\$)\])?$/;
+  const match = commandString.match(pattern);
+
+  if (!match) {
+    throw new CustomError("invalid_command");
+  }
+
+  let repeatCount = match[3] ? parseInt(match[3]) : null;
+  if (isNaN(repeatCount)) {
+    repeatCount = typeof value === "number" ? value : parseInt(value);
+  }
+  if (isNaN(repeatCount)) {
+    repeatCount = 1;
+  }
+
+  return [match[1], match[2] ? parseInt(match[2]) : null, repeatCount];
+};
+
 /**
  * @param {string} datarefName
  * @return { Promise<number | null> }
@@ -65,6 +90,61 @@ 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
+ * @param {number|string} [value]
+ */
+export const activateCommand = async (
+  commandNameWithOptionalDuration,
+  value,
+) => {
+  const [commandName, duration, repeatCount] = parseCommand(
+    commandNameWithOptionalDuration,
+    value,
+  );
+
+  const commandId = await getCommandId(commandName);
+
+  const url = new URL(
+    `http://localhost:${port}/api/v2/command/${commandId}/activate`,
+  );
+
+  for (let i = Math.max(1, repeatCount ?? 1); i--; ) {
+    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);
+    }
+  }
+};
+
 /**
  * @param {string} datarefNameWithOptionalIndex
  * @return {Promise<number|string>}
@@ -175,3 +255,23 @@ export const setDatarefValues = async (
     await setDatarefValue(datarefNamesWithOptionalIndex, value);
   }
 };
+
+/**
+ * @param {string|Array<string>} commandNamesWithOptionalDuration
+ * @param {number|string} [value]
+ * @return {Promise<void>}
+ */
+export const activateCommands = async (
+  commandNamesWithOptionalDuration,
+  value,
+) => {
+  if (Array.isArray(commandNamesWithOptionalDuration)) {
+    await Promise.all(
+      commandNamesWithOptionalDuration.map((command) =>
+        activateCommand(command, value),
+      ),
+    );
+  } else {
+    await activateCommand(commandNamesWithOptionalDuration, value);
+  }
+};

package/src/config.js

@@ -26,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
  */