digitalstrom Basic Concepts

Transcription

1 digitalstrom Basic Concepts digitalstrom Version: v1.3-branch * August 19, 2015 * Revision: 3c451f5c0c98db7edb b d5d1 1

2 2012, 2013, 2014, 2015 digitalstrom Alliance. All rights reserved. The digitalstrom logo is a trademark of the digitalstrom alliance. Use of this logo for commercial purposes without the prior written consent of digitalstrom may constitute trademark infringement and unfair competition in violation of international laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. digitalstrom retains all intellectual property rights associated with the technology described in this document. This document is intended to assist developers to develop applications that use or integrate digitalstrom technologies. Every effort has been made to ensure that the information in this document is accurate. digitalstrom is not responsible for typographical errors. digitalstrom Alliance Building Technology Park Zurich Brandstrasse 33 CH-8952 Schlieren Switzerland Even though digitalstrom has reviewed this document, digitalstrom MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL DIGITALSTROM BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. NO DIGITALSTROM AGENT OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATION, EXTENSION, OR ADDITION TO THIS WARRANTY.

3 Contents 1 Introduction Introduction to the digitalstrom basics Organization of this document Structure Objects Circuit Zone Group Device Device Identification Area Cluster Server Apartment Topology Event Objects Device Level System Level High Level Information Flow Operating Concept Distributed Intelligence Scenes, Activities and Presets Function and group related scenes Basic Presets Stepping Area scenes Local push button Special scenes Temperature control scenes Group independent scenes Deep Off Standby Zone Active Auto Standby Absent Present Sleeping Wakeup

4 4.2.9 Door Bell Panic Fire Alarm Wind Rain Hail Local Priority Actions Scenes Calling a Scene Undo a Scene Store Current Value Activate Local Priority Set to Lowest Stepping Step Programming Mode Programming Mode Start Programming Mode Finish Configuration Read and Write Device Parameters Sensor Values Read Device Sensor Values Distribute Sensor Value Miscellaneous Device Identification (a.k.a. Blink ) Directly Set Output Value Function and group state machines 24 7 Communication Objects Device Level Physical Layer Downstream Upstream Automatic Repeat Query (ARQ) Latency Addressing Device Level Events Pushbutton Binary Input Event Status Event Sensor Event Table Limits System level communication

5 7.3.1 ds485 Protocol dsm-api Webservices Limits Pushbuttons Input Processing Timing Low-Level-Events way device pushbutton way zone or area button way device pushbutton way zone or area button System Interfaces Settings Event Limits Configuration Binary Inputs Low-Level-Events Input Types System Behavior Input Processing Glossary digitalstrom Device digitalstrom Ready Device dsuid - ds Unique Identifier dsid - SGTIN SGTIN GID Function-ID Vendor-ID Product-ID GTIN Certification Rules 41 A Structure Reference 43 A.1 Circuit A.2 Zone A.3 Group A.4 Device

6 B Scene Command Reference 44 B.1 Presets B.2 Stepping B.3 Area scenes B.4 Local pushbutton B.5 Special scenes B.6 Temperature control scenes B.7 Group independent scenes C Device Parameters 48 C.1 Class 0 - Communication Specific Parameters C.1.1 Local Programming Mode C.2 Class 1 - digitalstrom Device Specific Parameters C.2.1 Firmware Version C.2.2 Serial Numer C.2.3 Function ID C.2.4 Vendor ID C.2.5 Product ID C.2.6 Structure and adressing C.2.7 OEM/GTIN C.2.8 Sensor Equipment C.2.9 Binary Input Equipment C.3 Class 3 - Function Specific Parameters C.3.1 Output Mode C.3.2 Pushbutton Configuration C.3.3 Dimm Time C.3.4 Flashing Mode C.3.5 LED Configuration C.3.6 Local Pushbutton C.3.7 Configuration Flags C.3.8 OEM/GTIN C.4 Class 6 - Sensor Event Table C.5 Class 64 - Output status C.5.1 Current output status D Device Scene Table 61 D.1 Scene Value D.2 Configuration Bits E Device Sensors 63 F Device Registration 64 6

7 1 Introduction 1.1 Introduction to the digitalstrom basics This document describes the basic system concepts of the digitalstrom system. Intended audience are Hardware and Software developers that want to create applications that interact with digitalstrom installations. Sample applications can be: Smartphone applications that control digitalstrom installations Scripts running in the digitalstrom server that extend the functionality of the system or interface to cloud based services Integration of 3rd party hardware with digitalstrom The document assumes that the user has experience using the digitalstrom components, either in an installation or through a development kit. The document only covers the software aspects of the digitalstrom technology. Information about planning, installation and usage can be found in the following link: Organization of this document The information in this document is presented in the following chapters: Structure Objects describes the topology of an electrical installation from the digitalstrom point of view, see 2 Event Objects presents the different layers where events occur in the system and their handling, see 3 Scenes and Activities introduces the set of commands available within the digitalstrom system, and describes their specific scopes, see 4 Communication Objects details the basic communication concepts within a digitalstrom installation, see 7 Actions List the commands that are understood by all digitalstrom enabled devices, see 5 The glossary and appendixes provide detailed information about parts of the system, see 10 Certification rules List the rules that all applications or devices have to comply to be digitalstrom ready, see 11 7

8 2 Structure Objects The following sections describe the structural basis of a digitalstrom installation. The structure objects need to be seen from a logical point of view. Although these objects represent real parts of the building they are defined to have a simple model of the installation. This is the basis for ease of use and Plug n Play mechanisms. 2.1 Circuit The power circuit is the natural basic structure element of an installation. The circuit is the physical connection between the circuit breaker on one end and each electric device connected on this line on the other end. 2.2 Zone A zone is the logical representation of the rooms, halls and other structural works of the building. In digitalstrom installations a zone is a logical combination of one or more power circuits or of one more subsets of a power circuit. In the simple case a power circuit completely covers solely one room, in this scenario there is a single zone object defined for this room which consists of the whole circuit and its electric devices. A power circuits often spans over multiple rooms, then the physical circuit can be split into multiple logical zones corresponding to the users usage behavior. 2.3 Group A group is the application class of devices. digitalstrom defines application groups to reflect the common usage of devices in buildings. Those predefined groups allow to have a simple system setup as all digitalstrom Ready Devices have their standard group preconfigured. All devices of the same application within the same zone are operated together per default. Some applications are not existing in the context of a single zone, but only in the context of the whole house or apartment, e.g. ringing door bells. 8

9 Group ID Name Color Application 1 Lights Yellow Room lights 2 Blinds Gray Blinds or shades outside 12 Curtains Gray Curtains and blinds inside 3 Heating Blue Heating 9 Cooling Blue Cooling 10 Ventilation Blue Ventilation 11 Window Blue Windows 48 Temperature Control Blue Single room temperature control 4 Audio Cyan Playing music or radio 5 Video Magenta TV, Video 8 Joker Black Configurable n/a Single Device White Various, individual per device n/a Security Red Security related functions, Alarms n/a Access Green Access related functions, door bell Table 1: digitalstrom application groups and their colors Devices assigned to the function Joker are customizable and in most cases the hardware allows them to be used with different consumer devices. For example the relay adapter plug or a wall push button input line can be assigned by the user to that application that they are used for. Devices of the category Single Device are not grouped in general. There are devices for which a group behavior and collective operation is not wanted anyhow. Common examples are vacuum cleaner, coffee machine, or the garage door. The security and access related functions are global apartment-wide applications and therefore do not have a status or relation to a particular zone. 2.4 Device A digitalstrom Device is an device with well defined system behavior and with digitalstrom communication capabilities. The digitalstrom Device is the combination of a terminal block with an attached native device. The digitalstrom Device is from the users point of view the complete piece of equipment, including all visible output values and input capabilities. This definition includes that a digitalstrom Device may be build out of multiple terminal blocks and components. The individual functions of digitalstrom Device are called Submodule. The Submodules are logically related to the functional groups depending on their use. Each submodule of a digitalstrom Device belongs exactly to one functional group and zone. A digitalstrom Ready Device is a device which complies to all rules of 9

10 the digitalstrom concept. Rule 1 A digitalstrom Ready Device has to be preconfigured in the right application group. This is essential to ensure that all electrical devices in one application group can be orchestrated together. Rule 2 A digitalstrom Ready Device must be configured for exactly one digitalstrom application group. The assigned application group must be non-ambiguous and is part of the static device configuration. Rule 3 The function of a devices output is the basis of its group membership. For devices without output function the target function of the switch button decides about the group membership. The concept of digitalstrom Devices is independent from the underlying technology of the communication hardware. Thus the digitalstrom system represents any kind of hardware equipment with the same methods, on condition that the hardware has communication capabilities and can be uniquely identified. For example technologies and products like the digitalstrom Powerline Terminal Blocks, TCP/IP network equipment, radio equipment, or in general components of other bus communication systems can be seamlessly integrated with the appropriate gateway functionality. 2.5 Device Identification digitalstrom Terminal Blocks are uniquely identified by a 32 bit serial number. This number is stored in non-volatile memory on the device and can be read programmatically by the system. Terminal Blocks itself are described by a global trade item number (GTIN, see glossary, 10.10). If the digitalstrom Device is combined with the Native Device this new article shall get a new GTIN, additionally to that one of the Native Device. This new GTIN can be stored on and read from the Terminal Block. The serial number of the Terminal Block and the GTIN of the article are then combined to build a so-called serialized global trade item number (SGTIN). The GTIN and SGTIN are standardized formats for identifying trade items, this standard is written by and under control of the GS1 organization. Following the SGTIN-96 standard the digitalstrom system identifies any digitalstrom Device with an unique number called dsid (see glossary 10.4). 2.6 Area An area is built by a subset of devices within a zone. This is a user definable set of devices. This is achieved by individual device configuration and is not based on an addressing mechanism. 10

