EDDIE Project

Welcome to the EDDIE, part of the Oniro* Project, main git repository! Oniro is an Eclipse Foundation project focused on the development of a distributed open source operating system for consumer devices.

*Oniro is a trademark of Eclipse Foundation.

About

The EDDIE repository is home of a middleware in the Oniro Project to enable distributed intelligence on Oniro devices.

The objective of the EDDIE project is to design a middleware running on top of the operating system of the various Oniro devices. Capable of giving to the applications and services a global view on a unified pool of virtual resources that can be exploited for an efficient execution of any application or service required by the user.

Contributing

See the CONTRIBUTING.md file.

License

See the LICENSES subdirectory.

Security

See the SECURITY.md file.

EDDIE structure

The structure of the EDDIE project is vertically divided into layers and this division reflects the structure of the EDDIE repository.

While the communication and the virtualization layer are detailed below and already present in the EDDIE repository, an intelligent layer is planned, to enable reasoning and smart resource distribution across the EDDIE network. Currently, there is only a mocked version of this layer.

Lastly an application management layer is also planned, providing advanced functionalities for process management in both local and remote EDDIE nodes.

Layers

In the following paragraphs there is a more detailed description of the layers of EDDIE.

Communication Layer

The bottommost component of EDDIE is the communication layer: it is responsible for all the networking bits of EDDIE, from the creation and setup of the connection to the message dispatching to other nodes.

Every device that runs EDDIE has a server component, application logic that describes what capabilities (resources) that device has and answers to requests from other nodes.
Alongside the server element, a EDDIE device is equipped with a client component, allowing the device to communicate actively in the network, performing requests to other devices.

Additionally, one node in the EDDIE network is elected as Resource Directory (RD): a new EDDIE node that wants to connect to the network should post its resources description in the RD, while from the RD it can retrieve the descriptions of other nodes.

The communication layer exposes a list of APIs to the higher layers of EDDIE, allowing complex actions and queries to be executed in the EDDIE network.

Virtualization Layer

The Virtualization layer is responsible for the interaction between the EDDIE network (through the communication layer) and the single EDDIE-enabled application running on the device.

This layer is composed of two elements that are communicating through the IPC mechanism of d-bus:

• a receiver component that exposes its API on d-bus, allowing multiple applications to interact with EDDIE at the same time. The API is composed of a single function PerformAction that models the action that the application wants to execute on the network, like changing or getting the status of a resource.
• a sender component is also present in the virtualization directory with the role of transmitting the requests generated by EDDIE-enabled application to the EDDIE service on the device.

Hardware Layer

The Hardware layer provides and interface between a physical device and its EDDIE counterparts.

It receives actuation requests coming both from the local and remotes EDDIE nodes and returns the current configuration of the hardware in case of a GET request or modify the parameters as requested by a POST request.

This layer if composed of two parts:

• the topmost one is the interface exposed to the communication layer of EDDIE and encapsulates the hardware functionalities of the hardware exposing CoAP GET/POST/DELETE request handlers;
• the bottommost one is the one responsible for retrieving or modifying the parameters of a device while interacting with the drivers or the hardware directly.

Each modeled resource in EDDIE is tied with a JSON description of its default configuration, found in the asset/json/config directory, and a description of its capabilities also in the form of a JSON file, found in the asset/json/ontology.

The current descriptions of the capabilities is temporary, as we plan to add a more general ontology engine, to improve +the expressive power of the JSON representations and to allow a more robust mechanism to perform intelligent tasks.

Intelligence Layer

The Intelligence layer provides the facilities to perform decisions based on the requests received by the different nodes and the current available resources on the network; in particular, this layer receive the requests from the Virtualization layer, process them using a JSON dictionary that contains the instructions to carry out the task.

A valid request for the Intelligent layer is expressed in JSON format and is composed of 4 field:

1. action: specifies the overall goal to achieve with the request; possible values for this field are: "find", "get" and "actuate";
2. action_description: further details the request received; only used if action = actuate;
3. h_constraints: a list of constraints to filter the eligible resources that can complete the request;
4. o_functions: a list of objective functions, providing a ranking mechanism for the resources.

An example of an actuate request for the activation of an alarm with close to a person and silent can be seen below:

{
  "action" : "actuate",
  "action_description" : "alarm",
  "h_constraints" : [{ "type" : "eddie.r.alarm"}],
  "o_function" : [
    { "feature" : "person"},
    { "feature" : "silent"}]
}

Internally, at every new request, the engine will request all the available in the network; the engine will then apply all the constraints, filtering out the resources that do not comply with the requested capabilities; finally, all resources are ranked based on the objective functions.

