File Type Specification

Transcription

1 1 2 Device Description File Recom Annex V Approved for first release: Approved for second release: Approved for final release: San Ramon, CA, USA, Executive Summary 10 Ver. Editor Change Date 0.1 TM First Draft Nov 28, 2016 Device Description File Page 1/10

2 Table of Contents 1. Introduction Scope and Purpose Acronyms and Abbreviations Definitions Conformance Levels Changelog of the DDF Fehler! Textmarke nicht definiert References... Fehler! Textmarke nicht definiert EnOcean Alliance & EnOcean GmbH Documents... Fehler! Textmarke nicht definiert. 2. Device Description File Motivation... 5 Device Description File Page 2/10

3 Introduction 1.1. Scope and Purpose This document is intended for device manufacturer creating DDF (Device Description Files) and Companies developing a DDF Parser. DDFs are part of the ReCom (Remote Commissioning Specification) and are used to specify the ReCom features of the Device. Additionally the DDF is used as an Electronical Datasheet and shall fully describe the capabilities of the device, e.g. the used/supported EEP (EnOcean Equipment Profiles) and or GP (Generic Profiles), different other Device Capabilities, the Hardware and Firmware Revision and a Description of the Device. The DDFs is part of the simplification of integrating and commissioning in EnOcean Devices inside of Buildings/Smart Homes and the Internet of the thing and is part of the new Certification Program. The idea is that in the end each Device has its own ProductID for identification and using this ProductID the installer using a Tool can load the self-describing DDF for this Device and can plan/ install / commission in the Device into his EnOcean network or even the full building network. Chapter 1 mentions the general scope, acronyms, definitions contributors, Chapter 2 describes the DDF format and changes in the Format over time. Chapter 3 is an HowTo for writing a DDF Acronyms and Abbreviations DDF: Device Description File EEP: EnOcean Equipment Profiles GP: Generic Profiles ReCom: Remote Commissioning Definitions EURID: EnOcean Unique Radio Identifier Unique Device Address of each module. This was called ChipID earlier. BaseID: Alternative Sender Address which can used. The Base ID can be modified by a device and can be used to replace one module with another. Using Base ID as base for sending, allows a device to use 128 different addresses for sending telegrams Conformance Levels MUST: Device Description File Page 3/10

4 This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification. MUST NOT: This phrase, or the phrase "SHALL NOT", means that something is prohibited by the specification. SHOULD This word, or the word "RECOMMENDED", means that, in particular cases, there may be valid reasons not to follow a point of the specification. However the full implications must be understood and weighed before choosing a different course SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" means that, in particular cases, there may be valid reasons where certain behavior is acceptable or even useful. However the full implications must be understood and weighed before choosing to implement anything described with this phrase. MAY This word, or the adjective "OPTIONAL", means that an item may or may not be implemented. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. In either case, both MUST be prepared to interoperate with each other, though perhaps with reduced functionality. 76 Device Description File Page 4/10

5 Device Description File 2.1. Motivation With the increasing complexity of use cases for Building automation/ Smart Homes and as Part of the Internet of things it is necessary that Device Installation becomes easier. Due to the limitation of the Energy Harvesting Devices and the EnOcean protocol, it is not possible that devices are describing them completely over the air, compared to other protocols. The DDF is a suggested solution to allow a device to describe itself completely. Each EnOcean Device, which has a Product ID, will have a DDF describing all the necessary features of the Device to Commission it into the network. The Product ID of a device can either be queried via ReCom or can be scanned from the QR Code if the Device does not Support Bidirectional Communication. All the information contained in the DDF allows an EnOcean network integrator to bind, and configure all devices as needed. The DDF uses a XML format for the description and a XSD is available for the validation of the XML Changelog of the DDF November 2016 ChipIDBased tag in TX has been renamed to EURID BaseIDBased tag in TX has been renamed to BaseID Properties type has been added to describe Device Property which are not configurable Parameters renamed to RecomParameters LinkEntry type added for EEP/GP tag for supported profiles to inform if a LinkEntry is used for the profile For RecomParameters the accesslevel (read/write or readwrite) and recommendeduserlevel (admin/user) attribute has been added. Product_ID: enforcing to use the 6Byte product id (2Byte Manufacturer ID + 4 byte Product Reference) LinkEntry Direction Ingoing renamed to Inbound and Outgoing to Outbound Juny 2016 Changes after the TWG Meeting: Tag SupportedRPC added for a list of RPC which are supported by the Device Param Type for Recom Device Paramaters has been reworked: o Text type added. Device Description File Page 5/10

6 o o o o Flag type removed. Data type has been replaced with Scaled type, which uses the EEP way for describing scaled parameters The device parameter can have a RPCWriteStartAddress and RPCWriteLength attribute to use the RPC Write command to modify the parameters. Length of parameters uses bytes for length description Version February 2015 First revision of the DDF available to the TWG Example DDF available In the ZIP folder 3 DDFs are available: Device_Description_File_ExamplePTM: A PTM device, which does not support any ReCom and only describes the send Profile Device_Description_File_ExampleSTM: A bidirectional Sensor device which allows the selection of the used profile Type via ReCom Device_Description_File_ExampleController: A complex Controller which support different ReMan/ ReCom devices DDF structure Overview Figure 1 XSD and XML A DDF is XML file which can be validated using the ReCom_Device_Description_Schema.xsd Device Description File Page 6/10