11 2.7 Cluster A cluster is built by a subset of devices of the same group from any zone. This is a user definable set of devices. All devices in a cluster share something common, for example Clusters can be defined for: all shades in the first floor the shades with orientation to the south all lights that are part of the christmas illumination The devices of a Cluster are still part of their respective zone and are under control of the room group operations. 2.8 Server The digitalstrom Server is the appliance where user specific extensions and adjustments to the digitalstrom system behavior can be implemented. These adjustments are individual to each user and therefore not part of the system behavior. More details of the user customization is in chapter 3.3. For example the digitalstrom Server Addon User Defined Actions gives the user advanced control over certain events and how his digitalstrom installation should behave. Furthermore the server appliance allows the user to have advanced automation and personalized functionality. There is exactly one instance of server per digitalstrom installation. The server is acting as a gateway between the digitalstrom components and the network or Internet and makes the digitalstrom system accessible from virtually anywhere. 2.9 Apartment The apartment is the logical totality of all digitalstrom components connected together in one installation Topology 11

12 Figure 1: digitalstrom Topology 3 Event Objects The digitalstrom concept is based on a hierarchical architecture. Three context levels communicate bidirectional using event objects on different abstraction levels. The Device level is represented by digitalstrom Devices, the System layer has a logical context in the zone and is physically represented by a digitalstrom Meter, and the User level which is present on the digitalstrom Server and its system customization through user definable actions and automatisms. 3.1 Device Level On the device level digitalstrom generates Low-Level-Events to signal and forward events to the system. Low-Level-Events are caused by sensor input data that is preprocessed through device specific decision engines and state machines. Device level events do not have a context, they are not bound to 12

13 a zone or functional group. Examples for Low-Level-Events are the events generated if a wall switch is pressed and a device on-off switch is toggled. 3.2 System Level The system layer processes Low-Level-Events, adds the context information of the event, and generates System-Level-Events. The event context consists of the corresponding zone of the device where the event occurred, the target function and color group of the device and the current state of the functional group in the specific zone. System-Level-Events are sent downstream as system actions and are forwarded upstream. Low-Level-Events without relevance on the system layer may bypass the system level processing and will only be forwarded to upper layers. For example the commands to turn the lights in a room on and to open the blinds are System-Level-Events. 3.3 High Level The highest layer receives System-Level-Events and provides them and additionally the system state for further processing and for external applications. The System-Level-Events are evaluated by user level applications and enables them to generate appropriate response actions taking user behavior and user defined parameters into account. The user level descriptions Turn light on in living room and Breakfast are examples for High-Level-Events. With digitalstrom Server modules the user is able to define his own personalized event descriptions and thus to create a customized system behavior. For a few High-Level-Events it is very likely that any user has the same understanding of the event meaning. Those High-Level-Events with high standardization potential are mapped directly to System-Level-Events, for example the door bell signal. 3.4 Information Flow The following graph illustrates the information flow between the three layers. 13

14 Figure 2: digitalstrom Information Flow 14

15 3.5 Operating Concept The functional groups and the zone are the central objects of the digital- STROM operating concept (6). Calling presets for groups in a zone is the basic method to control digitalstrom devices. Therefore this standard defines the default preset values for devices in each group to guarantee the well defined system behavior. Those default presets are subject of the particular functional group documents. From users point of view the room wall switches are the direct interface to the operating concept. For example a traditional light switch is expected to turn the lights in a room on and off. A digitalstrom wall switch behaves exactly like that, if the underlaying digitalstrom pusbbutton device and the corresponding digitalstrom light actuators belong to the light group. This Plug n Play mechanism uses an autodetection of device configuration and capabilities (F). 3.6 Distributed Intelligence A central aspect of the digitalstrom topology is the distributed intelligence. On device layer any digitalstrom Device has the knowledge how to react to System-Level-Events (see 4), and on the system layer the logic is split into the electrical circuits. Due to the distributed logic there is no need for a central communication management and the configuration complexity is reduced. Furthermore the overall system reliability is inherently increased. 15

16 4 Scenes, Activities and Presets A scene is the command that is sent to a group of devices and results in changes of output actuator states. Each digitalstrom Device keeps a table of preset values locally and knows how to react to scene commands. Every digitalstrom Ready Device has a well defined default scene configuration depending on its functional group. These standardized values ensure system compatibility and guarantee that future products and devices will behave harmonically in the existing infrastructure. The actuator change depends on the individual device configuration. Though there are the preset values defined, this configuration can be modified by the user to adopt device behavior to his needs. This personalization is the basis for creating different preconfigured scenarios which can be activated by a single scene command. Scenes directly correspond to System-Level-Events. An activity is the process of posting a scene command, in the API documentation also referred as call scene. On device level scene commands may have different effects: setting an absolute output value for each output channel relative output value changes stopping an output value change process, applies to actions that take longer time to complete ignoring the command and not to react on a specific scene temporary changing the output state for signalling or identification purposes Details of the scene configuration are explained in appendix Device Scene Table. The digitalstrom system implements 128 scene commands. The first half of 64 scenes is used for group specific actions, the second half are used in the context of a zone or for system wide functions. The group related scenes may have different meanings depending on the functionality of the group. For example the activities Light On and Open Blinds share the same scene command. Rule 4 digitalstrom Devices have to implement a default behavior for all 128 scene commands. The system behavior and default values are defined in the particular documents for each functional group. 16

17 4.1 Function and group related scenes The first 64 scene commands are related to the functional group. The intended behavior and the resulting preset is group dependent. The command is transferred using a multicast addressing scheme and is executed by every device that is part of the target group (addressing detailed in ). On the system layer the zone and group state machines track the activities and keep the status of the currently active scene. Thereby the system layer is able to implement state dependent behavior 6. Rule 5 When applications send a scene command to a set of digitalstrom Devices with more than one target device they have to use scene calls directed to a group, splitting into multiple calls to single devices has to be avoided due to latency and statemachine consistency issues. Section B defines the details of the terms and values Basic Presets digitalstrom defines 5 sets of basic presets per functional group. Each of these sets has different scene commands and separate configuration values in the digitalstrom Devices. For example the presets for room lights are defined as follows: Activity Description Preset 0 Lights off Preset 1 Lights on Preset 2 Lights on, Brightness 75% Preset 3 Lights on, Brightness 50% Preset 4 Lights on, Brightness 25% Auto Off Lights fading slowly off Table 2: Light Preset Stepping digitalstrom defines scene commands for stepping or dimming operations. Those commands increment or decrement the output value of actuators by a defined delta value. Rule 6 digitalstrom Ready Devices must ignore stepping commands if their output value is zero Area scenes digitalstrom defines 4 subsets of a group in a zone, called areas. The system implements distinct area commands for On/Off and stepping operations. 17

18 4.1.4 Local push button digitalstrom defines special scenes commands to reflect the usage with a device switch operated locally. These operations include Local On, Local Off and Local Stop Special scenes digitalstrom defines special scene commands for forcing the device to set the output value to maximum and minimum value. An additional scene command forces an output value change process to be stopped immediately Temperature control scenes The room temperature control group uses its own set of system-level-events to control the system behavior of the control algorithm. Each control scene is related to a predefined behavior and is associated with setpoint values for the temperature. 4.2 Group independent scenes The second half of 64 scene commands have a group independent meaning. Some of them are standardised High-Level-Events (e.g. Wakeup or Sleeping). Others are used for system wide functions (e.g. Absent, Door Bell), which are either a signal or an apartment state. Section B.7 defines the details of the terms and values Deep Off The activity Deep Off indicates that a zone is inactive and the user won t need the digitalstrom Devices in this single zone for a longer time. digital- STROM Ready Devices shall turn their power off. Devices with an integrated LED should indicate this state and turn it off Standby The activity Standby indicates that a zone is inactive but the user might return in a short term. digitalstrom Ready Devices shall switch to a standby mode Zone Active The activity Zone Active indicates that a zone will become active in a short term and devices should be prepared to be powered on. 18

