User Tools

Site Tools


Proposal for network interface selection and configuration in the IoTivity stack

This is a proposal for handling network interfaces by the IoTivity resource stack. It was requested by the OIC OSWG as a means of understanding how network interfaces might be handled by IoTivity. It is not a requirement, but it may lead to requirements in this area.

Now that we have agreed that a single adapter type is appropriate for all socket IP network communication, the question has arisen about how to allow applications to configure network interfaces. For example,

  • Work with zero interface configuration in most cases.
  • Provide configuration flexibility when needed (uncommon).
    • Perform discovery on one network interface but not another.
    • Choose one network for connection to a server when two paths are available.
    • Use IPv4 on one network and IPv6 on another.

The technical proposal is structured in stages to emphasize the simplicity and flexibility it provides. Each stage includes the capability of the previous stages. The stages can be implemented in this order to provide ever more capability:

  1. Default stage (no application involvement)
  2. Selection stage(minimal application involvement)
  3. Configuration stage (maximum flexibility)

The proposal focuses on discovery, primarily the FindResource call in the C++ interface, since after a resource is found, the network interface to reach it is fully determined. The challenge is getting to it in the first place.

The written proposal covers these areas:

  • Description of Default state
  • Description of Selection stage
  • Description of Configuration stage
  • Implementation notes (to demonstrate the simplicity of the proposal)

Description of Default stage

The only visible aspect of interface handling at the default stageis one argument to FindResource and FindDevice. It replaces OCConnectivityType, and at the Default stage always takes the value 0. As in the current Connectivity Abstraction, the earlier forms of FindResource and FindDevice without the extra argument may also be available.

The meaning of the default value 0 is:

  • Send Multicast discovery messages on all network interfaces.
  • Send Multicast messages with both IPv6 and IPv4 addresses (IPv6 first, followed immediately by IPv4).

A heuristic in the receive path for both client and server recognizes subsequent received packets with the same request token differing only in address family (IPv6 vs. IPv4). The second one is rejected silently, so only the first (typically IPv6) is processed.

Thus, most applications and most IoTivity systems will operate with no interface configuration. For the few cases where this does not work, such as sending Multicast messages to inappropriate subnets, the Selection stage may be added.

Description of Selection stage

The Selection stage is a superset of the Default stage. Setting the additional FindResource argument (OCInterfaceMask) to zero still results in the default behavior. OCInterfaceMask is a bit mask, described below. Additionally, a 24 entry array of Interface Descriptors is maintained in the IoTivity network layer. In the Selection stage, the entries in the ID array are filled in by IoTivity to support specific uses and never change.

Interface Description (ID)

Each Interface Description contains the following information (and likely more):

  • Interface name (eth0, eth1, wlan0, etc.)
  • Interface enabled (set by scan at startup and explicit rescan)
  • file descriptor bound to this interface
  • IPv4 interface binding (IPv4 address)
  • IPv6 local address binding (which of several IPv6 addresses is bound this file descriptor)
  • IPv6 local address scope ID
  • IPv6 multicast address
    • Node local (loopback): 1
    • Link local: 2
    • Site local: 5
    • Global: 0xe
  • Multicast TTL (reasonable values for multicast address type)
  • GATT addressing info

Note that each ID contains both the IPv6 and IPv4 information for that interface. Note that the word 'local' is overloaded in network technology: when not prefaced by a modifier it means 'local rather than remote'.

Interface Description array

When IoTivity starts up it will fill in the ID array with the following values:

0 eth0 IPv4 local address, IPv6 link local address and multicast address, TTL 1
1 wlan0 IPv4 local address, IPv6 link local address and multicast address, TTL 1
2 gatt0 GATT over BLE (non-IP interface)
3 bt0 IPv6 over BLE (6LoWPAN), IPv6 site local address and multicast, TTL 5
4 15.4? IPv6 over 15.4 (6LoWPAN), IPv6 site local address and multicast, TTL 5
5 reserved future non-ethernet, non-wifi interface
6 reserved future non-ethernet, non-wifi interface
7 reserved future non-ethernet, non-wifi interface
8 eth0 IPv4 local address, IPv6 site local address and multicast address, TTL 5
9 wlan0 IPv4 local address, IPv6 site local address and multicast address, TTL 5
10 eth1 IPv4 local address, IPv6 link local address and multicast address, TTL 1
11 wlan1 IPv4 local address, IPv6 link local address and multicast address, TTL 1
12 eth1 IPv4 local address, IPv6 site local address and multicast address, TTL 5
13 wlan1 IPv4 local address, IPv6 site local address and multicast address, TTL 5
14-23 reserved tbd

