RobMoSys Wiki

Hard real-time control software is often designed as monolithic components in order to circumvent the lack of temporal determinism of today's general purpose robot middlewares. COCORF will overcome this by combining the RobMoSys composition approach with the proven microblx real-time function block framework [1, 2]. This will enable building modular and predicable control systems by composing reusable blocks based on the function block model of computation. Microblx introspection facilities will be used to generate RobMoSys compliant digital function block data-sheets containing formalized constraints and QoS properties. Interoperability to existing robotics middlewares as well as separation of criticality domains will be realized by means of mixed-port function blocks. To validate the technology and to support early adopters, the approach will be illustrated by developing a generic control reference architecture and accompanying demonstration for the Assistive Mobile Manipulation Pilot. In this manner, COCORF lays the foundation for an extended RobMoSys Ecosystem of reusable, real-time function blocks.

The project foresees four milestones:

• M1: RobMoSys compliant composition DSL and digital data-sheet for function blocks
• M2: Mixed-port function blocks to ROS are available
• M3: Reference architecture completed
• M4: End of project

COCORF contributes to the following RobMoSys user stories [8, 9]:

• Composition of components:

By using the COCORF composition extensions, system builders are supported in the construction of reusable, hard real-time safe components.

• Management of Non-Functional Properties:

microblx supports management of non-functional properties by providing relevant information. For example, the current execution timing properties (i.e. min/max) of schedules are made available on a tstats port (also see demo below).

• Description of building blocks via model-based data sheets

(WIP). COCORF is developing tooling to allow automatic data-sheet generation from function blocks. This provides Component builders with accurate and up-to-date information on the blocks they are composing.

microblx uses a Lua based internal DSL to describe systems in so-called .usc (microblx system composition) files. Until COCORF, these descriptions contained a flat list of blocks, configurations and connections. This works fine for small systems, but falls short for larger systems where reusability and modularity are of more concern.

The technical requirements for the composition extensions as well as the high-level approach are elaborated in a technical requirements document [5]. The main requirements are:

• The DSL must allow to include one or more subsystems
• An included subsystem must not require any knowledge of the supersystem (or that it is being included at all).
• It must be possible to override configurations of the subsystem from the super-system.
• It must be possible to connect to ports of an included subsystem
• It should be possible to remove elements of the subsystem from the supersystem (blocks, connections).
• The use of (third party) schedule computation tools via a form of plugin mechanism shall be supported. Nevertheless, it must be possible to specify schedules manually.

The implementation went largely as planned, however the following insight required deviating from the original plan. The original idea of extending ubx_launch(1) with a -a option to specify an activity model was abandoned in favor of the more generic approach of a “model mixin”. The latter permits specifying one or more additional models on the command line, of which each will be merged into the primary one. This not only addresses the requirement of supporting late binding to the platform (i.e. typically to to different activities), but provides an additional, orthogonal composition “operator”. Although not explored in depth, this promises to be useful for further use-cases (e.g. instrumentation), where functionality must be added while pollution of a reusable composition avoided.

As a self-contained example (to be shown at the ERF), a software only demo was prepared to illustrate i) how composition enables reuse and how ii) late binding to platform specific aspects is achieved using the model mixin feature. The code for this example can be found here [6].

The green composition (pid.usc) defines a reusable controller consisting of a trajectory generator (block traj, a 10d ramp in the example), a PID controller and a schedule (encapsulated by a passive trig block). One connection is made within the pid composition: from the trajectory generator out to the PID des port.

This composition can be now be reused in different use-cases and respective environment. This is achieved by including the basic composition in a parent composition, which overlays it to adapt it to its specific environment. For this demo, the pid.usc composition is to be reused in a simulation/testing environment (pid_test.usc). To that end a simulated sensor signal (sim) block is created and connected to the PID msr input. The schedule configuration is extended to include triggering of the new sim block. Additional connections are created to export the various internal signals from the blocks using real-time message queues (mq_X blocks) for debugging purposes. The connection from sched.tstats exports timing statistics such as worst case execution times out of the real-time context.

Alternatively, pid.usc could be reused on a real system by including it in a parent composition similar to pid_test.usc. Instead of creating and connecting a simulator block, such a composition would instead create a robot driver or sensor block and create the apppropriate connections.

