Commands deep dive
A command is a directive to the device to perform a specific task. 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.
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.
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
- For built-in commands, Formant Agent handles the command internally
- 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”
Before a command can be sent to a device, the command must be defined by an administrator.
As an administrator, navigate to Settings, Commands. This page lists the commands that are defined. To create a new command, click Add Command.
A command is defined by the following information:
|Name||Name your command to help you and others identify it|
|Definition||Determines what behavior to invoke on the device|
|Enable parameter||Toggle determines if additional data should be sent with 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)|
|Tags||Optional tags used to constrain which devices may be sent this command|
Formant Agent has support for commands that are built-in to the agent.
|formant.get_file||Causes a file to be ingested|
|formant.publish_ros_topic||Publishes a message to a ROS topic|
|formant.run_script||Runs a script|
Visit the documentation on built-in commands for more details
If the built-in commands do not satisfy your use case, you can build custom commands using the Formant Agent API. Visit the documentation on building custom commands for more details.
Adding new commands
Before a command can be sent to a device, the command must be defined in the agent and added in the web application. Visit the documentation on adding new commands for more details
After a command has been created, it may now be issued to a device.
As any user, navigate to the Device Channel by clicking the device name in the sidebar. In the page header is listed any commands available to this device (as determined by tags). Click the command name to issue the command. You are presented with a confirmation dialog box. If the command requires a parameter value, input the value here. Then click “Run 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.