Command Definitions

A command definition declares a command once, on an asset template: for example, "Set curtailment cap" on a plant template, or "Reset fault" on a motor template. Every asset made from the template carries its own copy of the command, which you then bind to a point on that asset's equipment.

Where definitions live

1. Open Templates and choose the template.
2. Open its Commands section. The Command Definitions card lists the template's commands with their type, category, risk level and timeout.
3. Select Add Command. On a template with no commands yet, the button reads Add First Command.

New definitions are added to the template's current version. A template with no version yet asks you to create one first. To change or delete a definition, open the menu at the end of its row and choose Edit or Delete.

Operators and admins can add and edit definitions. Only admins can delete one. When your role cannot add, change or delete definitions, a line under the count says so.

Definition fields

The Add Command Definition dialog (Edit Command Definition when you edit one) has these fields:

Select Create Command to save a new definition, or Update Command to save changes.

Command types

Value Write

A value write sends one value to one point on the equipment: a setpoint, an operating mode, or a flag. After the write, the gateway reads the point back, and the record says whether the equipment holds the value that was written. Value writes work over OPC UA and Modbus.

Method Call

A method call runs a method on an OPC UA object, for example a reset or a calibration routine. Method calls are limited today:

• OPC UA only. A Modbus connector cannot carry a method call.
• No input arguments. Fleetera refuses a method call whose command declares parameters, or that is sent with parameters, and sends nothing. Use method calls only for methods that take no arguments.
• Only through a gateway that can run them. The gateway's runtime reports which command types it can run. If it does not report method calls, the command shows Gateway cannot run it or Not determined and cannot be sent.
• No read-back. A method call that completes shows Completed with no verification, because there is no value to read back.

Categories

The Execute Command wizard groups commands by category.

Risk levels

The risk level decides how a command is confirmed. It cannot be switched off for a single command, and Fleetera checks it on the server, so it applies to the API as well as the app.

Two-person approval is an organization setting, off unless an admin turns it on. See Critical commands and approval.

Parameters schema

A command can take parameters, such as the value a setpoint command writes. Each parameter can have a label, a type, a unit, a minimum, a maximum, and whether it is required. When someone sends the command, Fleetera shows a field for each parameter with its unit and range, and will not send a value outside the range.

The definition dialog does not edit parameters. They arrive with the template when you import it: each entry in the template file's commands list can carry a parametersSchema. For example:

{
  "key": "curtail_setpoint_kw",
  "name": "Set curtailment cap",
  "commandType": "value_write",
  "category": "operational",
  "riskLevel": "high",
  "timeoutMs": 30000,
  "parametersSchema": {
    "type": "object",
    "required": ["limitKw"],
    "properties": {
      "limitKw": {
        "type": "number",
        "title": "Curtailment cap",
        "unit": "kW",
        "minimum": 0
      }
    }
  }
}

Two more keywords on the written parameter widen the read-back comparison, in the parameter's own units: readbackTolerance (an absolute difference, for example 0.5) and readbackRelativeTolerance (a fraction, for example 0.001). Without them, a numeric read-back must match the written value to within one part in a million.

A command bound to a Modbus coil must declare a parameter of type boolean, see Coils need a boolean parameter.

From definitions to commands on assets

When you create an asset from a template, the asset gets its own copy of each of the template's commands. An asset that already existed when a command was added does not get it until you sync.

Each copy keeps the name, risk level, timeout and parameters it was created with. Editing a definition later changes what new copies get, not the commands already on assets. The send dialog and the record show the asset's own copy, which is why the same command can carry a different risk on different assets.

Sync to existing assets

The Sync to existing assets button on the template's Commands section puts the template's commands on every asset already made from it. When the asset count can be read, the button names it, for example Sync to 7 existing assets. It is available to operators and admins.

The Sync commands to existing assets dialog says, before anything runs:

• how many existing assets use the template;
• the keys of the commands the sync adds to each asset that does not have them yet;
• whether any definition is missing from the command catalogue, which the sync adds first.

Select the sync button in the dialog to run it. The sync only adds what is missing. An asset keeps every command it already has, and a command already on an asset is not changed to match the definition. Running it again creates nothing new.

The result lists definitions and command instances created or already present, and how many assets were synced. If some assets failed, the dialog is titled Sync finished with failures, names the assets that failed with the reason, and says that everything else went through. Running the sync again is safe.

The button is unavailable, with the reason beside it, when no assets use the template yet or when the template has no commands.

Next steps