Commands

A command is the return path of the platform. Variables carry readings up from a Device; a command carries one value back down to it, over the same connection, and records who sent it and what happened.

Overview

Commands belong to the Connect stage because they run on the link the Edge Server already maintains with the equipment. Once a Device is connected and its Variables are reporting, adding a command gives operators a way to act on what they see: start the generator that a dashboard shows offline, write a new demand limit while an alarm is active, clear a stored peak at the end of a billing period.

Three objects make up the system. A command is the definition on the Device: a name, a value type, and the topic suffix it publishes on. A command event is the record written every time that command is sent, carrying the value, the person who sent it, and the result. A command group is a saved value plus a name pattern, so one action can be applied to matching commands across many Devices at once.

Commands are configured per Device under Administration → Devices, and their execution record lives under Events → Commands in the sidebar. Command groups have their own area under Administration → Command Groups.

Commands on a Device

Open a Device from Administration → Devices and choose the Commands tab. The table lists every command defined on that Device with its type, name, ID and topic suffix, and the ID and topic suffix each have a copy button because both are needed when wiring up firmware or an integration.

Click New Command to define one.

Field	Notes
Name	5 to 100 characters, unique within the Device. This is the label operators see everywhere the command is offered.
Type	BOOLEAN, NUMBER, STRING, TIME, COMPOSITE or ARRAY. Fixes the shape of the value the command accepts.
Topic Suffix	5 to 255 characters. Appended to the Device's command topic, so the Device subscribes to <organizationId>/<deviceId>/commands/<topicSuffix>.
Description	Optional, up to 200 characters. Shown under the command name in dialogs and in Commands History.
Configuration	Type-specific limits offered to whoever sends the command. Numbers take a min, max and step or a list of named options; strings take a list of options; times take a min and max; composite and array commands describe their fields.

The configuration is what turns a raw value into a safe control. A NUMBER command with a min of 0, a max of 1000 and a step of 25 gives the operator a bounded input rather than a free text box, and a STRING command with options becomes a picker. Composite commands carry several named fields in one message, and array commands carry a list of those field sets, which is how schedules and multi-step sequences are sent in a single write.

Import loads commands from a .csv file and matches on the command ID, so the same file both creates new commands and updates existing ones. The export button on the same tab produces all-commands.csv in that format, which makes copying a command set from one Device to another a download and an upload. Commands provisioned by a managed device template are marked as such and cannot be edited or deleted on the Device: change the template instead.

Sending a Command

Choose Send Command from a command's row menu. The dialog that opens matches the command type: a switch with Send True and Send False for boolean commands, a bounded numeric input or an option list for numbers, a text field or picker for strings, a time picker for TIME, and a field per configured entry for composite and array commands. The command's description is shown in the dialog, so whoever is about to press send reads the same explanation the person who defined it wrote.

Commands can also be sent from a control on a dashboard or a one-line diagram, and through the API, which is how a scheduler or an external system triggers them without anyone opening the app.

Sending writes the command event immediately with the result sent, then publishes the payload to the Device's command topic over MQTT. The payload carries the value as desiredState alongside the commandEventId, so a Device that reports back can quote the event it is answering. When the publish is accepted the event turns success; when it fails the event turns failed. Success therefore means the platform handed the message to the Device's topic, not that the equipment has finished acting on it. Confirmation of the physical outcome comes from the Variables the Device reports afterwards, which is why operators usually watch the reading rather than the command row.

LoRaWAN devices follow the same flow with one difference: the value is encoded by the device profile's codec and dispatched as a downlink, so it is delivered on the device's next receive window rather than instantly.

Commands History

Events → Commands is the record of every command sent in the Organization. It opens on the current year to date and lists the newest first.

Each row carries the status badge, the command name with its description underneath, who triggered it, and when. A command raised by the platform rather than by a person is attributed to System, which is how scheduled and API-driven writes are distinguished from operator actions. The search box matches command names and descriptions, the columns toggle controls which of Status, Triggered By and Triggered At are shown, and the export button writes the current page to CSV with the triggering user's email included.

The three statuses map to the send flow above: sent means the event was written and the publish has not resolved, success means the platform published to the Device, and failed means it could not. A row stuck on sent is worth investigating on the Device side rather than resending straight away.

Command Groups

A command group answers "send this same value everywhere it applies". Instead of naming individual commands, a group stores a name pattern, a command type and one desired value, then resolves to whatever matches at the moment it runs. Adding a Device with a matching command name brings it into the group automatically, with nothing to update.

Open Administration → Command Groups and click Command Group to create one.

Field	Notes
Name	Required, up to 100 characters.
Description	Optional, up to 200 characters.
Command Name	The pattern matched against command names across the Organization.
Match Type	Exact, Starts With, Ends With, Contains or Regex. Everything except Exact is case-insensitive.
Command Type	Only commands of this type are matched, so a boolean group never writes to a numeric command of the same name.
Desired Value	The value sent to every matched command. A switch for boolean groups, a number field for numeric groups, a text field for string groups.

A group has two tabs. Settings holds the fields above. Preview runs the pattern and lists exactly what it currently resolves to, with the Device and Location of each command.

Check the preview before running a group. A Starts With pattern that reads well in the form can pick up a command you did not intend on a Device added last week, and the preview is the only place that shows what will actually be written.

Execution is scoped by Location: a group runs against the matched commands at the Locations you name, so the same "Monthly Exercise" group can be run building by building rather than across the estate at once. Each matched command is sent individually and writes its own row to Commands History, so a partial failure is visible per Device rather than hidden behind a single result. Group execution is currently available through the API only.

Permissions

Defining commands and sending them are separate rights, so an operator can act on equipment without being able to change what the controls do.

Permission	Grants
Devices.ReadCommands	Seeing the Commands tab on a Device
Devices.CreateCommand, Devices.UpdateCommand, Devices.DeleteCommand	Defining, editing, importing and deleting commands
Devices.SendCommand	Sending a command to a Device
Events.ReadCommandsHistoricalEvents	The Commands History page
Events.CreateCommandEvent	Recording a command event
CommandGroups.ReadCommandGroups	Administration → Command Groups
CommandGroups.CreateCommandGroup, UpdateCommandGroup, DeleteCommandGroup	Creating, editing and deleting groups
CommandGroups.SendCommandToCommandGroup	Executing a group

Commands close the loop on the stages around them. They act on Devices brought in during the Connect and Collect stages, they are triggered from the Visualize stage on a dashboard control or a one-line diagram, and the trail they leave in Commands History is the record of who changed what, next to the alarm record of how the equipment responded and the readings in Data Explorer.