Action definition (.action files) in ROS - Deep Dive

Overview - Action definition (.action files)

What is it?

An action definition in ROS is a special file with the .action extension that describes a task a robot can perform over time. It defines three parts: the goal (what you want done), the result (what you get back), and feedback (updates while working). These files help robots handle complex tasks that take time and need updates.

Why it matters

Without action definitions, robots would struggle to manage tasks that take time or need progress updates, like moving to a location or picking up objects. Actions let robots communicate clearly about goals and progress, making them more reliable and responsive in real situations.

Where it fits

Before learning action definitions, you should understand ROS messages and services, which handle simple data exchange and immediate requests. After mastering actions, you can build complex robot behaviors that require ongoing feedback and cancellation, like navigation or manipulation.

Mental Model

Core Idea

An action definition is a contract that tells a robot what to do, how to report progress, and what to send back when done.

Think of it like...

It's like ordering a pizza: you tell the restaurant your order (goal), they update you while cooking (feedback), and finally deliver the pizza (result).

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   Goal      │ → │  Feedback   │ → │   Result    │
│ (Request)   │   │ (Progress)  │   │ (Outcome)   │
└─────────────┘   └─────────────┘   └─────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding ROS Messages Basics

Concept: Learn what ROS messages are and how they define data structures for communication.

ROS messages are simple files that define data fields like numbers or text. They let different parts of a robot talk by sending structured data. For example, a message might say 'position: 5 meters' or 'speed: 2 m/s'.

Result

You can create and use messages to send data between robot parts.

Understanding messages is essential because actions build on this idea to send more complex, structured information.

2

Foundation

Introduction to ROS Services

Concept: Learn how ROS services allow a node to send a request and wait for a reply.

Services are like phone calls: you ask a question and wait for an answer. They are good for quick tasks that finish fast, like 'turn on the light' or 'get sensor data'.

Result

You can make simple request-response interactions in ROS.

Knowing services helps you see why actions are needed for longer tasks that can't finish immediately.

3

Intermediate

Structure of .action Files

🤔Before reading on: do you think .action files contain code or just data definitions? Commit to your answer.

Concept: Learn the three parts of an action file: goal, result, and feedback sections.

A .action file has three parts separated by '---'. The first part defines the goal data sent to start the action. The second part defines the result data sent when the action finishes. The third part defines feedback data sent repeatedly while the action runs.

Result

You can write .action files that describe what data your robot needs to perform tasks and report progress.

Knowing the three parts clarifies how actions manage ongoing tasks with updates and final results.

4

Intermediate

Generating Code from .action Files

🤔Before reading on: do you think .action files run by themselves or need extra steps to work? Commit to your answer.

Concept: Learn how ROS tools convert .action files into code for different programming languages.

ROS uses build tools to read .action files and create message and service code automatically. This code lets your robot nodes send goals, receive feedback, and get results without writing all communication details manually.

Result

You can use generated code to implement action clients and servers easily.

Understanding code generation saves time and prevents errors by automating communication setup.

5

Intermediate

Using Actions in Robot Programs

🤔Before reading on: do you think actions are only for sending goals or also for receiving updates? Commit to your answer.

Concept: Learn how action clients send goals and receive feedback and results from action servers.

An action client sends a goal message to an action server. The server works on the task and sends feedback messages to update progress. When done, it sends a result message. Clients can also cancel goals if needed.

Result

You can build programs that handle long tasks with progress updates and cancellation.

Knowing the client-server interaction pattern helps design responsive robot behaviors.

6

Advanced

Handling Preemption and Cancellation

🤔Before reading on: do you think once an action starts, it must finish? Commit to your answer.

Concept: Learn how actions support stopping or changing tasks before completion.

Actions allow clients to cancel goals if conditions change or errors occur. Servers must handle cancellation requests gracefully, stopping work and sending partial results if needed.

Result

Your robot can adapt to new commands or emergencies by stopping ongoing actions.

Understanding cancellation prevents robots from getting stuck on outdated tasks.

7

Expert

Internal Communication and Timing in Actions

🤔Before reading on: do you think feedback messages are guaranteed to arrive in order and without delay? Commit to your answer.

Concept: Learn how ROS manages message delivery, timing, and reliability for actions.

Actions use ROS topics and services under the hood. Feedback and result messages travel over topics, which are asynchronous and may have delays or drops. The action protocol handles these issues by tracking goal states and resending important info if needed.

Result

You understand how actions remain reliable despite network delays or message loss.

Knowing the communication details helps debug and optimize robot responsiveness.

Under the Hood

Action definitions are parsed by ROS build tools to generate message and service code. At runtime, an action server listens for goal requests via a service call. Once accepted, it publishes feedback and result messages on topics. The client subscribes to these topics to receive updates. The system tracks goal states to manage cancellations and completions.

