2 symbiosis in the viviverse symbiosis in the viviverse.…2 symbiosis in the viviverse 4 2...

Crossing horizons takes a ship

2 Symbiosis in the

ViViVerse Public Specification.

January 2015 by Hansjoerg Petschko

2 Symbiosis in the ViViVerse

2

Contents

1 Release History and Notes ................................................................................................................................................ 3

1.1.1 History ......................................................................................................................................................................... 3

1.1.2 Notes ........................................................................................................................................................................... 3

2 Motivation ............................................................................................................................................................................... 4

2.1 A simple control loop: Thermostat ................................................................ Error! Bookmark not defined.

2.2 Component Sharing and Auto Detection ................................................... Error! Bookmark not defined.

3 Family symbiosis ................................................................................................................................................................... 6

3.1 Families ........................................................................................................................................................................... 6

3.2 Donors and Acceptors ............................................................................................................................................... 7

3.3 Biotics .............................................................................................................................................................................. 8

3.3.1 Command sets ......................................................................................................................................................... 8

3.3.2 Metabolics ................................................................................................................................................................. 9

3.3.3 Genes........................................................................................................................................................................ 10

3.3.4 Choosing the right biotic type ........................................................................................................................ 11

4 The Agora ............................................................................................................................................................................. 12

5 Donor queries ..................................................................................................................................................................... 13

5.1 Synchronous queries............................................................................................................................................... 13

5.2 Asynchronous queries ............................................................................................................................................ 13

5.3 Ectoviv queries .......................................................................................................................................................... 13

6 Symbioses and Environment ......................................................................................................................................... 14

7 Companions ........................................................................................................................................................................ 15

8 Ectoviv Symbiosis .............................................................................................................................................................. 16

8.1 Dendrons ..................................................................................................................................................................... 16

8.2 The Whisper protocol ............................................................................................................................................. 16

8.3 Pheromones and Market Places ......................................................................................................................... 16


3

1 Release History and Notes

1.1.1 History

December 2014: Separation from vivid introduction

January 2015: First official version

November 2016: Name changes (symbiosis replaces business)

1.1.2 Notes

It is recommended to read the document 1 Vivids and Organelles before reading this document.


4

2 Motivation

Figure 1 The ViViVerse component diagram of the Thermostat application with integrated HMI


5

Figure 2 The ViViVerse Component Diagram of the Thermostat application with external HMI


6

3 Family symbiosis

3.1 Families

When a component (e.g. an organelle) provides functionality for other components, these features or

services will usually have a common context. Think of the object which implements the control loop in

the PosCtrl application (the Ego). The application shall have a user interface (the Visage) which, in the

simplest case, shall display the deviation from the default track and give the user the possibility to start

and stop the control loop. The Ego should thus provide a notification whenever the deviation changes

and a way to change the control loop state. These features clearly belong together and could be

combined in a feature set. In the VVV the feature sets are called families.

Figure 3 The family symbol

Whenever organelles interact with each other, they do so by first looking for members of the family which

provides what they need and then getting a link to the family interface of the organelle selected from

the available family members. It is therefore seemly to say, that the backbone of the symbiosis in the

VVV is the family.

The services provided by the family are described in a family description1. The family description contains

the unique family name and the unique family guid. The name uses uppercase letters for separating

words, like for the family PositionSensor3D. The description also contains a list of the features provided by

the family. We will learn more about this in one of the next chapters.

If an organelle provides more than one feature set, like e.g. a weather station, which measures air

temperature, air pressure and humidity, it can declare itself a member of more than one family - in our

case TemperatureSensor, PressureSensor and HumiditySensor. In fact, it is far better to do it like that, than

found the compound family WeatherStation, because this way it is possible that other organelles, which

are looking for a temperature sensor only, can still find and be able to make use of the organelle.

Families can be derived from each other, providing the possibility of increasing specialisation. Derivation

is indicated in the family name string by an underscore between the base and the derived family:

Base_Derived. We have already stumbled across the family PositionSensor3D_GNSS, which adds GNSS specific

functionality to the generic family of the 3D position sensors. While it is possible to indicate derivation

in the names, it is not possible to do so in the family guids. Because of this, a derived family provides

information about the family it is derived from. Deriving from more than one family, by this aggregating

