Protocole UPnP

Un périphérique est un conteneur de services simples ou imbriqués. Cette information est stockée dans un document XML que le périphérique doit contenir. En addition à l'ensemble de services, la description liste aussi des propriétés (comme le nom du périphérique et icônes) associées à ce périphérique.

Le périphérique contient des services.

Un service est la plus petite unité de contrôle dans un réseau UPnP. Un service expose les actions et les modèles de son état avec des variables d'état. Par exemple, un service d'horloge peut être modélisé avec une variable d'état, current_time, qui définit l'état de l'horloge, et deux actions, set_time et get_time, qui permettent de contrôler le service. Semblable à la description du périphérique, cette information fait partie d'une description XML standardisé par le forum UPnP. Un pointeur (URL) de ces descriptions de service est contenu dans le document de description de l'appareil. Les dispositifs peuvent contenir de multiples services.

Un service dans un dispositif UPnP est constitué d'une table d'état, un serveur de contrôle et un serveur d'événements. La table d'état modèle l'état du service par le biais des variables d'état et les mises à jour lorsque l'état change. Le serveur de contrôle reçoit des demandes d'action (comme set_time), les exécute, met à jour la table d'état (des réponses et des retours). Le serveur d'événements publie des événements aux abonnés intéressés à tout moment l'état des changements de service. Par exemple, le service d'alarme incendie enverrait un événement aux abonnés intéressés lorsque son état passe à «sonner».

Le point de contrôle est un contrôleur qui est capable de découvrir et de contrôler les périphériques. Après la découverte du périphérique le point de contrôle peut :

• récupérer la description du dispositif et obtenir une liste des services associés ;
• récupérer des descriptions de service pour les services intéressants ;
• invoquer des actions pour contrôler le service ;
• s'abonner au serveur d'événements du service. Chaque fois qu’il y a un changement de l'état du service, le serveur d'événements enverra un événement au point de contrôle.

Il est prévu que le périphérique intègre la fonctionnalité de point de contrôle (mais aussi que le point de contrôle intègre celle de périphérique) pour permettre un véritable réseau Peer-to-Peer.

Les points de contrôles et les périphériques cherchent un serveur DHCP pour se procurer une adresse IP. Si aucun serveur DHCP n'est disponible, Auto-IP est utilisé pour obtenir une adresse.
Les équipements envoient un message DHCPDISCOVER via DHCP. Si un DHCPOFFER est reçu les équipements continuent le processus d’obtention dynamique d’une adresse IP, sinon, ceux-ci doivent utiliser un Auto-IP.

Pour configurer automatiquement une adresse IP, les équipements utilisent un algorithme aléatoire pour choisir une adresse en 169.254/16. L’adresse sélectionnée doit être testée pour savoir si elle est déjà utilisée, si tel est le cas il faut choisir une autre adresse[2]

Pour le test les équipements envoient des requêtes ARP avec leur adresse IP pour voir si d’autres équipements utilisent cette adresse. Si une réponse est reçue, c’est que l’adresse est déjà utilisée et doit donc être modifiée. Ensuite, les équipements envoient encore 2 requêtes ARP pour être sûr que d’autres équipements ne gardent pas des caches ARP avec l’adresse IP qui a pu être utilisée par un autre équipement.
Après avoir acquis une adresse IP, les équipements doivent tester régulièrement la présence du serveur DHCP[3].

Dans la découverte, le périphérique fait ce qu’on peut appeler de la publicité. Il envoie un message NOTIFY à tous les points de contrôles en utilisant UDP.

NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
CACHE-CONTROL: max-age = (la durée d’expiration de la publicité)
LOCATION: (l’URL du périphérique)
NT: search target (type de la publicité( concernant le périphérique ou un service))
NTS: ssdp:alive (sous-type ssdp:alive pour les publicités et ssdp : byebye pour quitter)
USN: (identifiant unique pour la publicité)

Après cela, le point de contrôle recherche le périphérique ou le service.
Il envoie un message M-SEARCH.

