SDT_Components.md 17.2 KB

SDT Components

In this document an overview about the SDT 2.0 definitions and component hierarchy is given.

Contents

Domain
RootDevice | Device
   DeviceInfo
ModuleClass
   Action
   Data / DataPoint
      DataType
   Event
Doc

SDT Overview

The followng UML diagram presents an overview about the SDT components.

The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML diagram follows the following approaches:

Components

Domain

The Domain is the top-level component that defines all modules and devices of a domain. A Domain can import definitions of other domains.

A Domain can define Modules or RootDevices only, or may choose to provide both.

Attributes

  • id : The identifier for that Domain. Required.

Elements

  • Imports : XML import/include of other XML files. Optional.
  • Modules : A list of Module components that are global to the whole domain. Optional.
  • RootDevices : a List of RootDevices components. Optional.

Example

<Domain xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns="http://homegatewayinitiative.org/xml/dal/2.0" 
    id="org.homegatewayinitiative">
    <Imports>
      <xi:include href="./dal-core.xml" parse="xml" />
    </Imports>
    <Modules>
        <!-- List of Domain global Modules goes here -->
    </Modules>
    <RootDevices>
        <!-- List of RootDevices goes here -->
    </RootDevices>
</Domain>

RootDevice

A RootDevice is the definition of a physical device that may contain optional embedded sub-devices. It represents the idea an appliance that is addressable on a Home Area Network where one or more sub-Devices provide certain functionalities.

For each physical device on the network at least one RootDevice must be defined. If the physical device is a simple device, ie. it does not contain embedded devices, e.g. a light switch, it does not include further Devices. On the other hand, if the pyhsical is a compound device, ie. it does contain embedded devices that can be addressed separately, the RootDevice should contain Devices for each of the identifiable embedded devices.

There is also the possibility to have more than one RootDevice for one physical device if a physical device offers more than one distinguishable services or when it is for other reasons meaningful to deliberatly separate the device's services.

An example for a compound device is a connected power-strip where each of the sockets can be switched on and off individually. The power-strip itself can provide functions such as "all sockets off" and "overall power consumption".

If the RootDevice includes sub-Devices then each sub-device may be of the same type or of different types. The functionality (Actions) of the RootDevice may be different from the functionality of its sub-Devices.

If the RootDevice does not include sub-devices then the RootDevice is the actual adressable device that provides all the functionality of the connected appliance.

RootDevices may define their own ModuleClasses or refer to predefined ModulesClasses of the same or another Domain.

Attributes

  • id : The identifier for that RootDevice. The identifier must be unique at least in the scope of the domain, but the final scope is also influenced by implementing technologies. Required.

Elements

  • Doc : Documentation for the RootDevice. Optional.
  • Modules : A list of Module components that are local to the RootDevice. Optional.
  • DeviceInfo : Further meta-data about the RootDevice. Optional.
  • Devices : A list of Device components. Optional.

Example

<RootDevice id="aRootDevice">
    <Doc>Some documentation</Doc>
    <Modules>
        <!-- List of Modules local to the RootDevice goes here-->
    </Modules>
    <DeviceInfo>
        <!-- The DeviceInfos for the RootDevice goes here-->
    </DeviceInfo>
    <Devices>
        <!-- List of Sub-Devices of the RootDevice goes here-->
    </Devices>
</RootDevice>

Device

Devices are optional components of a RootDevice. They represent physical sub-devices inside another device (the RootDevice).

Devices may define their own ModuleClasses or extend ModulesClasses of its or another Domain.

Attributes

  • id : The identifier for that Device. The identifier must be unique at least in the scope of the domain, but the final scope is also influenced by implementing technologies. Required.

Elements

  • Doc : Documentation for the Device. Optional.
  • Modules : A list of Module components that are local to the Device. Optional.
  • DeviceInfo : Further meta-data about the Device. Optional.

Example

