ZigBee

13 mai ZigBee

Suite à mon intégration dans le groupe HoMiDom, j’ai décidé d’utiliser le protocole ZCL (Zigbee Cluster Library) pour mon application sur Arduino.

Je travaille donc depuis sur le développement du driver ZigBee pour HoMiDom et le programme Arduino en ZigBee.

N’étant pas un excellent anglophone  ;)  je traduit et interprète les spécifications Zigbee Cluster Library au fil de l’eau.

Cet article est donc mon bloc note ZigBee ZCL !


Le contexte ZigBee ZCL

Le matériel utilisé reste identique :

- une platine USB XBee avec un  module ZigBee PRO série 2 monté dessus (provenant de chez  Planète Domotique)

- Une arduino avec le shield XBee

Dans un premier, nous allons nous intéresser à la trame ZCL. Nous reviendrons plus tard sur la trame complète à envoyer.

Format d’une trame ZCL

Une trame ZCL est composée d’un ZCL Header et d’un ZCL PayLoad.

ZCL Header Frame Control Frame Type
Manufacturer specific
Direction

Disable default response

Reserved
Manufacturer code 0/16 bits
Transaction sequence number 8 bits
Command identifier 8 bits
specifies the cluster command being used
If the frame type sub-field of the frame control field is set to 0b00, the
command identifier corresponds to one of the non-reserved values
If the frame type sub-field of the frame control field is set to 0b01, the command
identifier corresponds to a cluster specific command.
ZCL Payload Frame payload

ZCL Header

Le champ ZigBee Frame Control

Le champ ZCL Frame Control est de 8-bits de longueur et contient des informations définissant le type de commande et autres indicateurs de contrôle. Le champ Frame Control doit être formaté comme suit :

  • bits 0 et 1 : Frame Type
  • bits 2 : Manufacturer specific
  • bits 3 : Direction
  • bits 4 : Disable default response
  • bits 5 à 7 : Reserved (doit être réglée à 0)

Frame Type

Le sous-champ Frame Type est de 2 bits de longueur et doit être réglé ainsi :

00 : La commande concerne l’ensemble du profil

01 : La commande est spécifique à un cluster

10-11 : Reservé

Manufacturer specific

Le sous-champ Manufacturer specific est de 1 bit de longueur et spécifie si cette commande fait référence à une extension spécifique à un fabricant de profil.

Si cette valeur est définie à 1, le champ du code fabricant doivent être présents dans le cadre ZCL.

Si cette valeur est définie à 0, le champ du code fabricant ne sera pas inclus dans le cadre ZCL.

Direction

Le sous-champ direction indique la direction du client / serveur pour cette commande.

Si cette valeur est définie à 1, la commande est envoyé à partir du côté serveur d’un cluster sur le côté client d’un cluster.

Si cette valeur est définie à 0, la commande est envoyé à partir du côté client d’un cluster sur le côté serveur d’un cluster.

Disable default response

Le sous-champ Disable default response est de 1 bit de longueur.

S’il est définie à 0, la commande de réponse par défaut sera retournée.

Si elle est définie à 1, la commande de réponse par défaut ne sera retournée que s’il ya une erreur.

Le champ ZigBee Manufacturer code

Le champ Manufacturer code est de 16 bits de longueur et correspond au code ZigBee du fabricant attribué pour des extensions propriétaires à un profil.

Ce champ est inclus dans le cadre ZCL uniquement si sous-champ Manufacturer specific du champ Frame Control est à 1.

Le champ ZigBee Transaction sequence number

Le champ Transaction sequence number est 8-bits de longueur et spécifie un numéro d’identification de l’opération de telle sorte qu’une trame de commande de réponse puisse être liée à une trame de commande demande. L’application elle-même doit maintenir un compteur 8-bits qui est copié dans ce domaine et incrémenté de un pour chaque commande envoyée.

Quand une valeur de 0xff est atteint, la commande suivante est re-démarrer avec une valeur de 0x00.
Le champ Transaction sequence number peut être utilisé par un dispositif de contrôle, qui peut avoir émis plusieurs commandes, afin qu’il puisse correspondre aux réponses reçues à la commande concernée.

Le champ ZigBee Command identifier

Le champ ZCL Command identifier est le 8 bits de longueur et spécifie la commande cluster utilisée.

Si le sous-champ Frame Type du champ Frame Control est réglé sur 0b00, l’identificateur de commande correspond à l’une des valeurs non réservés ci-dessous :

