a hardware platform for software-driven functional ...argouml is a free software that is distributed...

www.visorsurf.eu Wednesday, December 20, 2017

Horizon 2020 Program (2014-2020)

FET-Open Novel ideas for radically new technologies

H2020-FETOPEN-2016-2017

A Hardware Platform for Software-driven Functional Metasurfaces

D2.1: Initial UML definition of the HSF programming interface and virtual functions1

Abstract: This document provides the initial Unified Modelling Language description

of the HyperSurface programming interface. It defines the basic programming

methods that the HyperSurface should support, and links them at a high level to the

intended virtual (metasurface) functionality that they should yield.

Contractual Date of Delivery 31/12/2017

Actual Date of Delivery 31/12/2017

Deliverable Security Class Public

Editor Sotiris Ioannidis

Contributors Christos Liaskos, Ageliki Tsioliaridou

Konstantinos Michail, Marios Milis, Dimitrios

Kouzapas, Alexandros Pitilakis, Nikolaos

Kantartzis, Andreas Pitsillides

Quality Assurance Julio Georgiou

1This project is supported by the European Commission under the Horizon 2020 Program (2014-2020) with Grant agreement no: 736876

VISORSURF D2.1 H2020-FETOPEN-2016-2017/№ 736876

www.visorsurf.eu - 2 - Wednesday 20 December 2017

The VISORSURF consortium consists of:

FORTH Coordinator Greece

UCY Principal Contractor Cyprus

IZM Principal Contractor Germany

SG Principal Contractor Cyprus

UPC Principal Contractor Spain

AALTO Principal Contractor Finland



Document Revisions & Quality Assurance

Internal Reviewers

1. Anna Philippou (UCY) 2. Panayiotis Kouvaros (UCY)

Revisions

Version Date By Overview

0.1.0 6/9/2017 Christos Liaskos,

Ageliki Tsioliaridou

Sections covering the UML form of virtual functions have been

completed.

0.2.0 15/9/2017

Christos Liaskos, Ageliki Tsioliaridou, Alexandros Pitilakis, Nikolaos Kantartzis, Andreas Pitsillides

Sections covering the HyperSurface architecture and the electromagnetic

aspect modelling have been completed.

0.3.0 21/11/2017

Konstantinos Michail,

Marios Milis, Dimitrios Kouzapas,

Taqwa Saeed, Andreas Pitsillides

Sections covering the description of the gateway communication protocols

have been completed.

Version ready for internal review.

2.0.0 11/12/2017 Christos Liaskos,

Ageliki Tsioliaridou

Internal review completed and comments addressed. Final version of

the document.



Table of Contents

DOCUMENT REVISIONS & QUALITY ASSURANCE ......................................................................... 3

TABLE OF CONTENTS................................................................................................................................... 4

1 INTRODUCTION .................................................................................................................................... 6

1.1 DOCUMENT OUTLINE ................................................................................................................................ 6

2 MODELLING TOOLS ............................................................................................................................ 7

2.1 LIST OF UML DIAGRAMS .......................................................................................................................... 7 2.2 UML DIAGRAM CREATION SOFTWARE ................................................................................................. 8

3 THE HYPERSURFACE ARCHITECTURE ..................................................................................... 9

3.1 THE FUNCTIONALITY & CONFIGURATION LAYERS ................................................................................... 9 3.2 THE METASURFACE LAYER................................................................................................................ 10 3.3 THE INTRA-TILE CONTROL LAYER .................................................................................................... 10 3.4 THE TILE GATEWAY LAYER ............................................................................................................... 11

4 QUALITATIVE DESCRIPTION OF THE HYPERSURFACE OPERATIONAL WORKFLOW ................................................................................................................................................... 12

5 UML DIAGRAMS OF THE API ........................................................................................................ 16

5.1 GENERAL USE CASE DIAGRAM ............................................................................................................... 16 5.2 THE DATABASE DIAGRAM ................................................................................................................. 19

5.2.1 Table DoA .................................................................................................................................... 22 5.2.2 Table Frequencies ...................................................................................................................... 23 5.2.3 Table Polarities ........................................................................................................................... 23 5.2.4 Table SwitchStates ..................................................................................................................... 25 5.2.5 Table FunctionTypes ................................................................................................................. 25 5.2.6 Table Tiles ................................................................................................................................... 26 5.2.7 Table Switches ............................................................................................................................ 26 5.2.8 Table PhysicalSetup ................................................................................................................... 26 5.2.9 Table ParameterizedFunctions ................................................................................................ 28 5.2.10 Table FunctionEMProfiles ................................................................................................... 29 5.2.11 Table FunctionToConfigCompiler ........................................................................................... 30

5.3 THE CLASS DIAGRAM ......................................................................................................................... 31 5.3.1 Interface DBDataHolder .......................................................................................................... 32 5.3.2 Class DirectionOfArrival .......................................................................................................... 33 5.3.3 Class Frequency ......................................................................................................................... 34 5.3.4 Class Polarity .............................................................................................................................. 34 5.3.5 Class SwitchState ....................................................................................................................... 35 5.3.6 Class SwitchPosition .................................................................................................................. 35 5.3.7 Class Switch ................................................................................................................................ 36 5.3.8 Class Tile ...................................................................................................................................... 37 5.3.9 Class ParameterizedFunction .................................................................................................. 38 5.3.10 Class FunctionEMProfile...................................................................................................... 39 5.3.11 Class Environment ..................................................................................................................... 40 5.3.12 Class InterruptHandler ........................................................................................................ 40 5.3.13 Class ExceptionCommunicationError ............................................................................... 41 5.3.14 Class ExceptionDBError ...................................................................................................... 41 5.3.15 Class HardwareError .......................................................................................................... 41 5.3.16 Class InterruptGateway ....................................................................................................... 42 5.3.17 Description of Key Procedures ............................................................................................ 42 5.3.17.1 API Task Execution Workflow ............................................................................................ 42 5.3.17.2 The Tile.setEMFunction() callback ..................................................................................... 43 5.3.17.3 The Tile.getEMFunction() callback .................................................................................... 45 5.3.17.4 The Tile.doHardwareCheck() callback .............................................................................. 46 5.3.17.5 The Switch.set/getState() callback ..................................................................................... 47



5.3.17.6 The Switch.doHardwareCheck() callback ......................................................................... 47 5.3.17.7 The Environment.isTileSupported() Callback .................................................................. 48

5.4 THE GATEWAY EXTERNAL COMMUNICATION PROTOCOL ................................................................. 48 5.4.1 Communication Establishment................................................................................................ 49

5.5 THE GATEWAY INTERNAL COMMUNICATION PROTOCOL ................................................................. 50

6 REFERENCES ........................................................................................................................................ 56



1 Introduction

This document constitutes the VISORSURF deliverable D2.1 which is one of the objectives of the project Task 2.1 (“T2.1. UML definition of the HyperSurface programming interface and the underlying virtual functions”). As such, it is one of the deliverables of WP2, whose context is “to study the exposed VISORSURF programming interface (API), its transformation (compiling) to controller directives and their relay within the controller network. This API and middleware, clearly specified in UML, will expose the HyperSurface functionality in the form of parametric virtual functions, each corresponding to a metasurface capability (electromagnetic steering, absorption, polarization & non-linear response).” Such functionalities are useful in a wide variety of setups in next generation wireless communications [1-6,11,13,14].

Based on these official descriptions, the current document will introduce the physical system properties to be controlled, i.e., the electromagnetic behavior of a metasurface, describe how this control can be enforced via electronic means, and proceed to detail the software design that will be employed by an end-user for setting and obtaining the desired type of electromagnetic behavior.

The described software design constitutes an initial, envisioned version, given that the electromagnetic design of the metasurface and its electronic control elements are scheduled to be finalized at M24. The software design is set to undergo revision cycles until the end of the project at M36, remaining up to date with decisions taken in hardware design-oriented work packages, WP1, WP3 and WP4 [12].

1.1 Document outline

The document adheres to the following structure:

Section 2 describes the employed modelling tools and modelling software. Specifically, the Unified Modelling Language is briefly presented in terms of diagrams included in its specification. The diagram drawing software is discussed as well.

Section 3 provides a high-level overview of the HyperSurface architecture and its hardware and software components.

Section 4 proceeds to provide a qualitative description of the HyperSurface operational workflow, extracting logical representations of entities and their coarse interactions.

Section 5 provides the UML diagrams describing the HyperSurface programming interface.

Finally, the document is concluded in Section 6, and a list of references is provided in Section 7.



2 Modelling Tools

This task seeks to define the programming interface of the HyperSurface. The Unified Modelling Language (UML) has been chosen for this task. UML is a general-purpose language for specifying, visualizing, constructing and documenting the artifacts of systems. Its benefits include:

It is appropriate for many kinds of applications running on any type and combination of hardware, operating system, programming language, and network.

It allows to zoom out from a detailed view of a system to the environment where it executes. Additionally it allows to focus on different aspects of the application, such as control flow, communication patterns, and timing behavior.

It has mostly graphical notation, thereby making it easy to convey critical points.

