\documentclass{article} 
% \usepackage[czech]{babel} 
\usepackage{ucs}
\usepackage[utf8x]{inputenc} 
\usepackage{graphicx}

\title{Protocole xAAL - Version 0.1-json}

\author{Corinne Le Moan}

\date{Mars 2012}

\begin{document}
\maketitle

\section{ Transport }
Bus multicast IP (adresse et numéro de port TBD)

\section{ Device }
Un device possède :
\begin{itemize}
\item Un type (integer) composé de :
  \begin{itemize}
  \item Un numéro de méta-type (short) désignant la catégorie de types
    (e.g. éclairage, chauffage, ...)
  \item Un numéro (short) de sous-type qui renvoie à un schéma device
    (variable, action/response, event).
  \end{itemize}
\end{itemize}
Le type 0xFFFFFFFF est réservé et signifie "any", désigne tous les types.
On réserve une plage particulière "expérimentale" (i.e. lorsque quelqu'un
fait une implem et n'a pas encore obtenu un numéro de notre bureau
d'attribution). Par exemple "0xFF89" pour le méta type et idem pour le
sous-type.
\begin{itemize}
\item Un identifiant (ou adresse), numéro unique sur le bus
  \begin{itemize}
  \item codé sur 1 mot de 32bits
  \item Génération du numéro :
    \begin{itemize}
    \item codé en dur en usine,
    \item auto généré (random),
    \end{itemize}
  \item Il est vérifié par un genre de "arp gratuit" par des requêtes
    "IsAlive"
  \item Il n'est pas attribué par un superviseur
  \end{itemize}
\item Un équipement peut être composé de plusieurs sous-équipements
  (embedded) et aura ainsi plusieurs types et plusieurs IDs
  (i.e. thermomètre + hydromètre)
\item Dans le même ordre d'idée, une gateway aura dans ses "embedded" tous
  les équipements administrés par elle.
\end{itemize}

\section{ Schéma de type de device }
Chaque équipement est typé, i.e. correspond à un schéma.  Le schéma est
fortement inspiré de UPnP (cf
[[http:\textit{upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf}]], chapitre 2). 

Un schéma définit : 
\begin{itemize}
\item Une liste d'actions
 \begin{itemize}
 \item Chaque action possède :
  \begin{itemize}
  \item un nom
  \item une liste d'arguments, chaque argument étant défini par :
   \begin{itemize}
   \item un nom
   \item une direction (in ou out)
   \item un type (?)
\end{itemize}
\end{itemize}
\end{itemize}
 \item Une liste de variables (leur changement de valeur génère par défaut un évènement sur le bus), chaque variable étant définie par :
 \begin{itemize}
 \item un nom,
 \item un type
 \item une valeur par défaut (?)
 \end{itemize}
\end{itemize}


\section{ Composants particuliers du bus }
\section{ Gateway }
Une passerelle ou gateway est un composant masquant un protocole plus bas niveau sur le bus (xAP, X10, X2D, X3D, ...)

\section{ Annuaire }
Le service d'annuaire est facultatif.
Il permet d'administrer la complexité du réseau d'équipements en leur attachant des informations de localisations, de présentations voires de fonctionnalités.
Concrêtement, par soucis d'ouverture et d'extensibité (au sens souplesse d'utilsilisation et non au sens monté en charge), ces informations sont matérialisés par des tags.



\section{ Message }
Tous les messages transmis sur le bus respectent la syntaxe suivante :
\begin{verbatim}
{
    "msg" :
       <!--2 elements array -->
       [   <!-- first element is the header of message -->
         { 
           "msgtype":<message type id>,
           "source":<device ID source>, 
           "target":<device ID destination>, 
           "devtype":<device type>
         }
         ,
         <!-- second element is the body of message -->
         {             ...          }        
       ] 
}
\end{verbatim}


\section{ Description du header }
\begin{verbatim}
{ 
  "source":<ID source>, 
  "target":<ID destination>,
  "devtype":<Type device>, 
  "msgtype":<Type message>
}
\end{verbatim}

Un ID est codé sur 32 bits.  Un ID de "broadcast" = 0xFFFF. 
Le type de message est un entier sur 32 bits (cf détails plus bas) et le
type de device est celui de la destination si "Type Message" <256, la source
si "Type Message" >255.

\section{ Type de message }

\begin{itemize}
\item Le type de message est codé par un entier 32bits non signé
\item L'octet de poids fort indique la version du protocole (e.g. ici on
  parle du protocole 0x1)
\item Le bit de poids faible indique si c'est un message de type requête
  (0x1) ou de type réponse/notification (0x0). Ce bit permet donc de
  déterminer la portée du DeviceType de l'entête (respectivement celui de la
  destination, respectivement celui de la source).
