\documentclass[12pt,twoside]{article}
\usepackage[utf8]{inputenc} % apparemment utf8x est mieux qu’utf8 mais c'est incompatible avec biblatex...
\usepackage[T1]{fontenc}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{amsfonts}
\usepackage{textcomp}
% \usepackage[style=numeric,backend=biber]{biblatex}
\usepackage{csquotes}
\usepackage[english]{babel}
\usepackage[pdftex]{hyperref}
\usepackage{verbatim}
\usepackage{alltt}
\usepackage{hhline}
\usepackage{lmodern}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage[a4paper,margin=2cm]{geometry}
% \usepackage[letterpaper,margin=2cm]{geometry}
% \usepackage[hmarginratio=1:1]{geometry}
\usepackage{listings}
\usepackage{float}
\usepackage{url}
\usepackage{tabularx}
\usepackage{calc}
% \usepackage[scaled]{luximono} % des fontes "tt" avec gras et italique
  % /!\ Fontes non dispos sous debian!  Faire:
  % # wget http://tug.org/fonts/getnonfreefonts/install-getnonfreefonts
  % # texlua install-getnonfreefonts
  % # getnonfreefonts -a
  % # getnonfreefonts-sys -a
  % # texhash
  % # rm install-getnonfreefonts
\usepackage{xspace}
% \usepackage{garamondx}
% \usepackage{slantsc}	% des fontes small caps penchées
\usepackage{wasysym}

% \bibliography{labo}


\newcommand{\xAAL}{\textsc{xAAL}\xspace}

\begin{document}

\title{A brief introduction to \xAAL v0.2}

\author{Jérôme Kerdreux \and Maria Teresa Segarra \and Philippe Tanguy \and Christophe Lohr}

\maketitle

\begin{abstract}
This paper gives a brief description of \xAAL such defined by the IHSEV/HAAL
team of Telecom Bretagne and its status in 2014.

Be aware that this is an ongoing work.
\end{abstract}


\section{Motivation} 

Many vendors offer home-automation solutions.  Small devices are plugged
everywhere at home.  They talk to each other using dedicated link layers and
protocols (powerline channels, radio channels, etc.).  There are almost as many
home automation protocols as manufacturers (or alliances of manufacturers). 
The consequence is a strong issue about interoperability: how to make a
device from vendor A (e.g.  a switch) talking with a device from vendor B
(e.g.  a lamp)?

Solutions exist to address the interoperability issues (the state-of-the-art
is not presented in this document).  All solutions play around the idea of a
so-called \emph{gateway}: a box (a small computer) is equipped with two or
more modules, each module talking a given home-automation protocol; then a
piece of software over those modules make it possible to forward messages
between protocol A and protocol B.  Moreover those boxes embed additional
functions to make all of this usable: HMI (via web and/or smartphones),
configuration facilities, connectors to extra services in the cloud, etc. 
Such solutions are however partial from the interoperability point of view 
since those boxes are hardly able to talk to each other.

Starting from those basements we decided to reorganize and formalize
architectures of those boxes, which are in fact all composed of the same
functionalities.  So, we propose to split functionalities into well defined
functional entities, communicating to each other via a messages bus over IP. 
Each entity may have multiple instances, may be shared between several
boxes, and may be physically located on any box.  As a result, the \xAAL
system will be interoperable by design (hopefully).



\section{General Architecture}
The \xAAL system uses an IP \emph{multicast bus} (IPv4 or IPv6).
It is basically a distributed architecture: the functions described below
may be present several times, be implemented and grouped into 
hardware components of various manners, and talk to each others via the
\xAAL bus.

There are several advantages to a communication by way of a bus:
\begin{itemize}
\item Do not have to handle a large set of point-to-point communications,
  which saves resources within devices.

\item A bus allows the \emph{discovery}: when a new component appears in the
  installation, it announces itself.  All other entities can then take it
  into account.  Similarly, when a new component enters, it can query the
  bus to discover the other components already present.  This greatly
  facilitates the configuration, allows dynamicity as well as the evolution
  capacities of the system.
\end{itemize}


\subsection{Functional Architecture}
Figure \ref{archi} shows the general functional architecture of the \xAAL
system.

\begin{figure}
\centering
\includegraphics[width=0.8\linewidth]{bus-xaal_devices}\\[4ex]
\includegraphics[width=0.8\linewidth]{bus-xaal_databases}\\[4ex]
\includegraphics[width=0.8\linewidth]{bus-xaal_activators}
\caption{Functional Architecture of \xAAL.\label{archi}}
\end{figure}



\paragraph{Native Equipments.}
  Some home automation devices (sensors, actuators) can communicate natively
  using the \xAAL protocol.

\paragraph{Gateways.}
  In general, the home automation devices only support their own proprietary
  communication protocol. 
  Therefore, \emph{gateways} will have the responsibility to translate
  messages between the manufacturer protocols and the \xAAL protocol.

  At this level it is assumed that, within an installation, there are as many
  gateways as manufacturer protocols used in the building.

  According to the technologies and the manufacturer protocols, each gateway
  will handle the following issues: pairing between the gateway and devices,
  addresses of devices, configuration, and the persistence of the
  configuration.

  Note that it may be interesting to be able to query a gateway about the
  mapping between \xAAL addresses and manufacturers addresses of devices. 
  The mapping information given by the gateway may be useful for the
  configuration of the database of metadata (described below).  Indeed,
  during the configuration, the installer usually notes the manufacturer
  physical address of devices with their location in the house.  To
  facilitate the configuration of this database (location information
  associated with the \xAAL address of devices), it may be interesting, at
  the beginning, to look at the manufacturer identifier or address of the
  devices.