<Device id="aDevice">
    <Doc>Some documentation</Doc>
    <Modules>
        <!-- List of Modules local to the Device goes here-->
    </Modules>
    <DeviceInfo>
        <!-- The DeviceInfo for the Device goes here-->
    </DeviceInfo>
</RootDevice>

DeviceInfo

The DeviceInfo is an element of RootDevice or Device where a device vendor can provide metadata for a device that may be presented to an end-user.

Attributes

None.

Elements

  • Name : Vendor-specific name of a device. Required.
  • Vendor : Name of the vendor for the device. Required.
  • FirmwareVersion : Current version number of the firmware or other version information. Optional.
  • VendorURL : A URL that points to further information for that device. This might be the product page on the web or an URL to the device manual. Optional.
  • SerialNumber : The serial number or serial string. Optional.
  • Doc : Documentation for the DeviceInfo. Optional.

Example

<DeviceInfo>
    <Name>SomeDeviceName</Name>
    <Vendor>ACME</Vendor>
    <FirmwareVersion>1.0</FirmwareVersion>
    <VendorURL>http://www.example.com/</VendorURL>
    <SerialNumber>1234.5</SerialNumber>
</DeviceInfo>

Module, ModuleClass

The ModuleClass represents the concept of a reusable module that defines the Actions, Data and Events for a single functionality of a device. A connected device may contain or refer to single or multiple ModuleClasses to specify its inherent services it exposes for use by applications.

Modules represent instantiations of ModuleClasses.

ModuleClasses can be defined by a domain (on the level of the Domain component) or in RootDevices/Devices: The first are global to a Domain and can be used (refered to) by all RootDevices resp. Devices of a Domain; the later are local to the RootDevices/Devices where it is defined in. ModuleClasses defined on the Domain level can be imported, extended and used by other domains.

New ModuleClasses can be defined by extending existing ModuleClasses from the same or other domains to add new or overriding defined Actions, Data and Events.

Attributes

  • Name : Name of the ModuleClass. The name must be unique in the scope of the Domain. Required.

Elements

  • extends : Reference to a another ModuleClass that is extended with this ModuleClass. Optional.
    The element has the following attributes:
    • domain : Identifier / Reference of the Domain of the extended ModuleClass. Required when extends is specified.
    • class : Name of the ModuleClass in the Domain thet is extended.
  • Doc : Documentation for the ModuleClass. Optional.
  • Actions : A list of Action components, each defining a single action. Optional.
  • Data : A list of Data components. Optional.
  • Events : A list of Event components. Optional.

Example

<ModuleClass name="BooleanState">
    <Doc>Some documentation</Doc>
    <Actions>
        <!-- List of Actions goes here-->
    </Actions>
    <Events>
        <!-- List of Events goes here-->
    </Events
    <Data>
        <!-- List of DataPoints goes here-->
    </Data>
</ModuleClass>

Action

An Action defines a single procedure call for a ModuleClass. It is basically used for calling a function on a physical device in order to set or request data, or to invoke an action at a Device. #

It is also possible that an Action results in calling multiple functions on the device. Examples for this are the assembly of single function calls into one Action in order to provide sanity checks on the arguments, or for managing and fullfil transactional function calls on the device.

Attributes

  • name : The name of the Action. The name must be unique in the scope of the ModuleClass. Required.
  • type : The return type of the Action. It must comply to one of the defined DataTypes. Optional. If no type is specified the Action does not return a value.

Elements

  • Doc : Documentation for the Action. Optional.
  • Arg : Zero or more occurances of argument definitions for an Action. Optional.
    The Arg has the following attributes and elements:
    • name : The name of the Arg. Attribute. Required.
    • type : The type of the Arg. It must comply to one of the defined DataTypes Attribute. Required.
    • Doc : Documentation for the Arg element. Optional.

Example

The following are two examples for actions implementing a getter and a setter for boolean values.

<Action name="get" type="boolean">
    <Doc>Obtain the current associated state. Example of a getter.</Doc>
</Action>

