Skip to content

Commit 01d382f

Browse files
JanStaschulatralph-lange
authored andcommitted
rclc_executor: updated example section.
1 parent 3aecb00 commit 01d382f

1 file changed

Lines changed: 103 additions & 81 deletions

File tree

  • _docs/concepts/client_library/real-time_executor

‎_docs/concepts/client_library/real-time_executor/index.md‎

Lines changed: 103 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ As stated before, this Executor is based on the RCL library and is written in C
238238
- Given a set of handles, a trigger condition based on the input data of these handles shall decide when the processing is started.
239239

240240
- Avaiable options:
241-
- AND operation: fires when input data is available for all handles
241+
- ALL operation: fires when input data is available for all handles
242242
- ANY operation: fires when input data is available for at least one handle
243243
- ONE: fires when input data for a user-specified handle is available
244244
- User-defined function: user can implement more sophisticated logic
@@ -272,7 +272,7 @@ For each handle the user can specify, if the callback shall be executed only if
272272

273273
The trigger condition defines when the processing of these callbacks shall start. For convenience some default conditions have been defined:
274274
- trigger_any(default) : start executing if any callback has new data
275-
- trigger_and : start executing if all callbacks have new data
275+
- trigger_all : start executing if all callbacks have new data
276276
- trigger_one(&`data`) : start executing if `data` has been received
277277
- user_defined_function: the user can also define its own function with more complex logic
278278

