Network Wrapper Server/Client Architecture

[drdanz]

This is currently a work in progress, feel free to add suggestions below.

Architecture Description

A device driver should derive from the abstract class yarp::dev::DeviceDriver. This interface contains methods common to all device drivers, such as open and close. Additionally a device driver should implement a selection of other interfaces that capture what it shares with other families of devices. For example a camera might implement yarp:dev::IFrameGrabber (a "raw" interface to the raw data) and/or yarp::dev::IFrameGrabberImage (a higher-level source of images).

Even if a device is normally opened as a plugin through the PolyDriver class, and the process instantiating the device driver locally does not know exactly what interfaces are implemented by the device, the process is still able to access to these interfaces by calling the view<T>() template method.

YARP Network Wrapper Server/Client architecture extends this functionalities to a remote device.

A "Network Wrapper Client" (NWC) is a device driver (i.e. derived from the yarp::dev::DeviceDriver class), and implements the same interfaces that a normal device would implement, but instead of being connected to a physical device, it is connected to a "Network Wrapper Server" (NWS), or equivalent for different middlewares.
A "Network Wrapper Server" (NWS) is a very thin layer that is attached (using the IWrapper::attach() method), and that should not have any logic inside, besides forwarding the interfaces to the client.
In this way, it is possible to develop an application that can work indifferently with a local or with a remote device, without any need to change the code of the application, but just adjusting a few parameters.

NWC and NWS are tightly coupled, and communicate using some protocol (which does not necessarily imply that YARP is used underneath, in the future there might be NWC and NWS couples using ROS or some other protocol to communicate).
NWS and NWC can be replaced by something else that uses the exact same protocol.

Historical Notes and Rationale

The following sections are supposed to give a rationale to the changes that are currently happening in the backstage.

YARP and ROS wrappers

In the past, network wrappers were for YARP only.
Recently, with the introduction of YARP-ROS compatibility layer, wrappers started implementing also the compatibility with the ROS middleware, with tons of if and switch cases inside the code. Obviously, this doesn't scale to other middlewares.

There is no limit to how many wrappers can be attached to a device. We are therefore currently working to split the wrappers in two separate wrappers (one for YARP and one for ROS) that can be attached to the same device. Unfortunately this has the limitation that only one of them can be launched using yarpdev, and in order to use both of them contemporarily, it is necessary to use yarprobotinterface. We are currently considering whether to modify yarpdev to support attaching multiple wrappers.

Naming

In the past (and at the time of writing), NWS have often been called including one or more of these terms:

• Wrapper
• Network Wrapper
• Server

NWC have been called including one or more of these terms in their names:

• Client
• Remote

The server and client nomenclature was not always the same, therefore it was not always immediate to understand which client should be connected to a server.

Moreover the name "server" is used also for servers that are not network wrappers, and the name "wrapper" is used also for devices that do not implement a client/server architecture (e.g. calibrators).

After several discussions we came out with this new nomenclature, that should avoid any ambiguity

• Network Wrapper Client (NWC)
• Network Wrapper Server (NWS)

We also decided that the couples of NWC and NWS should share a part of the name, so that it is easy to understand which devices can be connected.

Devices that are actually servers (i.e. servers that are devices, so that they can be started from yarprobotinterface) will not change their name.

We also decided to include in the name the middleware used underneath (even for YARP).

Logic inside the wrappers

In the past (and at the time of writing), a few wrappers had "logic" inside. This means that using a device locally it is different, compared to using it remotely. This also means that a few wrappers, in order to avoid this differences, had to implement the same interfaces of the device wrapped.
In order to make things as small and clear as possible, network wrappers should not have any logic inside, and instead a separate wrapper (note: not a network wrapper here) should be created, and the NWS should be attached to this device instead of to the actual device.
NWS and NWC using a transport that is different from YARP, can require some conversion in order to match with the standards used by the middleware underneath. This kind of conversion is acceptable

Definition of the protocol

Historically, the protocol used in YARP NWC and NWS was defined inside the code. This is not recommended, since it requires for that the server and client are kept in sync. For more recent devices, the definition of the protocol was moved to a thrift file, allowing to modify it in just one place.

Recommendation

Naming convention

The name of the device consists of 3 parts, separated by a _ character:

• A "significative" common part shared by both devices (camelCase, with the first word lowercase)
• nwc or nws.
• The name of the middleware (lowercase) (yarp, ros, etc.)

For example:

NWS	NWC
controlBoard_nws_yarp	controlBoard_nwc_yarp
multipleAnalogSensor_nws_yarp	multipleAnalogSensor_nwc_yarp

Directories

NWC, NWS and protocol should be in the same directory

Definition of the protocol

Using Thrift is currently the recommended way to do define the protocol between NWC and NWS

Logic inside

NWC and NWS should not have any logic inside, besides the one required to replicate the interfaces remotely. Any logic should be moved to a different device.
Logic in NWS and NWC using a transport that is different from YARP is acceptable in order to match the data with what is expected from the middleware used underneath. This means that any conversion that is performed by the NVS must be matched by an inverse conversion on the NVC.

---