<Action name="setTarget">
    <Doc>Set the associated state to the specified value. Example of a setter.</Doc>
    <Arg name="value" type="boolean">
        <Doc>The desired value of the associated state.</Doc>
    </Arg>
</Action>

Data

The Data component represents a list of DataPoints of a ModuleClass.

DataPoints serve to provide information to application developers about the internal structure, types and attributes of a device's data model. There are no implicite setter or getter actions to manipulate the data points directly. To do this, Actions must be defined and used explicitly.

Though DataPoints only refer to single data points of a physical device it is possible to describe hierarchies by model the path to the data point in the hierarchy by a path-like structure like to the pathname of a UNIX file system. Here, the root node of the hierarchy is a slash (/ 0x2F) and the segments or nodes along the path are also separated by slashes. The actual datapoint is the last leaf at the path.

In EBNF:

name          = dataPointName | "/" path ;  
path          = segment "/" path | dataPointName ;  
segment       = string ;  
dataPointName = string ;  
string        = (* character string excluding the character "/" *) ;

Attributes

None.

Elements

  • DataPoint : Zero or more occurances of DataPoints. Optional.
    A *DataPoint
    has the following attributes and elements:
    • name : The name (and possible path in a hierarchical data model) of the DataPoint. Attribute. The name must be unique in the scope of the ModuleClass.Required.
    • type : The type of the DataPoint. It must comply to one of the defined DataTypes. Attribute. Required.
    • writable : Boolean value that indicates whether this DataPoint is writable by an application. Attribute. Optional. Default: false.
    • readable : Boolean value that indicates whether this DataPoint is readable by an application. Attribute. Optional. Default: false.
    • eventable : Boolean value that indicates whether an internal or external change of this DataPoint raises an event. Attribute. Optional. Default: false.
    • Doc : Documentation for the DataPoint element. Optional.

Example

<Data>
    <DataPoint  name="attributeName" type="string" writable="false">
        <Doc>Some documentation for the DataPoint</Doc>
    </DataPoint>
</Data>

DataType

The following DataTypes can be used in the SDT's Action, Arg and DataPoint elements and attributes. If not stated otherwise datatypes should comply to the equivalent datatypes defined in XML Schema Part 2: Datatypes Second Edition:


Event

An Event is a component that defines properties for events that are raised as reactions to changes in DataPoints of a Device's data model. These state changes can happen either through a device-internal change, e.g. a low battery level, or by external means, e.g. a user operates a switch or the temperature in a room rises beyond a certain threshold.

Attributes

  • name : The name of the Event. The name must be unique in the scope of the ModuleClass. Required.

Elements

  • Data : A list of Data components for an event's payload. Optional.
  • Doc : Documentation for the Event Element. Optional.

Example

<Event name="stateChanged">
    <Data>
        <DataPoint name="state" type="boolean">
        </DataPoint>
    </Data>
</Event>

Documentation

The Doc documentation element is optionally available in most components of the SDT. Its purpose is to provide a short documentation for the respective element. The documentation language should be English.

The text inside the Doc element can be structure using a very limited subset of HTML elements. The possible structuring is defined in EBNF as follows:

Doc            = "<Doc>" docContent "</Doc" ;
docContent     = docText | { paragraph | image } ;
docText        = { text | emphasizedText | boldText | monotypeText } ;
emphasizedText = "<em>" text "</em>" ;
boldText       = "<b>" text "</b>" ;
monotypeText   = "<tt>" text "</tt>" ;
paragraph      = "<p>" docText "</p>" ;
image          = "<img src=" url ">" "<caption>" text "</caption>" "</img>" ;
url            = "\"" (* valid URL *) "\"" ;
text           = (* XML text element *) ;

The intended use for each element is:

  • emphasizedText : Emphasize the included text, e.g. printing it in italics font.
  • boldText : Print the included text in bold font.
  • monotypeText : Print the included text in a monospaced fonttype, e.g. to emphasize source code.
  • paragraph : Structure the text in paragraphs.
  • image : Include an image in the text. The image is loaded from the specified URL and must include a caption text.