\item Un message de type requête:
  \begin{itemize}
  \item DeviceType = { ClassID, TypeID }
    \begin{itemize}
    \item soit 0xFFFFFFFF (\textit{any}): on s'adresse à tous les types de
      devices sur le bus
    \item soit un ClassID précis, et un TypeID=0xFFFF: on s'adresse à tous
      les types d'une classe donnée
    \item soit un ClassID précis et un TypeID précis: on s'adresse à un type
      bien déterminé
    \end{itemize}
  \item SrcID: le DeviceID de l'émetteur du message (peut être l'adresse 0x0
    dans certains cas, par exemple pour gérer le genre d'arp gratuit,
    lorsque l'on n'a pas encore choisi un ID pour soi-même)
  \item DstID: le DeviceID d'un device particulier à qui l'on adresse une
    requête, ou bien l'adresse de broadcast 0xFFFFFFFF
  \end{itemize}
\item Un message de type réponse ou notification
  \begin{itemize}
  \item DeviceType: celui du device qui émet la requête (et pas de any
    d'aucune sorte)
  \item SrcID: le DeviceID de l'émetteur du message
  \item DstID: le DeviceID du device qui a fait la requête et à qui l'on
    répond, ou bien l'adresse de broadcast 0xFFFFFFFF, notamment pour les
    messages de notification
  \end{itemize}
\end{itemize}


\section{ Les différents types des messages }

\subsection{ Requête de type "Who is alive?" (0x01000101) }
\begin{itemize}
\item Pas de body
\item Sollicite des annonces de type "Alive" pour découvrir qui est actif
  sur le bus
\item De manière globale: DstID broadcast, et DeviceType any
\item Spécifiquement à un ClassID précis
\item Spécifiquement à un ClassID+TypeID précis
\item Spécifiquement à un DeviceID précis
\end{itemize}

\subsection{ Annonce (ou réponse) de type "Alive" (0x01000100) }
\begin{itemize}
\item Dans le body :
  \begin{itemize}
  \item la liste des équipements "embedded", rien si aucun,
  \item le device ID de l'"embedder", rien si aucun
  \end{itemize}
\item Le device s'annonce spontanément sur le bus lorsqu'il est branché
\item Le device s'annonce régulièrement (selon une périodicité de son choix,
  voir jamais)
\item Le device s'annonce suite à une requête "Who is alive?"
\item Le device peut choisir de ne pas s'annoncer s'il est en mode économie
  d'énergie, ou s'il ne sait pas traiter des requêtes "\textit{Who is
    alive?}"
\end{itemize}