19 4.2.4 Auto Standby The activity Auto Standby indicates that a zone is inactive. This signal is mainly provided to be generated automatically Absent The activity Absent indicates that the residents left their home. Devices which do not have to be necessarily on should turn their power off. This is an apartment state and will be reset by the Present scene command Present The activity Present indicates that the residents came back to their home. Devices that the user expects to be immediately availabe should turn their power on or go into standby mode Sleeping The activity Sleeping indicates that the apartment switches to night operation and the residents go to sleep Wakeup The activity Wakeup indicates that the apartment switches to daytime and the residents wake up. Devices which are likely to be used in the morning should be prepared to be powered on Door Bell The activity Door Bell indicates that someone is standing in front of the house door and wants to get in. This is a signal and does not change any group or zone states Panic The activity Panic indicates that the user is scared and believes there is someone in the apartment who should not be there. digitalstrom Ready Devices shall switch to a protection state. This is an apartment state and will be reset by the associated undo scene command (see 5.1.2) Fire The activity Fire indicates an active fire alarm and is meant as an additional alarm signal for the residents. This is an apartment state and will be reset by the associated undo scene command (see 5.1.2). 19

20 Alarm The activities Alarms [1..4] indicate an active alarm and is meant as an user defineable alarm signal for the residents. This is an apartment state and will be reset by the associated undo scene command (see 5.1.2) Wind The activity Wind is a signal to protect equipment and hardware of being damaged by high wind force or gust. This is an apartment state but can be used in a cluster as well. The state is reset by the associated No Wind activity Rain The activity Rain is a signal to protect equipment and hardware of being damaged by rain and water. This is an apartment state. The state is reset by the associated No Rain activity Hail The activity Hail is a signal to protect equipment and hardware of being damaged by a hail storm. This is an apartment state but can be used in a cluster as well. The state is reset by the associated No Hail activity. 4.3 Local Priority The local priority is a special device state where usually scene commands with group relation are ignored. This state is triggered by local push button presses on the device itself or by a particular device action command which is used by the zone state machine for area scene commands (see 5.1.4). The intended behavior for the local priority is to allow the device to keep its locally requested state even if the zone/group state is changed by the user. This state is reset by turning the device locally off or by specific scene commands that force to change the output state regardless of the local priority. For example the system wide function Absent shall have an effect on room lights regardless if they were turned on locally. 20

21 5 Actions A digitalstrom Device must understand the actions detailed in this section. 5.1 Scenes The scene actions can be sent to: a group of devices in a zone all devices in a zone all devices of a group in any zone a single device Calling a Scene The digitalstrom Device executes the given scene command and changes the output state according to its scene table value and configuration flags. The scene and state is valid until another scene command is executed. If the device is in the local priority state the scene is only executed if the IgnoreLocalPrio flag is set in the scene table for the called scene. The execution of this command can optionally be forced and regardless of current local priority state Undo a Scene The digitalstrom Device reverts all effects of the currently executed scene and executes the previously active scene. Only one previous scene command has to be stored. If no previous scene command is available this call shall be ignored. The action can be constrained to only revert a specific scene command Store Current Value Persistently store the current value of the digitalstrom Device s output in the scene table at the given scene command Activate Local Priority If the digitalstrom Device is currently executing the given scene, activate the local priority state. This action remotely sets the local priority state for a group of devices. 21

22 5.1.5 Set to Lowest Stepping Step Prepare the digitalstrom Device to start stepping from the off state. If the scene table contains a non zero value at the given scene number execute the scene according to the scene table but set the output value to the minimal stepping value instead of the value in the scene table. This action is necessary for stepping operations when the state of the addressed group is Off. Compare to the rule for scene commands Stepping, where stepping commands are to be ignored for devices in the Off state. 5.2 Programming Mode The programming mode actions are used internally by the digitalstrom Meter to control the wall switch scene programming operation Programming Mode Start This action indicates the start of a programming operation. Operate the digitalstrom Device s output in order to identify the device in the installation. The operation must complete within 4 seconds and the device must return to the previous state afterwards. Also prepare the device for scene table programming. Rule 7 digitalstrom Device have to complete the identification action on the command Programming Mode Start within 4 seconds Programming Mode Finish This command indicates the end of a programming operation. Operate the digitalstrom Device s output in order to identify the device in the installation. The operation must complete within 4 seconds and the device must return to the previous state afterwards. 5.3 Configuration Read and Write Device Parameters For configuration purposes a digitalstrom Device must support the reading and writing of device parameters. The device parameters are detailed in appendix sections C and D. Rule 8 Application processes that do automatic cyclic reads or writes of device parameters are subject to a request limit: at maximum one request per minute and circuit is allowed. 22

23 5.4 Sensor Values Read Device Sensor Values digitalstrom Devices with sensor equipment provide a table with entries for each available sensor. The table entries and the corresponding measurements are detailed in C.2.8 and E. Rule 9 Application processes that do automatic cyclic reads of measured values are subject to a request limit: at maximum one request per minute and circuit is allowed Distribute Sensor Value The command distributes a single numerical measured value. The measurement can be sent to: a group of devices in a zone all devices in a zone all devices of a group in any zone digitalstrom Devices may change their output state depending on their type and configuration. 5.5 Miscellaneous Device Identification (a.k.a. Blink ) Operate the digitalstrom Device output in order to identify the device in the installation. For example for a light device: on-off-on-off or a shade device: up-down-up-down Directly Set Output Value Unconditionally set the digitalstrom Device s output value. The current local priority state is ignored. Rule 10 The action command Set Output Value must not be used for other than device configuration purposes. 23

24 6 Function and group state machines The Low-Level-Events generated by devices are received and interpreted by the digitalstrom Meter. The digitalstrom Meter translates these events (7.2) into actions (5). This translation process takes several parameters into account, like type and group membership of the originating device. The translation is done according to function specific state machines (SM). These state machines define the user visible behavior of a digital- STROM system. The SMs each have a state per context appropriate to the function (e.g. per function and zone, per function in an installation, per installation). The state machines are also responsible for the handling of STOP actions in functions where it is required. For a detailed description of the behavior refer to the function specific state machine documents. 24

25 7 Communication Objects 7.1 Device Level Physical Layer The transfer direction of events from device to system level is called upstream, the system to device event transfer direction is the downstream direction Downstream Downstream data is sent by the digitalstrom Meter and received by any digitalstrom Device on the same power circuit. The downstream commands are received by all devices but only processed by previously selected devices and ignored by all others Upstream Upstream data is sent by the digitalstrom Device and received by the digitalstrom Meter on the same power circuit. Other digitalstrom Devices on the same power circuit do not receive the upstream event data Automatic Repeat Query (ARQ) In case of parallel transmissions of upstream data by two or more digital- STROM Devices the event data may not be received by the digitalstrom Meter. To guarantee delivery of event data the system implements an automatic repeat query mechanism. An automatic retransmission of the event data takes place if the upstream reception is not acknowledged within a defined timeout period. Generally there is an explicit acknowledge command necessary, but several actions can make use of an implicit acknowledge by reception of downstream scene commands Latency Event transfer over the power line takes noticeable time, which increases in case of retransmissions. The overall latency of typical actions is shown in table 3. Description Latency in ms Pushbutton tip to resulting system level event reception by devices 600 Query of device parameter to reception of value 1200 Downstream transmission of zone/group scene command to reception by devices 250 Table 3: Latency of typical operations 25

26 7.1.5 Addressing The downstream communication implements three different levels of addressing. Broadcast Broadcast addressing is defined both for zones and groups. A zone number of zero indicates that a downstream command is directed to all devices regardless of their zone membership. A group number of zero indicates group broadcast addressing and the downstream command is directed to all devices regardless of their group membership. Group and Cluster Sending commands to a specific group or cluster within a zone is known as multicast addressing. This method is preferred for scene commands. Device Unicast addressing to a single device is the slowest transfer mechanism. This method is mainly used for configuration purposes. 7.2 Device Level Events Events on device level are generally created due to any sensor input data being available. The sensor data is then evaluated and preprocessed by device specific decision engines and state machines. If the pushbutton configuration is local device mode the device decides about local actions it has to take. If the device is about to change its output state it has to send this information upstream. If the pushbutton configuration is system mode the event information has to be sent upstream. System mode includes zone pushbuttons, area pushbuttons, application mode, any mode which is not exclusive processed locally in the device Pushbutton Pushbutton event data include a button index and the type of key press. Details of this event are defined in section 8. Pushbutton events are used as direct input to the system state machines (6) Binary Input Event Binary input events are generated by level triggered input lines. They have the binary states on or off. Binary input events are used as direct input to the system state machines (18). 26

