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.

[erlingrj]

Update

After more consideration I think that we should stick with two attributes and have a type field to signify which NetworkChannel we use.

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

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

// 3. Specify also the address
@interface(type="TcpIp", address="127.0.0.1")
fed = new MyFederate()

// 4. Specify several channels 
@interface(type="TcpIp", address="127.0.0.1")
@interface(type="CoAP", address="127.0.0.1")
fed = new MyFederate()

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

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

// 7. Provide your own channel.
@interface(type="Custom", 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
@link(type="TcpIp")
fed1.out -> fed2.in

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

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

@interface(type="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
@link(type="TcpIp", server_port=42)
feds_out.out -> feds_in.in

// 5. Multi-connection, all individual connections share the same channel option
@link(type="TcpIp", server_port=42)
fed1.out, fed2.out -> fed3.in, fed4.in

[erlingrj]

@LasseRosenow any comments on using the attribute names interface and link?

[LasseRosenow]

Sounds good to me. I think it is a sane level of detail.

Regarding the naming I think it is fine, but I have some worries that people might be confused when reading interface because of common OOP patterns.

Maybe call it NetInterface and NetLink?

But not a strong opinion, if you think within lingua-franca this is already clear enough then just go for it!

[erlingrj]

Then I would prefer network_interface and network_link.

[erlingrj]

Update after last meeting:

1. We need an additional way of differentiating multiple identical interfaces of the same federate. Current proposal is adding a name parameter:

@interface(name="if0", type="TcpIp", address="192.168.0.1")
@interface(name="if1", type="TcpIp", address="10.10.0.1")
f = new Fed()

When connecting such a federate we reference the interface name

@link(left_if="if1", right_if="if0", server_side="right", server_port=10234)
f.out -> other.in

I think for clarity we should always require that the interfaces have a name parameter. But we don't have to specify left_if and right_if unless there are multiple interfaces available at the federates.

[erlingrj]

Thanks for adding this. I think the former proposal looks better/cleaner. I think it is also related to only being lower-case. So it is not so fundamental. I think you are right that there are some clear advantages to having the lanugageserver do instant validation on the attributes and not have to compile the program to get errors.

I modified your proposal a little. I think we can rename TcpIp to just tcp. Can we call it just coap and provide the underlying protocol (currently only UDP) as a parameter?

@interface:tcp(name="if1, address="192.168.1.1")
@interface:coap(name="if2, address="192.168.1.1")
@interface:uart(name="uart1", index=1)
@interface:custom(name="MyInterface", args="1")
f = new Fed()

Another alternative is:

@interface_tcp(name="if1, address="192.168.1.1")
@interface_coap(name="if2, address="192.168.1.1")
f = new Fed()

[LasseRosenow]

It is possible to have the transport protocol as an argument, but we should default to udp for coap. I don't so much see the use-case for coap on tcp right now, but of course I can just add it for now anyways :)

[LasseRosenow]

I think I agree that using the highest layer is enough. Tcp is of course over IP => no need to write that down and Coap is usually udp_ip.

For CoAP this might get more interesting though. People are working on running CoAP over UART and other serial protocols as well so in this case maybe it can be a problem in the future if we were to support these use cases one day.

[tanneberger]

I like this!

But you would enforce that the user must always specify an interface name? Otherwise, we could default the channel type (tcp, uart, coap), which works fine as long as you only have one of each type; if you have multiple, you need to set the name attribute.

@interface:tcp(address="192.168.1.1") expands into @interface:tcp(name="tcp", address="192.168.1.1", port=8000, ...)
@interface:coap(address="192.168.1.1") expands into @interface:tcp(name="coap", address="192.168.1.1", port=9000, ... )
@interface:uart(index=1) expands into @interface:uart(name="coap", index=1, baud=9200, ... )

[erlingrj]

What you propose is what is currently implemented (only that the default starting port number is 1024)

[tanneberger]

@erlingrj Another thought:

I would suggest that we actually introduce the @lf-component::type() syntax properly, because then we can annotate other lf-objects like reactions later.

@reaction::pretvm(wcet=10msec)
reaction (t) {= ... =}

[erlingrj]

Yes, this syntax would work (double colon) and it does look nicer