Why designed this way?

Actions were designed to handle tasks that take time and need progress updates, which services alone can't manage. Using separate topics for feedback and results allows asynchronous updates without blocking. This design balances simplicity and flexibility, avoiding complex protocols while supporting real-time robot needs.

┌───────────────┐          ┌───────────────┐
│ Action Client │          │ Action Server │
└──────┬────────┘          └──────┬────────┘
       │ Goal Request (Service)     │
       │──────────────────────────▶│
       │                           │
       │ Feedback (Topic)           │
       │◀──────────────────────────│
       │                           │
       │ Result (Topic)             │
       │◀──────────────────────────│
       │                           │
       │ Cancel Request (Service)   │
       │──────────────────────────▶│

Myth Busters - 4 Common Misconceptions

Quick: Do you think actions are just faster services? Commit to yes or no.

Common Belief: Actions are just services that run faster or asynchronously.

Reality: Actions are a separate communication pattern designed for long-running tasks with feedback and cancellation, unlike services which are simple request-response.

Why it matters: Treating actions like services can lead to poor robot behavior, missing progress updates or inability to cancel tasks.

Quick: Do you think feedback messages always arrive in order and never get lost? Commit to yes or no.

Common Belief: Feedback messages from actions are guaranteed to arrive in order and without loss.

Reality: Feedback messages use ROS topics, which are asynchronous and can be delayed or dropped; the system handles this but does not guarantee perfect delivery.

Why it matters: Assuming perfect delivery can cause bugs if the program relies on every feedback message.

Quick: Do you think the .action file contains executable code? Commit to yes or no.

Common Belief: .action files contain code that runs the action logic.

Reality: .action files only define data structures; the logic is implemented separately in action servers.

Why it matters: Confusing definition files with code can cause misunderstanding of where to write robot behavior.

Quick: Do you think an action must always finish once started? Commit to yes or no.

Common Belief: Once an action starts, it cannot be stopped until completion.

Reality: Actions support cancellation requests, allowing clients to stop tasks before they finish.

Why it matters: Ignoring cancellation can make robots unresponsive or stuck on outdated tasks.

Expert Zone

1

Action feedback frequency should balance between responsiveness and network load; too frequent updates can overwhelm the system.

2

Action servers must carefully manage goal states to avoid race conditions when handling simultaneous goals and cancellations.

3

Generated action code varies slightly between ROS versions and languages, requiring attention when mixing client and server implementations.

When NOT to use

Avoid using actions for very short or instantaneous tasks; services are simpler and more efficient there. For complex workflows involving multiple steps, consider using behavior trees or state machines instead of a single action.

Production Patterns

In real robots, actions are used for navigation goals, arm movements, and sensor calibration tasks. Developers often combine actions with state machines to manage sequences and fallback behaviors. Monitoring action states and timeouts is common to ensure robustness.

Connections

Asynchronous Programming

Actions implement asynchronous communication patterns similar to async/await in programming languages.

Understanding asynchronous programming helps grasp how actions send goals and receive feedback without blocking the robot's main processes.

Client-Server Architecture

Actions follow a client-server model where clients request tasks and servers perform them with updates.

Knowing client-server basics clarifies how action clients and servers interact and manage task states.

Project Management Progress Tracking

Actions' feedback and result reporting resemble how project managers track task progress and completion.

Seeing actions like project tracking helps understand why feedback is crucial for long tasks and how cancellation relates to changing priorities.

Common Pitfalls

#1 Ignoring feedback messages and only waiting for results.

Wrong approach:

client.send_goal(goal)
result = client.wait_for_result()
# No feedback handling

Correct approach:

def feedback_cb(feedback):
print('Progress:', feedback.progress)
client.send_goal(goal, feedback_cb=feedback_cb)
result = client.wait_for_result()

Root cause:

Not handling feedback misses important progress updates, reducing responsiveness.

#2 Writing logic inside the .action file instead of separate server code.

Wrong approach:

# In my_action.action
int32 goal
# Trying to add code here (wrong)

Correct approach:

# my_action.action
int32 goal
---
int32 result
---
float32 progress

# Logic implemented in separate action server node

Root cause:

Confusing data definition files with executable code leads to misplaced logic.

#3 Not handling goal cancellation requests in the server.

Wrong approach:

def execute_cb(goal):
while not done:
do_work()
return result

Correct approach:

def execute_cb(goal):
while not done:
if server.is_preempt_requested():
server.set_preempted()
return
do_work()
return result

Root cause:

Ignoring cancellation requests causes unresponsive or stuck actions.

Key Takeaways