\paragraph{Schemas Repository.}
  The home automation devices are all described by a \emph{schema} (the 
  nature of the equipment, how to interact with it). These schemas are
  listed in one or more \emph{schemas repositories}.

  Like schemas repositories are \xAAL devices they are present on the \xAAL
  bus.  Other entities query them via this bus to get schemas describing
  others devices (whenever those devices are active or not on the bus).


  \begin{itemize}
  \item One queries registry on a schema name. If known, it returns an 
    URL where the content of the schema can be downloaded.
  \item Associated with a schema, in addition to the description of the
    device itself, there may be metadata: language used for 
    descriptions, date or version number, an URL for documentation, 
    an URL for an HMI (links to html fragments, possibly hosted somewhere
    else on the Internet), etc., an URL for update, etc.
  \item Note that the registry is also described itself by a schema (to
   be drafted). This schema describes how to advertise schemas (so it is a 
   little meta...)
  \end{itemize}

  In a given installation, there may be zero or more schemas repository
  talking on the \xAAL bus.

  The schema definition of a device must be especially careful.  A number of
  general purpose schemas are to be specified by our ``\xAAL International
  Bureau of Standardization'' \smiley.  More specific schemas may be further
  defined by the manufacturers themselves.

  Consequently, there can be conflicts: given a schema name, several
  registries on the bus could return schemes having divergent descriptions.

  Then, it is necessary to plan a mechanism for conflict resolution: either
  in a static way (where an administrator invalidate or delete conflicting
  schemas in a register), or dynamically (where registers spread  priority
  information in addition to schemas; letting receivers to short schemas).
  This point has not yet been decided in the current specification.

  Furthermore, one can consider several ways to update these schemas: via
  the \xAAL bus itself, or by Internet (the register is going to download
  updates about schemas at addresses that we shall have indicated to it), or
  by an other means (installation CD, etc.). Also, this point must be 
  afterward clarified.


\paragraph{Database of Metadatas.}
  Each automation device within a facility is likely to be associated to a
  piece of information:  at least location information (e.g. declare that the
  equipment typed as a lamp and having address X is located in the kitchen), 
  and possibly a symbolic name (e.g. device having address X is called 
  "lamp\#1").

  All this information is grouped in a \emph{database of metadata}.
  For openness and extensibility (as flexibility and not in the
  sense scalability), this information is stored as a set of tags.

  This database contains somehow the configuration of home automation
  installed.

  The database of metadata is present on the \xAAL bus. Other \xAAL devices
  can query it via this bus to obtain tags associated to the identifier of a
  device, or conversely a list of devices associated with one or more tags.


  \begin{itemize}
  \item For each device, the database is fed with information: its \xAAL
    address, its type and a set of tags.
  \item Information can be added, updated or deleted.
  \item One can question it on tags associated to a device.
  \item One can question it on devices associated on some tags or types.
  \item One can question it on existing tags or known types.
  \item Note that a device may be known by the database without being
    actually present on the bus. 
    (The presence is managed in a different way.)
  \end{itemize}

  There should be at least one database of metadata on the bus. There could
  be several.  

  The creation of this database must be established with the greatest
  care.  It will thus be advisable to implement the classic mechanisms of
  organization of tags (or quality of data): check inconsistencies,
  synonyms, ambiguities, provide facilities renaming tags, etc.  For
  instance, the classic trap is to specify location information in two
  places, for example indicate a \emph{friendly name} tag "living-room lamp", 
  then add a \emph{location} tag "living-room" (by chance in this case,
  information is redundant but convergent...)

  Note: this notion of friendly name can be found in UPnP... In fact this
  mechanism is a source of problems: either it is diverted from its initial 
  role to put location information as in the previous example, or it is
  left to the manufacturer value (how many DLNA TV or smartphones have for
  friendly name \emph{Media Server}?...)
  

\paragraph{Cache.}
  Unidirectional sensors are quite common: one can not question them, they
  just send their information in a sporadic way.  (E.g.  A thermometer which
  sends the temperature only if it changed.)

  So, there should be at least one cache on the \xAAL bus that stores this 
  information so that other entities can query it whenever necessary.

  Such a cache should store at least the notifications sent by the devices. 
  One can further wonder about the relevance of recording messages of type
  command/response.

  As in any caching mechanism, it is necessary to associate a timestamp to
  cached information.  When another entity on the \xAAL bus asks the cache
  for information, it also gets the age of the cached information, and
  decides by itself if it is good enough or not.
  This is not the responsibility of the cache to manage the relevance of
  data according to their age, this is the responsibility of the client that
  makes the request.

  Again, incoherencies may arise if two caches return information that has
  the same timestamp but divergent values.  We assume that this phenomenon
  is a priori very rare.  Consequently we do not intend to define a
  particular mechanism to manage incoherencies.  Only the client entity is
  in charge of sorting received information according to its own criteria.


\paragraph{Automaton of Scenarios.} 
  Scenarios are advanced home automation services like for example: start a
  whole sequence of actions from a click of the user, or at scheduled times,
  or monitor sequences of events and then react, etc.

  To do this, \xAAL proposes to support it by one or more entities of the
  type \emph{automaton of scenarios}.

  These automatons of scenarios are also the right place to implement
  virtual devices: for example a scenario could aggregate and correlate a
  variety of events from real devices, and then synthesizes information such
  as "presence" and notify it on the bus, in order to be used by other
  entities.  By proceeding in this way, this scenario should appear by
  itself as a device on the bus, with its address and its schema.  This
  scenario is a kind of virtual device.

  As usual, there may be inconsistencies, conflicts or deadlock between
  scenarios (one turns on the light, the other off).  This is not the \xAAL
  specification itself which is going to prevent it.  Conflicts are supposed
  to be treated as far as possible off-line when editing scenarios.  The
  specification does not require the use of a model-checker based on colored
  timed Petri network or anything like this...  It remains a research
  subject, certainly very interesting, but outside the framework of
  specifying \xAAL.  (If anyone wants it, it can introduce a monitoring
  device, which is itself a kind of engine of little particular scenarios.)


\paragraph{User Interfaces.}
  One or many  user interfaces are provided by specific entities connected
  to the \xAAL bus.  This can be a real hardware device with a screen and
  buttons; or a software component that generates Web pages (for instance)
  to be used by a browser on a PC, a connected TV, or whatever; or software
  that provides a REST API for mobile applications (tablets, smartphones),
  to an external server on the cloud for advanced services, to an MQTT
  server, or to offer features for service composition, etc.

  Even there, it seems natural to be able to arrange several user interfaces
  (smartphone, tablet, remote control, etc.) within a home automation
  system.


\paragraph{Synthesis.}
Such a functional architecture allows managing the dynamic aspects of the
infrastructure (modularity, scalability, adaptation, etc.).  Thus, advanced
functions such as HMI or automaton of scenarios can adapt themselves
automatically to the infrastructure and to its modifications (if equipment
enters / leave, if one fails or is replaced, etc.).

