Commands
Introduction
A command is a directive sent to the device in order for it to perform a specific task. One can use Formant's built-in commands (available by default) or create custom commands of their own (using Formant APIs). Commands may be used to trigger data ingestion, run scripts, or a variety of other, similar behaviors.
There are two types of commands that can be created.
- Built-in commands - These are commands available by default.
- Custom commands - These are commands created by the user/admin using Formant API. For more information, visit the help documentation on creating custom commands.
Both of these commands can be configured on the Commands page. You can add a friendly name, description, and specify the device channel on which the commands should appear.
A command is defined by the following information:
| Field | Description |
|---|---|
| Name | Name your command to help you and others identify it |
| Definition | Determines what command to invoke on the device |
| Enable parameters | Toggle determines if additional data should be sent with the command |
| Parameter value | Optional parameter value to be sent with this command (otherwise the parameter value will be collected from the user when the command is issued) |
| Description | Description to display to the user when the command is run |
| Choose device | Use tags to constrain the devices on which to enable the command |
Life of a Command
- A user issues a command to a device
- The command is stored in Formant Cloud pending delivery to the device. If the device is offline or unreachable, the command will stay in the cloud for 72 hours. The command is listed in-app as “issued”
- The command is transmitted to the device, and is listed in-app as “delivered”
- Agent receives the command
4.1 For built-in commands, Formant Agent handles the command internally
4.2 For custom commands, Formant Agent delivers the command to the application via Agent API - The agent sends any data requested by the command
- The agent sends the command result, and the command is listed in-app as “complete”
Command expiry
A command request that is not delivered to the agent in 72 hours will be expired and never be delivered.
Running Commands
To run a command,
- Click on the more menu on the right side of any of the device Views.
- Click on one of the commands menu item from the drop-down menu.
- Choose the command you want to run.
- If the command prompts you, enter any necessary parameters. Parameters for a command will depend upon the nature of the specific command. Talk to your administrator if you do not know what the parameter should be.
- Once finalized, click Run Command.
Don't see the command in drop down?
The command needs to be configured by an administrator on the Commands page for it to appear on the device channels.
Built-in Commands
Formant agent has support for commands that are built-in to the agent. This makes it easier for users to start using commands without having to write code.
The built-in commands that come with the Formant agents are defined below:
| Command Definition | Description | Parameters |
|---|---|---|
| formant.get_file | Get a file from the device. This causes a file to be ingested | Absolute file path on the device |
| formant.publish_ros_topic | Publishes a message to a ROS topic | String to be published to the specified ROS topic |
| formant.run_script | Run a script on the device | Absolute file path on the device. The script should start with shebang. |
To use a built-in command, first add a command from the above table. The parameter should be enabled and set to the desired value. If the parameter value is not set, then it is collected from the user when they issue the command.
Add new command
Before a command can be accessed by a user from the command dropdown menu of a device View, the command must be defined and enabled by an administrator.
From the burger menu select Settings ⇒ Command. This lists the commands that are currently defined.
To create a new command, click Add Command.
Name
Choose a friendly name that other users can understand. This is the name that will be listed under the device channel.
Choose devices
Choose devices on which this command should be enabled. The device list should be filtered down using the tags you have defined for devices.
Don't have devices set with tags?
Check out our documentation for adding tags on devices
Configure Commands
Choose command definition
Choose the commands that you want to enable.
- The built-in commands are displayed as a drop-down menu.
- You will have to type in any custom commands.
Enable/disable command parameters
Commands have the option to be assigned parameters. If you want to restrict the command to specific parameters, or if the command has no parameters, use the toggle button to disable parameters.
Enter default parameters
Add the default parameters here. If a default parameter is entered, users will not see a screen to set parameters. This is useful when you want to restrict the scope of a command to the default parameter set.
For example, you could limit run_script command to only running a specific script on the device. In order to do this, first set Enable Parameters to ON. Then set the path of the command you want to run.
Add description
Add a description so that users can understand what the command is about and/or any required parameters. This is a field that is displayed to the users when they run the command.
Monitoring the status of a command
There are three states that an issued command can be in.
When a command is issued, it is added to the command queue in the cloud and is moved to the Issued state. It stays in this state until the device is online. If the device is unreachable after 72 hours, the commands are expired and will not be delivered to the device.
If/when the device comes online, the commands are delivered to the device. Unlike the Cloud command queue, the maximum number of pending command requests on a device (saved on the device but not yet read by the agent API) is 10. If a new command comes in after that, the oldest one will be dropped.
After the agent has processed the command, it sends a response, which is then passed on to the cloud along with a status of Success or Failure.
These states are represented by events on the timeline and the event list page.
Updated about 2 years ago