SixML - Description

Diese Seite beschreibt den Austausch von Nachrichten, mit denen Klienten die Eigenschaften von Geräten und den zur Verfügung stehenden Diensten erfahren. Description-Nachrichten stellen die größten Nachrichten im SCF-Framework dar. Sie werden daher idealerweise nur einmalig bzw. nach Geräteänderungen angefragt, anderenfalls sollten sie aus einem lokalen Cache geladen werden.

 

 

Gerätebeschreibung

Nach dem Empfang von Discovery-Nachrichten müssen Klienten über die von Geräten zur Verfügung gestellten Dienste informiert werden. Entspricht das gecachte DeviceDescriptionDate nicht dem Datum aus der Discovery-Nachricht oder hat der Klient keinen Platz für einen Cache, muss die Beschreibung vom Gerät abgefragt werden.

DeviceDescriptionRequest

Der Klient schickt dazu eine Nachricht mit folgendem Aufbau:

DescriptionRequest.Device, DeviceID	

24-1-20-42-1-20-0

1 Byte                                  24                                      DescriptionRequest
  1 Byte                                1                                       
  1 Byte                                20                                      DeviceDescription
1 Byte                                  42                                      DeviceID
  1 Byte                                1                                       
  1 Byte                                20                                      20
1 Byte                                  0                                       EndOfPacket

<DescriptionRequest class="DeviceDescription" >
  <DeviceID>20</DeviceID>
</DescriptionRequest>
	

DeviceDescriptionResponse

Die Antwort des Gerätes hat den folgenden beispielhaften Aufbau:

DescriptionResponse.Device, DeviceID, DeviceExpectedLifeTime, DeviceName, DeviceLocation, DeviceDescriptionTag*, ServiceDescriptionContainer [...]*
	
25-2-20-01-42-1-20-43-2-00-30-44-5-76-105-103-104-116-48-3-03-00-00-49-2-01-244-70-11-72-01-03-73-01-03-75-03-09-00-00-70-11-72-01-20-73-01-20-75-03-16-00-00-70-15-72-01-40-73-01-40-79-02-19-136-75-03-16-00-16-70-11-72-01-01-73-01-01-75-03-16-00-128-0
	
1 Byte                                  25                                      DescriptionResponse
  1 Byte                                2                                       
  2 Bytes                               20-01                                   class:DeviceDescription;result:Ok
1 Byte                                  42                                      DeviceID
  1 Byte                                1                                       
  1 Byte                                20                                      20
1 Byte                                  43                                      DeviceExpectedLifeTime
  1 Byte                                2                                       
  2 Bytes                               00-30                                   HexValue:0x00-1E;DecValue:30
1 Byte                                  44                                      DeviceName
  1 Byte                                5                                       
  5 Bytes                               76-105-103-104-116                      Light
1 Byte                                  48                                      DeviceLocation
  1 Byte                                3                                       
  3 Bytes                               03-00-00                                DiningRoom
1 Byte                                  49                                      DeviceDescriptionTag
  1 Byte                                2                                       
  2 Bytes                               01-244                                  Lamp
1 Byte                                  70                                      ServiceDescriptionContainer
  1 Byte                                11                                      
      1 Byte                            72                                      ServiceID
        1 Byte                          1                                       
        1 Byte                          03                                      3
      1 Byte                            73                                      ServiceType
        1 Byte                          1                                       
        1 Byte                          03                                      Persistence
      1 Byte                            75                                      ServiceFlags
        1 Byte                          3                                       
        3 Bytes                         09-00-00                                Implementation:Basic;SuppCtrlRequests:0x00;version:0.9
1 Byte                                  70                                      ServiceDescriptionContainer
  1 Byte                                11                                      
      1 Byte                            72                                      ServiceID
        1 Byte                          1                                       
        1 Byte                          20                                      20
      1 Byte                            73                                      ServiceType
        1 Byte                          1                                       
        1 Byte                          20                                      ServiceManagement
      1 Byte                            75                                      ServiceFlags
        1 Byte                          3                                       
        3 Bytes                         16-00-00                                Implementation:Basic;SuppCtrlRequests:0x00;version:1.0
1 Byte                                  70                                      ServiceDescriptionContainer
  1 Byte                                15                                      
      1 Byte                            72                                      ServiceID
        1 Byte                          1                                       
        1 Byte                          40                                      40
      1 Byte                            73                                      ServiceType
        1 Byte                          1                                       
        1 Byte                          40                                      DigitalOutput
      1 Byte                            79                                      ServiceDescriptionTag
        1 Byte                          2                                       
        2 Bytes                         19-136                                  Light
      1 Byte                            75                                      ServiceFlags
        1 Byte                          3                                       
        3 Bytes                         16-00-16                                Implementation:Basic;SuppCtrlRequests:0x01;version:1.0