It is readily supported by modelling and simulation tools.

A UML description essentially provides the following parts of a software design:

The definition of the involved entities (i.e., the system classes),

The workflow and interactions between those entities.

UML is a visual language that fully relies on diagrams. The UML standards define a multitude of diagram types, aimed at describing all kinds of software applications, spanning all ranges of complexity and all phases of the software development and distribution cycle. For these reasons, not all diagrams are applicable to any given software type or modelling phase. Below, we briefly mention all existing types of UML diagrams (version 1.4).

2.1 List of UML diagrams

Class Diagrams

A UML Class Diagram is a type of Structure Diagrams that shows the classes comprising a software package, their member variables and methods, as well as the relationships between them. It is the most complete diagram with regard to information pertaining to the final implementation.

Use Case Diagrams

A UML Use Case Diagram is a type of Behavior Diagrams that displays the dependencies between the actors and use cases. A UML Use Case Diagram displays the system on the conceptual level.

Sequence Diagrams

A UML Sequence Diagram is a type of Interaction Diagrams that describes the interactions between the objects and classes that are involved in a given scenario and the sequence of messages exchanged between them.

Collaboration Diagrams

A UML Communication Diagram is a type of Interaction Diagrams that displays the interactions of objects by means of messages communicated.

Activity Diagrams



A UML Activity Diagram is a type of Behavior Diagrams that graphically describes the decomposition of some activity to sub-components and a workflow connecting them.

Database Diagrams

A UML Database Diagram describes the persistent data storage structures, their relations and format restrictions.

State Machine Diagrams

A UML State Machine Diagram is a type of graph describing the operation of a system, where vertices represent system states and edges correspond to allowed transitions between states. The state diagram also includes the conditions under which a transition is triggered.

2.2 UML diagram creation software

ArgoUML1 and Oracle JDeveloper2 were chosen as the tools for creating the needed UML charts. ArgoUML is preferred in cases where the UML model is intended to describe a workflow of a system, before proceeding to actual software development. JDeveloper is preferred for modelling elements closer to their development-ready form.

ArgoUML supports all standard UML diagrams. It runs on any Java platform, which constitutes it a cross-platform tool that any partner can use on his personal computer regardless of operating system. ArgoUML is a free software that is distributed under the Eclipse Public License (EPL) 1.0.

Argo UML supports a wide variety of collaboration features, internationalization in 11 languages, automatic source code generation when the modelling has reached its final, complete form, automatic model checking for compliance with user-specified constrains and a wide variety of diagram export formats (vector and canvas based image outputs).

JDeveloper is chosen as the development environment for the VISORSURF WP2 software deliverables, given that it constitutes the official Java development platform by Oracle.

Oracle JDeveloper is a free integrated development environment that simplifies the development of Java-based applications by addressing every step of the application lifecycle. JDeveloper offers complete end-to-end development for Oracle's platform and Oracle's applications.

1http://argouml.tigris.org

2http://www.oracle.com/technetwork/developer-tools/jdev/overview/index.html

http://argouml.tigris.org/

http://www.oracle.com/technetwork/developer-tools/jdev/overview/index.html



3 The HyperSurface Architecture

According to the technical annex of the proposal, a HyperSurface tile is envisioned as a planar, rectangular structure that can host metasurface functions over its surface with programmatic control. It comprises a stack of virtual and physical components, shown in Figure 1, which are detailed below.

3.1 The Functionality & Configuration layers

A HyperSurface tile supports software descriptions of the metasurface electromagnetic functions and allows the programmer to customize, deploy or retract them on demand via a programming interface with appropriate callbacks. These callbacks have the following general form:

outcome ← callback(action_type, parameters)

The action_type is an identifier denoting the intended function to be applied to the impinging waves, such as STEER or ABSORB. Each action type is associated with a set of parameters. For instance, STEER commands require: i) an incident wave direction, ii) an intended reflection direction, and iii) the applicable wave frequency band; ABSORB commands require no incident or reflected wave direction parameters. Notice that metasurfaces can act as angle-independent absorbers, i.e., absorbing from any direction [8].

The functionality layer is exposed to programmers via an API that serves as a strong layer of abstraction. It hides the internal complexity of the HyperSurface and offers

Figure 1 : The functional and physical architecture of a single HyperSurface tile. A desired and supported EM function is attained by a switch state configuration setup. The configuration commands are propagated within the tile via the controller intra-network. Inter-tile and external communication are handled by standard gateway hardware.



general purpose access to metasurface functions without requiring knowledge of the underlying hardware and physics. Thus, the configuration of the phase switch materials that matches the intended electromagnetic function is derived automatically without the programmer’s intervention.

3.2 The Metasurface Layer

The metasurface layer denotes the hardware comprising dynamic meta-atoms whose configuration may be altered to fit the intended electromagnetic function. In general, the metasurface hardware comprises passive and active elements (e.g., copper patches and varactors respectively). For instance, the example of Figure 1 comprises conductive square patches (passive) and CMOS switches (active). Custom configurations can be created by setting the switches to appropriate impedance values. In a simple case, the ON (most conductive) or OFF (most insulating) switch states can be considered (e.g. [9]). We note that dynamic meta-atom designs constitute an extensively studied subject in the literature, offering a wide variety of choices in terms of active/passive element combinations [7,8,10,15].

The meta-atom size and the thickness of the tile are important design factors, which define the maximum frequency for electromagnetic wave interaction. As a rule of thumb, meta-atoms are bounded within a square region of λ⁄10↔λ⁄5, λ being the electromagnetic interaction wavelength. The minimal HyperSurface thickness is also in the region of λ⁄10↔λ⁄5. Thus, for an interaction frequency of 5 GHz, the meta-atom would have a size of  ~7.5 mm, and the HyperSurface would have similar thickness. Moreover, a minimum of 10 × 10 meta-atoms are usually required to exhibit an electromagnetic functionality such as STEER or ABSORB.

3.3 The Intra-tile Control Layer

The intra-tile control layer is composed of the electronic hardware component that enables the programmatic control over the HyperSurface. It comprises a network of controllers, each with responsibility over one active meta-atom element. The control over a switching element is achieved via the control wiring (Figure 1 (red highlight)). Additionally, the controllers are able to exchange information in order to propagate switch configuration information within the tile. For example, a grid topology using separate wiring (Figure 1 (blue highlight)) can be employed for the control tasks. The networked controller approach minimizes the required control wiring which benefits the manufacturing cost and the cross-talk minimization with the intended electromagnetic functionality.

The control wiring can be used for powering the control nodes and the active metasurface elements. For instance, in the case of CMOS elements which require a constant power supply, the control wiring can carry a constant voltage level while the exchanged information is encoded as fluctuations over this level. Other power supply options are allowed, according to the specific tile design. Separate power lines can be deployed in the most power-hungry cases, while extremely-low power designs may enable autonomous tiles that rely on energy harvesting. Furthermore, a fully wireless design for the interconnection of the controllers that employs energy harvesting can be envisaged.



3.4 The Tile Gateway Layer

The tile gateway layer specifies the hardware (Gateway) and protocols that enable the bidirectional communication between the controller network and the external world (such as the Internet) and the communication between the tiles. This provides flexibility in the HyperSurface operation workflow as the following explains.

In general, multiple tiles are expected to be used as coating of large areas, as detailed later in Section 4. Moreover, the tile hardware is intended to be inexpensive, favouring massive deployments. The networked tile architecture allows for offloading demanding tasks to powerful, external servers. A basic external service is responsible of deducing and returning the optimal tile configurations to be deployed after taking into consideration the status of other HyperSurfaces and their environment. Based on these specifications, existing Internet-of-Things (IoT) platforms can constitute exemplary choices for tile gateways [13]. The sensing capabilities of existing IoT platforms enable the monitoring of the tile environment, such as the impinging wave power, thus enabling the adaptive tuning of the tile functions.

We note that future advancements in electronics manufacturing may allow for the mass production of miniaturized, powerful and inexpensive inter-tile controllers. These future controllers may be able to directly support advanced communication protocols. Therefore, they may be able to communicate with the external world directly, without requiring a gateway to act as a mediator. Depending on their capabilities, advanced controllers may also act as ambient intelligence, handling the decisions for the HyperSurface configuration in an autonomous fashion, without the need for an external calculation service.

The described interconnectivity approach can also be employed during the tile design phase for the automatic definition of the supported electromagnetic functions and their input parameter range. Since deriving the tile behaviour via analysis is challenging in all but static meta-atom cases, an approach based on learning heuristics can be alternatively employed. According to it, an intended electromagnetic function is treated as a fitness function and, subsequently, the tile is evaluated against it via illumination by an external wave (input) and reflection/absorption measurements (output). A learning heuristic is then employed to detect iteratively the best switch configuration that optimizes the output of the objective function. Once detected, the best configuration is stored in a lookup table for any future use. It is noted that metasurfaces are generally not known to exhibit any inherent limitation regarding the electromagnetic functions that they can support.



4 Qualitative description of the HyperSurface operational workflow

