Syntax for specifying network channel options

[erlingrj]

Let's settle on a syntax for specifying network channel properties for connections between federates. We add attributes in two places.

1. At the federate instance.
2. At connections between federates.

We must keep the possibility of banks of federates, multiport federates and arbitrary connection statements into mind. We should strive to have sane defaults such that it is possible to write programs without any attributes and they still work.

Federate instance attributes

For the federate instance we use attributes to express which NetworkChannels it supports, addresses and network interfaces.

// 1. No attribute, means TcpIp with automatic address assignment and 
fed = new MyFederate()

// 2. Specify only NetworkChannel
@TcpIp
fed = new MyFederate()

// 3. Specify also the address
@TcpIp(address=192.168.1.1)
fed = new MyFederate()

// 4. Specify several channels 
@TcpIp(address=192.168.1.1)
@UdpCoAP(address=192.168.1.2)
fed = new MyFederate()

// 5. Bank of federates. Specify address of first, the rest are inferred (previous + 1)
@TcpIp(address=192.168.1.1)
feds = new [3] MyFederate()

// 6. Bank of federates, specify all:
@TcpIp(addresses=[192.168.1.1, 132.134.231.3, 123.123.123.3])
feds = new [3] MyFederate()

// 7. Provide your own channel.
@UserDefined(name=MyNetworkChannel, args="provide arguments here")
fed = new MyFederate()

Federate connection parameters

// 1. No attribute, we will use the first NetworkChannel of fed1 and a corresponding with fed2 and select connection properties
fed1 = new MyFederate()
fed2 = new MyFederate()

fed1.out -> fed2.in

// 2. Specify only NetworkChannel
@TcpIp
fed1.out -> fed2.in

// 3. Specify also port, and that the TcpIp server is on the right hand side port.
@TcpIp(port=115, server=right)
fed1.out -> fed2.in

// 4. Bank of federates. Will have address .1, .2, and .3
@TcpIp(address=192.168.1.1)
feds_out = new [3] MyFederate()

@TcpIp(address=192.168.1.100)
feds_in = new [3] MyFederate()

// All channels will have the server on lhs and it will be on port 42
@TcpIp(port=42)
feds_out.out -> feds_in.in

// 5. Multi-connection, all individual connections share the same channel option
@TcpIp(port=43)
fed1.out, fed2.out -> fed3.in, fed4.in

Is there something crucial I am overlooking? We still have the problem when there are multiple network interfaces. Unfortunately, Zephyr does not provide a nice way to configure multiple interfaces directly from a config file, you must do this in the source code, I am not sure how this works for RIOT.

@LasseRosenow @tanneberger

[erlingrj]

The following comment was written by @LasseRosenow :

Unfortunately, Zephyr does not provide a nice way to configure multiple interfaces directly from a config file, you must do this in the source code

Is this a problem? We could generate this source code as well right? :)