\subsection{ Requête de notification d'état (0x01000201) }
\begin{itemize}
\item Pas de body
\item Sollicite un message de notification d'état
\item De manière globale, spécifique, ou entre les deux (cf plus haut)
\end{itemize}
\subsection{ Message de notification d'état (0x01000200) }
\begin{itemize}
\item Body :
  \begin{itemize}
  \item L'intégralité des variables d'état du device tel que définit dans
    son type
  \item Le nom de la ou des variables qui ont changé de valeur
  \end{itemize}
\item Le device émet ce message :
  \begin{itemize}
  \item spontanément, c'est-à-dire lorsque son état a changé,
  \item en réponse à une requête de status du device, le device peut choisir
    de ne pas répondre à la requête correspondante s'il ne sait pas écouter
    le bus par exemple.
  \end{itemize}
\end{itemize}

\subsection{ Requête de type action (0x01000301) }
\begin{itemize}
\item Toujours de manière spécifique (pas de broadcast ou de any)
\item Body:
  \begin{itemize}
  \item Un RequestID: un entier de 64bits non signé (aléatoire)
  \item Un ActionID: le numéro de la requête tel que définit dans le schéma
  \item Une table de paramètres: les paramètres requis pour l'action en
    question, tel que définit dans le schéma (Absent si l'action ne requiert
    pas de paramêtre)
  \end{itemize}
\end{itemize}
\subsection{ Réponse à une action (0x01000300) }
\begin{itemize}
\item Répond spécifiquement à l'émetteur de la requête (i.e. sur son
  DeviceID à lui).
\item Body:
  \begin{itemize}
  \item RequestID: recopie celui de la requête
  \item ActionID: rappel le numéro d'action de la requête
  \item ReturnCode: un entier 32bits signé. Toujours présent.
  \item Une table de variables de retours tel que définit dans le schéma
    (Absent si l'action ne fournit pas de variables en retour)
  \end{itemize}
\end{itemize}

\begin{itemize}
\item Note: la spécification ne dit rien quant à l'absence de réponse. D'une
  part, puisque l'on est en UDP, la requête comme la réponse peut se
  perdre. D'autre part, il y a des device qui ne savent qu’émettre et pas
  écouter sur le bus. La spécification n'impose pas de mécanisme de timeout:
  certains device n'ont pas nécessairement d'horloge sous la main, et
  peuvent gérer les réponses aux requêtes dans un buffer circulaire (et si
  une réponse arrive tellement tard que l'on a oublié la question, tant pis)
\item Autre argument concernant la non-réponse à une requête: dans le cas
  d'une requête non unicast (soit réellement broadcast, soit sur une classe
  de type), il parraît naturel que les équippements qui ne peuvent honorer
  la requête puissent choisir de se taire plutôt que de polluer le bus avec
  des messages d'erreur.
\end{itemize}





\section{ Meta-type d'équipements }



\begin{tabular}{|c|c|c|} 
  \hline 
  Valeur num & Valeur texte & Description \\ \hline
  FFFF & any & any \\ \hline
  FF89 & tbd & TBD \\ \hline
  0001 & soft & software \\ \hline
  0002 & light & light \\ \hline
  0003 & hvac & HVAC (heating, ventilation, and air conditioning) \\ \hline
  0004 & shutter & Shutter \\ \hline
  0005 & sensor & Sensor \\ \hline
  0006 & security & Security \\ \hline
  0007 & command & Command \\ \hline
\end{tabular}


\section{ software }

\begin{tabular}{|c|c|c|} 
  \hline 
  0001 & soft.x2dgateway & X2DGATEWAY \\ \hline
  0002 & soft.monitoring & Command and monitoring application \\ \hline
\end{tabular}


\section{ light }

\begin{tabular}{|c|c|c|} 
  \hline 
  FF89 & light.tbd & TBD \\ \hline
  0001 & light.switch & simple switch light \\ \hline
  0002 & light.dimmable & dimmable light \\ \hline
\end{tabular}



\section{ HVAC }

\begin{tabular}{|c|c|c|} 
  \hline 
  FF89 & hvac.tbd & TBD \\ \hline
  0001 & hvac.heater & heater \\ \hline
\end{tabular}


\section{ Shutter }


\begin{tabular}{|c|c|c|} 
  \hline 
  FF89 & shutter.tbd & TBD \\ \hline
  0001 & shutter.deltadore.4630 & Deltadore roller shutter 4630 \\ \hline
\end{tabular}



\section{ Sensor }

\section{ Security }

\section{ Command }

\begin{tabular}{|c|c|c|} 
  \hline 
  FF89 & command.tbd & TBD \\ \hline
  0001 & command.switch.onoff &on/off switch \\ \hline
  0002 & command.remotecontrol.deltadore.tyxia1601 & 1 shutter, 2 lights, remote control \\ \hline
\end{tabular}




\end{document}