functionality into one family, is not possible, but chained derivation is: Base_Dervied1_Derived2. For

1 In other contexts, this is called a contract (web services) or a profile (Bluetooth)


7

example, manufacturers could add functionality to the GNSS receivers, which is specific only to their

products.

The family description only provides limited functionality for ‘browsing’ through the functionality of the

family and for discovering at runtime, what the family can do. With one exception, which will be described

in chapter Error! Reference source not found., there is no meta information, neither for machine nor for h

uman interpretation.

3.2 Donors and Acceptors

We will refer to the families and those who declare themselves members of these families – and therefore

must implement the promised functionality - as donors. Those who use the services of the donors will be

referred to as acceptors.

Figure 4 The icons for donors and acceptors

Of course, any donor can at the same time be the acceptor of other donors and vice versa. For example,

the Ego in the PosCtrl application uses most of the other organelles for the control loop while itself

providing functionality to the Visage.

Figure 5 The Ego as acceptor and donor


8

3.3 Biotics

In the previous chapter, we used the term ‘family interface’. Thinking of the same term in programming,

where it is used for a set of function pointers, this should not lead you to the conclusion, that families

can only provide callable functions. In fact, a family can provide three different types of services, which

we call biotics in the VVV.

Figure 6 The icon for biotics

3.3.1 Command sets

Command sets consist of a set of synchronous and asynchronous commands. Each family can only have

one command set and each command set can have up to 65536 commands2. This biotic basically is the

sort of interface - made up of function pointers - which we mentioned above.

Figure 7 The icon for command sets

Synchronous commands block the caller while they are executed. When the donor is part of the same

vivid as the acceptor (endoviv symbiosis), they are implemented as direct function calls. In this case, there

are no timeouts. When the donor and acceptor belong to different vivids (ectoviv symbiosis),

(de)serialisation and message sending is involved and the execution confirmation, together with the

results, is expected within a certain time.

Asynchronous commands return immediately and the acceptor is notified about the execution

completion. If wanted, the caller receives a control structure which can be used for aborting commands,

getting intermediate results like progress percentage values and getting final results. With ectoviv

symbiosis, the command call returns immediately before the donor has acknowledged the command

reception. If the acknowledge does not arrive in time, the command is reported to the acceptor as having

failed.

With asynchronous commands, everything can be done that the other symbiosis items can do, but in a

far more flexible way. This flexibility though comes at the price of a larger programming effort for the

family implementation. For example, metabolics can also be provided using asynchronous commands,

which makes sense if complex filter criteria than a metabolic provides shall be applied. But in doing so,

the programmers have to implement the subscriber management and delivery mechanisms themselves,

instead of using the ones provided by the framework.

2 For remote procedure calls, the command ID is serialised into a 16-bit integer, hence the limitation


9

3.3.2 Metabolics

Metabolics are values of interest to others that frequently change, often triggered by real world events,

hence their name. Metabolics can be retrieved in a single shot or subscribed on an ‘on change’ or on a

time basis. A family can provide up to 65536 metabolics, each of them counting as a separate biotic.

Figure 8 The icon for metabolics

Metabolics are read only values by nature. They can only be altered indirectly via the input values used

for determining them.

Any type (plain value, structure or class) can be used as a metabolic, with only an assignment operator,

a validity check and a string conversion being required. Complex types may also need to provide

serialisation and deserialisation for ectoviv symbiosis. In case of endoviv symbiosis, the delivery of the

changed values is either done synchronously or asynchronously – depending on the subscription. Ectoviv

symbiosis requires message sending, which is always done asynchronously.

/***************************************************************************************************************************************\

Class:

position_3d

----------------------------------------------------------------------------------------------------------------------------------------

Description:

Holds the three coordinates of a 3D position together with the time when they were measured.

\***************************************************************************************************************************************/

class position_3d : public point_3d

{

// construction, destruction

public:

position_3d( void );

position_3d(

length easting,

length northing,

length height,

tempus measuring_time );

// operations

public:

void set_to_defaults( void );

wstring& to_string( wstring& value ) const;

// data members

public:

tempus measuring_time; // the measurement time (might be provided by the sensor or by the computer)

}; // position_3d

typedef metabolic<position_3d, position_3d&> mb_position_3d_t;

Code example 1 Declaration of the position metabolic of the PositionSensor3D family

