Deep dive

From remote debugging to data discovery, learn how Formant works from top to bottom.

    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.  

    1. Built-in commands - These are commands available by default
    2. 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

    1. A user issues a command to a device
    2. 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”
    3. The command is transmitted to the device, and is listed in-app as “delivered”
    4. Agent receives the command
      1. For built-in commands, Formant Agent handles the command internally
      2. For custom commands, Formant Agent delivers the command to the application via Agent API
    5. The agent sends any data requested by the command
    6. 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.


    Managing Commands

    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:


    Field Description
    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 


    Limits on 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.


    Built-in Commands

    Formant Agent has support for commands that are built-in to the agent.

    Command Definition Description
    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 

    Custom Commands

    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

    Issuing Commands

    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”.

    Monitoring Commands

    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.


    © 2020 Formant • 1999 Bryant St · San Francisco, CA 94110