27 7.2.3 Status Event digitalstrom Devices can generate events depending on status changes of internal applications. This includes malfunctions, error conditions and device specific notifications Sensor Event Table digitalstrom Devices may implement a generic preprocessing algorithm which allows generation of events depending on thresholds of sensor input data. The thresholds and limits for the preprocessing algorithm are stored in well defined table format in the digitalstrom Device. Details of the event table format are defined in the appendix Class 6 - Sensor Event Table. The event data includes the index of the triggering table row. This index is unique only per device. These table index events are device specific and therefore not system relevant and bypass the system state machines. They are signalled on the user level Limits digitalstrom Ready Devices must ensure that they do not monopolize the upstream data channel. They must have a transmission control algorithm that controls the upstream event data rate. Rule 11 digitalstrom Ready Devices must not send upstream events continously and must stop sending Low-Level-Event data even if the event is still or repeatedly valid. Transmission of pushbutton events must be abondoned after a maximum time of 2.5 minutes. Automatically genereated events must not exceed a rate limit of 10 events per 5 minutes. 7.3 System level communication digitalstrom uses a central communication controller digitalstrom Meter (dsm) on each power circuit placed directly behind the circuit breaker. The dsm s are connected among themselves and with the digitalstrom Server over a RS485 line and communicate using the ds485 protocol ds485 Protocol The ds485 protocol is a data link layer communication protocol running over a shared medium. The protocol implements token passing medium access control and thus guarantees a fair scheduling of transmission requests dsm-api The dsm-api is the application layer protocol to interface with the digital- STROM components. From external application side the dsm-api is an in- 27

28 ternal interface, enclosed in the digitalstrom Server and should not be used directly Webservices The digitalstrom Server provides webservice interfaces for external applications. This interface includes a more abstract representation of the digitalstrom components and a convenient data model. Rule 12 Applications shall use the digitalstrom Server webservice interface for communication with the digitalstrom system. Directly interfacing the dsm-api shall be avoided because it is an internal interface and its API may change in the future Limits Applications must ensure that they do not monopolize the downstream data channel. Therefore they have to take that scene commands are not executed at a arbitrary rate. Rule 13 Applications that automatically generate Call Scene action commands (see 5.1.1) must not execute the action commands at a rate faster than one request per second. 28

29 8 Pushbuttons The term pushbutton refers to the input line of a digitalstrom terminal block for wall switches or the on-off switch of electrical devices. digital- STROM requires to use pushbuttons instead of switches to be able to enhance the simple on-off functionality. digitalstrom Devices are able to detect in which manner the user activated the button, for example a single tip, a hold operation, or fast sequence of consecutive tips. 8.1 Input Processing Timing Depending on the duration and pulse duty of pushbutton tips different events are generated. The following table defines the timing requirements of the pushbutton evaluation. A H (High) means the button input is Active, a L (Low) means the input is inactive. Pushbutton Event Single Tip Double Tip Triple Tip Quadruple Tip Hold Start Single Click Double Click Triple Click Short-Long Short-Short-Long Timing 140ms <= H < 500ms 140ms <= H < 500ms, L < 800ms, 140ms <= H < 500ms 140ms <= H < 500ms, L < 800ms, 140ms <= H < 500ms, L < 800ms, 140ms <= H < 500ms 140ms <= H < 500ms, L < 800ms, 140ms <= H < 500ms, L < 800ms, 140ms <= H < 500ms, L < 800ms, 140ms <= H < 500ms a H >= 500ms b H < 140ms H < 140ms, L < 140ms, H < 140ms H < 140ms, L < 140ms, H < 140ms, L < 140ms, H < 140ms H < 140ms, L < 140ms, H>= 500ms H < 140ms, L < 140ms, H < 140ms, L < 140ms, H >= 2500ms a Subsequent tips start again at generating Double-Tip signals and wrap around each 3 tips: Single Tip - Double Tip - Triple Tip - Quadruple Tip - Double Tip - Triple Tip - b After initial Hold Start detection each second a Hold Repeat signal is generated. After the button input is released a Hold End signal is generated. Table 4: Pushbutton timing 29

30 8.2 Low-Level-Events A pushbutton operates either in device or in zone mode, and it may have one (1-way) or two input lines (2-way). Depending on this configuration the pushbutton has a different system behavior. In device mode some operations are executed only locally. The pushbutton input events are encoded using a Click-Type and a Key- Number. The tupel of Click-Type and Key-Number identifies the kind of Low-Level-Event. Where Click-Type encodes the manner the button has been activated, the Key-Number is an index for the operating mode of the pushbutton depending on 1-way, 2-way and device or zone mode. The following sections describe the different Low-Level-Events generated by pushbutton clicks in dependence of the operation mode. The Low- Level-Event names listed in the tables below are used as input signal names in the state machine documentation of the particular functional groups. Notice The short-short-long sequence is always reserved for device internal use and configuration purposes way device pushbutton In device pushbutton mode the Single Tip events are processed locally and toggle the output state of the device. If the device output is in a slow change operation a Single Tip stops the change process. The Hold Start event is processed locally if the device output is active and step the output value alternately down and up. If the output is inactive the button hold operation sequence is signaled upstream with an initial Hold Start, consecutive Hold Repeat and a final Hold End event. The short-long sequence is processed locally and enables local configuration of the default scene values for Preset1 to Preset4. If digitalstrom Devices do not have an output the local pushbutton mode is not supported. Pushbutton Event Click type Key Number Low Level Event Name Single Tip 11 4 LOCAL_ON Hold Start 4 4 HOLD_START Hold Repeat 5 4 HOLD_REPEAT Hold End 6 4 HOLD_END Table 5: Output off or inactive 30

31 Pushbutton Event Click type Key Number Low Level Event Name Single Tip 10 4 LOCAL_OFF Table 6: Output on or active Pushbutton Event Click type Key Number Low Level Event Name Single Tip 14 4 LOCAL_STOP Table 7: Output is currently changing Pushbutton Event Click type Key Number Low Level Event Name Double Tip 1 4 TIP_2X Triple Tip 2 4 TIP_3X Quadruple Tip 3 4 TIP_4X Single Click 7 4 CLICK_1X Double Click 8 4 CLICK_2X Triple Click 9 4 CLICK_3X Table 8: Output in any state way zone or area button There is no local processing of input events in zone or area mode. All events are forwarded upstream regardless of the device output state. Pushbutton Event Click type Key Number Low Level Event Name Single Tip 0 0 TIP_1X Double Tip 1 0 TIP_2X Triple Tip 2 0 TIP_3X Quadruple Tip 3 0 TIP_4X Single Click 7 0 CLICK_1X Double Click 8 0 CLICK_2X Triple Click 9 0 CLICK_3X Hold Start 4 0 HOLD_START Hold Repeat 5 0 HOLD_REPEAT Hold End 6 0 HOLD_END Table 9: Zone pushbutton Low-Level-Events way device pushbutton Pushbuttons with two input lines have designated Up and Down functions. Input on these buttons generate different Low-Level-Events than the 1-way button. 31

32 In device pushbutton mode the Single Tip events on both inputs are processed locally, tips on the Up input turns the device output on, tips on the Down input turn it off. The Hold Start event on both input lines is processed locally and step the output value accordingly up and down. Holding the Up button if the output is inactive turns the output on, if the output is capable of stepping with the lowest possible output value otherwise with the maximum output value. Holding the Down button if the output is active steps the output value down: if the device output is capable of stepping the output value is reduced down to the minimum value but not to the off state, switched mode outputs do ignore Hold Start events. If the output is inactive the button hold operation sequence on the Down input is signaled upstream with an initial Hold Start, consecutive Hold Repeat and a final Hold End event. The short-long sequence is processed locally and enables local configuration of the default scene values for Preset 0 4 to Preset If digitalstrom Devices do not have an output the local pushbutton mode is not supported. Pushbutton Event Click type Key Number Low Level Event Name Single Tip 11 5 LOCAL_OFF Hold Start 4 5 HOLD_START_DOWN Hold Repeat 5 5 HOLD_REPEAT_DOWN Hold End 6 5 HOLD_END_DOWN Table 10: Down input, output off or inactive Pushbutton Event Click type Key Number Low Level Event Name Single Tip 11 5 LOCAL_OFF Table 11: Down input, output on or active Pushbutton Event Click type Key Number Low Level Event Name Double Tip 1 5 TIP_2X_DOWN Triple Tip 2 5 TIP_3X_DOWN Quadruple Tip 3 5 TIP_4X_DOWN Single Click 7 5 CLICK_1X_DOWN Double Click 8 5 CLICK_2X_DOWN Triple Click 9 5 CLICK_3X_DOWN Table 12: Down input, output in any state 32

33 Pushbutton Event Click type Key Number Low Level Event Name Single Tip 12 6 LOCAL_ON Double Tip 1 6 TIP_2X_UP Triple Tip 2 6 TIP_3X_UP Quadruple Tip 3 6 TIP_4X_UP Single Click 7 6 CLICK_1X_UP Double Click 8 6 CLICK_2X_UP Triple Click 9 6 CLICK_3X_UP Table 13: Up input, output in any state way zone or area button There is no local processing of input events in zone or area mode. All events are forwarded upstream regardless of the device output state. Pushbutton Event Click type Key Number Low Level Event Name Single Tip 0 1 TIP_1X_DOWN Double Tip 1 1 TIP_2X_DOWN Triple Tip 2 1 TIP_3X_DOWN Quadruple Tip 3 1 TIP_4X_DOWN Single Click 7 1 CLICK_1X_DOWN Double Click 8 1 CLICK_2X_DOWN Triple Click 9 1 CLICK_3X_DOWN Hold Start 4 1 HOLD_START_DOWN Hold Repeat 5 1 HOLD_REPEAT_DOWN Hold End 6 1 HOLD_END_DOWN Table 14: Down input, 2-way zone pushbutton Pushbutton Event Click type Key Number Low Level Event Name Single Tip 0 2 TIP_1X_UP Double Tip 1 2 TIP_2X_UP Triple Tip 2 2 TIP_3X_UP Quadruple Tip 3 2 TIP_4X_UP Single Click 7 2 CLICK_1X_UP Double Click 8 2 CLICK_2X_UP Triple Click 9 2 CLICK_3X_UP Hold Start 4 2 HOLD_START_UP Hold Repeat 5 2 HOLD_REPEAT_UP Hold End 6 2 HOLD_END_UP Table 15: Up input, 2-way zone pushbutton 33