@@ -352,109 +352,131 @@ rclc_executor_add_subscription(&exe, &sub2, &my_sub_cb2, ALWAYS);
352352
rclc_executor_add_subscription(&exe, &sub3, &my_sub_cb3, ALWAYS);
353353
rclc_executor_add_timer(&exe, &timer);
354354
// trigger when handle 'timer' is ready
355-
rclc_executor_trigger_one(&exe, &timer);
355+
rclc_executor_set_trigger(&exe, rclc_executor_trigger_one, &timer);
356356
// select LET-semantics
357357
rclc_executor_data_comm_semantics(&exe, LET);
358358
// spin forever
359359
rclc_executor_spin(&exe);
360360
```
361361

362-
While these Executor features are well suited for the embedded use-case, we identified also a number of software design patterns in robotics which are improving deterministic execution.
363-
364362
#### Sense-plan-act pipeline
365363

366-
#### Sensor fusion
367-
368-
- Multiple rates
369-
- Co-relating task activation
370-
371-
#### High priorty path
372-
373-
374-
375-
### Summary
376-
377-
C executor with standard ROS2 semantics. If you want more deterministic behavior, you can do that for data-driven or time-driven software architectures.
378-
379-
- Standard ROS2 semantic (react on every DDS event)
380-
381-
- Can define trigger (AND, ANY, ONE, user-defined function)
382-
383-
- Sequential processing order
384-
385-
- LET semantics
386-
387-
### Future work
388-
389-
- Full LET semantic (sending at the end of the period)
390-
- one publisher that periodically publish
391-
- if multiple periods are implemented in multiple threads, need to
392-
make publishing in each phase atomic.
393-
- support client, services, guard conditions as handles
394-
395-
396-
### Download - UPDATE!
397-
The LET-Executor can be downloaded from the micro-ROS GitHub [rcl_executor repository](https://github.com/micro-ROS/rcl_executor). The package [rcl_executor](https://github.com/micro-ROS/rcl_executor/tree/dashing/rcl_executor) provides the LET-Executor library with a step-by-step tutorial and the package [rcl_executor_examples](https://github.com/micro-ROS/rcl_executor/tree/dashing/rcl_executor_examples) provides an example, how to use the LET-Executor.
398-
399-
400-
REMOVE THIS STUFF BELOW HERE
401-
402-
## Rcl LET-Executor
403-
This section describes the rcl-LET-Executor. It is a first step towards deterministic execution by providing static order scheduling with a let semantics. The abbreviation let stands for Logical-Execution-Time (LET) and is a known concept in automotive domain to simplify synchronization in process scheduling. If refers to the concept to schedule multiple ready tasks in such a way, that first all input data is read for all tasks, and then all tasks are executed. This removes any inter-dependence of input data among these ready tasks and hence input data synchronization is not necessary any more[[BP2017](#BP2017)] [[EK2018](#EK2018)].
364+
In this example we want to realise a sense-plan-act pipeline in a single thread. The trigger condition is demonstrated by activating
365+
the sense-phase when both data for the Laser and IMU are available. Three executors are necessary `exe_sense`, `exe_plan`
366+
and `exe_act`. The two sensor acquisition callbacks `sense_Laser` and `sense_IMU` are registered in the Executor `exe_sense`.
367+
The trigger condition ALL is responsible to activate the sense-phase only when all data for these two callbacks are available.
368+
Finally all three Executors are spinning using a `while`-loop and the `spin_some` function.
404369

370+
The definitions of callbacks are omitted.
405371

372+
```C
373+
...
374+
rcl_subscription_t sense_Laser, sense_IMU, plan, act;
375+
rcle_let_executor_t exe_sense, exe_plan, exe_act;
376+
// initialize executors
377+
rclc_executor_init(&exe_sense, &context, 2, ...);
378+
rclc_executor_init(&exe_plan, &context, 1, ...);
379+
rclc_executor_init(&exe_act, &context, 1, ...);
380+
// executor for sense-phase
381+
rclc_executor_add_subscription(&exe_sense, &sense_Laser, &my_sub_cb1, ON_NEW_DATA);
382+
rclc_executor_add_subscription(&exe_sense, &sense_IMU, &my_sub_cb2, ON_NEW_DATA);
383+
rclc_let_executor_set_trigger(&exe_sense, rclc_executor_trigger_all, NULL);
384+
// executor for plan-phase
385+
rclc_executor_add_subscription(&exe_plan, &plan, &my_sub_cb3, ON_NEW_DATA);
386+
// executor for act-phase
387+
rclc_executor_add_subscription(&exe_act, &act, &my_sub_cb4, ON_NEW_DATA);
388+
389+
// spin all executors
390+
while (true) {
391+
rclc_executor_spin_some(&exe_sense);
392+
rclc_executor_spin_some(&exe_plan);
393+
rclc_executor_spin_some(&exe_act);
394+
}
395+
```
396+
#### Sensor fusion
406397

407-
### Concept
408-
The LET-Executor consists of tho phases, configuration and running phase. First, in configuration phase, the total number of handles are defined. A handle is the term in the rcl-layer to generalize _timers_, _subscriptions_, _services_ etc.. Also in this phase, the execution order of the callbacks is defined. Secondly, in the running phase, the availability of input data for all handles is requested from the DDS-queue, then all received input data is stored and, finally, all callbacks corresponding to the handles are executed in the specified order. With this two-step approach, the LET-Executor guarantees a deterministic callback execution (pre-defined static order) and implements the LET semantics while executing the callbacks.
398+
The sensor fusion synchronizing the multiple rates with a trigger is shown below.
409399

410-
### Example
400+
```C
401+
...
402+
rcl_subscription_t aggr_IMU, sense_Laser, sense_IMU;
403+
rcle_let_executor_t exe_aggr, exe_sense;
404+
// initialize executors
405+
rclc_executor_init(&exe_aggr, &context, 1, ...);
406+
rclc_executor_init(&exe_sense, &context, 2, ...);
407+
// executor for aggregate IMU data
408+
rclc_executor_add_subscription(&exe_aggr, &aggr_IMU, &my_sub_cb1, ON_NEW_DATA);
409+
// executor for sense-phase
410+
rclc_executor_add_subscription(&exe_sense, &sense_Laser, &my_sub_cb2, ON_NEW_DATA);
411+
rclc_executor_add_subscription(&exe_sense, &sense_IMU, &my_sub_cb3, ON_NEW_DATA);
412+
rclc_executor_set_trigger(&exe_sense, rclc_executor_trigger_all, NULL);
413+
414+
// spin all executors
415+
while (true) {
416+
rclc_executor_spin_some(&exe_aggr);
417+
rclc_executor_spin_some(&exe_sense);
418+
}
419+
```
411420

412-
We provide an example for using the LET-Executor. First, the callbacks _my\_sub\_cb_ and my_timer\_cb_ are defined for a subscription and a timer, respectivly. Then, the ROS _context_ and the ROS _node_ are defined as well as the subscription object _sub_ and the timer object _timer_.
421+
The setup for the sensor fusion using sequential execution is shown below.
422+
Note that the sequetial order is `sense_IMU`, which will request the aggregated IMU message, and then `sense_Laser`
423+
while the trigger will fire, when a laser message is received.
413424

414-
The Executor is initialized with two handles. Then, the _add_ functions define the static execution order of the handles. In this example, the subscription _sub_ shall be processed before the timer _timer_. Finally, the Executor is activated with the _spin\_period_ function, which is continuously called every 20 ms.
415425
```C
416-
#include "rcl_executor/let_executor.h"
426+
...
427+
rcl_subscription_t sense_Laser, sense_IMU;
428+
rcle_let_executor_t exe_sense;
429+
// initialize executor
430+
rclc_executor_init(&exe_sense, &context, 2, ...);
431+
// executor for sense-phase
432+
rclc_executor_add_subscription(&exe_sense, &sense_IMU, &my_sub_cb1, ALWAYS);
433+
rclc_executor_add_subscription(&exe_sense, &sense_Laser, &my_sub_cb2, ON_NEW_DATA);
434+
rclc_executor_set_trigger(&exe_sense, rclc_executor_trigger_one, &sense_Laser);
435+
// spin
436+
rclc_executor_spin(&exe_sense);
437+
```
438+
#### High priorty path
417439

418-
// define subscription callback
419-
void my_sub_cb(const void * msgin)
420-
{
421-
// ...
422-
}
440+
This example shows the sequential processing order to execute the obstacle avoidance `obst_avoid`
441+
after the callbacks of the sense-phase and before the callback of the planning phase `plan`.
442+
The control loop is started when a laser message is received. Then an aggregated IMU message is requested,
443+
like in the example above. Then all the other callbacks are always executed. This assumes that these callbacks
444+
communicate via a global data structure. Race conditions cannot occur, because the callbacks
445+
run all in one thread.
423446

424-
// define timer callback
425-
void my_timer_cb(rcl_timer_t * timer, int64_t last_call_time)
426-
{
427-
// ...
428-
}
429-
430-
// necessary ROS 2 objects
431-
rcl_context_t context;
432-
rcl_node_t node;
433-
rcl_subscription_t sub;
434-
rcl_timer_t timer;
447+
```C
448+
...
449+
rcl_subscription_t sense_Laser, sense_IMU, plan, act, obst_avoid;
435450
rcle_let_executor_t exe;
451+
// initialize executors
452+
rclc_executor_init(&exe, &context, 5, ...);
453+
// define processing order
454+
rclc_executor_add_subscription(&exe, &sense_IMU, &my_sub_cb1, ALWAYS);
455+
rclc_executor_add_subscription(&exe, &sense_Laser, &my_sub_cb2, ON_NEW_DATA);
456+
rclc_executor_add_subscription(&exe, &obst_avoid, &my_sub_cb3, ALWAYS);
457+
rclc_executor_add_subscription(&exe, &plan, &my_sub_cb4, ALWAYS);
458+
rclc_executor_add_subscription(&exe, &act, &my_sub_cb5, ALWAYS);
459+
rclc_executor_set_trigger(&exe, rclc_executor_trigger_one, &sense_Laser);
460+
// spin
461+
rclc_executor_spin(&exe);
462+
```
436463

437-
// define ROS context
438-
context = rcl_get_zero_initialized_context();
439-
// initialize ROS node
440-
rcl_node_init(&node, &context,...);
464+
### Summary
441465

442-
// create a subscription
443-
rcl_subscription_init(&sub, &node, ...);
466+
The RCLC Executor is an Executor for C applications and can be used with default rclcpp Executor semantics. If additional deterministic behavior is necessary, the user can rely on pre-defined sequential execution, trigged execution and LET-Semantics for data synchronization.
444467

445-
// create a timer
446-
rcl_timer_init(&timer, &my_timer_cb, ... );
468+
### Future work
447469

448-
// initialize executor with two handles
449-
rcle_let_executor_init(&exe, &context, 2, ...);
470+
- Full LET semantics (writing data at the end of the period)
471+
- one publisher that periodically publishes
472+
- if Executors are running in multiple threads,
473+
publishing needs to be atomic
474+
- add support for handle types: client, services, guard conditions
450475

451-
// define static execution order of handles
452-
rcle_let_executor_add_subscription(&exe, &sub, &my_sub_cb, ...);
453-
rcle_let_executor_add_timer(&exe, &timer);
454476

455-
// spin with a period of 20ms
456-
rcle_let_executor_spin_period(&exe, 20);
457-
```
477+
### Download
478+
The RCLC-Executor can be downloaded from the micro-ROS GitHub [rclc repository](https://github.com/micro-ROS/rclc). The package [rclc](https://github.com/micro-ROS/rclc/tree/feature/new_api_and_LET_executor_trigger/rclc) provides the RCLC-Executor library and the package [rclc_examples](https://github.com/micro-ROS/rclc/tree/feature/new_api_and_LET_executor_trigger/rclc_examples) provides an example, how to use the LET-Executor.
479+
458480

459481

460482
## Callback-group-level Executor

0 commit comments

Comments
 (0)