Date	Edit
2021-01-08	Changed field separator from - to _
2021-01-11	Added exception to not having logic inside for NVS/NVC using different middlewares
2021-05-26	NWS/NWC can be replaced by "equivalent" using the same protocol, minor fixes

[PeterBowman]

This is great news. I'd just add that we (roboticslab-uc3m) never adopted the XML schema as required by yarprobotinterface, therefore we have our own .ini-based set of configuration files and resort to either using yarpdev or our own device launchers. I'm pointing this out because of:

Unfortunately this has the limitation that only one of them can be launched using yarpdev, and in order to use both of them contemporarily, it is necessary to use yarprobotinterface. We are currently considering whether to modify yarpdev to support attaching multiple wrappers.

Also, is deferred attach now the preferred way for communicating a NWS and its subdevice? So far we are vastly depending on the other method, i.e. sequentially opening subdevices (yarpdev knows how to bind both devices via yarp_prepare_plugin(... EXTRA_CONFIG WRAPPER=...))). Unless I'm wrong I also presume this method is somewhat limiting in that it only allows one wrapper-one subdevice (hence the above quote and my +1 for the yarpdev modification). Some network wrappers such as controlboardwrapper2 allow either of both solutions, is this aimed to be preserved?

[jgvictores]

+1 to keeping yarpdev.

A first step towards promoting yarprobotinterface would be to improve http://www.yarp.it/git-master/yarprobotinterface.html (currently empty; while the yarpdev counterpart http://www.yarp.it/git-master/yarpdev.html is nicely documented). In any case, migration from all our .ini to .xml will be quite titanic 😨 so b/w compat is highly appreciated.

PS: The whole nwc/nws renaming scheme is excellent!!

[drdanz]

Just to clarify, yarpdev is not going to be deprecated, and it will work normally without any change.
The only problem is that at the moment wrappers use both with yarp and ros at the same time, and the new architecture specification will not allow this. Therefore this should be done attaching 2 rws to the same subdevice, and yarpdev does not allow this at the moment.

[drdanz]

Also no wrappers currently available in YARP is going to disappear any time soon, they will probably be deprecated for a while, but you will still be able to use them while we find a solution.

[traversaro]

Something that I realized after a bit, is that the names:

• controlBoard-nws-yarp
• controlBoard-nwc-yarp

Only differ for a single character, and so they may be easily swapped to due human error. I don't think it is a big problem, but it could make sense to being a bit more explicit and have:

• controlBoard-nwServer-yarp
• controlBoard-nwClient-yarp

?

[diegoferigo]

I was thinking the same, it could be confusing and requires some mental parsing effort every time you read the name.

[drdanz]

I also considered this, but I think that this is a kind of one-character-error that you notice immediately, since nothing will work in your setup, it is not the kind of issue that you will spend hours to debug, therefore the "short" version sounds good to me.
What do other people think?

[traversaro]

I am not sure about this, as it is a device invocation problem, as a starter it is a runtime problem, not a compile time one, so I am afraid that it would be possible that you write the code or the configuration files that uses the wrong one even days before you actually try to run it, so understanding which one you did wrong may not be trivial.

[drdanz]

@randaz81, @elandini84 what do you think about this point?

[diegoferigo]

This is really nice, I always thought that the overall situation of network client / servers was a bit confusing and when I had to develop a big application with many devices I remember it took a while to understand where to put what and what to expose. I'm glad to see that the separation we obtained is compatible with what discussed here (cc @Yeshasvitvs @lrapetti).

I'm also happy to see that the usage of the thrift protocol is now recommended. A shiver runs up my spine every time I see code that reads raw Bottles 😱

The only drawback we found in our day-to-day work with thrift is the interfacing with Simulink and our wb-toolbox. Unfortunately there's no simple way to have a single block that reads the wire serialization of a generic thrift. In other words, for every thrift message, a new custom block has to be developed. This is something we have to keep in mind @robotology/iit-dynamic-interaction-control.

[drdanz]

I don't know much about simulink and wb-toolbox, but we might investigate if it is possible to do this automatically, generating some extra code from the thrift file.

[PeterBowman]

On a side note, let's take controlboardwrapper2 (server) and remote_controlboard (client) which communicate with each other through ports that conform to the following suffix naming scheme:

server	client
/rpc:o	/rpc:i
/command:i	/command:o
/stateExt:o	/stateExt:i

Command and state ports are one-way channels. Since RPC communication entails both input/output operations (request+reply), would it make sense to rename /rpc:o to /rpc:s and /rpc:i to /rpc:c?

[drdanz]

This makes sense to me, but this convention is used in several other places, and it does not really have any impact for this specification, therefore I'd discuss this somewhere else.

[drdanz]

After some testing, we noticed that the - is causing issues with the current yarp-plugin stuff.
Since we don't want to make changes to this part in order to implement this architecture, we decided to change the - to _, i.e. controlBoard_nws_yarp.

[drdanz]

About the not having logic part, I realized that other middleware could use different standards, measure units, etc.
I think it is reasonable to assume that there could be some logic inside, in order to match the standard of the transport being used.

For example, YARP uses degrees, but ROS uses radiants, therefore a nvs using ROS as transport should convert data to radians and an nwc should convert data to degrees.