We proceed to make a coarse, computer science-based modeling of the HyperSurface operation. To better understand the programming entities involved, we first provide an overview of the physical setup.

An external programming entity (“Caller”), which could be a regular computer, obtains an implementation of the HyperSurface API (that will be described in UML). It then executes a HyperSurface command. The command is translated to data packets that are sent to the HyperSurface Gateway using a given communication protocol. The Gateway diffuses the information within the controller network of the HyperSurface using an inter-controller communication protocol. The controllers receive the information pertaining to them and set the states of the switch elements accordingly. The collective end-state of the switch elements is then matched to the intended electromagnetic function of the HyperSurface.

Based on this coarse description, we identify the following conceptual entities involved in the HyperSurface API workflow:

The Caller or User. The entity that calls the HyperSurface API. The User Service. A user-side daemon that receives and handles interrupts,

e.g., messages spontaneously generated by tiles. The Callback. A single function of the HyperSurface API. The Configuration. A data entry containing the information for mapping a

Callback to a specific set of Switch Element states. The Configuration Database (DB). A database containing several discrete

configurations. The Configuration Resolver. The software that resolves a Callback to a

given Configuration. The Switch Element. A switch element of the HyperSurface. It can be set to

any state within a set of possible states. The Switch State. The state of a switch element. It can comprise several

impedance values, i.e., discrete combinations of resistance and capacitance. The gateway external communication protocol. It is the protocol that

transfers data between the HyperSurface and the Caller. The Gateway. The HyperSurface Gateway hardware, as described in the

proposal. The HyperSurface controller communication protocol. The protocol

that transfers data between the gateway and the switch controllers, as well as between the controllers themselves.

The HyperSurface Tile. The complete, assembled HyperSurface unit.

We now define the tentative form of the API callbacks. As mentioned in Section 3, these callbacks have the following general form:

outcome ← callback( action_type, parameters ) The action_type is an identifier denoting the intended function, e.g.:

STEER, ABSORB, POLARIZE, FILTER.



Each action type is associated with a set of parameters. For instance,

STEER commands require: i) an incident wave direction, I, ii) an intended reflection direction, O, iii) the applicable wave frequency, F.

ABSORB commands require no O parameter. An important point is that the HyperSurface API serves as a strong layer of abstraction that hides the internal complexity of the HyperSurface. It offers user-friendly and general-purpose access to metasurface functions without requiring knowledge of the underlying hardware and Physics.

We proceed to illustrate the API Callback process for setting the state of a switch element as shown in Figure 3. The Caller executes an electromagnetic Function deployment Callback function, which in turn invokes the Configuration resolver. The resolver queries the Configuration DB and returns one or more Configurations that are combined into the configuration that best matches the intended electromagnetic function. The Configuration is conveyed to the Gateway using the corresponding protocol. The Gateway reformats the received configuration and executes actions to inform (and thereby set) each separate switch element accordingly. The HyperSurface controller protocol is employed towards this end. Finally, each switch element is set to its intended value, thereby “consuming” the corresponding part of the configuration.

Figure 2 : The configuration resolver may need to combine several configurations to produce the intended one.



The configuration resolver may need to combine several configurations to produce the intended one. The reason for this can be explained using the illustration of Figure 2. This Figure illustrates a HyperSurface illuminated by an electromagnetic wave incoming from a vertical impinging direction (angles θ=0, φ=0, using a spherical coordinate system relative to the middle point of the HyperSurface). Let us assume that the required function is of type ABSORB. The DB will contain several configurations corresponding to combinations of (φ, θ) angles, as shown by the spherical mesh.

Figure 4 : The API Callback process for setting the state of a switch element.

Figure 3 : Illustration of a monitor Callback to get the state of a switch element.



However, these combinations are discrete. Therefore, the Configuration resolver may need to return configurations for combinations that do not exist in the DB.

Possible directions to be explored for the combination of several configurations include:

The selection of the best matching configuration out of the intended ones.

A linear interpolation of existing configurations.

A non-linear interpolation approach, e.g., using a trained neural network.

We note that apart from setting the state of the switch elements, the API callbacks include functions for getting the state of the elements. We refer to these functions as monitor callbacks due to their immediate usage to monitor the state of the HyperSurface. In Figure 4, the Caller executes a monitor Callback to get the state of a switch element. Notice that this callback type requires no interaction with the configuration resolver or the configuration DB. This monitoring technique is called polling since switch elements are queried for their state.

Additionally, depending on the hardware capabilities of the controller nodes, the nodes themselves may trigger a monitoring event, such as a local malfunction. This approach, called reporting, is illustrated in Figure 5.

Notice that this approach requires a service to be active at the side of the Caller that is ready to receive incoming reports from the controllers. The Callback API specification will include a description of such services, if they are supported by the hardware capabilities.

In both polling and reporting monitoring approaches, time-outs or other transmission failures may occur for a variety of reasons (malfunction, interference, and power supply issue). The handling of these events will also be described in the Callback APIs by taking into account the behavior and capabilities of the involved hardware (Gateway and Controller nodes).

Figure 5 : A switch state reporting event triggered by the switch controller, rather than by external polling.



5 UML diagrams of the API

This Section details the UML diagrams that describe the operation of the API. We begin by presenting the use-case diagram which provides a high-level view of the API functionalities. Then, we proceed to describe the Database diagram which provides an insight of the software representation of the involved entities. The ensuing class diagrams provide the detailed modeling. Finally, various diagrams provide the planned functionality of several class member functions.

5.1 General Use Case Diagram

The use case diagram of the VISORSURF API is given in Error! Reference source not found.. The involved entities are the following:

The User represents the entity than can initiate API callbacks. In this sense, the User may represent a third-party application that includes the API callbacks in its source code, or a Graphical User Interface (GUI) that receives commands from a user (e.g., button click events) and subsequently triggers the corresponding API callback.

The Interrupt handling service is a persistent daemon (service) that receives and dispatches events originating from the HyperSurface hardware. For instance, a HyperSurface tile may report data obtained from a gateway sensor in a periodic fashion or upon an environmental trigger without the intervention of the user. We note that implementation-wise, this entity may not be implemented as a service at the operating system level. It can instead be implemented as a persistent execution thread that runs in parallel to the user callback execution thread. In this sense, it can be exemplary implemented as a thread within the aforementioned third-party application.

The HyperSurface Gateway represents the master electronic controller functionalities incorporated in the gateway. It stands between the intra-tile controllers and the user callbacks and acts as a representative of the tile to the external world. Sensing capabilities may be incorporated to the gateway as well.

The Configuration Database (DB) is the persistent storage point of the API. It contains the allowed HyperSurface electromagnetic (electromagnetic) functions and their corresponding switch states per tile. Additionally, it contains the allowed HyperSurface sub-components states, parameters and persistent data required for the API initialization.

The User, the Interrupt Service and the Database are located to common personal computing devices, such as desktops, laptops or smartphones. They can be located within the same physical device or at completely separate (but networked) ones, without further limitation. The HyperSurface Gateway is bound to each tile.



Figure 6 : The VISORSURF API Use Case Diagram



We proceed to detail the use cases mentioned in Figure 6 : The VISORSURF API Use Case Diagram .

The user can initialize the API prior to any other callback. The callbacks generally refer to (i) retrieving the state of a tile in the sense of retrieving the electromagnetic function that is presently deployed over it; and (ii) setting it to a required electromagnetic function.

The Environment initialization is called once per active user. It performs the following tasks:

It detects the tiles that are presently active and connected (discoverable) to the user by broadcasting a corresponding network message. The tiles that reply to the message report their identifier within a time threshold. The tiles that do so are logged as active in a browsable, user-space software structure.

It enumerates the supported tiles by contacting the Configuration DB service thereby obtaining the list of unique tile identifiers.

It validates the support for the presently active tiles by checking if their identifier exists in the stored list of supported tiles.

For each supported tile, it contacts the DB to retrieve the switches that comprise the tile (including their location on the tile and their allowed states), as well as the electromagnetic functions (including input and output parameters) supported by the tile.

Using the information returned by a successful initialization, a user may perform any of the following tasks:

Set the tile state to the required electromagnetic function with proper input and output parameters. This is accomplished by setting the state of the tile’s switches to the values obtained during the initialization. Three types of electromagnetic functions are planned at this point:

o STEER functions, which express the redirection of waves impinging on a tile from a given direction of arrival (input) to another (output).

o ABSORB functions, which express the full absorption of an electromagnetic wave impinging on the tile from a given direction of arrival (input).

o POLARIZE functions, which express the altering of the wave polarization from an initial state (input: initial polarization and direction of arrival) to another (output: initial polarization and direction of arrival).

Get the tile state, i.e., deduce the currently deployed electromagnetic function on a given tile. This can be accomplished in two ways, depending on the gateway hardware capabilities:

o The currently deployed electromagnetic function identifier may be persistently stored at the tile gateway. In this case, getting the deployed electromagnetic function is implemented by querying the gateway for this identifier.

o The most robust approach is to query the gateway for the current state of each contained switch. The returned states are compared to the allowed tile configurations retrieved from the DB during initialization thereby obtaining the corresponding electromagnetic function identifier.