1 Byte                                  70                                      ServiceDescriptionContainer
  1 Byte                                11                                      
      1 Byte                            72                                      ServiceID
        1 Byte                          1                                       
        1 Byte                          01                                      1
      1 Byte                            73                                      ServiceType
        1 Byte                          1                                       
        1 Byte                          01                                      Identification
      1 Byte                            75                                      ServiceFlags
        1 Byte                          3                                       
        3 Bytes                         16-00-128                               Implementation:Basic;SuppCtrlRequests:0x08;version:1.0
...
1 Byte                                  0                                       EndOfPacket

<DescriptionResponse class="DeviceDescription" result="Ok" >
  <DeviceID>20</DeviceID>
  <DeviceExpectedLifeTime HexValue="0x00-1E" >30</DeviceExpectedLifeTime>
  <DeviceName>Light</DeviceName>
  <DeviceLocation>DiningRoom</DeviceLocation>
  <DeviceDescriptionTag>Lamp</DeviceDescriptionTag>
  <ServiceDescriptionContainer>
    <ServiceID>3</ServiceID>
    <ServiceType>Persistence</ServiceType>
    <ServiceFlags Implementation="Basic" SuppCtrlRequests="0x00" version="0.9" />
  </ServiceDescriptionContainer>
  <ServiceDescriptionContainer>
    <ServiceID>20</ServiceID>
    <ServiceType>ServiceManagement</ServiceType>
    <ServiceFlags Implementation="Basic" SuppCtrlRequests="0x00" version="1.0" />
  </ServiceDescriptionContainer>
  <ServiceDescriptionContainer>
    <ServiceID>40</ServiceID>
    <ServiceType>DigitalOutput</ServiceType>
    <ServiceDescriptionTag>Light</ServiceDescriptionTag>
    <ServiceFlags Implementation="Basic" SuppCtrlRequests="0x01" version="1.0" />
  </ServiceDescriptionContainer>
  <ServiceDescriptionContainer>
    <ServiceID>1</ServiceID>
    <ServiceType>Identification</ServiceType>
    <ServiceFlags Implementation="Basic" SuppCtrlRequests="0x08" version="1.0" />
  </ServiceDescriptionContainer>
</DescriptionResponse>

Die Gerätebeschreibung besteht aus mindestens den folgenden Einheiten:

DeviceID	

Für DeviceID gelten die Bedingungen aus der Discovery.

DeviceExpectedLifeTime	

DeviceExpectedLifeTime ist 2 Bytes lang und wird in Minuten gemessen. Die minimal gültige Lebenszeit sind 30 Minuten, die maximal gültige Lebenszeit ist ein Tag (1440 Minuten).

DeviceName	

DeviceName enthält den Namen des Gerätes als Klartext und ist durch den Benutzer änderbar. Die Länge ist nicht fixiert, sie muss jedoch kleiner oder gleich 30 Bytes sein.

DeviceLocation 

DeviceLocation enthält die Geräteposition. Sie besteht aus den 3 Bytes { LocationID, LocationIndex, Floor }. Die Position ist durch den Benutzer änderbar.

DeviceDescriptionTag 

Das DeviceDescriptionTag beschreibt den Gerätetyp als vordefinierte Konstante, z.B. Heizung, Lampe oder Wetterdienst. Es kann z.B. genutzt werden, um bestimmte Geräteklassen zu erkennen oder um passende Icons zu wählen.

ServiceDescriptionContainer [ServiceID, ServiceType, ServiceFlags*] 

Um die Größe der Gerätebeschreibung zu begrenzen, werden die einzelnen Dienstbeschreibungen unabhängig versendet. Die Gerätebeschreibung enthält nur Basisdaten, um anschließend bei Bedarf über GetServiceDescription die komplette Dienstbeschreibung abzurufen. Innerhalb der Gerätebeschreibung enthält jeder ServiceDescriptionContainer mindestens die folgenden Untereinheiten:

ServiceID 

Die ServiceID dient der Identifikation von Diensten in Control- und Eventing-Nachrichten. Sie ist einmalig innerhalb des Gerätes und 1 Byte lang. Die ServiceIDs 0 sowie 250..255 sind nicht zulässig.

ServiceType 

Der ServiceType entspricht einer der definierten Konstanten oder ist herstellerspezifisch. Für standardisierte Dienste sind diese Information bereits hinreichend, da die zur Verfügung gestellten Werte und Aktionen sich aus dem entsprechenden Standard ergeben.