The highest ranked resource will then be selected to carry out the application request; if the resource completes the task successfully, the result will be forwarded to the application; if some error happens, the engine will select another resource to complete the request, based again on the ranking. If there are no more resources, the engine will return an error.

As for the Hardware layer, this implementation of the Intelligence layer is temporary and will be updated when ontologies will be added to EDDIE

Examples

Examples on how to use the EDDIE APIs can be found in /linux/examples.

For more details, take a look at the doxygen API documentations.

Linux build instructions

Prerequisites

The following part of the document details how to install and configure all packages and libraries required to have a working copy of EDDIE.

libcoap

libcoap is a C implementation of the application-level protocol CoAP.
The version of libcoap currently used by EDDIE is version 4.3.0.

If libcoap is already installed in your system you can skip the following installation procedure.

libcoap itself requires some packages to correctly complete its installation procedure: they can be installed with the following commands:

$ (sudo) apt-get install autoconf -y
$ (sudo) apt-get install libtool -y

Then launch these commands to install libcoap in your machine:

$ git clone https://github.com/obgm/libcoap.git
$ cd libcoap
$ git checkout release-4.3.0
$ ./autogen.sh
$ ./configure --disable-documentation --disable-dtls
$ make
$ (sudo) make install
$ (sudo) ldconfig

For further details on libcoap have a look at the GitHub repository and at the official libcoap documentation page.

Glib

Installation instructions for Glib and its requirements can be found at the Glib installation page.

Build

• If you want to run EDDIE on your local machine build the CMake project:

$ mkdir build && cd build
$ cmake ..
$ make
$ (sudo) make install

• Then you can find some binaries in the build/linux/ subdirectory:

  • eddie-endpoint is used to test the EDDIE communication layer by initializing an EddieEndpoint for the CoAP communication and resource registration and discovery. In this executable a resource directory discovery request is sent and if a one is not found, a new resource directory is initialized. If --exampleres flag is set, the node will publish some example resources, and finally, the node will retrieve the available resources in the resource directory. Run eddie-endpoint --help for more information.
  • eddie-virt-server runs a VirtualizationReceiver which starts a DBus server and initializes an EddieEndpoint.
  • eddie-virt-client is an example of application side code that, using VirtualizationSender, runs a DBus client to communicate with the virtualization server side.

• If you want to build the Oniro Blueprint for the EDDIE project, and run on an Oniro supported target: follow the instructions in the EDDIE blueprint git repository.

Zephyr build instructions

Description

A device node provides its resources by means of CoAP resources. The Zephyr node will publish its resources into the resource directory on linux using CoAP protocol. After publishing the resource, the Zephyr node will run a CoAP server providing an endpoint specified by the published resource.

We tested both the resource publish and the CoAP server endpoint, in the following setups:

• Two QEMU instances with bridged networking, one QEMU running EDDIE on Zephyr and the other running an EDDIE endpoint on Oniro Linux
• An EDDIE Zephyr node on the Arduino Nano 33 BLE board connected via OpenThread to a Raspberry Pi OpenThread border router that runs an EDDIE endpoint.

Run on QEMU

If you want to have QEMU with networking, create one tap device for each QEMU instance (you can use a script provided in oe-core):

$ sudo oe-core/scripts/runQEMU-gen-tapdevs 1000 1000 2 tmp/sysroots-components/x86_64/QEMU-helper-native/usr/bin

Bridge tap devices so the QEMU instances can communicate with each other

$ sudo ip link add br0 type bridge
$ sudo ip link set br0 up
$ sudo ip addr add 2001:db8:0:1::100/64 dev br0
$ sudo ip link set tap0 master br0
$ sudo ip link set tap1 master br0

Assuming the linux node with EDDIE service is running on tap0 network interface, use the following command to run the Zephyr node on QEMU using the tap1 interface.

$ west build -b QEMU_x86 -t run --pristine  --    -DOVERLAY_CONFIG=overlay-e1000.conf  -DCONFIG_NET_CONFIG_MY_IPV6_ADDR=\"2001:db8:0:1::1\" -DCONFIG_ETH_QEMU_IFACE_NAME=\"tap1\"    -DCONFIG_ETH_QEMU_EXTRA_ARGS=\"mac=00:00:5e:00:53:01\"

Run on Arduino Nano 33 BLE

• Build with the OpenThread overlay

$ west build -b arduino_nano_33_ble --  -DOVERLAY_CONFIG=overlay-openthread.conf

• Flash the image into your arduino board using bossac
• Run the EDDIE Linux node on the Raspberry Pi board following the EDDIE blueprint instructions.
• Follow the transparent gateway documentation to connect the Arduino board to the Raspberry Pi via OpenThread.

The Zephyr node will be able to publish its resources to the Linux node.