M-SEARCH * HTTP/1.1
HOST: 239.255.255.250:1900
MAN: (ssdp:discover)
MX: (temps d’attente)
ST: (type d’élément recherché à compare avec NT)

Et pour finir le périphérique envoie un message de réponse au point de contrôle (HTTP/1.1 200 OK) si le paramètre NT correspond à ST.

HTTP/1.1 200 OK
CACHE-CONTROL: max-age = ( la durée d’expiration de la publicité)
LOCATION: (l’URL du périphérique)
ST: (type d’élément recherché)
USN: (identifiant unique pour la publicité)

Les 3 requêtes utilisent le protocole SSDP.

À partir de l'argument LOCATION qui contient l'URL du périphérique, le point de contrôle peut accéder à un fichier XML qui contient plusieurs informations sur le périphérique et sur ses services. Il y a deux parties dans la description d’un périphérique : la description physique et la description logique[4].
La description de services informe sur les capacités du périphérique.
Obtenir la description du périphérique est simple : le point de contrôle envoie une requête HTTP GET à l’URL contenu dans le message de découverte (idem pour avoir la description du service).
Les documents de description doivent être envoyés en utilisant l'adresse IP contenue dans la réponse à la requête HTTP GET.
Si un périphérique a besoin de changer certaines de ses descriptions, il doit quitter la publicité et republier ensuite.
Par conséquent, le point de contrôle peut détecter un changement de description à la suite de l'apparition d'un périphérique dans le réseau ; il suffit pour cela qu’il vérifie la présence de la variable CONFIGID.UPNP.ORG dans la publicité[5].

Format d’un message HTTP GET :

HTTPget
GET /descriptionPath HTTP/1.1
HOST: hostname:portNumber
ACCEPT-LANGUAGE: language preferred by control point (optionnel)

Format d’un message HTTP REQUEST :

HTTP/1.1 200 OK
CONTENT-LANGUAGE: language used in description
CONTENT-LENGTH: bytes in body 
CONTENT-TYPE: text/xml; charset="utf-8" 
DATE: when responded
BODY(La description détaillée du service ou du périphérique)