Identifier Field Description
0x00 Read attributes
0x01 Read attributes response
0x02 Write attributes
0x03 Write attributes undivided
0x04 Write attributes response
0x05 Write attributes response
0x06 Configure reporting
0x07 Configure reporting response
0x08 Read reporting configuration
0x09 Read reporting configuration response
0x0a Report attributes
0x0b Default response
0x0c Discover attributes
0x0d Discover attributes response
0x0e Read attributes structured
0x0f Write attributes structured
0x10 Write attributes structured response
0x11 Reserved

Si le sous-champ Frame Type du champ Frame Control est réglé sur 0b01, l’identificateur de commande correspond à une commande d’un cluster spécifique. Les identificateurs de grappe de commande spécifique peut être trouvé dans chaque document décrivant les clusters.

ID du cluster ZigBee

Nom du cluster ZCL

Description

0x0000 Basic Attributes for determining basic information about a device, setting user device information such as location, and enabling a device.
0x0001 Power configuration Attributes for determining more detailed information about a device’s power source(s), and for configuring under/over voltage alarms.
0x0002 Device Temperature Configuration Attributes for determining information about a device’s internal temperature, and for configuring under/over temperature alarms.
0x0003 Identify Attributes and commands for putting a device into Identification mode (e.g. flashing a light)
0x0004 Groups Attributes and commands for group configuration and manipulation.
0x0005 Scenes Attributes and commands for scene configuration and manipulation.
0x0006 On/off Attributes and commands for switching devices between ‘On’ and ‘Off’ states.
0x0007 On/off Switch Configuration Attributes and commands for configuring On/Off switching devices
0x0008 Level Control Attributes and commands for controlling devices that can be set to a level between fully ‘On’ and fully ‘Off’.
0x0009 Alarms Attributes and commands for sending notifications and configuring alarm functionality.
0x000a Time Attributes and commands that provide a basic interface to a real-time clock.
0x000b RSSI Location Attributes and commands that provide a means for exchanging location information and channel parameters among devices.
0x000c Analog Input (Basic) An interface for reading the value of an analog measurement and accessing various characteristics of that measurement.
0x000d Analog Output (Basic) An interface for setting the value of an analog output (typically to the environment) and accessing various characteristics of that value.
0x000e Analog Value (Basic) An interface for setting an analog value, typically used as a control system parameter, and accessing various characteristics of that value.
0x000f Binary Input (Basic) An interface for reading the value of a binary measurement and accessing various characteristics of that measurement.
0x0010 Binary Output (Basic) An interface for setting the value of a binary output (typically to the environment) and accessing various characteristics of that value.
0x0011 Binary Value (Basic) An interface for setting a binary value, typically used as a control system parameter, and accessing various characteristics of that value.
0x0012 Multistate Input (Basic) An interface for reading the value of a multistate measurement and accessing
0x0013 Multistate Output (Basic) An interface for setting the value of a multistate output (typically to the environment) and accessing various characteristics of that value.
0x0014 Multistate Value (Basic) An interface for setting a multistate value, typically used as a control system parameter, and accessing various characteristics of that value.
0x0015 Commissioning Attributes and commands for commissioning and managing a ZigBee device.
0x0016 – 0x00ff Reserved.

La commande ZigBee Read Attributes (champ ZCL Command identifier)

Format de la commande Read Attributes

 

ZCL Header

Le champ de contrôle de la trame doit être spécifié comme suit :

Le champ Command identifier doit être réglé pour indiquer une commande profil large (0b00).

Le sous-champ Manufacturer specific doit être mis à 0 si cette commande est utilisée pour lire les attributs définis pour tous les groupes dans la ZCL ou 1 si cette commande est utilisée pour lire les attributs spécifiques au fabricant.

Attribute Identifier

Le champ Attribute Identifier est de 16 bits de longueur et doit contenir l’identifiant de l’attribut qui doit être lu.

Raison d’envoi

La commande Read Attributes est générée lorsqu’un dispositif tient à déterminer les valeurs d’un ou plusieurs attributs situé sur un autre appareil. Chaque champ Attribute Identifier doit contenir l’identifiant de l’attribut devant être lu.

Effet sur sa réception