ServiceFlags 

Über das Tupel ServiceFlags wird der Klient über zusätzliche Eigenschaften des Dienstes informiert. Es ist 3 Bytes gross.

ServiceFlags.ImplementationStatus 

Dieses Flag wird im 3.Byte in der Maske 0x03 übertragen (2 Bit). Es gibt an, ob der Dienst die Basisfeatures unterstützt (Wert 0), alle Features (Wert 1) oder herstellerspezifische Erweiterungen enthält (Wert 2).

ServiceFlags.SessionSupport 

Dieses Flag wird im 3.Byte in der Maske 0x04 übertragen (1 Bit). Es gibt an, ob der Dienst die Nutzung von SessionIDs unterstützt, um klientenspezifische Antworten zu generieren.

ServiceFlags.SupportedControlRequests 

Diese Flags werden im 2. und 3.Byte in der Maske 0xFFF0 übertragen (12 Bit). Sie geben an, welche dienstspezifischen ControlRquests der Dienst unterstützt.

0x01 - SetServiceValue
0x02 - GetMetaValues
0x04 - GetDescriptiveValues
0x08 - GetPropertyValues
ServiceFlags.Version 

Die Version wird im 1.Byte übertragen. Sie besteht aus Haupt- und Unterversion, jeweils als BCD-kodierter Wert (0x35 wäre die Version 3.5).

 

 

Dienstbeschreibung

Nach Abruf der Gerätebeschreibung kann der Klient die komplette Beschreibung jedes Dienstes einzeln abrufen:

DescriptionRequest.ServiceDescription, DeviceID, ServiceID
	
24-1-21-42-1-20-72-1-1-0
	
1 Byte                                  24                                      DescriptionRequest
  1 Byte                                1                                       
  1 Byte                                21                                      ServiceDescription
1 Byte                                  42                                      DeviceID
  1 Byte                                1                                       
  1 Byte                                20                                      20
1 Byte                                  72                                      ServiceID
  1 Byte                                1                                       
  1 Byte                                1                                       1
1 Byte                                  0                                       EndOfPacket

<DescriptionRequest class="ServiceDescription" >
  <DeviceID>20</DeviceID>
  <ServiceID>1</ServiceID>
</DescriptionRequest>

DescriptionResponse.Service

Die Antwort des Gerätes hat den folgenden beispielhaften Aufbau:

DescriptionResponse.ServiceDescription, DeviceID, ServiceDescriptionContainer [ServiceID, ServiceName*, ValueType, ActionDescriptionContainer[...]* ]	

25-2-21-01-42-1-20-70-63-72-01-01-33-01-40-100-55-101-19-103-02-01-01-35-01-73-34-10-80-114-111-112-69-118-110-116-73-68-101-16-103-02-02-05-34-10-85-112-100-97-116-101-77-97-115-107-101-14-103-02-03-05-34-08-73-110-102-111-77-97-115-107-0

1 Byte                                  25                                      DescriptionResponse
  1 Byte                                2                                       
  2 Bytes                               21-01                                   class:ServiceDescription;result:Ok
1 Byte                                  42                                      DeviceID
  1 Byte                                1                                       
  1 Byte                                20                                      20
1 Byte                                  70                                      ServiceDescriptionContainer
  1 Byte                                63                                      
      1 Byte                            72                                      ServiceID
        1 Byte                          1                                       
        1 Byte                          01                                      1
      1 Byte                            33                                      ValueType
        1 Byte                          1                                       
        1 Byte                          40                                      Composite
      1 Byte                            100                                     CompositeDescriptionContainer
        1 Byte                          55                                      
            1 Byte                      101                                     CompositePartDescriptionContainer
              1 Byte                    19                                      
                  1 Byte                103                                     CompositePartProperties
                    1 Byte              2                                       
                    2 Bytes             01-01                                   compositeID:1;compositeValueType:UInt8
                  1 Byte                35                                      ValueUnit
                    1 Byte              1                                       
                    1 Byte              73                                      Events
                  1 Byte                34                                      ValueName
                    1 Byte              10                                      
                    10 Bytes            80-114-111-112-69-118-110-116-73-68     PropEvntID
            1 Byte                      101                                     CompositePartDescriptionContainer
              1 Byte                    16                                      
                  1 Byte                103                                     CompositePartProperties
                    1 Byte              2                                       
                    2 Bytes             02-05                                   compositeID:2;compositeValueType:UInt32
                  1 Byte                34                                      ValueName
                    1 Byte              10                                      
                    10 Bytes            85-112-100-97-116-101-77-97-115-107     UpdateMask
            1 Byte                      101                                     CompositePartDescriptionContainer
              1 Byte                    14                                      
                  1 Byte                103                                     CompositePartProperties
                    1 Byte              2                                       
                    2 Bytes             03-05                                   compositeID:3;compositeValueType:UInt32
                  1 Byte                34                                      ValueName
                    1 Byte              8                                       
                    8 Bytes             73-110-102-111-77-97-115-107            InfoMask