7 Structure Overview The root node of the DDF is Enocean_Devices and contains a fixed attribute schemaversion, to inform the parser about the schema used Figure 2 Root node and 1 and 2 Level Entries The root node consist out of a Device and for each Device the 6byte Product_ID needs to be added. Device Node (Requiered) : xs:string <Device Product_ID="0x AB"> Name Node (Requiered) : xs:string The first mandatory child Node is the Name of the Device, a string. Description Node (Requiered) : xs:string The required Description node is a clear text string description of the product. Firmware Version Node (Requiered) : xs:string attribute For each product reference the firmware version is fixed, and the used firmware version is written here. Hardware Version Node (Requiered) : xs:string The product reference code is unique for each Hardware Version, which is reflected here. Frequency Node (Requiered) : FreqType The Frequency Node informs which valid EnOcean Radio Frequency is used. Currently these are Device Description File Page 7/10

8 TX Node (optional ) The TX node informs which EEP and/or GP a Device is capable of Transmitting and if the Profile is transmitted using the EURID or a BaseID. Additionally the LinkEntry attribute is used for each Profile to inform if the used profile generated an outbound LinkEntry for a bidirectional Profile. If no LinkEntry attribute is used for the EEP or GP profile the None attribute shall be used. RX Node (optional ) The RX node informs which EEP and/or GP a Device is capable of Receiving. Additionally the LinkEntry attribute is used for each Profile to inform if the used profile generated an inbound LinkEntry for a Profile. If no LinkEntry attribute is used for the EEP or GP profile (e.g. if the profile is bidirectional outbound profile) the None attribute shall be used. LinkTable_MetaData (optional ) This optional node, informs if the Device supports an outbound and/or inbound LinkTable and how many entries each Table can have. DeviceParameters Node (optional ) The DeviceParameters Node contains three optional child nodes: Properties, RecomParameters and Applications. Properties are non-changeable Device Parameters, like a Temperature Threshold or a nonconfigurable Heartbeat of a Device. RecomParameters are Device Parameters which can be read or/and written via ReCom and change the device behavior. Applications are recommended ReCom settings for typical Use Cases for a Device. For example a Led Controller could contain Application Settings for Stand Alone use, use in an office, use for a residential home. Properties Node (optional ) Each Property Node consist out of a Param node. Each param node has a Name Node, a description node, a value node and an unit node. RecomParameters Node (optional ) The RecomParamaters node contains multiple param node. The ReCom parameter node can contain an RPCWriteStartAddress and RPCWriteLength attribute, which describes if a RPC write/read command can be used to read or write all parameters at once. Each param node has an index attribute, an accesslevel attribute which can be read,write or readwrite and describes if the parameter can be read and/or written. The recommendeduserlevel attribute is a recommendation which sort of users shall be normally able to change this Parameter. This can either be admin or user. An admin is user with deep technical understanding (e.g. the EnOcean Network Manager or the electrician installing the system) and a user is someone using the device at normal operation (e.g. the home owner who want to change a few Device Description File Page 8/10

9 paramters). Each param node contains a description and then can either contain the scaled, text, enum or pivate node. Scaled Node A scaled item, is a parameter which represent a rational number and is scaled to a rawvalue. The Length_In_Bytes describes how many bytes the parameter is using, the default_value node is the Out Of box value of this parameter. Range and Scale define how the conversion between the raw and real value works. The Unit is the physical unit of the parameter. Range Min and Range Max. The Range represents the starting-point and the end-point of the respective data inside the telegram coding. Scale Min and Scale Max. The scale, represents the starting-point and the end-point of the respective real value Figure 3 Conversion of scaled item Text Node The text node only contains the Length_In_Bytes to describe how many bytes the Text can be. The UTF8 encoding is used to store texts inside of the device. This parameter can be used e.g. to store a Location of a device. Enum Node The enum Node is used to describe a enum. The Enum node contains the Default_Value, the Length_In_Bytes and EnumList Node. The EnumList Node is a list of all available enums. Each enum consist out of a description and the index of enum. A range of enums can be compromised to a scaledenum_value, which uses the same rules as a scaled node for conversion. The attribute indexmin and indexmax is the same as rangemin and rangemax. This mixture can be e.g. used if certain Values have a special meaning and other Values represent a physical unit. A typical example would be a configurable Wakeup time. 0 could be described as no wakeup, could be minutes and 255 random wake up time. Private Node The private node contains the Default_Value and Length_In_Bytes node. Device Description File Page 9/10

10 Application Node (optional ) An application Node consists out of different App node. Each app node starts with a description and then a list of Parameters. Each param is referenced with the index attribute and the ConfigValue is the rawvalue of the parameter for this configuration Index_Linked_Parameters Node (optional ) The index linked parameters consists first out of list of parameters using the param structure like the RecomParameters Node. Afterwards the Links node follows, which consist out of LinkEntry nodes. A link node describes which parameters can be modified for which type of EEPS and if the parameters are available for the inbound or the outbound table. Afterwards the Application node follows, which describes again recommended values for certain use cases. LinkEntry Node The link Entry node first starts with a list of EEP Type, to inform for which EEP this link of parameter is valid. Then a list of param Nodes follow. Each node contains an attribute index, this is the index used in the previous Parameters parm node list. OptionalCommands Node (optional ) The OptionalCommand node can consist out of the ResetDevice/RadioLinkTest and RepeaterFunctions node to list additional ReCom commands which are supported by the device. SupportedRPC Node (optional ) The supported RPC list different RPC which are supported. Each rpc node consist out of the FunctionCode node and the ManufacturerID Device Description File Page 10/10