The C++ class, which implements the family member, inherits the metabolic when deriving from

family_position_sensor_3d and just needs to set the metabolic to the new value. The delivery to the

subscribers is done by the VVV.

mb_position_3d_.set( new_pos );

Code example 2 Setting the metabolic

The subscriber must implement the function on_metabolic_delivery of the acceptor interface. It must

compare the delivered metabolic with its list of subscribed metabolics and then retrieve the appropriate

value.

/***************************************************************************************************************************************\

Function:

pos_ctrl_impl::on_mb_delivery

----------------------------------------------------------------------------------------------------------------------------------------

Description:


10

Is called by the metabolics to which we subscribed whenever the value changes.

----------------------------------------------------------------------------------------------------------------------------------------

Parameters:

deli_mb [i] the mb

Return Value:

\***************************************************************************************************************************************/

void pos_ctrl_impl::on_mb_delivery( delivered_mb& deli_mb )

{

// use a shortcut to the mb base

metabolic_base* mb = deli_mb.get_metabolic();

// if the delivered metabolic comes from the position sensor

if ( portfolio_[pos3d1_burei].is_this_metabolic( pos3d_mbpos_buiti, mb ) )

{

// get the new measurement

deli_mb.get( first_position_world_ );

// trigger a new deviation calculation

calculation_start_event_.set();

}

// if the delivered metabolic comes from …

else if ( … )

{

}

} // pos_ctrl_impl::on_mb_delivery

Code example 3 Metabolic delivery on the acceptor side

Once the new value has been retrieved, the subscriber should return as quickly as possible. The reason

for this is, that in the synchronous endoviv case the delivery is most likely done from within the thread

which receives the input from the physical sensor or which does the calculations that yield the new value

and thus should not be blocked.

3.3.3 Genes

Genes are values which define the current state or the behaviour of the family member. Genes can be

retrieved or changed and they can be locked. Genes can also be subscribed. The subscriber can be

notified when the gene value or when the lock state changes.

Figure 9 The icon for genes

Genes can be read/write or read only. In the latter case, only the donor can change them. Read only

properties cannot be locked.

As with metabolics, any type can be used as a gene and the same functionality is required.

/***************************************************************************************************************************************\

Structure:

dimensions

----------------------------------------------------------------------------------------------------------------------------------------

Description:

Contains the machine coordinates of some important points on the machine.

\***************************************************************************************************************************************/

struct dimensions

{

// construction, destruction

dimensions( void );

// operations

void set_to_defaults( void );

wstring& to_string( wstring& value ) const;

// data members

point_3d meas_point_mach, // [maco] the coordinates of the position measurement point

steering_point_mach; // [maco] the coordinates of the deviation determination point

}; // struct dimensions

typedef gene<dimensions> prp_dim_t;

Code example 4 Declaration of the dimensions-gene of the PosCtrl family

Providing a gene requires a little bit more work than providing a metabolic. The C++ class, which imple-

ments the donor, must contain an instance of the underlying type and link it to the gene in its constructor.


11

In the default case, changed gene values will be written directly into the donor’s instance. If the donor

wants to be notified when the gene changes, it can implement the function family::on_gene_set.

The subscriber of the gene must implement the function on_gene_change of the acceptor interface.

3.3.4 Choosing the right biotic type

Choosing the appropriate type of biotic for the provided functionality is straightforward most of the time.

But there are cases in which the decision is hard to make. Here is a list of scenarios and decision criteria

to help you:

1) Read only genes and metabolics.

Metabolics are easier to implement. On the other hand, one could ask the philosophical

question whether e.g. the number of registered users should really be a metabolic and not

rather be a read-only gene.

2) Gene changes which trigger complex and long running actions at the owner.

Although there is a mechanism which notifies the owner of a gene when it has been changed

by an acceptor, you might think about using a read-only gene together with an asynchronous

command for changing the gene.

3) Metabolic subscriptions with more complex subscription options.

When subscribing to a metabolic, it is only possible to either take each new value or receive the

current value at certain time intervals. If better filtering shall be possible, use an asynchronous

command, which runs as long as the subscription is valid, and deliver the values via

intermediate results. Unsubscribing is done by cancelling the command.


12

4 The Agora

The agora is the core organelle which holds a registry of the endoviv and ectoviv donors.