1 Byte                                  0                                       EndOfPacket

<DescriptionResponse class="ServiceDescription" result="Ok" >
  <DeviceID>20</DeviceID>
  <ServiceDescriptionContainer>
    <ServiceID>1</ServiceID>
    <ValueType>Composite</ValueType>
    <CompositeDescriptionContainer>
      <CompositePartDescriptionContainer>
        <CompositePartProperties compositeID="1" compositeValueType="UInt8" />
        <ValueUnit>Events</ValueUnit>
        <ValueName>PropEvntID</ValueName>
      </CompositePartDescriptionContainer>
      <CompositePartDescriptionContainer>
        <CompositePartProperties compositeID="2" compositeValueType="UInt32" />
        <ValueName>UpdateMask</ValueName>
      </CompositePartDescriptionContainer>
      <CompositePartDescriptionContainer>
        <CompositePartProperties compositeID="3" compositeValueType="UInt32" />
        <ValueName>InfoMask</ValueName>
      </CompositePartDescriptionContainer>
    </CompositeDescriptionContainer>
  </ServiceDescriptionContainer>
</DescriptionResponse>

Der Container für die Dienstbeschreibung besteht aus mindestens den folgenden Einheiten:

ServiceID	

ServiceID erlaubt die Zuordnung der abgerufenen Dienstbeschreibung. Sie entspricht der ServiceID aus dem dazugehörigen Request.

ValueType	

ValueType beschreibt den Variablentyp des diensteigenen ServiceValues. Der Dienst-Wert selbst ist nicht Teil der Beschreibung, da dies dem Cache-Konzept widersprechen würde. Er kann über die in Control definierte GetServiceValue-Nachricht abgerufen werden.

Die folgenden dienstspezifischen Einheiten sind optional:

ValueName	

ValueName enthält den Namen des diensteigenen Wertes. Die Länge ist nicht fixiert, sie muss jedoch kleiner oder gleich 30 Bytes sein. Für composite-Werte ist der ValueName leer.

ValueUnit	

ValueUnit enthält die optionale physikalische Einheit in einer wohldefinierten Form, welche unter Physikalische Einheiten beschrieben wird.

ServiceName	

ServiceName kann für eine weitergehende Dienstbeschreibung genutzt werden. Auch für standardisierte Dienste kann der ServiceName frei vergeben werden, er ist also nicht Teil des Standards. Die Länge ist nicht fixiert, sie muss jedoch kleiner oder gleich 30 Bytes sein.

Dienstbeschreibung - Aktionen

ActionDescriptionContainer [ActionID, ActionName, ArgumentDescriptionContainer [...]* ]	

Jeder Dienst kann Aktionen enthalten. Für jede Aktion des Dienstes wird eine ActionDescription geschickt. Jeder ActionDescriptionContainer enthält mindestens die folgenden Untereinheiten:

ActionID	

Die ActionID is einmalig innerhalb des Dienstes und 1 Byte lang. Die ActionIDs 0 und 255 sind nicht zulässig.

ActionName	

Der ActionName beschreibt die Aktion in menschenlesbarer Form (z.B. "SSwitch"). Die Länge ist auf 30 Bytes beschränkt.

ArgumentDescriptionContainer [ArgumentProperties, ValueName, ValueUnit*]	

Argumente werden im ArgumentDescriptionContainer übermittelt. Aus Platzgründen wird ein Teil der Eigenschaften im kombinierten Tupel ArgumentProperties (3 Bytes) übertragen:

ArgumentProperties {ArgumentID, ArgumentDirection, ArgumentType }	

Die ArgumentID is einmalig innerhalb der Aktion und 1 Byte lang. Die ArgumentIDs 0 und 255 sind nicht zulässig.

Die ArgumentDirection gibt an, ob das Argument ein Ein- oder Ausgabeparameter ist.

Der ArgumentType bestimmt den Variablentyp des Arguments (z.B. UInt8).

ValueName	

Der ValueName beschreibt das Argument in menschenlesbarer Form (z.B. "Res"), die Länge ist auf 30 Bytes beschränkt.

ValueUnit	

ValueUnit enthält die physikalische Einheit in einer wohldefinierten Form, welche unter Physikalische Einheiten beschrieben wird.

 

 

NACHRICHTEN