Add CLI tool for Actions

[jacobperron]

Feature request

Feature description

Analogous to topics and services, there should be a command line tool for actions:

    ros2 action

Here is a list of tool capabilities and proposed signatures:

• list action names associated with any running action servers or action clients

    # For example
    $ ros2 action list
    /fibonacci
    /some/name/space/my_action
  

• list action servers and action clients associated with an action name

    ros2 action info ACTION_NAME
    # For example:
    $ ros2 action info /fibonacci
    Action: /fibonacci
    Action Clients: 2
        /node/foo
        /another/node/bar 
    Action Servers: 1
        /baz
  

• display active goals on an action server

    ros2 action goals ACTION_NAME
    # For example
    $ ros2 action goals /fibonacci
    152790028afb49a3b3c61383e6b97320
    8c3449e71c9941ed8ad3d68fdd7f553c
    b07cb18ca2dc4cca95acfc131fc49223
  

• display the arguments for an action goal

    ros2 action goal info ACTION_NAME GOAL_UUID
    # For example:
    $ ros2 action goal info /fibonacci 152790028afb49a3b3c61383e6b97320
    Action: /fibonacci
    Goal ID: 152790028afb49a3b3c61383e6b97320
    order: 10
  

• display the type of an action's goal, feedback, and result

    ros2 action show ACTION_TYPE
    # For example:
    $ ros2 action show example_interfaces/Fibonacci
    # Goal
    int32 order
    ---
    # Result
    int32[] sequence
    ---
    # Feedback
    int32[] sequence
  

• find actions by action type

    # Accomplished with a ros2 action list option:
    $ ros2 action list --show-types
    /fibonacci [example_interfaces/Fibonacci]
    /some/name/space/my_action [test_msgs/NestedMessage]
  

• echo feedback, status, and result for an action goal

    ros2 action echo [--feedback] [--status] [--result] ACTION_NAME GOAL_UUID
    # For example, getting feedback, status, and result messages:
    $ ros2 action echo /fibonacci 152790028afb49a3b3c61383e6b97320
    Feedback:
        sequence: [0, 1, 1]
    Feedback:
        sequence: [0, 1, 1, 2]
    Feedback:
        sequence: [0, 1, 1, 2, 3]
    Result:
        sequence: [0, 1, 1, 2, 3]
    Status: SUCCESS
    # For example, only echo status and result messages:
    $ ros2 action goal echo --status --result /fibonacci 152790028afb49a3b3c61383e6b97320
    Result:
        sequence: [0, 1, 1, 2]
    Status: ABORTED
  

• send an action goal, display feedback as it is received, display the result when received, and cancel the action (when the tool is terminated):

    ros2 action send_goal ACTION_NAME ACTION_TYPE GOAL_MESSAGE
    # For example:
    $ ros2 action send_goal /fibonacci example_interfaces/Fibonacci "order: 5"
    Sending goal...
    Goal accepted.
    Feedback:
        sequence: [0, 1, 1]
    Feedback:
        sequence: [0, 1, 1, 2]
    Feedback:
        sequence: [0, 1, 1, 2, 3]
    Feedback:
        sequence: [0, 1, 1, 2, 3, 5]
    Result:
        sequence: [0, 1, 1, 2, 3, 5]
  

In addition, the ros2 node info command should also list actions associated with a give node. For example:

    $ ros2 node info /foo
    /foo
      Subscribers:
        # ... subscriptions listed here
      Publishers:
        # ... publishers listed here
      Services:
        # ... services listed here
      Actions:
        # ... actions listed here      

Design document: ros2/design#193

[gbiggs]

Overall, looks great and is a desperately needed tool!

This comment probably equally applies to ros2 topic and ros2 service, but it would be useful to be able to list just clients or just servers. I don't know if the current graph API provides enough information to do that, though.

Could you give some examples of the output you expect from each command?

[jacobperron]