The example can be launched using the following command (executed from the directory microblx/examples/usc/pid:

$ ubx_launch -c pid_test.usc,ptrig_nrt.usc

This launches pid_test.usc after merging the platform specific, minimal ptrig_nrt.usc composition, which instantiates a platform specific pthread trigger with non-real-time priorities (hence the _nrt).

For running with real-time priorities, the ptrig_rt.usc file can be specified instead of ptrig_nrt.usc. Note that this requires to be run with elevated priviledges:

$ sudo ubx_launch -c pid_test.usc,ptrig_rt.usc

The exported data can be viewed using the ubx-mq(1) command:

$ ubx-mq list
243b40de92698defa93a145ace0616d2  1    trig_1-tstats
e8cd7da078a86726031ad64f35f5a6c0  10   ramp_des-out
e8cd7da078a86726031ad64f35f5a6c0  10   ramp_msr-out
e8cd7da078a86726031ad64f35f5a6c0  10   controller_pid-out

and

$ ubx-mq read controller_pid-out
{10202389818.28,10202389818.28,10202389818.28,10202389818.28,10202389818.28,10202389818.28,10202389818.28,10202389818.28,10202389818.28,10202389818.28}
{10202434989.98,10202434989.98,10202434989.98,10202434989.98,10202434989.98,10202434989.98,10202434989.98,10202434989.98,10202434989.98,10202434989.98}
...

Digital data sheets [10] summarize important information about function blocks. This information, rendered in a human readable form supports system builders to effectively decice whether a block is suitable for a specific scenario and ii) how it can be used. For instance, a digital data-sheet should contain general information about the block such as its Software license, but also specific technical information such as the block API.

For microblx, digital datasheets can be generated by leveraging the existing introspection functionalities. To that end, the ubx-modinfo tool was extended to generate data sheets in various formats including JSON, reStructuredText and plain text. For example, the following shows the plain text version of the PID controller data sheet:

$ ubx-modinfo show pid
module pid
 license: BSD-3-Clause

 types:

 blocks:
  pid [state: preinit, steps: 0] (type: cblock, prototype: false, attrs: )
  ports:
    msr [in: double #conn: 0]  // measured input signal
    des [in: double #conn: 0]  // desired input signal
    out  [out: double #conn: 0] // controller output
  configs:
    Kp [double] nil // P-gain (def: 0)
    Ki [double] nil // I-gain (def: 0)
    Kd [double] nil // D-gain (def: 0)
    data_len [long] nil // length of signal array (def: 1)

Furthemore, the tool is already used to generate documentation in the reStructuredText format which in turn is used by the sphinx tool. The following command generates a reSt document for the PID block:

ubx-modinfo dump pid -f rest
Module pid
----------

Block pid
^^^^^^^^^

| **Type**:       cblock
| **Attributes**:
| **Meta-data**:   { doc='',   realtime=true,}
| **License**:    BSD-3-Clause


Configs
"""""""

.. csv-table::
   :header: "name", "type", "doc"

   Kp, ``double``, "P-gain (def: 0)"
   Ki, ``double``, "I-gain (def: 0)"
   Kd, ``double``, "D-gain (def: 0)"
   data_len, ``long``, "length of signal array (def: 1)"



Ports
"""""

.. csv-table::
   :header: "name", "out type", "out len", "in type", "in len", "doc"

   msr, , , ``double``, 1, "measured input signal"
   des, , , ``double``, 1, "desired input signal"
   out, ``double``, 1, , , "controller output"

The result can be seen here.

Started in March 2020.

Work planned to start in July 2020.

COCORF has several connections to RobMoSys. Firstly, the developments in workpackage 1 (composable DSL and digital data-sheet) are applications of the RobMoSys approach in a concrete, industrial software framework. Similarily, workpackage 2 (mixed port function blocks) transfers the RobMoSys mixed port connector approach from component based development to hard real-time function blocks.

The composition extensions have been realized and a first version has been announced on discourse [7]. Block digital data-sheet support has been completed and is already used to generate stub function block data-sheets[11]. The code changes for both features have been merged to the microblx development branch and are scheduled for release with the upcoming v0.8 release. At the time of writing, a third release candidate v0.8-rc3 has been released.

Workpackage 2 has the goal of implementing mixed port function blocks to connect to the ROS framework. Work has started in March 2020 as planned. First investigations of existing code has been carried out and a development of a prototype has started.

• [1] Markus Klotzbücher, Herman Bruyninckx, microblx: a reflective, real-time safe, embedded function blockframework, Proceedings of the Real-Time Linux Workshop 2013
• [2] Markus Klotzbuecher et al., microblx repository, 2020, https://github.com/kmarkus/microblx
• [3] RobMoSys, Roles in the Ecosystem, 2019, Roles in the Ecosystem
• [4] RobMoSys, Mixed-port Component, 2019, Mixed-port component
• [5] [Technical requirements for RobMoSys compliant composition for microblx launch DSL](https://github.com/kmarkus/microblx/blob/cocorf/docs/dev/001-blockdiagram-composition.md)
• [6] [PID demo](https://github.com/kmarkus/microblx/tree/cocorf/examples/usc/pid)
• [7] [COCORF composition extension announcement](https://discourse.robmosys.eu/t/cocorf-draft-concept-for-microblx-composition-extensions/259)
• [8] https://robmosys.eu/user-stories/
• [9] https://robmosys.eu/wiki/general_principles:user_stories
• [10] https://wiki.servicerobotik-ulm.de/how-tos:documentation-datasheet:start
• [11] https://microblx.readthedocs.io/en/latest/block_index.html