34 8.3 System Interfaces Settings digitalstrom Devices may have one pushbutton which can operate in different modes as described above. Beside the one system pushbutton there may be additional buttons with local functionality only. Notice digitalstrom supports only one pushbutton per digitalstrom Device with system functionality. Although used by the upper layer state machines the pushbutton operating mode parameters are stored locally on the device. That way the system can retrieve the mode parameters from the device and synchronize the settings Event Limits digitalstrom Devices have to take care about pushbutton or input malfunctions and may not generate any number of events, see Configuration The pushbutton parameters that are relevant for the system behavior and the state machine operations are stored on the digitalstrom Device itself. This ensures that a device operates in the same mode regardless of the circuit and zone where it is plugged in. Operating Mode This 4-Bit value ButtonId is stored in the device register LTNUMGRP0 (see C.3.2). Target Group This 4-Bit value ButtonGroup is stored in the device register LTNUMGRP0 (see C.3.2). Button Input Mode This 8-Bit value ButtonInputMode is stored in the device register LTMODE (see C.3.6). 34

35 9 Binary Inputs The term binary input refers to an input line of a digitalstrom Device which is connected to an corresponding binary status output signal of an electrical device. This input type is used for automation purposes and provides an interface to different kinds of status outputs. For example smoke detectors, wind monitors or motion detectors provide a binary status signal. 9.1 Low-Level-Events Each transition on the input line is signaled with an appropriate upstream event. Additionally, the state of a binary input line must be available at any time for synchronization, e.g. on system startup. The binary input events are encoded using a binary data type, the data may be either 0 (inactive) or 1 (active). The status of an input line is always available as a status value on the digitalstrom Server. The status change of an input line can be used as trigger for user defined activities. digitalstrom Devices have to take care about event rate limits input and may not generate an arbitrary number of events, see Input Types Each binary input line of digitalstrom Terminal Block has an associated type. This type is determined by the device registration process and later on evaluated for each binary input event received from this digitalstrom Device. 35

36 Input Type Assigned Natural Device and Description Index Presence 1 Presence detector Brightness 2 Presence in darkness 3 Presence detector with activated internal twilight sensor Twilight 4 Twilight sensor Motion 5 Motion detector Motion in darkness 6 Motion detector with activated internal twilight sensor Smoke 7 Smoke Detector Wind strength above limit 8 Wind monitor with user-adjusted wind strength threshold Rain 9 Rain monitor Sun radiation 10 Sun light above threshold Temperature below limit 11 Room thermostat with used-adjusted temperature threshold Battery status is low 12 electric battery is running out of power Window is open 13 Window contact Door is open 14 Door contact Window is tilted 15 Window handle; window is tilted instead of fully opened Garage door is open 16 Garage door contact Sun protection 17 Protect against too much sun light Frost 18 Frost detector Table 16: Binary input types Addionally each input line has an assigned target group which specifies which target function will be triggered by input signals. Currently only the Joker function is supported. Target Function Assigned Index Joker 8 Table 17: Binary input target functions 9.3 System Behavior The digitalstrom system automatically generates a system level events upon reception of binary events from Terminal Blocks. Depending on the current corresponding state, the input type and the target group an appropriate event is generated. Further system actions can be implemented by system add-ons. 36

37 State Change Smoke detector active Wind monitor active Wind monitor inactive Rain monitor active Rain monitor inactive Presence active Presence inactive Motion active Motion inactive Room thermostat active Room thermostat inactive System Activity Call fire alarm in apartment Call wind alarm in apartment or cluster Call no-wind activity Call rain alarm in apartment or cluster Call no-rain activity Set presence state in corresponding zone Clear presence state in corresponding zone Set motion state in corresponding zone Clear motion state in corresponding zone Call On activity in heating group of the corresponding zone Call Off activity in heating group of the corresponding zone Table 18: Binary input activities A state is cleared if all previously active inputs switched to inactive again. Logically the input signals are OR ed. For example the motion state in a zone is set to active when any motion detector in the same zone triggers, but the state will be cleared only if all motion detectors in the same zone are inactive. 9.4 Input Processing The input signal of a binary input line may be preprocessed by the digital- STROM Device. digitalstrom Terminal Blocks use an 8-Bit value BinaryInputMode that is stored in the device register LTMODE (see??). 37

38 10 Glossary 10.1 digitalstrom Device A digitalstrom Device is an device with well defined system behavior and with digitalstrom communication capabilities. The digitalstrom Device is from the users point of view the complete piece of equipment, including all visible output, sensor and input functions. This definition includes that a digitalstrom Device may be build out of multiple Terminal Blocks digitalstrom Ready Device A digitalstrom Ready Device is a device which complies to all rules of the digitalstrom concept dsuid - ds Unique Identifier The dsuid is a 136 bit unique id uses a format that is based on Universal Unique Identifiers (RFC 4122). The dsuid was introduced for such cases where a GTIN and/or serial number is unknown or not available for a component or product, or where multiple components are build upon the same basis Id. The dsuid has to be generated according to the following prioritized rules. The preferred methods allow to regenerate the dsuid and thus always recreate the same key. For the last-choice Random-dSUID it is an important requirement that the dsuid does not change over the lifetime. Modules that generate such a random dsuid have to store it persistently. 1. SGTIN-96 is available for a device Use this SGTIN A GTIN and serial number of device Combine GTIN and serial number to form a SGTIN-128 with Application Identifier 21: (01)<GTIN>(21)<serial number> and use the resulting string to generate a UUIDv5 in the GS1-128 name space 3. An existing UUID of a device is available Use the existing UUID 4. Another unique ID of the device is available within the kind of the device Generate name based UUIDv5 with unique ID in the relevant name space; pre-defined name spaces are existing, e.g. for EnOcean, IEEE MAC 5. Nothing from the above Only a locally unique ID can be generated, generate a random UUIDv4 38

39 10.4 dsid - SGTIN-96 The dsid is a 96 bit unique identifier and follows the SGTIN-96 (Serialized Global Trade Item Number) format defined by the GS1 standard organization. The SGTIN-96 number consist of 4 parts: 8 Bit Header: fixed value, 0x30 3 Bit Filter Value: 3 Bit Partition Value: indicates length of company prefix Bit Company Prefix 4-24 Bit Item Reference 38 Bit Serial Number 10.5 SGTIN-128 The SGTIN-128 (Serialized Global Trade Item Number) format is defined by the GS1 standard organization. The SGTIN-128 is a two part data object that consists of two application identifier and the related data, represented by e.g. the text string (01)<GTIN>(21)<serial number> GID-96 GID-96 is the legacy format of the dsid. The structure of the GID-96 Global Identifier standard was defined by EPCGlobal Inc. To keep compatibility with existing systems the legacy format of a dsid is furthermore supported. The SGTIN and GID-96 have a unique header prefixes and therefore can be used in parallel without overlap. The legacy dsid number is automatically generated for digitalstrom Devices with firmware revision prior to The GID-96 number consist of 4 parts: 8 Bit Header: fixed value, 0x35 28 Bit Manager Number: EPCGlobal uniquely assigned number, 0x04175FE 24 Bit Object Class: digitalstrom defined system objects 36 Bit Serial Number: digitalstrom product serial number The following Object Class values are defined by digitalstrom: Value Object Class 0 digitalstrom Device 1 digitalstrom Meter 2.. 0xFEFFFF Reserved 0xFF xFFFFFF Devices with Ethernet MAC Address Table 19: dsid Object Class Devices with Ethernet interface can be mapped into the aizo dsid address space. For example the digitalstrom Server is uniquely identified 39

40 by a generated dsid using its Ethernet MAC Address. For example the MAC Address 12:34:56:78:90:AB is translated to the dsid FEFF AB Function-ID The Function-ID is a 16 bit device configuration value that describes basic capabilities of digitalstrom devices. This value contains the standard group of a device, basic information about the functionality and the encoding of upstream data messages. The standard group of a digitalstrom Device corresponds to its default color group Vendor-ID The Vendor-ID is 16 bit device configuration value that describes the vendor company of the digitalstrom device. The following Vendor-ID s are defined: Value Vendor-ID 1 digitalstrom GmbH, Germany 2 digitalstrom AG, Switzerland 3 ONE Smart Control, Belgium Table 20: Vendor ID 10.9 Product-ID The Product-ID is a 16 bit device configuration value describing the product family and hardware platform. The Vendor-ID, Product-ID and standard color group together are inputs for looking up the GTIN and Product Code. The Product-Code is used by the digitalstrom Server and Server User Interface (Configurator) to decode product capabilities GTIN Global Trade Item Number (GTIN) is a format to uniquely identify trade items following the standards defined by the GS1 organization. As digitalstrom Devices do not have their full GTIN stored on the device, this number is generated by the digitalstrom Server using lookup tables like??. The digitalstrom Meter has its GTIN stored in the configuration area of the device, and a digitalstrom Server has a GTIN as well. 40

