xp-command 1.4.0 → 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`.
 
 ---
 
@@ -166,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:
 
@@ -194,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

@@ -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";
@@ -97,11 +102,34 @@ 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) => {
@@ -125,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-command",
-  "version": "1.4.0",
+  "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>}
@@ -175,3 +239,19 @@ export const setDatarefValues = async (
     await 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

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