Similar to ros2 srv list, we might want to list all available action types. I think it makes sense to use the same action command with the types verb:

 ros2 action types

[jacobperron]

This comment probably equally applies to ros2 topic and ros2 service, but it would be useful to be able to list just clients or just servers. I don't know if the current graph API provides enough information to do that, though.

This could be part of the info verb. I was imagining it would act like ros2 topic info and list the number of action clients and action servers for a given action (this could be expanded to include the names of the nodes). We might be able to accomplish this by looking at the status topic, assuming we can differentiate publishers and subscriptions.

Could you give some examples of the output you expect from each command?

I've updated the description to include example outputs.

[jacobperron]

In retrospect, the verb for echoing goal arguments (ros2 action goal info) will be difficult to implement given the current action implementation. Currently, this information is only shared through the goal service request and not exposed in a way for external tools to introspect. I'm considering removing the feature from the scope of this ticket and we can create a follow up ticket if there is a motion to add it.

Getting the result for a goal should be relatively easy. As long as the goal hasn't expired (action server configuration), then the CLI tool should be able to make a service call to get result for any completed goal.

[gbiggs]

The output of ros2 action goals ACTION_NAME does not look very useful. Could it be merged with showing the arguments? (Ignoring for now that the arguments display functionality may not be feasible.) Just seeing a list of UUIDs doesn't help me much if I then need to iterate over each one.

If this is mainly intended to be used in scripts then it's not a problem, but I don't think that is the intended use case.

[gbiggs]

ros2 action info ACTION_NAME showing how many clients and servers there are does not help me identify them. I think we should be explicit if this is a desired output or not.

[jacobperron]

The output of ros2 action goals ACTION_NAME does not look very useful. Could it be merged with showing the arguments?

I figured it is a way to get the possible identifiers to pass to the goal info verb. Without it, how can the user know what goal ID to pass? We can have an autocomplete feature, but I'm not sure we want to rely on it.

For user-friendliness, we can allow using a short-form of the UUID and/or generate readable names for goals (similar to how Docker generates names for containers).

ros2 action info ACTION_NAME showing how many clients and servers there are does not help me identify them. I think we should be explicit if this is a desired output or not.

Agreed. I've updated the output to list node names.

[ibaiape]

Extremely non-critical, but It's something I'm curious about.

Currently there's a separation between commands specific to interfaces, like .msg and .srv files, and "communication patterns" (don't know what the correct term would be for this...), like topic and service.

You might already see where I'm going with this. It's probably not an issue, and a syntaxis/naming problem at best, but I'd say that if the other CLI's differentiate between these I'd consider it expected behaviour that the action CLI does too. I see you are already getting at what I mean here:

Similar to ros2 srv list, we might want to list all available action types. I think it makes sense to use the same action command with the types verb:

ros2 action types

Again, I don't think this has much weight at all, just curious on this, as action interfaces are the only one of the three where the interface "shorthand" and it's "communication pattern" are identical.

So happy to hear someone is working on this! Much appreciated!

[jacobperron]

if the other CLI's differentiate between these I'd consider it expected behaviour that the action CLI does too.

This is a valid point that I've been thinking about a bit. It would be nice if the action tools were consistent with the others.
Because of the naming ambiguity with the interface type, "action", I originally proposed combining the interface and communication commands into one. However, I can think of a few ways to make the CLI tools more consistent:

1. Rename the "interface" command.

   It could be called ax or actiontype. With verbs analogous to the other interface CLIs:

    ros2 actiontype list
    ros2 actiontype package
    ros2 actiontype packages
    ros2 actiontype show
   

   The downside is that it does not match the shorthand name for action definitions files.

2. Rename the "communication" command.

   Not really sure what to name it (ax, actioncomm?). Similar downside to option 1.