Check the “Health” of a tile, i.e., deduce the working condition of the gateway and the tile switches. This is done by requesting the setting of a default state within a time limit. The state is then retrieved back and cross-checked for



equality to the default. This task naturally incorporates getting and setting the state of the tile switches.

Getting the state of one or more tile switches is also allowed to the user for potential GUI visualization and experimental purposes. However, the user is prohibited from setting a tile switch state, as this may break the overall correspondence of the switch states to a valid electromagnetic function.

The interrupt handling service is responsible for dispatching the following events:

Database Errors, corresponding to invalid data queries or null results.

Communication Errors, corresponding to network-related errors, such as timeouts.

Hardware Errors, corresponding to the detection of failing hardware components of the tile.

Gateway Interrupts, which are events raised spontaneously by the tile gateway without user intervention. These can be simple notifications (e.g., a warning regarding the state of the tile/switches) or they may carry useful data, such as periodically or event-triggered reports on quantities obtained from the sensor at the gateway side.

The aforementioned errors and interrupts are generalized as Generic Interrupts. Moreover, for the sake of presentation, the main API functionalities (GetTileState, Get/SetSwitchState, Get/SetTileState, InterruptHandling, HealthCheck) are generalized and referred to as Tasks that are processed by the API workflow.

5.2 The Database Diagram

We proceed to detail the Configuration DB structure in terms of SQL Tables, Relations and Restrictions. While the Configuration DB describes the persistence storage of the VISORSURF API, it also provides a natural view of the software-level modelling of the electromagnetic HyperSurface aspects.

It is noted that this section refers to the structure of the DB and not to the process of populating it, which is the objective of Deliverable D.2.2.

We begin by listing and giving a coarse description of the DB Tables. A detailed description per table follows.

The following tables are stubs, i.e., they can be considered as simple data holders, referenced by non-stub tables via foreign-key fields:

Table DoAs. It stores in rows all considered EM wave directions of arrival, over all tiles, which can serve either as input or as output parameters to electromagnetic functions.

Table Frequencies. It stores in rows the considered electromagnetic function frequencies, serving as input parameters to electromagnetic functions.

Table Function_Types. It stores string identifiers of the considered electromagnetic function types, e.g., “STEER”, “ABSORB” and “POLARIZE”.

Table Polarities. It stores the considered polarization effects of electromagnetic functions on waves impinging on the tile.

Table Switches. It stores the identifiers of all switches across all tiles.



Table Switch_States. It stores all allowed switch states across all controllers and tiles.

Table Tiles. It stores the identifiers of all tiles that can be handled (i.e., supported) based on the current data in the DB.

The following tables are complex, relying on foreign keys to the stub tables.

Table Parameterized_Functions. It holds all considered electromagnetic functions (i.e., function types and input-output parameter combinations) per tile.

Table Function_electromagnetic_Profile. It holds the overall electromagnetic behavior of each parameterized function by detailing reflection/refraction directions and losses and polarity effects, even for unintended inputs. (I.e., even when a tile is illuminated by a direction of arrival different than the one considered by the presently deployed parameterized electromagnetic function).

Table Function_to_Config. It holds the switch state configurations that correspond to each entry (row) of the Parameterized_Functions Table. In other words, it provides the compilation data from the intended electromagnetic function to the corresponding, specific tile switch states.

Table Physical_Setup. It holds the structural information of each supported tile. Specifically, it holds the switch positions (indexes) per tile, as well as the allowed states per switch.

The database diagram showing the private-foreign key relations among the tables is shown in Figure 7 : Database diagram The Parameterized_Functions Table refers via Foreign Keys:

To the stub tables DoAs, Frequencies, Polarities, Function Types, which serve as inputs/outputs to electromagnetic functions. Notice that DoAs is referred to twice, once as function input, and once as function output.

To table Tiles, which provides the context (i.e., the supporting tile) of the electromagnetic function.

To table Function_electromagnetic_profile, which describes the electromagnetic behavior of a tile when an electromagnetic function is deployed in it.

The Function_electromagnetic_profile Table refers via Foreign Keys:

To stub table DoAs twice, once for any impinging DoA and once for any resulting reflection/refraction direction.

To stub table Frequencies soas to indicate the tile behavior at a given impinging wave frequency (intended by the profile or not).

To stub table Polarities so as to indicate the effects on the polarization of the impinging wave per resulting reflection/refraction DoA.

The Function_To_Config table refers via Foreign Keys:

To table Parameterized_Functions so as to indicate the switch states corresponding to each electromagnetic function.

To stub tables Switch and Switch_States so as to indicate the intended (valid) state of each unique switch.



Figure 7 : Database diagram



Finally, the Physical_Setup table refers via Foreign Keys:

to stub tables Tiles (switch owner), Switches (so as to associate persistent indexes) and to Switch_States (so as to associate valid states).

We proceed to describe in detail the structure of each specific Table.

5.2.1 Table DoA

Figure 8 : Physical meaning of the DoA fields.

The Table DoAs is a stub-table containing all the Tile-Impinging Wave Directions that are considered:

By any tile,

By any EM Function.

It has three columns:

The “ID”, which is the primary key,

The “PHI” (Φ) and “ΤΗΕΤΑ” (Θ) which serve as spherical coordinates defining a wave direction impinging on the tile center, as shown in Fig. 8. A tile corner (e.g., bottom-left) is selected by convention to serve as the coordinate system origin. This convention holds for all tiles.

Remarks:

Θ (elevation, 0-90 deg) is measured from the normal to the metasurface (e.g. the z-axis). Θ=0 is normal incidence, regardless of Φ value. Θ=90 is grazing incidence. Θ=180 would normal incidence from the bottom of the plane.

Φ (azimuthal, 0-360 deg) is measured on the plane of the metasurface, starting from one of the axes (e.g. x-axis).

The PHI, THETA combination is constrained to be unique.

A DoA entry (row) can serve both as Direction of Arrival (DoAin) and Direction of Exit (DoAout). The difference is denoted by the use: if a DoA row is referenced as an output parameter of an EM Function, then it is naturally a DoAout.



5.2.2 Table Frequencies

The Table Frequencies is a stub-table containing all the interaction wave frequencies that are considered:

By any tile,

By any electromagnetic Function.

It has two columns:


The “F”, which is the frequency value (in Hz).

Remarks:

The “F” field is constrained to be unique.

5.2.3 Table Polarities

Figure 9 : Modelling electromagnetic wave polarization. The illustrated planes (grey) are defined by the incident DoAin and the tile-perpendicular vector. Similarly, another two planes (not shown) are defined by the exit DoAout and tile-perpendicular vector. Electric- and Magnetic-field components are expressed on the two corresponding a-,p-,s- coordinates, for DoAin and DoAout.



The Table Polarities is a stub-table containing all the polarities that are considered:

By any tile,

By any electromagnetic Function, as either input or output parameters.

It has 12 columns:


The “P_E_IN”, which is a p-like component of the incident electric field (as depicted in in Figure 9 : Modelling electromagnetic wave polarization. The illustrated planes (grey) are defined by the incident DoAin and the tile-perpendicular vector. Similarly, another two planes (not shown) are defined by the exit DoAout and tile-perpendicular vector. Electric- and Magnetic-field components are expressed on the two corresponding a-,p-,s- coordinates, for DoAin and DoAout.).

The “S_E_IN”, which is an s-like component of the incident electric field.

The “A_E_IN”, which is an a-like component of the incident electric field.

The “P_B_IN”, which is a p-like component of the incident magnetic field.

The “S_B_IN”, which is an s-like component of the incident magnetic field.

The “A_B_IN”, which is an a-like component of the incident magnetic field.

The “P_E_OUT”, which is a p-like component of the reflected/refracted (exit) electric field.

The “S_E_OUT”, which is an s-like component of the exit electric field.

The “A_E_OUT”, which is an a-like component of the exit electric field.

The “P_B_OUT”, which is a p-like component of the exit magnetic field.

The “S_B_OUT”, which is an s-like component of the exit magnetic field.

The “A_B_OUT”, which is an a-like component of the exit magnetic field.

Remarks:

The combination of the columns (apart from the “ID” column) is constrained to be unique.

Null values are allowed in all columns except for the “ID”.

The aforementioned modelling is intended to be generic enough to capture any of the usual polarizations (TE, TM, TEM) that may be employed during the project [10].

The decimal fields (i.e., all but the “ID”) are expressed in normalized form (i.e., in [0,1] with regard to the total field vector norm).

The a-like direction of the exit field is “positive” if it follows the exit DoA.



5.2.4 Table SwitchStates

Figure 10 : Circuit representation of the switch state.

The Table SwitchStates is a stub-table containing all the switch states that are considered:

By any switch in any tile.

It has three columns:


The “R” field.

The “X” field.

Remarks:

“R” and “X” represent the real and imaginary parts of the total impedance of a Switch element (Fig. 10). “R” is a real positive number. “X” is also real, but can take both negative and positive values, when the impedance exhibits capacitance and inductance respectively.