Action definitions in ROS describe tasks with goal, feedback, and result parts to manage long-running robot activities.

They enable robots to receive goals, send progress updates, and deliver final results asynchronously.

Actions use generated code and a client-server pattern to simplify complex communication.

Handling feedback and cancellations properly is essential for responsive and robust robot behavior.

Understanding actions bridges simple message passing and advanced robot task management.

Practice

1. What is the main purpose of an .action file in ROS?

easy

A. To define goals, results, and feedback for long-running tasks

B. To list all the nodes in a ROS system

C. To configure robot sensors

D. To specify message types for topics

Solution

1. Step 1: Understand the role of .action files

   .action files are designed to define the structure of actions, which include goals, feedback, and results for tasks that take time.

2. Step 2: Compare with other ROS files

   Unlike message or service files, .action files specifically handle long-running tasks with progress updates.

3. Final Answer:

   To define goals, results, and feedback for long-running tasks -> Option A

4. Quick Check:

   Action files = goals + feedback + results [OK]

Hint: Remember: .action files split into goal, result, feedback [OK]

Common Mistakes:

• Confusing .action files with .msg or .srv files
• Thinking .action files configure hardware
• Assuming .action files list nodes

2. Which of the following is the correct structure of a ROS .action file?

easy

A. goal fields --- feedback fields --- result fields

B. goal fields --- result fields --- feedback fields

C. result fields --- feedback fields --- goal fields

D. feedback fields --- goal fields --- result fields

Solution

1. Step 1: Recall the .action file format

   The .action file has three parts separated by lines with three dashes (---): first goal, then result, then feedback.

2. Step 2: Match the order

   The correct order is goal fields first, result fields second, and feedback fields last.

3. Final Answer:

   goal fields --- result fields --- feedback fields -> Option B

4. Quick Check:

   Order = goal, result, feedback [OK]

Hint: Remember order: Goal first, Result second, Feedback last [OK]

Common Mistakes:

• Mixing up the order of feedback and result
• Using only two sections instead of three
• Forgetting the --- separators

3. Given this .action file snippet:

int32 goal_value
---
int32 result_value
---
float32 progress

What is the type of the feedback field?

medium

A. int32

B. bool

C. string

D. float32

Solution

1. Step 1: Identify the feedback section

   The .action file is split by --- lines. The third section after the second --- is the feedback part.

2. Step 2: Check the feedback field type

   The third section contains float32 progress, so the feedback field type is float32.

3. Final Answer:

   float32 -> Option D

4. Quick Check:

   Feedback type = float32 [OK]

Hint: Feedback is always after second --- line [OK]

Common Mistakes:

• Confusing result and feedback sections
• Choosing goal field type instead
• Ignoring the --- separators

4. What is wrong with this .action file?

int32 goal_value
---
float32 feedback_value
---
int32 result_value

medium

A. Result section must come before feedback

B. The order of sections is correct; no error

C. Feedback section cannot have fields

D. Feedback section is in the wrong place

Solution

1. Step 1: Check the order of sections

   The file has goal fields first, then feedback fields, then result fields, separated by --- lines.

2. Step 2: Verify field types in each section

   Goal has int32, feedback has float32, result has int32. However, the correct order is goal, result, feedback.

3. Final Answer:

   Result section must come before feedback -> Option A

4. Quick Check:

   Correct order is goal, result, feedback [OK]

Hint: Check section order and field types carefully [OK]

Common Mistakes:

• Thinking feedback must come last
• Assuming feedback cannot have fields
• Mixing up result and feedback order

5. You want to define an action for a robot to move to a position with feedback on distance left and a result indicating success. Which .action file snippet correctly defines this?

hard

A. float64 target_x
float64 target_y
---
bool success
---
float64 distance_left

B. bool success
---
float64 target_x
float64 target_y
---
float64 distance_left

C. float64 target_x
float64 target_y
---
float64 distance_left
---
bool success

D. float64 distance_left
---
float64 target_x
float64 target_y
---
bool success

Solution

1. Step 1: Identify goal, feedback, and result roles

   The goal should specify the target position (target_x, target_y). Feedback should provide ongoing info (distance_left). Result should indicate success (bool success).

2. Step 2: Match the correct order in the .action file

   The order is goal fields first, then feedback fields, then result fields. float64 target_x float64 target_y --- float64 distance_left --- bool success matches this order correctly.

3. Final Answer:

   float64 target_x float64 target_y --- float64 distance_left --- bool success -> Option C

4. Quick Check:

   Goal=target, Feedback=distance, Result=success [OK]

Hint: Goal first, feedback second, result last with correct fields [OK]

Common Mistakes:

• Swapping feedback and result sections
• Putting result fields in goal section
• Mislabeling feedback as result