The typical work flow of an HMI could be:
\begin{enumerate}
\item query the bus to be aware of the present devices;
\item query the schema repository for the type of these devices, the type
  of data from the sensors / actuators, the possible actions, URLs to
  retrieve icons;
\item query the database of metadata about devices to get the configuration
  of the installation (a friendly name to display, location and other tags
  associated with each device);
\item query the cache for the latest known states of such equipment;
\item dynamically build display screens and control interfaces for these
  devices.
\end{enumerate}




\subsection{Hardware Architecture}
The interest of such a functional distributed architecture is to allow
greater freedom regarding the placement and grouping functions on hardware.

For example:
\begin{itemize}
\item A manufacturer of automation equipment could sell a \emph{box} that 
  would include: the gateway for its own home automation protocol, the 
  repository of schema for equipment of its brand, a cache for equipment
  managed by the gateway, some automaton of scenarios to implement 
  virtual devices, and a small metadata database for its own devices to 
  record their location.

\item A provider of automation services could sell a \emph{box} (different 
  from and complementary to the first one) that would include: a database
  for location of devices, automaton of scenarios, web interfaces,
  REST connectors to communicate with servers in the cloud to offer enriched
  services, etc.

\item A provider of virtual services (i.e selling only service and no
  equipment) could provide an application for smartphone or tablet
  that embarks: a user interface, an automaton of scenarios, a connector
  to its external servers for advanced services, etc.

\item A provider of services dedicated (for instance) to assistance for
  seniors, telemedecine, etc.  could offer its box (yet another) that would
  include: a gateway for specific equipment (medical, remote alarm, etc.),
  automatons of scenarios for monitoring\&alert, an interface to its
  external servers, etc.

\item A manufacturer of innovative connected objects (Internet of Things) 
  could sell these connected objects which would embark: the sensor/actuator
  component itself speaking natively in \xAAL, the repository of schema
  describing the object itself, automatons of scenarios, an interface to its
  external servers, etc.
 
\item Services or scenarios a bit complicated (e.g. based on actigraphy, or
  composition of adaptive services, etc.) could be made of automatons of
  scenarios, linked to a cache, linked to a database of metadata.

\end{itemize}


The reliance on IP as a means of interconnection and this lightweight
protocol allows, hopefully, flexibility and better interoperability between
these different actors who have nothing else than \xAAL message to disclose
to competition.

The really hard point is the definition of schemas and the rigor with which 
implementations comply with.



\section{The Transport Layer}
It uses IP multicast (IPv4 and/or IPv6). Thus, it is in UDP.

\begin{itemize}
\item The multicast IP address has to be defined.
\item The port number has to be defined. We reserve a range of ports
  numbers.
\item If there are several "home networks" in the building, they use
  different ports.

\item Messages will have a size limited by UDP (i.e. 65507 bytes in IPv4). 
  IP fragmentation operates normally.  (As opposed to approaches such as xPL
  that limit to the MTU (1500 bytes) and propose \emph{continue} flags.  IP
  fragmentation already handles this very well.) Remains the problem that
  some PICs do not necessarily manage well the IP fragmentation (e.g.  the
  basic IP stack for Arduino).  We only recommend trying to be limited to
  1500 bytes.  If services are willing to exchange larger amounts of data
  between devices, they are asked to leave the automation bus (which is not
  made for it) in favor of another transmission channel (e.g.  A TCP
  connection), that they can advertise via the \xAAL bus.

\item The IP configuration of devices is outside the scope of \xAAL.
  Equipment can use a static IP configuration, DHCP, the IPv6 Router
  Advertisement, Zeroconf, a Link-Local address (169.254.0.0/16, fe80::/64), 
  etc.

  Note however that thanks to the use of a multicast bus, the source address
  of the transmitters doesn't really matter (and is actually not used in
  our case).  Some equipment might be configured with a phony hard-coded IP
  address...

\item Note for developers: please avoid horrible stuff that have been seen
  with implementations of xPL or XAP buses (often in Java or .Net) regarding
  the use of a "hub": that piece of software that repeats messages from bus
  to applications running the same machine.  This is useless on almost all
  current operating systems: applications on the same machine may without
  problem have their own socket on the multicast bus, as long as dedicated
  socket options are used (typically \texttt{SO\_REUSEADDR} and
  \texttt{IP\_MULTICAST\_LOOP})...

\item The choice of IP multicast IP almost imposes the UDP protocol.  As UDP
  does not manage the detection of packet loss and retransmissions, there
  could have been more comfortable to choose TCP.  For people not convince
  by the UDP protocol:

  In the context of a network at home, it can be assumed that packet loss,
  though still possible, is a priori rather rare.

  By design, \xAAL has little requirements regarding error processing (cf.
  \ref{cas_erreur}). From this point of view \xAAL seems rather robust.

  Using TCP to manage packet loss only shifts the problem to the protocol
  stack (and in a heavy way: it is systematic for all messages, and the TCP
  automaton TCP consumes resources). With \xAAL, if one need error
  processing for some scenarios (which, finally, is not necessarily 
  systematically required) this will be at the services layer (located on 
  equipment which generally has comfortable resources).

\end{itemize}


\section{The Data Presentation Layer}
It is a question of deciding if the data transmitted by the \xAAL bus are
rather of textual nature or either of binary nature.

This point was the object of a debate within the team, where two schools of
thought wonder.


\subsection{The \emph{Binary Protocol} approach}
The main motivation is to stay at a low level: a protocol which can be coded
within a PIC (e.g.  in traditional C), rather than a sophisticated
middleware coming from the PC world and web applications.

It does not necessarily mean compact or compress messages, but simple
messages easy to write and parse (by cast to C data structures),
self-sufficient, in a constrained format, with a constraint variability, a
predictable size, etc.

More concretely we would decide to only manipulate 32-bit words, aligned on
32-bit (i.e.  with padding if necessary).

The disadvantage is that the debugging stage of messages is more complicated
than a textual approach, because a validation tool for analyzing the
exchanged frames is needed.  The other drawback and that it is too far from
trendy techno (around Web), and it will be a priori more difficult to entice
a community.