(RIOT OS also does this in code as far as I know: https://doc.riot-os.org/group__net__gnrc__netif.html)

[erlingrj]

Yes, we could do that. We could add a "hook" for network setup which is code-generated.

[erlingrj]

The following comment was written by @LasseRosenow :

// 1. No attribute, means TcpIp with automatic address assignment and

I would say: 1. No attribute, means Platform default with automatic address assignment

Because some platforms might not even support TCP. Especially for constrained devices I personally consider CoAP a more natural default. But that is not a strong opinion. It is just a default after all

Or maybe we should allow to configure the defaultCHannel at the top of the program

[erlingrj]

Yes, agreed! Let's make it platform-specific. We can add a target parameter to override the platform default:

target uC {
  network-channel-default: CoapUdp
}

[erlingrj]

The following comment was written by @LasseRosenow :

I still have some issues with this:

// 4. Specify several channels 
@TcpIp(address=192.168.1.1)
@UdpCoAP(address=192.168.1.2)
fed = new MyFederate()

Here we give CoAP and TCP different IP Addresses. This is not necessary.
But it can still be useful to give mulitiple IP Addresses. So to make it more clear I update the code to 2 TcpIp endpoints:

// 4. Specify several channels 
@TcpIp(address=192.168.1.1)
@TcpIp(address=192.168.2.1)
fed = new MyFederate()

Here we have 2 different IP endpoints for the TcpIpChannel, this can be useful when for example one uses ethernet and the other one uses 6LoWPAN. (Thinking interfaces)

What is still missing here is that if we are using multiple interfaces, we will need some place to map addresses to interfaces on the board that we flash to. I think this should maybe be solved using environment variables?

So we could maybe generate something like:

IP_192_168_1_1_NETIF and the user must then specify what interface on the board this IP corresponds to (in the makefile for example)

But I find this is really easy to cause errors.
So I would propose to instead go back to actually naming interfaces:

@Ip(if=eth0, address=192.168.1.1) // ethernet
@Ip(if=eth1, address=192.168.2.1) // 6LoWPAN
fed1 = new MyFederate()

@Ip(if=eth0, address=192.168.1.1) // ethernet
fed2 = new MyFederate()

// fed1 has multiple interfaces => We must specify which to use for this connection
@TcpIp(if=eth0 port=115, server=right) 
fed1.out -> fed2.in

// fed2 only has one interface. => No need to specify
@TcpIp(port=115, server=right)
fed2.out -> fed1.in

To make this run on the corresponding boards the user only needs to specify the following environment variables:
FED1_ETH0 = 3 and FED1_ETH1=4 and maybe FED2_ETH0 = 3.
At least in RIOT network interfaces are represented using numbers. So in that case we need to assign the correct numbers.

[erlingrj]

Here we give CoAP and TCP different IP Addresses. This is not necessary. But it can still be useful to give mulitiple IP Addresses. So to make it more clear I update the code to 2 TcpIp endpoints:

Thanks, for the thorough feedback. So, when using a single network interface, we should have a single IP address for this interface and use different port numbers if we want different channels?

But I find this is really easy to cause errors. So I would propose to instead go back to actually naming interfaces:

@Ip(if=eth0, address=192.168.1.1) // ethernet
@Ip(if=eth1, address=192.168.2.1) // 6LoWPAN
fed1 = new MyFederate()

This does make sense. I think we need to code-generate a struct, or rather array of structs, to carry this information. Is the notion of a network interface IP-specific. I.e. does it make sense to specify this for an I2C, SPI or BLE channel? I think no? Unless we are running IP over those physical interfaces.

But if we are dealing with several network interfaces we need a mapping between eth0 and a particular MCU ethernet peripheral. Is eth0 an arbitrary user-defined name, or should it match a label defined in e.g. the devicetree (in the case of Zephyr) or some similar device config in RIOT?

@ip(if=eth0, address=192.168.1.1) // ethernet
fed2 = new MyFederate()

Here I see you introduce @ip, but is it really necessary to add another level of hierarchy here? (that TcpIp and UdpCoap are both derived from Ip). Should we instead just do @tcpip and @CoapUdp?

To make this run on the corresponding boards the user only needs to specify the following environment variables: FED1_ETH0 = 3 and FED1_ETH1=4 and maybe FED2_ETH0 = 3. At least in RIOT network interfaces are represented using numbers. So in that case we need to assign the correct numbers.

This is a partial solution to the problem of mapping user-defined interface-names (e.g. @TcpIp(if=eth0)) to hardware. But it seems that it only solves the problem partially. By having the user specify: FED1_ETH0=3, they connect LF-netif's to RIOT-netif's. But there is still the missing link from RIOT-netif's to the actual memory-mapped devices on the MCU. How are the RIOT netif's configured in the first place? How are they named? Should we maybe make sure that the RIOT netif's are named correctly according to the annotations in the LF code? Initially we could require that the user configures the network interfaces correctly and in the future we could possibly code-generate for RIOT and Zephyr the code that does this.