41 Product Code GTIN Standard Color Product-ID Vendor-ID GE-KM x00C8 1 GE-TKM x04D2 1 GE-SDM x08C8 1 GE-SDS200-CW x18C8 2 GE-SDS200-CS x18C9 2 GE-SDS220-CT x18DC 2 GE-TKM x04DC 1 GE-TKM x04E6 1 GE-KL x0CC8 1 GN-KM x00C8 1 GN-TKM x04C8 1 GN-TKM x04D2 1 GR-TKM x04C8 1 GR-TKM x04D2 1 GR-KL x0CC8 1 GR-KL x0CD2 1 GR-KL x0CDC 1 RT-TKM x04C8 1 RT-SDM x08C8 1 SW-TKM x04C8 1 SW-TKM x04D2 1 SW-AKM x20C8 2 SW-AKM x20D2 2 SW-AKM x20DC 2 SW-KL x0CC8 1 SW-ZWS200-J x14C8 1 SW-ZWS200-F x14C9 1 SW-ZWS200-E+F x14CA 2 SW-SDS200-CW x18C8 2 SW-SDS200-CS x18C9 2 SW-SDS220-CT x18DC 2 Table 21: aizo Product Codes and GTIN s 11 Certification Rules Rule 1 A digitalstrom Ready Device has to be preconfigured in the right application group. This is essential to ensure that all electrical devices in one application group can be orchestrated together. Rule 2 A digitalstrom Ready Device must be configured for exactly one digitalstrom application group. The assigned application group must be non-ambiguous and is part of the static device configuration. 41

42 Rule 3 The function of a devices output is the basis of its group membership. For devices without output function the target function of the switch button decides about the group membership. Rule 4 digitalstrom Devices have to implement a default behavior for all 128 scene commands. The system behavior and default values are defined in the particular documents for each functional group. Rule 5 When applications send a scene command to a set of digitalstrom Devices with more than one target device they have to use scene calls directed to a group, splitting into multiple calls to single devices has to be avoided due to latency and statemachine consistency issues. Rule 6 digitalstrom Ready Devices must ignore stepping commands if their output value is zero. Rule 7 digitalstrom Device have to complete the identification action on the command Programming Mode Start within 4 seconds. Rule 8 Application processes that do automatic cyclic reads or writes of device parameters are subject to a request limit: at maximum one request per minute and circuit is allowed. Rule 9 Application processes that do automatic cyclic reads of measured values are subject to a request limit: at maximum one request per minute and circuit is allowed. Rule 10 The action command Set Output Value must not be used for other than device configuration purposes. Rule 11 digitalstrom Ready Devices must not send upstream events continously and must stop sending Low-Level-Event data even if the event is still or repeatedly valid. Transmission of pushbutton events must be abondoned after a maximum time of 2.5 minutes. Automatically genereated events must not exceed a rate limit of 10 events per 5 minutes. Rule 12 Applications shall use the digitalstrom Server webservice interface for communication with the digitalstrom system. Directly interfacing the dsm-api shall be avoided because it is an internal interface and its API may change in the future. Rule 13 Applications that automatically generate Call Scene action commands (see 5.1.1) must not execute the action commands at a rate faster than one request per second. 42

43 A Structure Reference A.1 Circuit The maximum supported cable length on one circuit is limited to 50 meters. The maximum number of digitalstrom components connected on the RS485 line is 63. A.2 Zone The maximum number of zones per circuit is limited to 15. A.3 Group The maximum number of groups per zone is limited to 63. The first 16 groups have a special meaning and cover all functional classes. The remaining 47 groups are reserved for user defined configurations. A.4 Device The maximum number of devices per circuit is limited to

44 B Scene Command Reference Scene command indices not mentioned here are reserved and must not be used. B.1 Presets Activity Scene Command Description Preset 0 0 Set output value to Preset 0 (Default: Off) Preset 1 5 Set output value to Preset 1 (Default: On) Preset 2 17 Set output value to Preset 2 Preset 3 18 Set output value to Preset 3 Preset 4 19 Set output value to Preset 4 Table 22: Preset 0 4 Activity Scene Command Description Preset Set output value to Preset 10 (Default: Off) Preset Set output value to Preset 11 (Default: On) Preset Set output value to Preset 12 Preset Set output value to Preset 13 Preset Set output value to Preset 14 Table 23: Preset Activity Scene Command Description Preset Set output value to Preset 20 (Default: Off) Preset Set output value to Preset 21 (Default: On) Preset Set output value to Preset 22 Preset Set output value to Preset 23 Preset Set output value to Preset 24 Table 24: Preset Activity Scene Command Description Preset Set output value to Preset 30 (Default: Off) Preset Set output value to Preset 31 (Default: On) Preset Set output value to Preset 32 Preset Set output value to Preset 33 Preset Set output value to Preset 34 Table 25: Preset

45 Activity Scene Command Description Preset Set output value to Preset 40 (Default: Off) Preset Set output value to Preset 41 (Default: On) Preset Set output value to Preset 42 Preset Set output value to Preset 43 Preset Set output value to Preset 44 B.2 Stepping Table 26: Preset Activity Scene Command Description Increment 11 Increment output value Decrement 12 Decrement output value B.3 Area scenes Table 27: Stepping scenes Activity Scene Command Description Area 1 Off 1 Set output value to Preset Area 1 Off (Default: Off) Area 1 On 6 Set output value to Preset Area 1 On (Default: On) Area 1 Increment 43 Initial command to increment output value Area 1 Decrement 42 Initial command to decrement output value Area 1 Stop 52 Stop output value change at current position Area Stepping Continue 10 Next step to increment or decrement Table 28: Area 1 Activity Scene Command Description Area 2 Off 2 Set output value to Area 2 Off (Default: Off) Area 2 On 7 Set output value to Area 2 On (Default: On) Area 2 Increment 45 Initial command to increment output value Area 2 Decrement 44 Initial command to decrement output value Area 2 Stop 53 Stop output value change at current position Area Stepping Continue 10 Next step to increment or decrement Table 29: Area 2 45

46 Activity Scene Command Description Area 3 Off 3 Set output value to Area 3 Off (Default: Off) Area 3 On 8 Set output value to Area 3 On (Default: On) Area 3 Increment 47 Initial command to increment output value Area 3 Decrement 46 Initial command to decrement output value Area 3 Stop 54 Stop output value change at current position Area Stepping Continue 10 Next step to increment or decrement Table 30: Area 3 Activity Scene Command Description Area 4 Off 4 Set output value to Area 4 Off (Default: Off) Area 4 On 9 Set output value to Area 4 On (Default: On) Area 4 Increment 49 Initial command to increment output value Area 4 Decrement 48 Initial command to decrement output value Area 4 Stop 55 Stop output value change at current position Area Stepping Continue 10 Next step to increment or decrement B.4 Local pushbutton Table 31: Area 4 Activity Scene Command Description DeviceOn 51 Local on DeviceOff 50 Local off DeviceStop 15 Stop output value change at current position B.5 Special scenes Table 32: Device scenes Activity Scene Command Description Minimum 13 Minimum output value Maximum 14 Maximum output value Stop 15 Stop output value change at current position Auto-Off 40 Slowly fade down to off value Table 33: Special scenes 46

47 B.6 Temperature control scenes Activity Scene Command Description Off 0 Comfort 1 Economy 2 Not Used 3 Night 4 Holiday 5 B.7 Group independent scenes Table 34: Temperature control scenes Activity Scene Command Deep Off 68 Standby 67 Zone Active 75 Auto Standby 64 Absent 72 Present 71 Sleeping 69 Wakeup 70 Door Bell 73 Panic 65 Fire 76 Alarm-1 74 Alarm-2 83 Alarm-3 84 Alarm-4 85 Wind 86 No-Wind 87 Rain 88 No-Rain 89 Hail 90 No-Hail 91 Table 35: Group independent activities and scene command values 47

48 C Device Parameters digitalstrom Devices have configuration parameters of different categories. The system relevant parameters described below are mandatory for digitalstrom Ready Devices. C.1 Class 0 - Communication Specific Parameters C.1.1 Local Programming Mode Offset 0x08, Length 8 Bit - PROGEN: Enable Local Programming Mode This parameter controls the local programming mode functions of a digitalstrom Device. Value Description 0 local programming mode disabled 1 only short-long allowed 2 only short-short-long allowed 3 both short-long and short-short-long allowed C.2 Class 1 - digitalstrom Device Specific Parameters Parameters in this class are read-only and are not allowed to be modified by user operations. C.2.1 Firmware Version Offset 0x00, Length 16 bit - VER: Firmware Version This is the firmware version of the digitalstrom Device. 0x0321 reads as C.2.2 Serial Numer Offset 0x02, Length 32 bit - DSID: digitalstrom-id This parameter contains the serial number, the lower 32 bits of the unique 96-bit dsid??. C.2.3 Function ID Offset 0x06, Length 16 bit - FID: Function-ID The Function ID defines the basic capabilities of the digitalstrom Device. C.2.4 Vendor ID Offset 0x08, Length 16 bit - VID: Vendor-ID Here the Vendor ID is defined. 48