The combination of the columns is constrained to be unique.

Null values are not allowed, in all columns.

Any equivalent circuit topology (with any combination of resistance, capacitance and impedance elements) can be represented by the simple complex form of Fig. 10.

5.2.5 Table FunctionTypes

The Table FunctionTypes is a stub-table containing all the function type identifiers that are considered:

By any tile,

By any electromagnetic Function.

It has two columns:


The “TYPE”, which is the STRING identifier of the function type (e.g., “STEER”).

Remarks:

The “TYPE” field in constrained to be unique.



5.2.6 Table Tiles

The Table Tile is a stub-table containing all the supported tile identifiers based on the data present in the database (i.e., electromagnetic profile, switch-to-configuration compilation data).

It has one column:

The “ID”, which is the primary key.

Remarks:

An “ID” (row) corresponds to one physical tile, and not to a tile type.

5.2.7 Table Switches

The Table Switches is a stub-table containing all the supported switch identifiers based on the data present in the database.

It has one column:

The “ID”, which is the primary key. This identifies the switch across the set of all switches from all the tiles in the DB.

Remarks:

An “ID” (row) corresponds to one physical switch, even if they are identical in terms of design and capabilities (i.e., not to a switch type, but a specific physical switch).

5.2.8 Table PhysicalSetup



Figure 11 : Meaning of the indexed position of switches on a tile. The origin follows the same convention as in the previous Figures.

The Table PhysicalSetup is a complex table describing the structure of all the supported tiles based on the data present in the database. Several rows describe the structure of a single tile which is identified by its ID.

It has seven columns:


The “TILE_ID”, which is the identifier of a physical tile (“TILE_ID” is a foreign key to table “Tiles”.)

The “SWITCH_ID” which is the identifier of a switch contained in the tile with ID “TILE_ID”. (“SWITCH ID” is a foreign key to table “Switches”.)

The fields “META_ATOM_I”, “META_ATOM_J” and “INTRA_ATOM_INDEX” (K), which describe the indexed position of a switch on a tile, as shown in Fig. 11. I and J describe the meta-atom position that owns a switch, while K=0,1,2,3 describes the switch position within the meta-atom.

The “ALLOWED_STATE ID” which points to an allowed switch state. (“ALLOWED_STATE ID” is a foreign key to table “Switch_States”.)

Remarks:

Null values are not allowed for any of the columns.


Multiple entries (rows) describe one tile that enumerates all switches and all allowed states per switch.

The value set and the meaning of the K index may change during the project duration to align with the final meta-atom design.



5.2.9 Table ParameterizedFunctions

The Table Parameterized_Functions is a complex table describing the supported electromagnetic functions (including their input-output parameters) of each tile based on the data present in the database.

It has seven columns:


The “TILE_ID”, which is the identifier of the tile over which the electromagnetic functions are applied. (The field is a foreign key to the table “Tiles”).The “FUNCTION_TYPE_ID” which is the identifier of the Function Type (string description, such as “STEER”). (“FUNCTION_TYPE_ID” is a foreign key to the table “Function_Types”).

The field “DOA_IN_ID” which identifies the input “impinging wave direction”. (“DOA_IN_ID” is a foreign key to the table “DoAs”).

The field “DOA_OUT_ID” which identifies the output “reflected/refracted wave direction”. (“DOA_IN_ID” is a foreign key to the table “DoAs”).

The “FREQUENCY_ID” which points to the input “intended wave frequency”. (“FREQUENCY_ID” is a foreign key to the table “Frequencies”).

The “POLARITY_ID” which points to an intended polarity alteration. (“POLARITY_ID” is a foreign key to the table “Polarities”).

Remarks:

Null values are allowed, except for the “ID”, “TILE_ID” and “FUNCTION_TYPE_ID” columns.


This modelling implies only one impinging wave (planar). This follows the common assumptions for metasurfaces [10]. However, multiple input directions can be handled, by allowing non-unique values in the “PARAMETERIZED_FUNCTION_ID” column.



5.2.10 Table FunctionelectromagneticProfiles

Figure 12 : Schematic of the full electromagnetic behaviour of a tile configured for a given, parameterized electromagnetic function.

The Table Function_electromagnetic_Profile is a complex table describing the complete electromagnetic behavior of all the supported tiles based on the data present in the database. Several rows describe the structure of a single tile which is identified by its ID.

It has six columns:

The “ID” which is the primary key.

The “PARAMETERIZED_FUNCTION_ID” which is the identifier of the electromagnetic function that is profiled. (“PARAMETERIZED_FUNCTION_ID” is a foreign key to the table “Parameterized_Functions”.)

The “ILLUMINATION_FREQUENCY_ID” which is the identifier of a frequency of a wave impinging on the tile. (“ILLUMINATION_FREQUENCY_ID” is a foreign key to the table “Frequency”.) This allows for the description of tile behaviors at frequencies other than the ones intended by the active electromagnetic function.

The “ILLUMINATION_DOA_ID” which is the identifier of a direction of arrival of a wave impinging on the tile. (“ILLUMINATION_DOA_ID” is a foreign key



to the table “DoAs”). The table contains both the DoA expected by the parameterized function, as well as DoAs that are unintended. This describes the electromagnetic behavior of a tile that has been configured for a given function but is (intentionally or unintentionally) illuminated by another DoA.

The “OUT_DoA_ID” which points to a DoA expressing a major reflection/refraction of the illuminating wave. (“OUT_DoA_ID” is a foreign key to the table “Switch_States”). Multiple reflection/refraction DoAs are allowed to correspond to one Illumination DoA.

The “OUT_POLARITY_ID” which points to a polarity alteration (“OUT_POLARITY_ID” is a foreign key to the table “Polarities”). One polarity alternation is allowed per OUT_DoA_ID.

The “LOSS_DB” field which describes the attenuation loss in decibels (dB) with regard to the power of the illuminating wave. One loss value per OUT_DoA_ID is allowed.

Remarks:



Multiple entries (rows) describe one electromagnetic function profile.

This modelling implies only one impinging wave (planar) per function. This follows the common assumptions for metasurfaces [10]. However, multiple input directions can be handled by transforming the “ILLUMINATION_DOA_ID” to a set of DoA identifiers, rather than just one DoA identifier.

The referenced tile id is contained in the “Parameterized_Functions”.

5.2.11 Table FunctionToConfigCompiler

Figure 13 : The structure of Table “Function_to_Config_compiler”, which holds the compilation information.

The Table Function_to_Config_compiler is a complex table that matches an electromagnetic function to the corresponding switch states. Several rows of the table are describing a single matching.

It has four columns:



The “ID” which is the primary key.

The “PARAMETERIZED_FUNCTION_ID” which is the identifier of the electromagnetic function to be matched to several switch configurations. (“PARAMETERIZED_FUNCTION_ID” is a foreign key to the table “PARAMETERIZED_FUNCTIONS”.)

The “SWITCH_ID” which is the identifier of a switch contained in the electromagnetic function of the tile. (“SWITCH_ID” is a foreign key to table “Switches”.)

The “SWITCH_STATE ID” which points to the proper state of the switch (identified by “switch_id”) so as to correspond to the intended electromagnetic_Function. (“SWITCH_STATE ID” is a foreign key to table “Switch_States”.)

Remarks:



Multiple entries (rows) describe one function-to-switch-states match.

The referenced tile id is contained in the “Parameterized_Functions”.

5.3 The Class Diagram

The class diagram (Figure 14 : The User API class diagram.) and the ensuing class descriptions provide the necessary details for a complete implementation of the VISORSURF API. The class diagram is an illustrated form of actual Java source code that has been already developed.

Notice that, at this stage, the source code excludes the bodies of specific functions that cannot be defined prior to the hardware finalization. The latter are designated as abstract Java classes. Their expected workflow is defined in separate subsections in UML schematic form.

The Class Diagram is closely related to the Database Diagram described in Section 5.2. The classes describe objects that are initialized based on the persistent data stored in the Database. Thus, many class objects can be seen as structured data with functionalities.

The API classes can be classified as:

Read-only data representers, with no additional functionality (Polarity, Frequency, ParameterizedFunction, FunctionelectromagneticProfile, DirectionOfArrival, SwitchState, SwitchPosition). These simply implement the Interface DBDataHolder.

Representers of physical objects, comprising data and functionalities (Tile, Switch). Their data representation aspect is obtained by implementing the DBDataHolder interface as well.

Workflow Handlers (Environment, InterruptHandler), which are singleton classes that initialize the API and handle the execution of tasks described in Section 5.2.

Interrupt representation objects (Exception_Communication, Exception_Hardware, Exception_DBError, Interrupt_Gateway).

We proceed to describe each class in detail below.



Figure 14 : The User API class diagram.



5.3.1 Interface DBDataHolder

The DBDataHolder interface provides a uniform way of initializing Java objects based on database entries.

The interface assumes that an identifier (primary key entry in the database table related to the class) has been passed to the object constructor as an argument. The identifier is stored within the object instance and can be accessed (read-only) via a get_ID() function call. Subsequently the bind() method is called by the constructor to contact the database, retrieve data corresponding to the identifier, and set object member