A réception de cette commande, le dispositif doit traiter chaque attribut spécifié et générer une commande lire read attributes response. La commande read attributes response doit contenir autant d’ Attribute Identifier que la trame Read Attributes en contient. Chaque statut de Read Attributes doit contenir l’attribut identifiant correspondant de cette trame de commande, une valeur d’état évaluée comme décrit ci-dessous, et, en fonction de la valeur d’état, la valeur de l’attribut lui-même.
Pour chaque attribut identifiant inclus dans la trame de commande, le dispositif doit d’abord vérifier qu’il correspond à un attribut qui existe sur ce dispositif. Si ce n’est pas, le dispositif fixe le champ d’état de l’enregistrement correspondant attribut de lecture statut UNSUPPORTED_ATTRIBUTE et ne comprend pas un champ de valeur d’attribut. Le dispositif passe ensuite à l’attribut suivant.
Si l’attribut identifié par l’attribut identifiant est pris en charge, le dispositif doit définir le champ d’état de l’enregistrement correspondant au statut SUCCESS et doit définir la valeur actuelle de l’attribut. Le dispositif passe ensuite à l’attribut suivant.

La commande ZigBee Read Attributes Response

Format de la commande Read Attributes Response

Octets:

Variable

Variable

Variable

Variable

ZCL

header

Read attribute status

record 1

Read attribute status

record 2

Read attribute status

record n

Chaque statut d’Attribute de lecture est formaté de la façon suivante :

Octets: 2

1

0 / 1

0 / Variable

Attribute identifier

Status

Attribute data type

Attribute

value

ZCL Header

Le champ de contrôle de trame doit être spécifié comme suit.

Le champ Frame Type doit être réglé pour indiquer une commande profil large (0b00). Le champ Manufacturer specific doit être mis à 0 si cette commande est utilisée comme une réponse à la lecture des attributs définis pour tous les groupes dans la ZCL ou 1 si cette commande est utilisée comme une réponse à la lecture des attributs spécifiques au fabricant.
Le champ Command identifier doit être défini pour indiquer la lecture des attributs de la commande Read Attributes Response.

Attribute Identifier

Le champ Attribute identifier est 16-bits de longueur et doit contenir l’identifiant de l’attribut qui a été lu (ou dont un élément a été lu). Ce champ doit contenir la même valeur qui a été inclus dans l’ Attribute identifier de la commande Read Attribute d’origine.

Statut

Le champ Statut est le 8-bits de longueur et précise le statut de l’opération de lecture sur cet attribut. Ce champ est fixée à SUCCESS, si l’opération a réussi, ou un code d’erreur si l’opération n’a pas réussi.

Attribute Data Type

Le champ type Attribute Data Type contient le type de données de l’attribut . Ce champ doit être inclus uniquement si le champ d’état associé contient une valeur de SUCCESS.

Attribute Value

Le champ de Attribute Value est de longueur variable et doit contenir la valeur actuelle de cet attribut. Ce champ doit être inclus uniquement si le champ d’état associé contient une valeur de SUCCESS.
Pour un attribut ou un élément de type simple, ce champ a le format indiqué dans le tableau des types de données (tableau 2.15). Pour un attribut ou un élément de type complexe, ce champ a le format indiqué à la figure ci-dessous :

Octets: 1

2

Variable

Variable

Element type

Number of elements

(m)

Element value 1

Element value m

Si le champ Number of elements a la valeur 0xFFFF, cela indique que l’attribut ou un élément en cours de lecture n’est pas valide / non défini. Dans ce cas, ou si le nombre de champ éléments a la valeur 0, les champs Element value ne sont pas inclus.
Pour un attribut ou un élément de structure de type, ce champ a le format indiqué à la figure ci-dessous :

Octets: 2

1

Variable

Variable

Number of elements

(m)

Element type

Element value 1

Element value m

Dans les deux cas, la valeur du champ Element value suit le même format que celle du champ valeur d’attribut. Ce format est donc récursive à toute profondeur nécessaire.
Si
le champ Number of elements a la valeur 0xFFFF, cela indique que l’attribut ou un élément en cours de lecture n’est pas valide / non défini. Dans ce cas, ou si le nombre de champ éléments a la valeur 0, les champs Element value ne sont pas inclus.

Raison d’envoi

La commande read attribute responose est généré en réponse à une commande read attribute ou une commande read attribute structured. La trame de commande doit contenir un champ attribut de lecture d’état pour chaque identifiant d’attribut spécifiés dans les attributs d’origine. Pour chaque acte de l’état attribut de lecture, le champ attribute identifier doit contenir l’identifiant spécifié dans les attributs d’origine. Le champ statut doit contenir un code d’état approprié.
xxx