49 C.2.5 Product ID Offset 0x0a, Length 16 bit - PID: Product-ID Here the Product ID is defined. C.2.6 Structure and adressing Offset 0x0c, Length 16 bit - ADDR: Short Address The dynamic device short address assigned by the digitalstrom Meter during device registration process F. Offset 0x0e, Length 16 bit - VC: Virtual Circuit The bit field indicating the zone membership of a device. Offset 0x10, Length 64 bit - GRP: Group Mask The bit field indicating the group membership of a device. C.2.7 OEM/GTIN Offset 0x1c, Length 16 bit - OEM_SERIAL: OEM Serial Number Device manufacturers may store a serial number of their bundled Native Device in the OEM_SERIAL register. Offset 0x1e, Length 8 bit - OEM_PARTNO: OEM Part Number Device manufacturers may store a part number if a complex digitalstrom Device is built of more than one Terminal Block. C.2.8 Sensor Equipment Offset 0x20, Length variable - ST: Sensor Table A table containing an entry for each available sensor in the device. 49

50 Register C.1: Sensor Table Entry Type Reserved Conversion Context Polling Polling Default polling interval Value Description 0 disabled 1 60 seconds 2 5 minutes 3 30 minutes 4 1 hour 5 6 hours 6 12 hours 7 24 hours Context Zone or global context Conversion 12 to 10 bit conversion, either high or low bits important Type Sensor Type (see E) C.2.9 Binary Input Equipment Offset 0x40, Length variable - BIT: Binary Input Table A table containing an entry for each available binary input in the device. 50

51 Register C.2: Binary Input Table Entry Input Mode Reserved Last Entry Input Type Target Group Target Group Id of the target functional Input Type Binary input type, see table 16 Last Entry 0 = more entries to follow, 1 = this is the last input entry Input Mode Input mode Id C.3 Class 3 - Function Specific Parameters C.3.1 Output Mode Offset 0x00, 8 bit - MODE: Output Mode This parameter describes, how the output is used, e.g. as dimmer or switch. This parameter is digitalstrom Device and product specific, depending on the hardware equipment only selected values are supported by a device. Output Mode Description 0 No output or output disabled 16 Switched 17 RMS (root mean square) dimmer 18 RMS dimmer with characteristic curve 19 Phase control dimmer 20 Phase control dimmer with characteristic curve 21 Reverse phase control dimmer 22 Reverse phase control dimmer with characteristic curve 23 PWM (pulse width modulation) 24 PWM with characteristic curve 33 Positioning control 39 Relay with switched mode scene table configuration 40 Relay with wiped mode scene table configuration 41 Relay with saving mode scene table configuration 42 Positioning control for uncalibrated shutter Table 36: Output Mode Register 51

52 C.3.2 Pushbutton Configuration Offset 0x01, 8 bit - LTNUMGRP0: Pushbutton Configuration This parameter controls the function of the pushbutton input. The parameter is divided into 2 parts: The lower 4 bit define the function and the upper 4 bit define the target group. For target group Joker special functions are available and the bush button can be operated as the corresponding panic, leave home or door bell Terminal Blocks. Higher 4 bit Target group 0 Reserved 1 Light 2 Blinds 3 Climate 4 Audio 5 Video 6 Reserved 7 Reserved 8 Joker 9-15 Reserved Table 37: Button Input Groups Lower 4 bit Description 0 local pushbutton (local + presets 2-4) 1 area 1 pushbutton (area 1 + presets 2-4) 2 area 2 pushbutton (area 2 + presets 2-4) 3 area 3 pushbutton (area 3 + presets 2-4) 4 area 4 pushbutton (area 4 + presets 2-4) 5 room pushbutton (presets 0-4) 6 extended 1 pushbutton (presets 10-14) 7 extended 2 pushbutton (presets 20-24) 8 extended 3 pushbutton (presets 30-34) 9 extended 4 pushbutton (presets 40-44) 10 extended area 1 pushbutton (area 1 + presets 12-14) 11 extended area 2 pushbutton (area 2 + presets 22-24) 12 extended area 3 pushbutton (area 3 + presets 32-34) 13 extended area 4 pushbutton (area 4 + presets 42-44) 14 apartment pushbutton 15 app pushbutton Table 38: Button Input Id s - Group

53 Lower 4 bit Description 0 reserved 1 alarm 2 panic 3 leave/come Home 4 reserved 5 door bell reserved 15 app pushbutton Table 39: Button Input Id s - Group Joker C.3.3 Dimm Time Offset 0x06, 8 bit - DIMTIME0_UP: Dimm Time 0 Up This transition time is used when dimming up. The formula for time calculation is: T = (100ms 2 exp ) (100ms 2exp ) (15 lin) 32 whereas exp = Bit 7..4 and lin = Bit Examples: 0x0F = 100ms, 0x1F=200ms, 0x27 = 300ms, 0x2F = 400ms, 0x37 = 600ms. Offset 0x07, 8 bit - DIMTIME0_DOWN: Dimm Time 0 Down This transition time is used when dimming down. See DIMTIME0_UP for time calculation. Offset 0x08, 8 bit - DIMTIME1_UP: Dimm Time 1 Up This transition time is used when dimming down. See DIMTIME0_UP for time calculation. Offset 0x09, 8 bit - DIMTIME1_DOWN: Dimm Time 1 Down This transition time is used when dimming down. See DIMTIME0_UP for time calculation. Offset 0x0a, 8 bit - DIMTIME2_UP: Dimm Time 2 Up This transition time is used when dimming down. See DIMTIME0_UP for time calculation. Offset 0x0b, 8 bit - DIMTIME2_DOWN: Dimm Time 2 Down This transition time is used when dimming down. See DIMTIME0_UP for time calculation. C.3.4 Flashing Mode Offset 0x0e, 8 bit - FOFFVAL0: Off Value for Programming Mode Flashing The digitalstrom Device flashes when entering or exiting the program- 53

54 ming mode. The flashing starts at the current output value, then there are FCOUNT0 flash cycles. Each cycle transitions to FONVAL0, then to FOFF- VAL0. After the last cycle, the initial output value is restored. Offset 0x0f, 8 bit - FONVAL0: On Value for Programming Mode Flashing This is the on value for the flashing cycles. See FOFFVAL0. Offset 0x10, 8 bit - FOFFTIME0: Off Time for Programming Mode Flashing The off value while flashing is held for this time. See OFFVAL0. Each step means 33ms. Example: 20 = 660ms. Offset 0x11, 8 bit - FONTIME0: On Time for Programming Mode Flashing The on value while flashing is held for this time. See OFFVAL0. Each step means 33ms. Example: 20 = 660ms. Offset 0x12, 8 bit - FCOUNT0: Flash Cycle Count for Programming Mode Flashing See OFFVAL0. 0 disables flashing, 255 flashes infinitely. Offset 0x13, 8 bit - FOFFVAL1: Off Value for Scene Flag Flashing The digitalstrom Device flashes when a scene is called and the corresponding bit is set in scene configuration. The flashing starts at the current output value, then there are FCOUNT1 flash cycles. Each cycle transitions to FONVAL1, then to FOFFVAL1. After the last cycle, the initial output value is restored (if DC bit is set in scene configuration) or a transition to the called scene value takes place. Offset 0x14, 8 bit - FONVAL1: On Value for Scene Flag Flashing This is the on value for the flashing cycles. See FOFFVAL1. Offset 0x15, 8 bit - FOFFTIME1: Off Time for Scene Flag Flashing The off value while flashing is held for this time. See OFFVAL1. Each step means 33ms. Example: 20 = 660ms. Offset 0x16, 8 bit - FONTIME1: On Time for Scene Flag Flashing The on value while flashing is held for this time. See OFFVAL1. Each step means 33ms. Example: 20 = 660ms. Offset 0x17, 8 bit - FCOUNT1: Flash Cycle Count for Scene Flag Flashing See OFFVAL1. 0 disables flashing, 255 flashes infinitly. 54