3. Merge all of the interface commands into one.

   The idea here is to combine ros2 srv and ros2 msg into a single command and add support for actions. For example:

    # List all .msg, .srv, and .action types available
    $ ros2 interface list
    Messages:
        # Message types listed here
    Services:
        # Service types listed here
    Actions:
        # Action types listed here
   
    # Only list .msg types
    $ ros2 interface list --only-msg
    Messages:
        # Message types listed here
   
    # List all packages that generate messages, services, or actions
    $ ros2 interface packages
    action_msgs
    builtin_interfaces
    diagnostic_msgs
    # etc ...
   
    # Only list packages that generate actions
    $ ros2 interface packages --only-actions
    action_msgs
    example_interfaces
    test_msgs
    # etc ...
    
    # Show an interface definition
    $ ros2 interface show example_interfaces/Fibonacci
    Action:
        # Goal
        int32 order
        ---
        # Result
        int32[] sequence
        ---
        # Feedback
        int32[] sequence
    
    # In case of ambiguity (e.g. message and service with same name), show both
    $ ros2 interface show test_msgs/Primitives
    Message:
        bool bool_value
        byte byte_value
        char char_value
        # etc ...
    Service:
        bool bool_value
        byte byte_value
        char char_value
        # etc ...
        ---
        bool bool_value
        byte byte_value
        char char_value
        # etc ...
   

   Downside is the command is more complex than the others, but not by much IMO.

4. Merge the msg and srv commands with topic and service.

   ros2 msg list becomes ros2 topic types
ros2 msg packages becomes ros2 topic packages
ros2 msg package becomes ros2 topic package
ros2 msg show becomes ros2 topic show.

   Likewise for the srv command.

   Subjectively, the downside is that using the topic command to get interface information is not intuitive. Especially, ros2 topic show.

IMO, option 3 makes the most sense, but I'd like to hear thoughts from others.

[gbiggs]

I like option 3 best. But I would prefer not to call it interface because that could collide with any future work where we might define actual node interfaces (as in the set of topics, services and actions that a node must use/provide to meet a specification).

what about ros2 types? Too generic?

[gbiggs]

I figured it is a way to get the possible identifiers to pass to the goal info verb. Without it, how can the user know what goal ID to pass? We can have an autocomplete feature, but I'm not sure we want to rely on it.

I was thinking that it could be merged with info, having a short form and long form of that verb.

$ ros2 action info /fibonacci
Goal ID: 152790028afb49a3b3c61383e6b97320
Goal ID: 8c3449e71c9941ed8ad3d68fdd7f553c
Goal ID: b07cb18ca2dc4cca95acfc131fc49223
$ ros2 action info -v /fibonacci  [or --args?]
Goal ID: 152790028afb49a3b3c61383e6b97320
- order: 10
Goal ID: 8c3449e71c9941ed8ad3d68fdd7f553c
- order: 1
Goal ID: b07cb18ca2dc4cca95acfc131fc49223
- order: 388
$ ros2 action info -v /fibonacci 152790028afb49a3b3c61383e6b97320
Goal ID: 152790028afb49a3b3c61383e6b97320
- order: 10

Possibly the usability is going down rather than up.

[dirk-thomas]

3. Merge all of the interface commands into one.

Sounds reasonable to me.

In case of ambiguity (e.g. message and service with same name), show both

I don't think this is a good idea. <pkgname>/<othername> is simply not a valid unique identifier anymore. Imo the caller would need to specify the type explicitly, e.g. <pkgname>/msg/<msgname>.

I would prefer not to call it interface ...

Interface is the term which is used throughout the design articles, the spec (IDL - Interface Definition Language) as well as implementation (all rosidl* pkgs).

[jacobperron]

The CLI, ros2action, was added in #214 with the following verbs implemented: info, list, send_goal, and show.

I will close this and open separate tickets for the goal and echo verbs as well as the proposed interface command.

[jacobperron]

Spin-off tickets:

• [ros2action] Display info about action goals on an action server #222
• Add ros2interface #223