Upon their synthesis, objects (the donors) which have family services to offer to others (the acceptors)

must register with the agora, upon dissolution they must unregister.

Donors and acceptors together are called symbionts.

Basically, it is a 4-dimensional array with each rank representing one dimension.

Acceptors can place donor queries into the agora, searching for objects which provide certain services.

The agora is an active object, in that it notifies acceptors, which have placed asynchronous queries, about

the registration or unregistration of matching donors.

The notifications are normally performed asynchronously.


13

5 Donor queries

When an acceptor needs services from another object, it fully or partially defines a holotaxon, by this

describing its needs and expectations, then places a query into the agora. The agora returns a set of

matching donors from which the acceptor selects the one(s) it wants to make symbiosis with.

Figure 10 The icon for donor queries

The holotaxon for a query for all real GNSS sensors in the system could look like this:

organelle_class__rebus/PositionSensor3D_GNSS//

The organelle class is defined in order to filter out simulators (which belong to the fantasmas) and the

species and identity are left empty.

If any real 3D position sensor would do, PositionSensor3D_GNSS could be replaced by

PositionSensor3D. By passing a search flag telling the agora that it should return also derived

families, this would also return e.g. theodolites.

5.1 Synchronous queries

Synchronous queries are not stored in the agora after they have run. They deliver only a momentary

snapshot of the registered donors.

5.2 Asynchronous queries

Asynchronous queries are stored in the agora until they are cancelled. Whenever a matching donor

registers or unregisters, the object which placed the query is notified.

5.3 Ectoviv queries

Ectoviv queries are not placed into the endoviv agora but into the agora of another vivid. They are the

most important (the other being pheromones) means to initiate ectoviv symbiosis, which is explained in

more detail in the next chapter.


14

6 Symbioses and Environment

For convenience, the VVV provides two classes which make it easier to implement symbioses between

organelles: symbiosis and environment.

The class symbiosis does the donor selection and biotics acquisitions for you, while the environment

basically is a fixed number set of symbiosis objects.

While you can let them completely handle the symbioses for you, you can have them also notify you

whenever a donor has been selected or has gone away.


15

7 Companions

If an organelle shall be used exclusively by another organelle, it can be synthesised as a companion

organelle.

In this case, the companion is synthesised while its princeps, the first in a band of equals, is synthesised

and it is dissolved together with its princeps. When companions do register with the agora, they do so

as ‘not publicly discoverable’ and thus cannot be discovered by others.


16

8 Ectoviv Symbiosis

In addition to be in symbioses with organelles within their own vivid (endoviv symbioses), organelles can

also symbiotise with organelles in other vivids. These symbioses are called ectoviv symbioses. Forming

symbiotic relationships between vivids and their organelles creates the ViViVerse.

An ectoviv symbiosis is initiated by placing a query into the agora of another vivid. To do this, it is

necessary to pass – together with the query - information about how to get in contact with the other

agora. The necessary information is the name of a Dendron.

8.1 Dendrons

The chaperone synthesises and organises dendrons, which are a kind of dynamic sub core organelles.

Their task is the exchange of messages between the vivid and its organelles and other vivids and their

organelles.

Dendrons use bridges for communication. Basically, each bridge should be capable of enabling ectoviv

VVV symbiosis, although experiments with CAN bus have displayed some limitations.

8.2 The Whisper protocol

The Whisper protocol is the VVV implementation of an RPC (remote procedure call) protocol and is used

for remote interaction. It is described in the document ‘3 The Whisper Protocol’.

8.3 Pheromones and Market Places

Donors can also register with the Agora of another vivid by using Pheromones. These are outbound

ectoviv queries handled by the agora of the Donor’s own vivid based on the configuration, thus no

programming is necessary to use them.

Figure 11 The icon of the pheromones

The use of Pheromones causes implicit ectoviv donor queries, because acceptors will find the ectoviv

donor in their agora even though they did not run an ectoviv query. Search flags used with the query can

filter out ectoviv donors.

Pheromones are mainly used to enable ectoviv symbiosis from within a private network. Since mobile

devices cannot be reached from outside the network provider’s net, they register their services at a server

where they can be found by others. These server instances of the VVV are called market places.

2 symbiosis in the viviverse symbiosis in the viviverse.…2 symbiosis in the viviverse 4 2...

Documents