Commands

The Commands API lets you expose commands of your plugin to be used by other plugins or by other Qatium components, like Q, our digital assistant.

addCommand()

Allows the plugin to expose commands to be used by other components: Digital assistant (Q), other plugins, other Qatium components, etc.

Method signature

TypeScript

type CommandDescription = <
  Receives extends Record<string, string>,
  Returns extends Record<string, unknown>
>{
  name: string;
  description: string;
  aliases: string[];
  arguments: Receives;
  returnType: Record<keyof Returns, string>;
}

type CommandAnswer<Returns extends Record<string, unknown>> = {
  data: Returns;
  openPanel?: boolean;
  turnOnVisuals?: boolean;
};

addCommand<Receives, Returns>(
  description: CommandDescription<Receives, Returns>,
  fn: (args: Record<keyof Receives, string>) => Promise<CommandAnswer<Returns>>
): void

Python

class CommandDescription:
  name: str
  description: str
  aliases: List[str]
  arguments: Arguments
  returnType: Dict[str, str]

class CommandAnswer:
  data: Optional[Dict[str, Any]] = None
  openPanel: bool = False
  turnOnVisuals: bool = False

add_command(description: Dict[str, Any], fn: CommandFn) -> None

Parameters

• description: CommandDescription<Receives, Returns>:

  • name: The name of the command.
  • description: A description of the command.
  • aliases: A list of aliases for the command.
  • arguments: An object describing the arguments your command will receive.
  • returnType: An object describing the returned result type.
  TypeScript

  const commandDescription = {
    name: "Close Valves",
    description: "It closes valves from the network",
    aliases: ["shutdown valves", "close TCV", "close shut-off valves"],
    arguments: {
      numOfValves: "number of valves to close"
    },
    returnType: {
      valvesClosed: "how many valves the command was able to close"
    }
  }

  Python

  description = CommandDescription(
    name='Close Valves',
    description='It closes valves from the network',
    aliases=['shutdown valves', 'close TCV', 'close shut-off valves'],
    arguments={
      'numOfValves': 'number of valves to close'
    },
    returnType={
      'valvesClosed': 'how many valves the command was able to close'
    }
  )

• fn: <Receives, Returns>(args: Record<keyof Receives, string>) => Promise<CommandAnswer<Returns>>: It will perform the command and then return a Promise<CommandAnswer>:

  TypeScript

  type CommandAnswer<Returns> = {
    /**
    * The data returned by the command.
    * It should match the keys in {@link CommandDescription.returnType}
    */
    data: Returns;
    /**
    * Whether or not to open the plugin panel after the command succeeds.
    *
    * @default false.
    */
    openPanel?: boolean;
    /**
    * Whether or not to turn on/off the plugin visuals after the command succeeds.
    *
    * @default false.
    */
    turnOnVisuals?: boolean;
  };

  Python

  class CommandAnswer:
    data: Optional[Dict[str, Any]] = None
    openPanel: bool = False
    turnOnVisuals: bool = False

  TypeScript

  // A command that sets the demand of a junction
  type Receives = { junctionId: string; demand: string };
  type Returns = { junctionId: string; newDemand: string };
  
  const setJunctionDemandCommand: CommandFn<Receives, Returns> = async (args) => {
    const { junctionId, demand } = args;
  
    sdk.network.setDemand(junctionId, demand);
  
    return {
      data: {
        junctionId,
        newDemand: demand
      },
      openPanel: true,
    };
  };

  Python

  async def set_junction_demand(args):
    junction_id = args['junction_id']
    demand = args['demand']
  
    sdk.network.set_demand(junction_id, demand)
  
    return {
      'data': {
        'junction_id': junction_id,
        'new_demand': demand
      },
      'openPanel': True
    }

Example

TypeScript

sdk.commands.addCommand(
  {
    name: "Set junction demand",
    description: "sets the demand of a junction",
    aliases: [
      "set demand",
      "change demand",
      "increase flow in junction",
      "set flow in junction"
    ],
    arguments: {
      junctionId: "the id of the junction",
      demand: "the new demand of the junction"
    },
    returnType: {
      junctionId: "the id of the junction",
      newDemand: "the new demand of the junction"
    }
  },
  async (args) => {
    const { junctionId, demand } = args;

    sdk.network.setDemand(junctionId, Number(demand));

    return {
      data: {
        junctionId,
        newDemand: demand
      },
      openPanel: true,
    };
  }
);

Python

sdk.command.add_command(
  {
    "name": "Set junction demand",
    "description": "sets the demand of a junction",
    "aliases": [
      "set demand",
      "change demand",
      "increase flow in junction",
      "set flow in junction"
    ],
    "arguments": {
      junctionId: "the id of the junction",
      demand: "the new demand of the junction"
    },
    "returnType": {
      junctionId: "the id of the junction",
      newDemand: "the new demand of the junction"
    }
  },
  set_junction_demand
)

availableCommands()

Returns the available commands to call. You can use this method to connect your plugin with other plugins, or with other Qatium components.

Usually you would connect two plugins you own, so they can interact with each other.

Method signature

TypeScript

availableCommands() : Command[]

Python

available_commands() -> List[Command]