Un point de contrôle envoie l’action au service du périphérique. Lorsque l’action a été exécutée (ou lorsqu'elle a échoué), le service retourne des résultats ou éventuellement des erreurs.
Il envoie un message de contrôle à l’URL de contrôle présente dans la description du périphérique. Le service retourne des résultats. Les effets de l’action changent les variables d’états du service. Quand ces variables changent, des événements sont publiés à tous les points de contrôle qui sont intéressés. Tant que les publicités d’un périphérique n’ont pas expiré, le point de contrôle considère que celui-ci est toujours fonctionnel[6]. Les points de contrôle doivent utiliser l'encodage UTF-8 pour tous les messages de contrôle et les réponses.
Si beaucoup d’informations doivent être envoyées en association de l’action, il n’est pas recommandé de les envoyer dans les arguments de SOAP. Il est possible par exemple d'envoyer l’URL en argument et d'utiliser les méthodes HTTP GET, PUT or POST pour transférer les données. L'encodage de transfert en bloc peut être utilisé si la quantité de données n’est pas connue à l’avance. Cet encodage permet de transmettre la ressource par morceaux consécutifs en précédant chacun par une ligne de texte donnant la taille de celui-ci en hexadécimal. Le transfert se termine alors par un morceau de taille nulle, où des en-têtes finaux peuvent être envoyés[7]. Les en-têtes supplémentaires liés à cet encodage de transfert sont :

Transfer-Encoding

Spécifie l'encodage de transfert. La seule valeur définie par la spécification RFC 2616[8] est "chunked".

Trailer

Liste toutes les en-têtes figurant après le dernier morceau transféré.

TE

Envoyé par le client pour spécifier les encodages de contenu supportés (Content-Encoding, ne pas confondre avec Transfer-Encoding car "chunked" est obligatoirement supporté par les clients et serveurs implémentant le standard HTTP/1.1), et spécifie si le client supporte l'en-tête Trailer en ajoutant trailers à la liste.

Protocoles utilisés lors du contrôle :

Dans la couche la plus élevée, les messages de contrôle contiennent d’abord les informations du constructeur (valeurs des arguments). En descendant, on retrouve aussi les informations du UPnP Forum (noms d’actions, noms d’argument, les noms de variables). Les messages sont formatés en utilisant les entêtes et les corps SOAP et ils sont délivrés via HTTP sur TCP/IP. Les messages de contrôle utilisent la méthode POST[9].

Exemple d’invocation de message:

POST path control URL HTTP/1.0
HOST: hostname:portNumber
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
USER-AGENT: OS name/OSversion UPnP/1.1 productName/versionName
SOAPACTION: "urn:schemas-upnp-org:service:serviceType:v#actionName"
<?xml version="1.0"?>
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:actionName xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>in arg value</argumentName>
<!-- other in args and their values go here, if any -->
</u:actionName>
</s:Body>
</s:Envelope>

Explication sur les éléments de ce message : HOST : hostname (nom de domaine ou l’adresse IP) et un port optionnel. Si le port est vide ou n’est pas donné, le port par défaut est le 80. USER-AGENT : exemple « unix/5.1 UPnP/1 .1 MyProduct/1.0 »

La balise <argumentName> est requise seulement si l’action a des arguments. Et pour chaque argument, un champ <argumentName> supplémentaire doit être ajouté.

Format d’une réponse à une action :

HTTP/1.0 200 OK
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
CONTENT-LENGTH: bytes in body
<?xml version="1.0"?>
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:actionNameResponse xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>out arg value</argumentName>
<!-- other out args and their values go here, if any -->
</u:actionNameResponse>
</s:Body>
</s:Envelope>

Messages d’erreurs :

HTTP/1.0 500 Internal Server Error
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
CONTENT-LENGTH: bytes in body
<?xml version="1.0"?>
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<s:Fault>
<faultcode>s:Client</faultcode>
<faultstring>UPnPError</faultstring>
<detail>
<UPnPError xmlns="urn:schemas-upnp-org:control-1-0">
<errorCode>error code</errorCode>
<errorDescription>error string</errorDescription>
</UPnPError>
</detail>
</s:Fault>
</s:Body>
</s:Envelope>

Les différentes valeurs pour <errorCode> et <errorDescription> sont décrites dans le tableau suivant :

Pour souscrire au serveur d’événement, le point de contrôle envoie un message de souscription qui contient l’URL du périphérique, l’identificateur du service et une URL pour la délivrance des messages [10].
Si la souscription est acceptée, le périphérique répond avec une durée et un identificateur unique pour la souscription. La durée de souscription doit être choisie en fonction de la présence du point de contrôle dans le réseau. Par exemple, si le point de contrôle quitte le réseau chaque minute, la durée doit être inférieure à une minute.
Pour garder la souscription active, le point de contrôle doit renouveler la souscription avant qu’elle n’expire. Dans ce cas, le message de renouvellement ne contient plus l’URL de délivrance mais l’identificateur de souscription. La réponse est la même que pour celle du message de souscription.

Si le point de contrôle n’a plus besoin d’être informé des événements, il doit envoyer un message "cancel" pour quitter la souscription.

Les messages d’événements, les noms des variables d’état et les valeurs courantes sont exprimés en syntaxe XML.

Le premier message d’événement concernant la demande de souscription contient les noms et valeurs des variables d’état et permet au point de contrôle d’initialiser son modèle de l’état du service. Le premier message est toujours envoyé même si le point de contrôle quitte la souscription.
Notons qu'il y a des variables qui changent trop rapidement ou qui contiennent des valeurs trop grandes pour que la notification d’événement soit utile. Dans ce cas, un filtrage ou une modération du nombre de messages d’événement est nécessaire. Le service désigne alors une ou plusieurs variables d’état comme étant non notifiées.
Le périphérique dispose d’une liste contenant les souscripteurs (points de contrôle). Si la souscription est expiré, l’identifiant de souscription est invalide et le périphérique efface le point de contrôle de cette liste. Il n’envoie dorénavant plus aucune notification à celui-ci et dans le cas où le point de contrôle essaie d’envoyer un message quelconque, celui-ci est négligé par le périphérique.
Il est fortement conseillé aux points de contrôle de surveiller constamment les messages publicités des périphériques. Ainsi, lorsqu'un périphérique quitte le réseau, le point de contrôle détecte que sa souscription est terminée[11]. Pile de protocoles pour la notification d’événement :

Dans la couche supérieure, on retrouve les messages de souscription et d’événements contenant les informations du constructeur comme les URL pour la souscription et la durée des souscriptions ou des valeurs de variables spécifiques. En descendant plus bas dans les couches, on retrouve les informations d’UPnP Forum comme les identificateurs des services et des noms de variables. Comme pour les messages de contrôles, on utilise HTTP sur TCP/IP[12].
Formats des messages :

Message de demande de souscription

SUBSCRIBE publisher path HTTP/1.1
HOST: publisher host:publisher port
USER-AGENT: OS/version UPnP/1.1 product/version
CALLBACK: <delivery URL>
NT: upnp:event
TIMEOUT: Second-requested subscription duration(Integer)

Réponse au message de souscription

Notez que dans l'exemple ci-dessous, le champ SID n'est pas utilisé pour la première souscription.

HTTP/1.1 200 OK
DATE: when response was generated
SERVER: OS/version UPnP/1.1 product/version
SID: uuid:subscription-UUID
CONTENT-LENGTH: 0
TIMEOUT: Second-actual subscription duration

Pour un renouvellement de souscription

SUBSCRIBE publisher path HTTP/1.1
HOST: publisher host:publisher port
SID: uuid:subscription UUID ( identificateur de souscription)
TIMEOUT: Second-requested subscription duration

Pour quitter une souscription :

UNSUBSCRIBE publisher path HTTP/1.1
HOST: publisher host:publisher port
SID: uuid:subscription UUID (identificateur de souscription)

Message de notification en mode (Unicast)

NOTIFY delivery path HTTP/1.0
HOST: delivery host:delivery port
CONTENT-TYPE: text/xml; charset="utf-8"
NT: upnp:event
NTS: upnp:propchange
SID: uuid:subscription-UUID
SEQ: event key
CONTENT-LENGTH: bytes in body
<?xml version="1.0"?>
<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
<e:property>
<variableName>new value</variableName>
</e:property>
<!-- Other variable names and values (if any) go here. -->
</e:propertyset>

Message de réponse à la notification d’événements

Si ce message n’est pas émis par le point de contrôle dans un délai de 30 secondes, le périphérique abandonne l’envoi de la notification mais conserve la souscription active pour une future notification d’événement.

HTTP/1.1 200 OK

Notification Multicast

 
NOTIFY * HTTP/1.0
HOST: 239.255.255.246:7900 *** note the port number is different than SSDP ***
CONTENT-TYPE: text/xml; charset="utf-8"
USN: Unique Service Name for the publisher
SVCID: ServiceID from SCPD
NT: upnp:event
NTS: upnp:propchange
SEQ: monotonically increasing sequence count
LVL: event importance
BOOTID.UPNP.ORG: number increased each time device sends an initial announce or update message
CONTENT-LENGTH: bytes in body
<?xml version="1.0"?>
<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
<e:property>
<variableName>new value</variableName>
</e:property>
<!-- Other variable names and values (if any) go here. -->
</e:propertyset>

le tableau suivant présente les différentes valeurs normalisées pour le champ level :

Pour ouvrir la page de présentation, le point de contrôle envoie un message HTTP GET et le périphérique répond avec un message HTTP Response[13].

• (en) UPnP Device Architecture 1.1 : Document Revision Date 15 October 2008, UPnP Forum, 15 octobre 2008, 136 p. (lire en ligne)

• (en) Understanding Universal Plug and Play, Microsoft, juin 2000, 42 p. (lire en ligne)