variables to their proper initial values. Exceptions are thrown by bind() corresponding to the potential error type (described further below).

The implementation of the described database contact/data retrieval is not strict and will depend on the database technology (e.g., MySQL, MSSQL, PostgreSQL, etc.). For instance, a static Database Connection Broker object can be passed to the object implementing the interface during construction and be subsequently called by bind().

5.3.2 Class DirectionOfArrival

Instances of the class DirectionofArrival represent rows of the database table “DoAs”. The member-variables PHI and THETA are as described in Section 5.2.1 (Figure 8).

Both variables are private class members, accessible only for read-access via the corresponding get() functions.

The member variable ID is the primary key value of the DoA Table row that is represented by a class instance. It is also exposed for read-access only via the get_ID() function as per the DBDataHolder interface implemented by this class.

Notice that this class (as well as every class described below) overrides the equals() and hashCode() member

functions of Java Objects. This facilitates their lookup in containers.

The overridden hashCode() simply returns the value of the ID member variable, which is a unique identifier of the table row represented by the class instance.

The overridden equals() function returns true for:

Objects of class DirrectionOfArrival, and

With equal identifiers (ID).



Thus, instances that are equal to one another, certainly refer to the same Direction of Arrival.

5.3.3 Class Frequency

Instances of the class Frequency represent rows of the database table “Frequencies”. The member variable F is the frequency value in Hz.

The class implements the DBDataHolder interface.

The member variables F and ID are private. They are set at initialization by calling the bind() function and are accessible for reading via the corresponding get() functions.

The overridden hashCode() simply returns the value of the ID member variable which is a unique identifier of the table row represented by the class instance.


Objects of class Frequency, and




5.3.4 Class Polarity

Instances of the class Polarity represent rows of the database table “Polarities”. The member-variables (E/B)_(A/P/S)_(IN/OUT) have the meaning described in Section 5.2.3 (Figure 9 : Modelling electromagnetic wave polarization. The illustrated planes (grey) are defined by the incident DoAin and the tile-perpendicular vector. Similarly, another two planes (not shown) are defined by the exit DoAout and tile-perpendicular vector. Electric- and Magnetic-field components are expressed on the two corresponding a-,p-,s- coordinates, for DoAin and DoAout.).


All member variables are private. They are set during the instance initialization by calling the bind() function and are accessible for reading via the corresponding get() functions.



Objects of class Polarity, and


5.3.5 Class SwitchState

Instances of the class SwitchState represent rows of the database table “SwitchStates”. The member-variables R, Χ have the meaning described in Section 5.2.4 (Figure 10).


All member variables are private. They are set during the instance initialization by calling the bind() function, and are accessible for reading via the corresponding get() functions.

The overridden hashCode() simply returns the value of the ID member variable, which is a unique identifier of the table row represented by a class instance.


Objects of class SwitchState, and




5.3.6 Class SwitchPosition

Instances of the class SwitchPosition do not represent rows of any the database table. This is a utility class that simply holds together the indices that describe the position of a switch over a tile. It is intended to be used primarily during the initialization of the Switch class instances (detailed below).

The member-variables i, j, k have the meaning described in Figure 11.

All member variables are private. They are set during the instance initialization and are accessible for reading via the corresponding get() functions.

The overridden hashCode() returns a practically unique integer derived by the i, j, k values in use. Specifically, it returns i*104+j*102+k, which is unique for k<100 and j<100.


Objects of class SwitchPosition, and


5.3.7 Class Switch

Instances of the class Switch represent rows of the database table “Switches”. Additionally, they link together several data from other tables that are related to the physical switches. Moreover, they implement facilities related to a switch.

The member-variable ID is the primary key of the Table Switches.

The ownerTile is an instance of the Tile class (described below), representing the tile on which the switch has been placed. The corresponding data are derived from Table Physical_Setup.

The position variable is an instance of the class SwitchPosition that contains the indexed position of the switch on its tile. The corresponding data are derived from Table Physical_Setup.

The set_State() and get_State() functions alter the state of the switch. While the get_State() is exposed to the user, the set_State is can be called only

internally so as to avoid setting tile switches to configurations that do not correspond to an electromagnetic function.



The function doHardwareCheck() performs a check on the switch functionality; it returns true if the switch is found to be operating as intended. The workflow of this function is described in Subsection 5.3.17.6.





Objects of class Switch, and


5.3.8 Class Tile

Instances of the class tile represent rows of the database table “Tiles”. Additionally they link together several data from other tables that are related to the physical tiles. Moreover, they implement facilities related to the tile.

The member-variable ID is the primary key of the Table Tiles.

The TileSwitchSet is a Java container instance that holds Switch instances that belong to the tile. The corresponding data are derived from the Table Physical_Setup.

The TileSwitchesByID and TileSwitchesByPosition are lookup Java containers that facilitate searching for specific switches belonging to the tile either by their switch identifiers or by their position (i, j, k indexes). The corresponding data are derived from the Table Physical_Setup.

The function doHardwareCheck() performs a check on the tile functionality; it returns true if it is found to be operating as intended. The workflow of this function is described in subsection 5.3.17.4.

The getDeployedelectromagneticFunction() returns the currently deployed electromagnetic function on the tile. Its operation is described in subsection 5.3.17.3.



The lookupelectromagneticFunction(criteria) is a utility function that searches the database for all the parameterized functions that match to the parameters provided as inputs and can be deployed on the tile. The corresponding data are derived from the table Function_EK_Profile.

The lookupelectromagneticFunctionProfile(ParameterizedFunction f, DirrectionOfArrival in) funciton returns the electromagnetic function profile of function f for the DoA “in”.

The setelectromagneticFunction(int function_db_id) function sets the electromagnetic function with identifier “function_db_id” (primary key column of the table Parameterized_Functions) to the tile.

The resetelectromagneticFunction() function sets the tile to the default electromagnetic function, i.e., the one with identifier “defaut_FunctionDB_ID” (where the member variable is set during construction).





Objects of class Tile, and


5.3.9 Class ParameterizedFunction

Instances of the class ParameterizedFunction represent rows of the database table “Parameterized_Functions”. The class member variables have the same meaning as the columns of database table “Parameterized Functions”.

The member-variable ID is the primary key of the Table Parameterized_Functions.





Objects of class ParameterizedFunction, and




5.3.10 Class FunctionelectromagneticProfile

Instances of the class FunctionelectromagneticProfile represent rows of the database table “Function_electromagnetic_Profile”. The class member variables have the same meaning as the columns of database table “Function_electromagnetic_Profile” and are as described in subsection 5.2.10, Figure 12 : Schematic of the full electromagnetic behaviour of a tile configured for a given, parameterized electromagnetic function..

The member-variable ID is the primary key of the Table Function_electromagnetic_Profile.

As with Table “Function_electromagnetic_Profile”, this class assumes one impinging direction of arrival and one or more exit directions. These exit directions are gathered in a Java container named DoAs_out. Each exit direction is matched to its polarization alteration and attenuation loss via the lookup containers Out_DoAs_to_Polarity and Out_DoAs_to_LossDB respectively.





Objects of class FunctionelectromagneticProfile, and




5.3.11 Class Environment

This static class constitutes the entry point of the API. It is called to (i) initialize the API; (ii) setup the user callback processing workflow (e.g., a GUI) and the interrupt processing workflow.

The class initiates by attempting the creation of a Database Connection Object (or Connection Pool) by calling the initializeDBConnection() member function. This object can then be passed by reference to any other class instance that requires connectivity to the database.

The class initialization proceeds to enumerate the active and supported tiles by

following the process outlined in subsection 5.3.17.7. For each supported and active tile, it instantiates all Tile objects (and the required hierarchy of contained objects) and stores them into the TileIDToTileObject lookup container.

An instance of the InterruptHandler class is created to handle gateway interrupts and exceptions in a centralized manner.

Finally, the task dispatching service described in subsection 5.3.17.1 is initiated by calling the StartService() member function.

Upon an exit request, the class destroys the database connection by calling the destroyDBconnector() member function.

5.3.12 Class InterruptHandler

The InterruptHandler class is a facility intended to provide a central place in the API source code for handling raised exceptions and gateway interrupts.

The class implements the singleton pattern, allowing only one active instance per API instantiation. This ensures that all exceptions are treated in a serial orderly fashion.



During its instantiation, the InterruptHandler instance receives the calling Environment instance by reference, to facilitate accessing its structure and status while handling exceptions and interrupts. This is accomplished by calling the set_Environment() callback, which sets the “env” member variable accordingly.

The handle() member function is the central interrupt handling process. It checks for the class type of the Exception provided as input and calls the corresponding member function (i.e., either handle_DBError(), handle_CommunicationError(), handle_HardwareError(), handle_Interrupt_Gateway(), handle_GenericError()) to handle it.

5.3.13 Class ExceptionCommunicationError

This class extends the standard Java Exception to allow for a custom string message to be passed on.

It is intended to be raised on communication errors, such as network connectivity and timeout exceptions.

