Skip to content

Blackboard

Now that our robot Larry can reliably drive from A to B, we want to tweak the hardware and increase the update rate of our cyclic sensor data. For example, we might decide that only sending out the ultrasonic sensor distance every 100 ms might no longer be sufficient. Similarly, a user might want to have the capability to configure the battery threshold at which Larry raises a low-battery alarm.

As systems grow more complex, they often accumulate thousands of individual configuration settings such as these. Some are shared between participants, others are participant-specific. With hundreds of participants in play, managing the configuration efficiently becomes critical.

A naïve approach would be to use publish-subscribe: where one participant manages the configuration and publishes updates to all subscribing participants, but this can quickly turn into a memory bottleneck. Consider a 1 MB configuration shared with 1000 participants. Since iceoryx2 always pre-allocates memory for the worst case, it must reserve 1001 MB of memory - one copy for the publisher and one potential copy for each subscriber. Apart from the memory waste, there is also the risk of configuration inconsistencies.

The solution is the blackboard messaging pattern: a key-value repository in shared memory. Each participant can access exactly the entries it needs, such as the ultrasonic sensor’s update rate. Any shared-memory-compatible and trivially-copyable type, can be stored in the blackboard.

Let’s implement an example where a user app can configure the sensor update rate. A higher rate means Larry reacts to obstacles faster and can drive faster.

Writer

As always, we start by creating a node:

var Node := TNodeBuilder.New
  .Create(TServiceType.Ipc)
  .Value;

With the blackboard pattern, all key-value pairs must be defined when the service is created. Unlike publish-subscribe, you cannot announce a key without providing a value. That means exactly one participant is responsible for creating the service and initializing default values. All other participants may open the service later.

We now create a blackboard with two settings:

  • the update rate in milliseconds, and
  • the battery threshold for triggering the low-battery alarm.

For keys we use the TStaticString type. Currently, only Rust, C++ and Delphi can share the TStaticString in-memory. If the blackboard is also to be used in C or Python, integers can be used instead.

type
  T50Bytes = array [0..49] of Byte;

type
  TKeyType = TStaticString<T50Bytes>;

var BatteryKey, UsSensorKey: TKeyType;
var Ok := BatteryKey.Init('battery_threshold')
  and UsSensorKey.InitUtf8('ultra_sonic_sensor_update_rate_in_ms');
if (not Ok) then
begin
  WriteLn('Blackboard keys could not be created.')
  Halt(-1);
end;

var Service := Node
  .ServiceBuilder(TServiceName.Create('global_config').Value)
  .BlackboardCreator<TKeyType>
  // low battery warning when load is below 25%
  .Add<Single>(BatteryKey, 0.25)
  // // default ultrasonic update rate = 100 ms
  .Add<UInt32>(UsSensorKey, 100)
  .Create
  .Value;

Note

The declaration of TKeyType may seem a bit confusing. See Delphi Topics for an explanation ot static strings.

Note

Also note the Init and InitUtf8 methods of TStaticString. Many Iceoryx2 API's related to strings offer both a 16-bit Unicode version (without suffix) and 8-bit UTF-8 version (with an Utf8) suffix. Whenever possible, you should use the UTF-8 version since this bypasses UTF-8 conversion and is this more efficient (both in terms of speed and memory fragmentation).

Now we create a writer port to update values:

var Writer := Service
  .WriterBuilder
  .Create
  .Value;

To update an entry, we first obtain a handle for it. The handle is type-checked, so if you provide the wrong type, you’ll get an error instead of silently corrupting the data.

var BatteryThresholdHandle := Writer
  .Entry<Single>(BatteryKey)
  .Value;

var UpdateRateHandle := Writer
  .Entry<UInt32>(UsSensorKey)
  .Value;

In the event loop, we periodically check for user input and update entries as needed:

while (Node.Wait(TDuration.FromMillis(100)).HasValue) do
begin
  var NewBatteryThreshold := GetBatteryThreshold;
  if (NewBatteryThreshold.HasValue) then
    // small value -> simple copy API
    BatteryThresholdHandle.UpdateWithCopy(NewBatteryThreshold.Value);

  var NewUpdateRate := GetUpdateRate;
  if (NewUpdateRate.HasValue) then
    UpdateRateHandle.UpdateWithCopy(NewUpdateRate.Value);
end;

Reader

On the subscriber side, we reuse the node setup from the publish-subscribe example and skip to opening the blackboard service:

var Service := Node
  .ServiceBuilder(TServiceName.Create('global_config').Value)
  .BlackboardOpener<TKeyType>
  .Open
  .Value;

And create a reader port:

var Reader := Service
  .ReaderBuilder
  .Create
  .Value;

We’re interested in the ultra_sonic_sensor_update_rate_in_ms. We obtain a handle that always points to the latest value:

var UsSensorKey: TKeyType;
UsSensorKey.InitUtf8('ultra_sonic_sensor_update_rate_in_ms');
var UpdateRateHandle := Reader
  .Entry<UInt32>(UsSensorKey)
  .Value

The sensor loop looks almost identical to our original publisher code, except that the update interval now comes from the global configuration:

while (Node.Wait(TDuration.FromMillis(
  UpdateRateHandle.Get.Value)).HasValue) do
begin
  var Sample := Publisher.LoanUninit.Value;

  var Distance: TDistance;
  Distance.DistanceInMeters := GetUltraSonicSensorDistance;
  Distance.SomeOtherProperty := 42;

  var InitializedSample := Sample.WritePayload(Distance);
  InitializedSample.Send.Value;
end;