Finally, this is not the approach that was chosen by the team for the
implementation of \xAAL.  However, a draft of specification has been defined
and is available on request, this is the \emph{version 0.1-bin}.

In the future it might be interesting to look at the Mihini/M3DA protocol to
do this...


\subsection{The \emph{Text-Based Protocol} approach}
The advantage of a text-based protocol is that developers only need to check
the frames exchanged.

The disadvantage is that the messages are more complex to build, and even
more complicated to parse.

The adopted compromise was to choose Json as exchange format of data.
Many libraries are available in many development environments.

Furthermore, it is rather close to the Web World, and as the last
generations of IT specialists were massively and firstly formed to the
technologies of the Web, we can hope for a better membership with this
public, as well as with certain public of decision-makers...

This approach was experimented in the previous implementations of \xAAL made
by the team (\emph{version 0.1-json}).  The specifications in the following
document are based on a text protocol approach and extend to describe the
current \emph{version 0.2}.

An interesting variant would be to use certain aspects of
CoAP\footnote{\url{https://datatracker.ietf.org/doc/draft-ietf-core-coap/}}
(or a subset)... To consider for the future... even if the proximity to the 
Web World appears nevertheless of a limited technical interest...


\section{Definition of a device}\label{def_device}
A \emph{device} has:
\begin{itemize}
\item a \texttt{devType}: references the \emph{schema} and defines the type
  of the device.  It is hard-coded into the device.
  
  \begin{itemize}
  \item This schema identifier is a string consisting of a pair of words
    separated by a dot.
    \begin{itemize}
    \item The first word refers to a class of device type (e.g. lighting,
      heating, multimedia, etc.).
    \item The second word refers to a type in a given class (e.g. within
      the lighting class one may have an on-off lamp, a lamp with dimmer, a 
      mirror ball, etc.). The second word may also refer a schema extension 
      by a manufacturer (cf. \ref{heritage_schemas}).
    \end{itemize}
  \item The identifier \texttt{"any.any"} is reserved and refers to all
    types of all classes.
  \item And for example the pair \texttt{"lamp.any"} means all types of
    the class \texttt{"lamp"}.
  \item We reserve a special name: \texttt{"experimental"}, for the
    class, as well as the type.
    (I.e. When someone makes a device but has not got a name for our 
    \xAAL International Standardization Office.) 
  \end{itemize}

\item An \texttt{address}: a device ID, unique on the bus.

  \begin{itemize}
  \item The device identifier is a UUID (RFC 4122): the textual
    representation of a 128-bit random number.\\
    For instance: \texttt{634c4471-bc3e-47f2-8cd3-eadfc08c6c6a}
  \item Address \texttt{00000000-0000-0000-0000-000000000000} is reserved. 
    This is the broadcast address and refers to all devices.
  \item How is assigned an address?
    \begin{itemize}
    \item Either, this is hard-coded in the factory.
    \item Auto-generated (random)  at the time of installation.
      However it is recommended that this address remain persistent: i.e.
      please save it (if possible) during power breaks.
    \item There are in principle very high probability of having no collision
      of UUIDs.  However, it is technically possible to verify that an UUID
      is not already used on the bus by a kind of "Gratuitous ARP", i.e.  by
      \texttt{isAlive} requests to ensure that no one else already use this
      address.
    \item But certainly not assigned by a bus supervisor or something like
      that!
   \end{itemize}
  \end{itemize}

\item An equipment may consist of several devices. This is typically the
  case of a gateway. (E.g. An equipment which is going to make the bridge
  between our \xAAL bus and X10, Zigbee, X2D, Z-Wave, HomeEasy, KeeLoq,
  etc.)  But it may also be the case of a small weather station with several
  sensors that measures indoor/outdoor temperature, humidity, etc.
  \begin{itemize}
  \item Such equipment is then called a \emph{composite device},
  \item and each of its components is an \emph{embedded device}.
  \item The composite device announces (possibly) itself on the bus with its
    own address and its own schema name. Others can interact with him
    specifically  (e.g. for its configuration, consult battery level, etc.).
    It also announces the list of its embedded (their address).
  \item Each embedded is also announced on the \xAAL bus like an ordinary 
    bus-native device, with its own address and its own schema name. Embedded
    may be question about their parent, i.e. the composite to which they are
    linked. (Note: the real bus-native devices have as parent=0).
  \item A composite device can also choose to be not visible, do not announce
    itself, nor indicates that it has embedded devices, nor that those 
    embedded devices have it for parent.
  \end{itemize}
\end{itemize}


 
\section{Defining a Schema (the type of device)}\label{ref_schema}
Each device is typed, i.e. described by a \emph{schema}.  Those schemas are
inspired by the UPnP
approach.\footnote{\url{http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf},
chapter 2.}.  We have not yet defined the dialect to write these schemas. 
Presumably it will be XML (one still need to write the DTD), or the so
called \emph{JSON Schema}\footnote{\url{http://json-schema.org/}} (assuming
that the proposed draft becomes an RFC).

\begin{itemize}
\item The schema provides a bit of a semantic to a device and describes
  its capabilities: a list of possible methods on this device (mechanism of
  request-response), a list of notifications that it emits spontaneously, 
  and a list of state variables (a device announces any change of values on 
  the bus).

\item A list of \emph{methods}. Each method is described by:
  \begin{itemize}
  \item a unique name which identifies it within the schema;
  \item a textual description (see later how to handle the language and
    issues of internationalization);
  \item A list of arguments, each argument is defined by:
    \begin{itemize}
    \item a name
    \item a direction (in/out)
    \item the unit (in the sense of the International Bureau of Weights and
      Measures...)
    \item a description
    \end{itemize}
  \end{itemize}

\item A list of \emph{notifications}. Notifications are messages that the
  device emits by itself on the bus. These notifications are defined by:
  \begin{itemize}
  \item a name
  \item a description
  \item a list of variables (name, unit)
  \end{itemize}

\item A list of \emph{state variables}.  If the value changes, it generates
  by default a notification on the bus. (Note that a device may also be 
  composed of a number of additional internal variables that are not 
  monitored and are not subject to notification...) Each state variable is 
  defined by:
  \begin{itemize}
  \item a name
  \item a description
  \item the unit
  \item a default value (?)
  \end{itemize}
\end{itemize}


\subsection{Inheritance of schemas} \label{heritage_schemas}
There is a notion of inheritance between schemas. A schema can extend an
existing schema. We define the first 3 levels of this genealogy:

\begin{enumerate}
\item A generic schema common to all existing devices of the world that
  everyone has to implement.

\item A specific schema for every class (e.g. \emph{lamp},
  \emph{thermometer}, \emph{switch}, etc.). Such specific schemas thus
  inherit from the generic schema.

\item A specific schema for each type that inherits from a class schema,
  which indicates the level of functionality (e.g. a lamp type can be on/off,
  some are of a trigger type, and others with dimmer...)

\item Thereafter, manufacturers of home automation equipment will naturally
  define their own schemas among their product range. However, it is
  forbidden for these manufacturer schemas to be defined as level 1 schemas
  (the generic schema is the only one), or as level 2 schemas (class schemas).
  Schemas from manufacturer are necessarily extensions of schema from level 2
  or higher. About the naming of schema (the pointed pair described in
  \ref{def_device}), the second word is then left with the discretion of the
  manufacturer. (Manufacturers frustrated by this situation are cordially
  invited to discuss with our Standardization Office if they wish to 
  introduce new schema at level 2 or 3.)
\end{enumerate}

Note: please think, while listing the APIs of devices described by these
schemas, that some devices will not be able to listen to the bus and will
only emit notifications changes of their state variables.


\subsection{Naming of Schemas}
The naming of schemas has to be done carefully in order to maintain as much
as possible the consistency of things in the minds of everyone...  In too
many systems (e.g.  xAP xPL), the name of devices and their typing is
regularly misused to put concepts that do not have their place in it.

\paragraph{What is a schema.}
Two things: It is hoped that the schema name refers above all to the
functionality of the device, means to interact with it.  Secondary, this
name must also give an idea of the nature of the sensor.

\paragraph{What is not a schema.}
\begin{itemize}
\item The name is not supposed to refer to a technology of manufacturer
  (and even less to a specific model).

\item The schema name must not refer to a given use: a door contact switch
  (that transmits "open/closed" notifications) can be used both for
  safety (on windows or on the main door) as well as for actigraphy (on
  kitchen drawers); in the same way a thermometer (that sends notifications
  of temperature) may be dedicated to a weather station or to the management
  of heating.  So there are no reasons to have categories like
  \emph{security} or \emph{hvac} (Heating, Ventilation and
  Air-Conditioning)!  This are chapters in a catalog of sale of a
  manufacturer, not categories of functions of home automation equipment. 
  If wanted, the role associated with a sensor (security, heating, etc.) is
  recorded as a tag in the metadata database.

\item One shall avoid carefully junk categories such as the "software" type
  (that already is seeing!). Obviously there will be a number of software 
  components. Also, some equipment will be purely software (e.g. an 
  application such as a web-radio on a PC). The fact that the component is 
  in soft rather than in hard has no interest from the \xAAL point of view.
\end{itemize}


\section{Generic Schema}
This is the basement of every schema. All other schemas have to inherit from
it somehow.

\begin{itemize}
\item Internal parameters:
  \begin{itemize}
  \item \texttt{devType}: the name of the schema to which the device obeys;
  \item \texttt{address}: a string, an UUID (the address of the device);
  \item \texttt{parent}: a string, an UUID (the address of the parent in the
    case of a composite, or 0 if not);
  \item \texttt{busAddr}: a string specifying the IPv4 or IPv6 address of
    the \xAAL bus used by the device.  Well, this value is obvious since one
    is talking to the device via this bus;
  \item \texttt{busPort}: an unsigned integer (well, limited to 65535),
    indicating the UDP port of \xAAL bus;
  \item \texttt{TTL}: an 8-bit unsigned integer indicating the TTL used for
    sending multicast packets;
  \item \texttt{key}: a string, the cryptographic key for encrypted 
    communications.
  \end{itemize}

\item State variable:
  \begin{itemize}
  \item \texttt{ciphers}: a table of string among \texttt{"none" "md5"
    "sha256" ...}, the list of supported ciphers.
%   \item None imposed by the generic schema
  \end{itemize}

\item Notification:
  \begin{itemize}
  \item \texttt{alive}: emitted when starting the device and then
    periodically at a rate left to the discretion of the device. The
    notification message contains no parameters, the \emph{body} is empty.
    (See the definition of messages below.)
  \item \texttt{stateChange}: emitted at every change of one of the state
    variables. The body of the message contains only state variables
    which changed.
  \item \texttt{error}: issued when the device detects an error.
    \begin{itemize}
    \item \texttt{description}: the textual description of the error
    \item \texttt{code}: a numeric code of the error.
    \end{itemize}
    This is intended to be overridden in the definitions of specific
    schemas.
  \end{itemize}

\item Methods:
  \begin{itemize}
  \item \texttt{isAlive}: This request has no attributes and no return value. 
    There is no response messages addressed specifically to the sender of
    this request. Instead of this, recipients(s) must respond as much as 
    possible by an \texttt{alive} notification addressed to all. 
  \item \texttt{getDescription}
    \begin{itemize}
    \item \texttt{vendorId} (out): string or number assigned by our office?
    \item \texttt{productId} (out): string
    \item \texttt{version} (out): string
    \item \texttt{parent} (out): address of the parent if any, or 0.
    \end{itemize}
  \item \texttt{getState}
    \begin{itemize}
    \item \texttt{<state variables>}:  A priori this method will be
      overridden in the definition of specific schemas of each device in
      order to return all state specific parameters added by each type of 
      device.
    \item Attention: we do not return the internal parameters 
      \texttt{devType}, \texttt{address} that are anyway in the header, nor
      the \texttt{parent} which is returned by the \texttt{getDescription}.
    \end{itemize}
  \item \texttt{setBusConfig}
    \begin{itemize}
    \item \texttt{busAddr} (in/out): a string specifying the IPv4 or IPv6
      address of the bus on which \xAAL is supposed to switch.
      
      If the returned address is not the sent one that means that the device
      could not be set with this address (in short, there is an error, and
      an error notification).

    \item \texttt{busPort} (in/out): an unsigned integer (well, limited to
      65535), indicating the port on which the \xAAL bus is supposed to
      switch.
      
      Similarly, if the value returned is not the one that had been sent, is 
      that there was an error.

    \item \texttt{TTL} (in/out): an 8-bit unsigned integer indicating the
      TTL used for sending multicast packets.
 
      A priori we put 1 by default, but it seems normal to leave the option
      of setting it too.
    \end{itemize}
  \end{itemize}
\end{itemize}


\section{Definition of a message}
A message consists of a \emph{header} and a \emph{body}. The header is 
mandatory, while the body is optional.

\smallskip

Figure \ref{xaalmsgs} gives an example of \xAAL messages.

\begin{figure}
\scriptsize
\begin{tabular}{cc}
\begin{minipage}{0.45\linewidth}
\begin{verbatim}
{
 "header":
  {
   "version": "0.2",
   "source": "bd081741-ceb6-41eb-87e0-6628d4959657",
   "target": "83c84e87-a230-4245-8829-f788fa6365a0",
   "devType": "thermometer.queryable",
   "msgType": "request",
   "action": "getState",
   "cipher": "none",
   "signature": ""
  }
}
\end{verbatim}
\end{minipage} 
&
\begin{minipage}{0.45\linewidth}
\begin{verbatim}
{
 "header":
  {
   "version": "0.2",
   "source": "83c84e87-a230-4245-8829-f788fa6365a0",
   "target": "bd081741-ceb6-41eb-87e0-6628d4959657",
   "msgType": "reply",
   "devType": "thermometer.queryable"
   "action": "getState",
   "cipher": "none",
   "signature": ""
  },
 "body": 
  {
    "temperature": 9.3000000000000007
  }
}
\end{verbatim}
\end{minipage}
\end{tabular}
\caption{Example of \xAAL messages\label{xaalmsgs}}
\end{figure}



\subsection{Header}
The header of a message includes:
\begin{itemize}
\item \texttt{version}: The version of the protocol. This document describes
  version 0.2.
\item \texttt{source target}: Source and destination addresses of the
  message.\\
  Note that the destination address can be 0, which means the message is of
  broadcast type.  The receivers (thus everybody) are invited to filter the
  relevance of the message on the basement of the device type (name of the
  schema).  Notification messages are often of broadcast type, but not
  necessarily.  In contrast, response messages are addressed specifically to
  the address of the requester.
\item \texttt{devType}: The schema name (the pair \emph{classe.type}) 
  to which relates this message. So typically if it is a message of request
  type, devType is the schema name of the recipient device; and if a response 
  message or a notification, devType is the schema name of the sender.\\
  Note that in the case of a request (broadcast or not), the requester may
  use the keyword \texttt{any} to the class as for the type.  By cons, in
  their reply (if exists), the devices explicitly specify their
  \texttt{devType}.  (Actually, one can not have \texttt{any} within
  responses nor notifications.)
\item \texttt{msgType}: The type of the message among \texttt{request reply
  notify}. Thus, typically, a message \texttt{request} is followed by a
  \texttt{reply} if it is necessary to return values to the requester (or a
  broadcasted notification if it is more useful from the application point
  of view.)
  Note that the specification does not define any sequence number or nor id 
  for request-response... Inconsistencies may happen; it is discussed below.
\item \texttt{action}: The name of the action brought by the message from
  the list of \emph{methods} and \emph{notifications} described in the schema 
  whose name is indicated in the message.
\item \texttt{cipher}: The safety mechanism used in the message. So far the
  \texttt{none} mechanism has been defined...\\
  In the future we may consider SHA mechanism (SHA1 SHA256 SHA512?), with
  a key shared across the bus.\\
  One can also consider asymmetric encryption such as PGP (or SSH); the
  private key of each device being hard-coded, and public key written on a
  sticker on devices and shared in the bus (and signed by the owner of the
  installation)...\\
  See below for a discussion on the subject.
\item \texttt{signature}: the signature of the message by the selected
  cipher...
\end{itemize}



\subsection{Body}
The body contains parameters and values for queries, responses and          
notifications, if needed.

The body is optional: it depends on what has been defined in the schema and
the action. 


\subsection{Cases of error}\label{cas_erreur}
The spirit of the \xAAL specification is primarily to focus on
interoperability.  It is guided by the will to propose, not to constrain... 
Consequently \xAAL has very few safeguards against the failure.  It is the
responsibility of developers of \xAAL components to do the best they can.

The specification says nothing about the lack of response. On the one hand,
since it is UDP, the query as the answer may be lost.  On the other hand,
there are devices that only know how to emit but not to listen to on the
bus.  The specification does not impose any timeout mechanism: some device
does not necessarily have a clock at hand and can manage responses to
requests in a circular buffer (and if a reply arrives so late that we forgot
question, too bad)...

Another argument concerning the non-response to a request: in the case of a
non-unicast query (i.e.  actually a broadcast one or on an overall class
type), it seems natural that devices unable to honor the request may
choose to remain silent rather than solicite the bus with error messages.

In some cases we may want to ensure that messages are not lost (e.g. alarm,
urgency). Since the loss is not supported by the \xAAL protocol layer itself,
this can be supported by the application above. Several strategies can be 
considered:
\begin{itemize}
\item After an action request to a device, the requester questions the target 
  device to see if there has been a change in its state variables;
\item The API of a request includes an ad-hoc parameter (e.g. 
  \texttt{requestId}) that the device has to repeat in its answer;
\item etc.
\end{itemize}

The cases of error or inconsistency are possibly many. The specification
does not impose a specific behavior.  So, in case of inconsistent message,
duplicates, divergent answers or notifications, \emph{the behavior is
unspecified}.  (Please do not make any assumption on error recovery.)

One might want to declare nevertheless that, faced with a poison message,
there is the obligation to reject it, to ignore it. Unfortunately, for some
equipment, it is not possible to undo what it started to do (not enough
memory or partial action). In short, the specification imposes nothing. If
the error can be recovery, fine, do it! Otherwise, don't worry!
The developers have the responsibility to be careful, and do the best.

For example, in some cases it is relatively easy to decide:
\begin{itemize}
\item A device receives a request to its own address, with a specific schema
  name which is not his one. It can easily identify the problem and ignore
  the request.
\item A device receives a request but the name of the method does not exist 
  in the schema. It can easily identify the problem and ignore the request.
\item A device receives a request but some parameters are missing, or of the
  wrong type.  Depending of the context, it may have started to partially
  fulfill a number of tasks for the requested method and may end up in
  trouble.  Maybe, it cannot undo what he began.  Therefore no one can
  impose it rejects the message.  If he does, that's fine.  If not, too bad. 
  At the most, it sends a relevant error code.
\item Conversely, if there are missing returned values in an answer, or of
  the wrong type, the device that initiate the request may have started to
  partially process the response... It is asked to at its best.
\item If the schemas are written carefully, they can provide a number of
  messages error. But this is the responsibility of schemas, not of the
  \xAAL bus.
\end{itemize}



\section{Security}
In preliminary work, we have not proposed a model for security mechanism.
Today, security seems to be required. This section draws some perspectives.

Let us consider an infrared remote control: the RC5 link (or RC6) is
not encrypted. To hack the transmission between the remote and the TV, it is
necessary that the neighbor can aim with its own remote control through the
window of the living room. These are the walls of the room which
insure the safety of the transmission, not the protocol itself.

It is the same for IP protocols: it is necessary to be already present
on the network to be able to attack it. It is necessary to be
physically plugged to wire with Ethernet; WiFi connections have (usually)
WPA keys that one have to know; remains powerline adapters for which
encryption if available but rarely enabled...

And finally, to contrast, think that the firewall configuration of the home
network can be bad, or a PC on the network can be compromised by virus...

So, one can do something...

\subsection{Need for security}
When one talk about security, one must first define against what one need
protection. In our case, it is not a question of dealing with cases of 
failure, but rather cases of malice.

Among the classical precepts for security (integrity, confidentiality,
availability, non-repudiation, authentication), what does one need?

At least, it is necessary to ensure the authentication of messages sender,
that messages are not corrupted, and that replay can not be done.

Remains the issue of confidentiality: a priori this does not necessarily
matter if the neighbor can listen (as long as he cannot inject false
messages).  However this can be annoying for certain use-cases: this can be
a problem if others may be informed that the alarm control is swiched off,
or that the door is unlocked...

On the other hand, it is necessary to keep in mind that one may have very
simple devices and that encryption mechanisms are resource-intensive.

In addition, to implement this it is necessary to go through a
configuration stage (to set up encryption keys). This can be complex. (One
can have a look at automatic configuration mechanisms for WiFi key, such as
WPS.)


\subsection{Proposals for security}
\begin{itemize}
\item \texttt{"cipher":"none"}: it is necessary to keep the possibility of
  communicating without encryption, just for all those devices that are too
  light to embed encryption mechanisms and configuration keys.

\item \texttt{"signature":xxx}: a signature mechanism with a conventional
  hash function (MD5 SHA1 SHA-256 SHA-512 Blowfish...) with a shared key.
  This ensures authentication and integrity. On the other hand it
  implies to manage the configuration of device to set up this key.

  Another approach is to use asymmetric key mechanisms: the private key being
  hardcoded into the device, its public key is written on a sticker on the
  device, with a mechanism for sharing a signature of these keys by others
  (like PGP).\\

  Nevertheless, to avoid replay it must be added in the signed message a
  little something that makes it unique...  For this, a timestamp can be
  added.  Or, the schema of the device can provide a mechanism for
  challenge-response: first ask the device for a cookie, and then return it
  in the next message by signing it.  Such a mechanism has its right place
  in the schema of the device, not in the \xAAL protocol itself.

\item Confidentiality: it implies encrypting the information in the message.
  There are two possible approaches:
  \begin{itemize}
  \item This can be specified not by \xAAL but in the schema of the device
    that needs it: one exchanges a public \emph{data} parameter, but the
    value is encrypted.
  \item Another approach would be to redefine the message format by adding
    a new body block which will be fully encrypted.
  \end{itemize}
\end{itemize}

At the moment, all this is still embryonic. However the general idea is that
security must be possible but optional.


\section{Best Practices}
The \xAAL specification in itself allows numerous of things, good and
bad...  Along preceding pages some suggestions of good practice were
discussed.  They are grouped here.


\subsection{Composite Device}
In the home automation domain, it is common  to find devices which include
several functions in one unit: e.g.  thermometer, door opening sensor, pilot
wire (this is a real case).

With \xAAL this is organized around the notion of \emph{composite device}. 
(It is our way to manage multiple inheritances...) This device is then going
to expose as many \xAAL devices as elementary functions.  In the example
here: a device with the thermometer schema, a device with the door opening
schema, a device with a pilot wire schema.

Furthermore, the device will exhibit itself with the composite schema,
whose sole function is to list its embedded devices (give addresses and
schema names).  The fact of exposing itself as a composite is not mandatory,
it is only recommended: it does not provide any functionality from the home
automation point of view, but it allows expressing the hardware architecture,
which can aid in the diagnosis and maintenance.

\subsection{Gateway}
Let us summarize the role of a \emph{gateway}:
\begin{itemize}
\item Transform  \xAAL messages into messages of a home-automation protocol
  of a manufacturer, and vice-versa;
\item Manage the pairing between itself and manufacturer devices;
\item Manage the configuration of these devices (eg  Z-Wave being
  bidirectional, it is the so-called "Z-Wave base" which pushes certain 
  parameters towards devices: here the \xAAL gateway plays then the role of 
  the Z-Wave base, so it manages these Z-Wave parameters but does not exhibit
  them on the \xAAL bus);
\item Expose the devices of the manufacturer on the \xAAL bus with their
  \xAAL address and their \xAAL schema;
\item Do the mapping between the \xAAL addresses and the manufacturer
  addresses;\\
  Note that this mapping can be useful in the configuration of the database
  of metadata.  (For instance when the power is reconnected after
  installing some automation devices: all will appear in a mess on the
  bus...  It is thus necessary to identify which is which.) The gateway can
  therefore be asked on this mapping.  For each device, the mapping is
  typically a pair: the \xAAL address, manufacturer address.  From one
  manufacturer to another, the notion of address may differ (e.g.  somes
  add the notion of group).  However, thanks to the flexibility of Json,
  the address format for each manufacturer will be defined later.  (At least
  it is a dictionary that contains the variable \texttt{ProtocolName} plus
  something about the manufacturer address.)

\item Do the translation between the functions of manufacturer devices and
  methods described in \xAAL schemas;\\
  This translation is supposed to be fairly straightforward, since the 
  gateway is almost transparent in this point of view.
\end{itemize}

By design, a gateway appears as a composite device. This is a somewhat more
sophisticated than the simple composite device previously described, but it
is a device that exhibit itself as such on \xAAL bus.

\smallskip
There is the case of gateways that handle manufacturer devices that are
themselves composite.

Let us take the case of the «Door / Window Sensor 3 in 1
FIB-FGK-101».\footnote{\url{http://www.planete-domotique.com/autres/par-technologie/zwave/capteur-d-ouverture-3-en-1-fibaro.html}}
This Z-Wave equipment does: door/window opening detection, thermometer,
digital data relay (to connect an add-on). The Z-Wave gateway will therefore
exhibit on the \xAAL bus:

\begin{itemize}
\item A door opening detection device (with a schema "opening detection"
  and its own \xAAL address);\\
  This device has for \emph{parent} the composite device described below.
\item A thermometer device (with the schema "thermometer" and his own \xAAL
  address); \\
  This device has for \emph{parent} the composite device described below.
\item A device "digital data" (with the schema "digital data" and his own
  \xAAL address); \\
  This device has for \emph{parent} the composite device described below.
\item A composite device (with the schema "composite" and his own \xAAL
  address);\\
  This composite device has for \emph{embedded} the previous three devices.\\
  Moreover, it has for \emph{parent} the composite gateway described below.
\item A gateway device (with the schema "gateway" and its own \xAAL
  address);\\
  This composite device has for \emph{embedded} the previous four devices.\\
  It has no \emph{parent}.
\end{itemize}


\subsection{Virtual Device}
In the functional \xAAL architecture, the automatons of scenarios are an
ideal place to implement "intelligent" home-automation services. 
For example:
\begin{itemize}
\item When an order is received, trigger a whole series of actions 
  (e.g. "evening of TV".)
\item Or conversely, by correlating a variety of events, synthesize
  information (e.g. "Presence of a user").
\end{itemize}

In so doing, the automaton appears then itself on the \xAAL bus as being a
device.  It is a \emph{virtual device}, but a device with its own methods,
notifications, state variables: in brief, is defined by a schema and other
entities can interact with it via the \xAAL bus.  

The fact that it is virtual has no impact from the \xAAL point of view.  It
is a device like others.


\subsection{Device Overloading another one}
A home automation system may have multifunctional devices.

Let us consider for example the "Micro-module Z-Wave Switch FGS-211". 
\footnote{\url{http://www.domotique-store.fr/domotique/modules-par-types/micro-modules/19-fibaro-fgs-211-relay-switch-module-micro-module-zwave-switch-relais-simple-on-off.html}}
This equipment has a size studied to be inserted into a wall outlet and is
able to control any electrical device (lamp, fan, shutters, etc.).

This type of micro-module, more and more common, provides complex
functionality.  This is what says the catalog about this one:
\begin{itemize}
\item on/off relay  controlled by Z -Wave or connected buttons;
\item Can use 1 or 2 buttons (the second optional button can control one or
  more other modules associated with Z-Wave);
\item The buttons can be bistable (on/off) or monostable (pulse pushbutton);
\item Report state via Z-Wave.
\end{itemize}

Therefore, the Z-Wave gateway that supports it will exhibit on the \xAAL bus
the following devices:
\begin{itemize}
\item A device of type relays with state feedback (with the schema "relay",
  and its own address) corresponding to the electrical device connected to
  it and thus controlled by the micro-module (but at this level it does not
  say if the controlled electrical device is a lamp, a fan, a shutter or
  something else);
\item A device of type button (either with the schema "bistable", or either
  with the schema  "monostable" according to the chosen configuration),
  and correspondent in the second optional button 
  (since the first button is used for the manual command of the relay);
\item And possibly a composite device embarking the two previous ones.
\end{itemize}

However, one misses the information of configuration saying that behind this
module this is a lamp which is controlled and not a fan nor a roller blind.

To do this, one will define a new \xAAL entity, a new device  that will
expose the "lamp" schema and that will do the translation between actions on
this "lamp" device and actions on the device "relay" device described
above. This new device is a virtual in a way, but mostly it just overloads 
the generic device. So, this can be called an \emph{overloading device}.
(And from the \xAAL point of view it has as parent the preceding generic
device.)

Note that since it is the gateway that exposes this new overloading device,
this gateway is not completely transparent in our architecture: it must be
configured to set up how generic devices are overloaded.  We believe that
these configurations should be located in the gateway and not in (for
example) in the metadata database.  Indeed, it is the setting of inner
workings of the device, not an attribute which just tag it.

Strictly speaking, a gateway that will handle a generic micro-module should
therefore expose on the \xAAL bus two devices: the generic one plus the 
overloading one. However, for reasons of simplicity for implementation 
(and also because we know how are the developers), it is quite acceptable
that the gateway makes the economy of the generic device and only expose 
on the \xAAL bus the overloading device.


\subsection{Hidden Device}
Some devices are not intended to be presented in user interfaces. This is
the case of gateways, composites, automaton of scenarios, metadata databases, 
caches, interfaces themselves, generic devices that are masked by an
overloading device, etc.

One should not make assumption of which device should be hidden or not. This
property (if needed) should be an explicit tag within the metadata database.
(Possibly with a default value according to the class diagram, but a tag
that can be changed later.)

User interfaces know all devices (hidden or not), but choose to display only
those that are not hidden unless the user explicitly requests it (like in a
file manager on your PC you can choose "show hidden files").

This information (to specify that a device is hidden or not) could be just
local to the HMI and be managed locally inside the HMI.  However, we think
this is specific to the automation system and must be stored in the metadata
database and available to all.

\section{Acknowledgments}
We wish to thank Corinne Le Moan and Florian Le Nestour for their active
participation in the first work on \xAAL.

\newpage
\appendix

\section{Draft of Schemas}
At the moment, the formalization of schemas has not yet been decided. 
Nevertheless, here are some general ideas on what could contain these
schemas.

{\small \verbatiminput{schemas/draft.txt}}

\end{document}