5.3.14 Class ExceptionDBError


It is intended to be raised on database errors, such as queries returning invalid or unexpected results (e.g., empty sets).

5.3.15 Class HardwareError


It is intended to be raised on Hardware errors. Such errors are raised by the Tile.doHardwareCheck() and Switch.doHardwareCheck() functions.



5.3.16 Class InterruptGateway

This class extends the standard Java Exception to allow for a custom string message to be passed on. It is created by the gateway and sent to the running instance of the API. An instance of the class carries information about gateway-triggered events.

While this may not denote an error, it is considered as a potential interrupt of the API workflow and thus treated in the same central place as the

Exceptions. Future versions of the API may disassociate gateway interrupts from exceptions in terms of dispatch process. The design will be finalized based on the tile hardware capabilities.

5.3.17 Description of Key Procedures

In the following subsections we describe the planned high-level operation of several key -procedures in the class diagram and its components. This will lead to source code implementations once the structure and capabilities of the hardware components of the project (gateway and intra-tile controllers) are finalized.

5.3.17.1 API Task Execution Workflow

Figure 15 - State chart describing the general task execution workflow of the API (for one tile).



Figure 15 - State chart describing the general task execution workflow of the API (for one tile).shows the task execution workflow of the VISORSURF API. As discussed in Section 5.1, a Task is a generalization of the main, high-level actions that can be executed via the API, i.e.:

Set the tile state to a parameterized electromagnetic function.

Get the tile state, i.e., deduce the currently deployed electromagnetic function on a given tile.

Check the “Health” of a tile, i.e., deduce the working condition of the gateway and the tile switches.

Get the state of one or more tile switches.

Handle Interrupts.

As shown in Figure 14 : The User API class diagram., once the API has been initialized, it can start dispatching task requests. Once a task is received, the API checks if it signals the exit of the running process, and if it does, it proceeds to program termination. Notice that this refers to the user software that runs on a common laptop, desktop, or mobile device, and not to any process running within the tile hardware.

If the task refers to any type of the aforementioned list then it is executed accordingly. Upon success, the API returns to an idle state and is ready to dispatch further tasks. Upon failure, the task description raises an error which is handled by the API as instructed by the implementation of the respective processes in the InterruptHandler class. If the error is recoverable then the API can continue its operation. If not, the process exits.

We note that the task execution process is intended to be blocking with regard to tasks referring to the same tile, at least as an initial design approach. This will strongly depend on the capabilities of the tile hardware: if the hardware itself supports single-threaded operation without pre-emption, then the API will comply as well.

5.3.17.2 The Tile.setelectromagneticFunction() callback

Figure 16 - Sequence chart of the Tile.setelectromagneticFunction() callback. illustrates the execution of the Tile.setelectromagneticFunction(parameterized_function_id) callback. The function receives as input the “parameterized_function_id” that corresponds to the intended electromagnetic function. The user is assumed to have:

Obtained the Tile_id of the tile of interest.

Browsed the supported parametric functions for this tile.

Browsed the electromagnetic profiles of the supported parametric functions.

Deduced the required parameterized function and the corresponding “parameterized_function_id”.

Subsequently, the function callback proceeds to contact the Database and extract the:

Switches belonging to the tile.

The switch states corresponding to the parameterized function (i.e., configuration).



Figure 16 - Sequence chart of the Tile.setelectromagneticFunction() callback.

Finally, the configuration is deployed to the tile via Switch.setState(…) callbacks. Once again, it is noted that the Switch.setState(…) callbacks may be executed in a serial manner. However, if supported by the final gateway hardware, they could be executed in parallel.



5.3.17.3 The Tile.getelectromagneticFunction() callback

Figure 17 - State Chart of the Tile.getelectromagneticFunction() callback.

The Tile.getelectromagneticFunction(), shown in Figure 17 - State Chart of the Tile.getelectromagneticFunction() callback., is similar to its set counterpart. The user is assumed to have obtained the identifier of the tile of interest beforehand. Then, the callback execution follows these steps:

The switches of the tile are enumerated.

The state of each specific switch is then requested by the tile gateway. o If any switch fails to report within a given time span, or if any

networking-related error occurs, the callback returns an error of type “CommunicationError”. The InterruptHandler dispatches this error as programmed by the user.

Upon success, the switch state ids are put in a set and are ordered by ascending switch identifier.

The tile-supported electromagnetic functions are iterated over to obtain the ordered switch states (by ascending switch identifier) for each one.

The set returned is compared with the iterated sets. o If a match is found, the corresponding Function id is returned by the

function. o If a match is not found, the callback returns a DBError, indicating a

potential lack of data in the DB.



Notice that the gateway may also hold the parameterized function id during the Tile.setelectromagneticFunction(). If this is within the gateway hardware capabilities, then the getelectromagneticFunction callback may simply request this identifier. The described process can then be applied only if the returned identifier is null or erroneous in any way.

5.3.17.4 The Tile.doHardwareCheck() callback

Figure 18 - State Chart of the Tile.doHardwareCheck() callback.

The Tile.doHardwareCheck() callback, shown in Figure 18 - State Chart of the Tile.doHardwareCheck() callback, performs a check on the proper hardware operation of the switch components of a given tile.

The user is assumed to have obtained the identifier of the tile of interest.

Subsequently, the callback checks the state of each switch (described in a separate callback below). If all switches pass the check, then the function terminates successfully. If not, then it returns the switch identifiers that failed.

Once again, the check over the switches can be either sequential or parallel, depending on the final gateway capabilities.



5.3.17.5 The Switch.set/getState() callback

The Switch setState() and getState() share the same general structure, shown in Figure 19 - State Chart of the Switch.set/getState() callback..

In general, both functions are hardware-implemented and rely on the hardwired communication protocol between the gateway and the intra-tile controllers.

Here we identify the general errors that should be checked against during the callback execution.

Any communication timeout or other connectivity error (such as path failure) is reported and raised first. Should the network communication part succeed but the switch controller fail, an error code is returned and a HardwareError is raised with the appropriate description and trace-back

information.

Figure 19 - State Chart of the Switch.set/getState() callback.

5.3.17.6 The Switch.doHardwareCheck() callback

Figure 20 - State Chart of the Switch.doHardwareCheck().

The Switch.doHardwareCheck callback is shown in Figure 20 - State Chart of the Switch.doHardwareCheck().

The user is assumed to have obtained the identifier of the tile and switch of interest. Subsequently, the callback does the following:

The current switch state is retrieved and stored.

A default state is set to the switch.



The new current switch state is retrieved and compared for equality to the default. If these match, then the callback terminates successfully. Otherwise, a HardwareError is thrown and handled by the InterruptHandler.

Notice that the Switch.get/setState callbacks may throw errors, as described in the corresponding UML charts above.

5.3.17.7 The Environment.isTileSupported() Callback

Figure 21 - State Chart of the Environment.isTileSupported() Callback.

The Environment.isTileSupported callback workflow is shown in Figure 21 - State Chart of the Environment.isTileSupported() Callback.

The user is assumed to have obtained the identifier of the tile of interest.

The callback terminates successfully (i.e., denoting that a tile is indeed supported by the API, based on the data present in the configuration Database), if the tile identifier is found within the Tiles table.

This function assumes that the database itself is well-formed and does not contain logical errors. (This is described in D2.2).

If any communication error occurs (e.g., timeout or network error during the communication with the database), a ConnectionError is raised and handled by the InterruptHandler.

5.4 The Gateway External Communication Protocol

The HyperSurface Gateway will communicate with the “external World”, that is the External Caller, through a Wireless Communication Protocol. This protocol may be based on Bluetooth/BLE or other wireless Protocol that will be decided at the time of the implementation. The protocol will provide the required performance and robustness to serve the specific HyperSurface Tile Communication needs.



5.4.1 Communication Establishment

The Communication between the two sides will be established through a pairing mechanism. Figure 22: and Figure 23: show the pairing process workflow from the external Caller UI and the GW perspective, respectively.

Figure 22: State Chart of the External GW Communication Establishment - External Caller side

Figure 23: State Chart of the External GW Communication Establishment - Hyper Surface GW side

As soon as the communication is established, the HyperSurface GW enters an Idle State in which it is waiting either for a command from the external Caller or a report/interrupt from the HyperSurface Controller Network. Further to the Commands Execution processes presented in previous sections, Figure 24: demonstrates in more detail the external Commands Handling mechanism on the HyperSurface GW. More specifically, each external command coming to the GW is analyzed and a set of internal Commands (to be sent to the controller network – see next section) is extracted accordingly. Commands Builder is responsible for this process. Then the extracted list of commands passes to the Commands Sequencing and Prioritizing controller in which a proper sorting is performed based on specific rules which will be defined accordingly. Finally, the sorted list passes to the Commands Execution Handler which is responsible for executing (i.e., sending to the controller Network) each command sequentially. The sequencing and prioritizing of the commands to be sent by the GW will be further analyzed in conjunction with the adopted intra-tile communication protocol. During the whole process, any error raised is automatically reported to the external Handler. Also the results and statuses of the commands execution is also properly reported.