Note that the actual contents of this table in the Selection stage is a subject for discussion based on use cases.


The bits in OCInterfaceMask correspond to the capabilities in the ID array. Specifically,

0 eth0 (link local)
1 wlan0 (link local)
2 gatt
3 6LoWPAN over BLE
4 6LoWPAN over 15.4
5-7 reserved
8 eth0 (site local)
9 wlan0 (site local)
10 eth1 (link local)
11 wlan1 (link local)
12 eth1 (site local)
13 wlan1 (site local)
14-23 reserved, tbd
24-28 reserved for modifier flags
29 use IPv4
30 use IPv6
31 reserved

Note that the first 24 bits correspond exactly to the respective entries in the ID array.

The Selection stage is entirely compatible with the Default stage because of these two rules:

  1. If no interface is selected (lower 24 bits zero), use socket default behavior, which multicasts (and receives) on all interfaces.
  2. If neither address family (IPv6, IPv4) is selected, use both with the filtering heuristic described in the Default stage.

At the Selection stage, there is one additional API function:

void SetServerInterfaceMask(OCInterfaceMask)

Just as OCInterface mask in FindResource and FindDevice controls client behavior, SetServerInterfaceMask controls receiving requests on a server. In fact, it also controls receiving responses on a client. Note that the default value (a zero OCInterfaceMask) provides behavior identical to reception behavior at the Default stage.

Description of Configuration stage

The Configuration stage contains the functionality of the first two stages, but it allows the array of Interface Descriptions to be changed. At the Configuration stage, the user can modify the ID array. The bits in OCInterfaceMask still correspond to the entries in the ID array, but the user can configure the ID array to suit a particular purpose. The ID array can be configured in two ways:

  1. A new API allows the ID array to be modified by the application.
  2. A file (interface.cfg) is read by IoTivity at startup to set the values of the ID array.

If the application programmer changes the ID array, it is the responsibility of the programmer to set the bits in OCInterfaceMask to match the new values of the ID array.

IoTivity at startup performs the following operations in order:

  1. Fill in the ID array with the values from the Selection stage.
  2. Read and apply the interface.cfg file to modify the ID array.

The application can then modify the ID array with the new IP, and changes apply immediately to new connections.

Both the interface.cfg file and the new API support these types of changes:

  • Modify an existing ID (change TTL, pick a specific Link Local address, etc.)
  • Replace an existing ID (change interface name, set all values, etc.)
  • Add a new ID in any of open array entries (14-23).

This ability to spell out the configuration allows an application to be configured to run in varying network environments without recompiling the client or server (as long as the require interfaces are supported by IoTivity.)

Implementation notes

All this flexibility might seem to create a development burden, but careful implementation can make the development time and code size quite small.

First, we can choose to stage development and release.

  1. The first release of IoTivity might include only the Default stage. It covers most cases, and is extremely easy to implement, since it doesn't involve the ID array and takes advantage of the natural behavior of IP sockets.
  2. A subsequent release might add the Selection stage. It covers almost all cases, and it only requires static setup of the ID array at IoTivity startup.
  3. Based on user feedback, we could choose when to provide the Configuration stage, which might be complicated by dynamic changes to the ID array.

For the Default stage, we should create a pair of sockets (IPv6 and IPv4) for each active interface. All of them should be added to the CoAP multicast group for the CoAP port (5683). (For DTLS we will need that many more sockets bound to the CoAP DTLS port (5684)). When an application requests a FindResource, we will iterate through all the available interfaces to send the multicast message. Two listening sockets (CoAP and CoAP DTLS) are sufficient.

Selection stage behavior is slightly more complex. As in the Default stage, we open a pair of sockets (IPv6 and IPv4) for each active entry in the ID array at startup, storing its file descriptor in the associated array element. When a FindResource request arrives, do one of two things:

  1. If the lower 24 bits of OCInterfaceMask are zero, send the request to all interfaces, as in Default stage.
  2. If non-zero, loop through the bits and use the file descriptor in the corresponding ID array entry to send the message. (Maybe only one bit will be set in a particular request.)

The Configuration stage can be quite a bit of code, but it doesn't need to be done right away.


This has been a somewhat detailed description of a needed addition to IoTivity. It is nearly invisible for most users and usages, and it provides varying stages of flexibility and capability to advanced users and usages. I hope it can be considered for immediate inclusion in our plans and work.

proposal_for_network_interface_management_in_iotivity_stack.txt · Last modified: 2015/03/27 18:53 by John Light