55 C.3.5 LED Configuration Offset 0x18, 8 bit - LEDCON0: LED Configuration 0 Register C.3: LED Configuration GRPC Reserved DDM DFM DCS GRPC: LED Color Mode Normally the LED shows automatically the color for the user selected group (e.g. using short-short-long). But it is also possible to overwrite this color for some scenes using the scene configuration flags and this register with GRPC=0. GRPC Description 0 use DCS register for specific color 1 automatic color for user programmed group Reserved Should always be 0. DDM: LED Brightness Select how the LED brightness is controlled. This flag is only used if GRPC is set to 1. DDM Description 0 full brightness 1 brightness depends on output value (higher value = brighter) DFM: LED Flash Mode Select when the LED flashes. DFM Description 0 0 always on, flash during transition 0 1 always on, flash when output on 1 0 always on 1 1 always flashing DCS: Direct Color Selection Directly select a specific color. DCS Description use LEDRGB0..1 registers blue green cyan red magenta yellow white Offset 0x19, 8 bit - LEDCON1: LED Configuration 1 See LEDCON0. 55

56 Offset 0x1a, 8 bit - LEDCON1: LED Configuration 2 See LEDCON0. Offset 0x1b, 8 bit - LEDRGB0: LED RGB Register 0 Offset 0x1c, 8 bit - LEDRGB1: LED RGB Register 1 Register C.4: LED RGB Register R B G LEDRGB1 7 0 LEDRGB0 R: LED Brightness Red 5 bit LED brightness for color red B: LED Brightness Blue 5 bit LED brightness for color blue G: LED Brightness Green 6 bit LED brightness for color green C.3.6 Local Pushbutton Offset 0x1d, 8 bit - LTCON: Local Pushbutton Configuration Register C.5: LTCON Local Mode Reserved EXT-Input is local push button T-Input Local Mode Push button events only local EXT-Input EXT-Input is local push button T-Input T-Input is local push button Offset 0x1e, 8 bit - LTMODE: Local Pushbutton Mode 56

57 Value Description 0 Standard button 1 Turbo button: limited operation, hold, click and programming click disabled Reserved 5 2-way up, paired with input way up, paired with input way up, paired with input way up, paired with input way down, paired with input way down, paired with input way down, paired with input way down, paired with input way up/down Reserved 16 Standard binary input 17 Inverted binary input 18 Binary input, rising edge 1 19 Binary input, falling edge 1 20 Binary input, rising edge 0 21 Binary input, falling edge 0 22 Binary input, toggle mode on rising edge 23 Binary input, toggle mode on falling edge C.3.7 Configuration Flags Offset 0x1f, 8 bit - DEVICECFG: Device Configuration Flags Register C.6: DEVICECFG Reserved Protect Configuration Protect Configuration Device configuration is locked C.3.8 OEM/GTIN Offset 0x2a, 48 bit - GTIN: Global Trade Item Number Device manufacturers store the GTIN of their bundled Native Device in the GTIN register. This register is used by the digitalstrom Server to get extended device information like descriptive text, icons, website and service URL s (see 2.4). 57

58 C.4 Class 6 - Sensor Event Table digitalstrom Devices may implement the sensor event table, see This table can hold up to 16 entries. Each entry consists of 6 bytes. The first entry starts at offset 0x00, the second at offset 0x06, the third at offset 0x0C and so on. Each entry consists of: Sensor-ID to compare relational operator threshold value to compare with hysteresis action If an entry matches the conditions, the action is executed. The action normally is: sending the event to user level. But the digitalstrom Device could also request the digitalstrom Meter to poll the value of the affected sensor. It is also possible to let the digitalstrom Device send a pushbutton event instead. To disable a table entry, write all bytes to 0xff. Register C.7: Sensor Event Table Offset 0 Sensor-ID RelOp Action Sensor-ID If the digitalstrom Device gets a new value from an internal sensor with this Sensor-ID, it will be compared. RelOp: Relational operator 0:=, 1:<, 2:>, 3=reserved Action 0:send push-event with entry-number, 1:request polling of Sensor-ID value, 2:send pushbutton event, 3:reserved 58

59 Register C.8: Sensor Event Table Offset 1..3 Threshold Hysteresis 11 0 Threshold (offset 1, bit & offset 2, bit 3..0) The value to compare with Hysteresis (offset 2, bit & offset 3, bit 7..0) The works like this: hysteresis For the relational operator =: If the sensor value equals the threshold value to compare with, the action will be executed Additional events for this table entry will only be executed, if the sensor value drops below threshold hysteresis or rises above threshold + hysteresis For the relational operator <: If the sensor value is lower than the threshold value to compare with, the action will be executed Additional events for this table entry will only be executed, if the sensor value rises above threshold + hysteresis For the relational operator >: If the sensor value is higher than the threshold value to compare with, the action will be executed Additional events for this table entry will only be executed, if the sensor drops below threshold hysteresis 59

60 Register C.9: Sensor Event Table Offset 4 reserved condition reserved reserved, write 0 condition 0:execute action always, 1:execute action only if outputvalue = 0, 2:execute action only if outputvalue > 0, 3=execute action never Register C.10: Sensor Event Table Offset 5 Key Number Click Type Key Number only used if Action = 2. See 9.1. Click Type only used if Action = 2. See 9.1. C.5 Class 64 - Output status C.5.1 Current output status The actual device output value of the first output channel can be read back for configuration purposes from offset 0. 60

61 D Device Scene Table The scene table contains values and settings for 128 presets. Each entry consists of a value for each output channel and configuration bits. D.1 Scene Value After a scene call a transition takes place from the current value to the new scene value. The output transition depends on the scene configuration bits and the internal local priority state. The bitlength of the scene value is not set to a fixed value. D.2 Configuration Bits There are 8 configuration bits for each scene. 61

62 Register D.1: Scene Configuration DT LC FLASH reserved LPRIO DC DT: Dim Time Control the transition time between the current value and the new scene value. DT Description 0 0 use last dimtime 0 1 use dimtime from register DIMTIME0 1 0 use dimtime from register DIMTIME1 1 1 use dimtime from register DIMTIME2 LC: LED Configuration Control the behavior of the LED. LC Description 0 0 use last LED configuration 0 1 use LED configuration from register LEDCON0 1 0 use LED configuration from register LEDCON1 1 1 use LED configuration from register LEDCON2 FLASH: Flash Configuration If this bit is set, the output flashes (as configured with FOFFVAL1,FONVAL1, FOFFTIME1, FONTIME1 and FCOUNT1). After flashing the output transistion takes place (if DC is not set and internal local priority state is not set or LPRIO is set). reserved Must not be modified and written back as read. LPRIO: Ignore Local Priority If this bit is set, the output transition takes place even if the internal local priority state is set. The new local priority state depends on the newly called scene. DC: Output Don t Care Flag If this bit is set, the output value will not be changed. The output transition will not take place. 62

63 E Device Sensors digitalstrom Devices optionally include up to 15 sensor objects. The list of possible sensors include internal device specific measurements and externally supplied values. The table of implemented sensor objects per device is defined per digitalstrom Device parameters (see C.2.8). Each of the sensor objects has a well defined type. The following table defines the sensor types used in the system. Unused sensor type numbers are reserved. All sensor types can be sent upstream, sensor types can also be sent downstream to digitalstrom Devices. Sensor Description Unit Min 12 Bit Max 12 Bit Resolution Type 4 Active power Watts (W) Output current Ampere (ma) Electric meter Watthours (kwh) 0 40,95 0,01 9 Temperature indoors Kelvin (K) ,375 0,25 10 Temperature outdoors Kelvin (K) ,375 0,25 11 Brightness indoors Lux (Lx) ,795 logarithmic: lx = x, x = 800 log (lx) 12 Brightness outdoors Lux (Lx) ,795 logarithmic: lx = x, x = 800 log (lx) 13 Relative humidity indoors Percent (%) 0 102,375 0, Relative humidity Percent (%) 0 102,375 0,025 outdoors 15 Air pressure Pascal (hpa) ,75 0,25 18 Wind speed m/s 0 102,375 0,025 0,5 19 Wind direction degrees 0 511, Precipitation mm/m ,375 0, Carbon Dioxide ppm ,795 logarithmic: ppm = x, x = 800 log (ppm) 0,25 25 Sound pressure level db 0 255, Room temperature Kelvin (K) ,375 0,025 set point 51 Room temperature Percent (%) 0 102,375 0,025 control variable 64 Output current (H) Ampere (ma) Power consumption Volt-Ampere (VA) Table 40: Sensor Types 63

64 F Device Registration A device needs to be registered at the digitalstrom Meter who also tracks the device availability state. If a new device is connected to the circuit, the device sends its unique device ID (dsid) to the digitalstrom Meter. The digitalstrom Meter then assigns a circuit-wide, unique short address to the device. If the device was seen in the circuit before, it will get the same short address as before. At registration time some parameters are synchronized with the digitalstrom Meter. The parameters to read depend on the Function-ID which is read first. More parameters are: pushbutton configuration (room/area/...), output mode (switchable or dimmable) and Product-ID. If the digitalstrom Meter is powered on, there is no need to register all devices again. The digitalstrom Meter sends its own unique ID to the devices and only devices which were not registered at this digitalstrom Meter before will then request a registration. The digitalstrom Meter detects if there are more than one devices which needs to be registered at the same time. It will then switch to a slower registration mode which allows to register up to 128 new devices at the same time. The digitalstrom Meter checks the device availability every 24 hours. Each known device is contacted by the digitalstrom Meter and if the device does not respond, the state will be set to inactive. 64