Figure 24: State Chart of the external Commands handling process of the HyperSurface GW

5.5 The Gateway Internal Communication Protocol

The HyperSurface Internal Communication Protocol consists of a wired protocol that is fully customized to handle all specific requirements as well as functionalities of the hardware switch elements and network controllers. Hence, the exact commands and routing parameters of the internal communication protocol cannot be fully described or analyzed until the final form of the hardware switch elements are available. However, an initial study is described in D2.3.

In general, the internal communication (intra-tile) will be realized by utilizing dedicated data packets that will ensure high performance and robustness. The packet structure is shown in Figure 25. All internal commands (see Section 5.4) are represented using one data packet. Status and Error reports as well as acknowledgments coming from the controller network are also given in the form of a data packet. Indicatively, a generic Data Packet is shown below in Figure 25. For a more detailed discussion, see D2.3. Since there is a tradeoff between controller complexity, packet overhead and robustness, some fields are indicated as optional. Their detailed study will be included in D2.5.

Start Packet

Delimiter Dest ID

Source ID (optional)

Packet SN (optional)

Packet type and

CTRL

Data Payload

Error checking

Figure 25: Indicative internal Communication Protocol Data Packet



A packet includes a Dest ID (and optionally a Source ID). These fields will be used by the intermediate controllers in order to properly route the packet to its destination.

Each packet has a unique SerialSequence Number. This number can be utilized to handle timing issues during communication. This is because the HyperSurface controllers and switch elements have no clock capabilities and thus processes pertaining to time will be controlled by the GW. The SerialSequence number may also be used for the Command Acknowledgment identification by the GW.

Packet type and CTRL data will be used to define the exact action that needs to be performed by the receiver or an intermediate controller based on the specific command. These Bytesfield are firstly checked by each controller on the packet reception process.

Data Payload includes additional information/details regarding the exact command to be executed. In the case of ACK it can also contain information about the statuses of the node controllers and the HyperSurface.

Error checking trailing bits are used to ensure robustness of communication. In the case of a CRC error a packet re-transmit may be requested by the controller node.

As presented in previous sections, the communication between the GW and the network Controller(s) is performed using acknowledgments for every command (data packet). Acknowledgments are given in the same packet form and are generated by the network controller nodes for each packet received and for each intermediate action. In this way the process of transferring/communicating data inside the Switch Elements Controllers network is fully controlled by the GW. The latter is responsible for reporting statuses and errors to the External Error Handler. The indicative procedure of internal communication during a Command Execution is presented in Figure 26. The diagram shows each procedure step in case of fault detection, successful execution, and Execution Timeout events



Figure 26: Indicative Command Execution Sequence Diagram

Figure 27 shows a Sequence Diagram that describes the interaction between the components of two intra-tile controllers (the sender and the receiver) during the transmission of the bits of the data packet. The hardware for the communication is done using three asynchronous signals that interconnect the sender output channel

Figure 27 : Sequence Diagram: Intra-tile controller communication.



component and the receiver input channel component: data signal, req signal, and ack signal. The sender output channel component asynchronously sets the data line to the value of the sent bit. It then asynchronously sets the req signal to 1. Then the receiver input channel reads the data signal and sends its value to the receiver input buffer to be stored. After the data bit is stored, the receiver input channel sets the ack line to 1. The values of the two lines are then asynchronously reset, where the sender output channel sets the req signal to 0 and the receiver input channel sets the ack signal to 0. The entire sequence is repeatedly performed until all the bits of the packet to be transmitted are stored in the receiver input buffer and the state of the req and ack signals are reset (thereby becoming ready for the next packet transmission).

In Figure 28 there is a Statechart diagram that describes the states of the intra-tile controller during its operation. Assume that the intra-tile controller holds in its memory the x and y coordinates (xAddr and yAddr), the size of the grid (size), and the intra-tile controller orientation (orientation).

When the intra-tile controller initially begins computation, the internal memory is not set as in state On_Receive_Address. In the initial configuration an addressing protocol

is responsible for sending either through input1 or input2 a packet that contains addressing information. Following the protocol, the intra-tile controller transits to state Received_Address. The state checks if the packet is of addressing type and proceeds by setting its x and y coordinates and by computing its orientation. The next state of the intra-tile controller is On_Receive where it waits on input channels input1 and input2 for a configuration packet. From the state On_Receive the intra-tile controller transits to state process packet whenever it receives a message. If the packet is a configuration packet, then the controller checks for the type of the packet. Additionally it checks for the destination of the packet. If the packet is not addressed to the current intra-tile controller, then the controller transits to state On_send where the packet is prepared for routing by calculating the output channel to be transmitted. The On_send state transitions by sending the packet either on outpu1 or output2 and returns to the On_Receive state. When on the Process Packet state if the receiver intra-tile controller is the packet target then the controller transits to the Actuate state. In the Actuate state the controller sets the meta-material strips and then prepares an

Figure 28 : Statechart Diagram: Intra-tile controller.



acknowledgement packet to be sent to the gateway. The send is done by transitioning to state On_send and following the interaction accordingly.



6 Conclusion

The present documented described the HyperSurface Application Programming Interface (API) structure, as envisioned by M12. The API seeks to serve as a strong layer of abstraction, hiding the HyperSurface physics, allowing a non-specialist software developer to interact programmatically with it and create new applications.

The present document provided a qualitative description of the HyperSurface operation, and defined a model to represent it using software terms. UML descriptions were supplied, ranging from high-level use cases to detailed Class and Database diagrams.

The API will be revised, updated and maintain throughout the project, adapting to the maturity level of the electromagnetic design (WP1) and electronic controller development (WP3) actions.



7 References

[1] Adnan Aijaz, Meryem Simsek, Mischa Dohler, Gerhard Fettweis: Shaping 5G for the Tactile

Internet in 5G Mobile Communications. Springer, 2017.

[2] Paul Ferrand, Mustapha Amara, Stefan Valentin, Maxime Guillaud: “Trends and challenges

in wireless channel modeling for evolving radio access”, IEEE Communications Magazine, pp.

93—99, 2016.

[3] Bo Han, Vijay Gopalakrishnan, Lusheng Ji, Seungjoon Lee: “Network function

virtualization: Challenges and opportunities for innovations”, IEEE Communications

Magazine, pp. 90—97, 2015.

[4] S. Han, K. G. Shin: Enhancing Wireless Performance Using Reflectors in INFOCOM 2017.

[5] Kao-Cheng Huang, Zhaocheng Wang: Millimeter wave communication systems. Wiley,

2011.

[6] Younsun Kim, Hyoungju Ji, Juho Lee, Young-Han Nam, Boon Loong Ng, Ioannis Tzanidis,

Yang Li, Jianzhong Zhang: “Full dimension mimo (FD-MIMO): the next evolution of MIMO in

LTE systems”, IEEE Wireless Communications, pp. 26—33, 2014.

[7] Seung Hoon Lee, Muhan Choi, Teun-Teun Kim, Seungwoo Lee, Ming Liu, Xiaobo Yin, Hong

Kyw Choi, Seung S. Lee, Choon-Gi Choi, Sung-Yool Choi, Xiang Zhang, Bumki Min: “Switching

terahertz waves with gate-controlled active graphene metamaterials”, Nature Materials, pp.

936—941, 2012.

[8] Daecheon Lim, Dongju Lee, Sungjoon Lim: “Angle- and Polarization-Insensitive

Metamaterial Absorber using Via Array”, Scientific reports, pp. 39686, 2016.

[9] S. Lucyszyn: Advanced RF MelectromagneticS. Cambridge University Press, 2010.

[10] Alexander E. Minovich, Andrey E. Miroshnichenko, Anton Y. Bykov, Tatiana V. Murzina,

Dragomir N. Neshev, Yuri S. Kivshar: “Functional and nonlinear optical metasurfaces: Optical

metasurfaces”, Laser & Photonics Reviews, pp. 195—213, 2015.

[11] Marvin K. Simon, Mohamed-Slim Alouini: Digital communication over fading channels.

John Wiley & Sons, 2005.

[12] The~VISORSURF~project: “A Hardware Platform for Software-driven Functional

Metasurfaces”, Horizon 2020 Future Emerging Technologies, 2017. URL .



[13] Christos Verikoukis, Roberto Minerva, Mohsen Guizani, Soumya Kanti Datta, Yen-Kuang

Chen, Hausi A. Muller: “Internet of Things: Part 2”, IEEE Communications Magazine, pp.

114—115, 2017.

[14] Cheng-Xiang Wang, Xuemin Hong, Xiaohu Ge, Xiang Cheng, Gong Zhang, John

Thompson: “Cooperative MIMO channel models: A survey”, IEEE Communications

Magazine, 2010.

[15] Alexander Y. Zhu, Arseniy I. Kuznetsov, Boris Luk'yanchuk, Nader Engheta, Patrice Genevet: “Traditional and emerging materials for optical metasurfaces”,

a hardware platform for software-driven functional ...argouml is a free software that is distributed...

Documents