Effet sur sa réception

Sur réception de cette commande, le donneur est informé des résultats de sa demande de lecture des attribus et, pour chaque demande de succès, la valeur de l’attribut demandé.
Si la fragmentation n’est pas supportée, et si certains attribut n’ont pas été renvoyés, l’initiateur peut émettre une demande complémentaire pour un des attributs.

La commande ZigBee Write Attributes

Format de la commande Write Attributes

La commande Write Attributes est formatée de la façon suivante :

Octets:

Variable

Variable

Variable

Variable

ZCL

header

Write attribute

record 1

Write attribute

record 2

Write attribute

record n

Chaque Write attribute record sont formatés de la façon suivante :

Octets: 2

1

Variable

Attribute identifier

Attribute data type

Attribute data

ZCL Header

Le champ Frame Control doit être spécifié comme suit :

Le sous-champ Frame Type doit être réglé pour indiquer une commande profil large (0b00).

Le sous-champ Manufacturer specific doit être mis à 0 si cette commande est utilisée pour écrire des attributs définis pour tous les groupes dans la ZCL ou 1 si cette commande est utilisée pour écrire des attributs spécifiques au fabricant.
Le champ Command identifier doit être défini pour indiquer la commande d’écriture des attributs.

Attribute identifier

Le champ Attribute identifier est 16-bits de longueur et doit contenir l’identifiant de l’attribut qui doit être écrit.

Attribute data type

Le champ Attribute data type contient le type de données de l’attribut qui doit être écrit.

Attribute data

Le champ Attribute data est de longueur variable et doit contenir la valeur réelle de l’attribut qui doit être écrit.

Raison d’envoi

La commande Write Attribute est généré lorsqu’un périphérique souhaite modifier les valeurs d’un ou plusieurs attributs situé sur un autre appareil. Chaque Write attribute record doit contenir l’identifiant et la valeur de l’attribut devant être écrit.

Effet sur sa réception

Lors de la réception de cette commande, le dispositif doit tenter de traiter chaque attribut spécifié et de construire une commande write attribute response. Chaque Write attribut status record de la commande construite doit contenir l’identifiant et une valeur d’état évaluée comme décrit ci-dessous.
Pour chaque write attribute record inclus dans la trame de commande, le dispositif doit d’abord vérifier qu’il correspond à un attribut qui est mis en œuvre sur ce dispositif. Si ce n’est pas, le dispositif fixe le champ d’état correspondant à UNSUPPORTED_ATTRIBUTE et passe au prochain attribute.
Si l’attribut identifié par l’attribut identifiant est pris en charge, le dispositif doit vérifier si le domaine de l’attribut type de données est correct. Sinon, le dispositif fixe le champ d’état correspondant à INVALID_DATA_TYPE et passe au prochain attribute.

Si l’attribut type de données est correct, le dispositif doit vérifier si l’attribut est accessible en écriture. Si l’attribut est désigné comme étant en lecture seule, le dispositif fixe le champ d’état correspondant à READ_ONLY et passe au prochain attribute.

Si l’attribut est accessible en écriture, le dispositif doit vérifier que la valeur fournie dans l’attribut est dans la plage spécifiée de l’attribut. Si la valeur fournie n’entre pas dans la plage spécifiée de l’attribut, le dispositif fixe le champ d’état à INVALID_VALUE et passe au prochain attribute.
Si la valeur fournie dans l’attribut est dans la plage spécifiée de l’attribut, le dispositif doit écrire la valeur fournie à l’attribut identifié et passe au prochain attribute. Dans ce cas (succès), un write attribute status record ne doit pas être généré.
Lorsque tous les attributs à écrire ont été traités, le dispositif doit générer la commande write attributes response.

« S’il n’y a pas d’écriture des enregistrements de l’attribut de situation dans la commande construite, ce qui indique que tous les attributs ont été
écrite avec succès, un seul dossier écrire l’attribut de situation doit être inclus dans le commande, avec le champ d’état mis à la réussite et l’attribut identifiant de terrain omis. »

ZCL Payload

Le champ ZigBee Frame payload

Le Frame payload a une longueur variable et contient des informations spécifiques à certains types de commande individuelle.

La longueur utile maximale pour une commande donnée est limité par la pile de profil en cours d’utilisation, en conjonction avec la spécification applicable au cluster et le profil d’application. Une fragmentation sera utilisée le cas échéant.

Be Sociable, Share!
No Comments

Post A Comment