digitalSTROM Server

h1. dSM

The dSM is the main entry for accessing the hardware for the dSS. It is somekind of master for one singular circuit, it hosts the handling of the behavior of one or more room. It is not a classical master, because it received buttonpresses from "Taster"-Slaves, and make a broadcast to all slaves with a command which scene has been called. It is in the responsibility for the slaves, what exacly a specfic scene call means to them. The dSM do not know, what a slave will do on a scene-call.

In real world, there are many constellations of circuit wireing in any building. For that reason, a dSM drives the concept of virtual rooms, called here "Zone". Each dSM can actualy have up to 15 different zones, each with a individual, not-iterative ZoneID. 

All dSMs are connected through a rs485 bus, where a token-bus protocol named "dS485" handles the routing of singular telegrams. That telegrams are commands or requests from and to the dSMs. When a Buttonpress has been issued by a dSID-"Tasterslave", the dSM for that circuit receives it, then determine with the properties of that buttonpress, the properties of a slave and the current state of a zone which new state for that zone has to be. That command will be send throught the powerline to his slave and also throught dS485 to all other dSM, because there might be other dSMs/circuit which has also slaves in the same zone (two dSMs can share a Zone with the same ZoneID). Since that dS485-telegram is sended as a broadcast to all dSMs, a dSS can also "sniff" that telegram and knows about the zone-states without any further requesting the dSMs.

h2. dSM-datamodel Classes (conceptional)

From a conceptional view, a digitalSTROM-System at hardware-level with multiple dSMs and slaves has 4 classes of "things":

* dSM/Circuit

* Device/dSID

* Zone

* Group

Each dSM has a number of Devices, which are pluged into his circuit.

Each dSM can provide a measurement of the current powerconsumption (in Watt), which the circuit is currendly drained, and a energy-counter (in kWh).

Each dSM can have up to 15 different Zones.

Each Device is a Member of one Circuit and a Member of one Zone.

Each Device can be in multipe "User"-Groups, but is always Member of one singular "Standard-group"

Each Device have a scene-memory, where his behavior on a specific Scenecall is saved.

Each Device has (beside some other Information) a function-ID, which defines what behavior is called thought the dSM, when a event has been issued by that device (a light device has function-id 0x1***, so when a button-press-event comes from that device, the dSM know, that a scenecall for light must be issued)

Each Zone has multipe Devices and can be hosted on one or many dSMs.

Each Zone has 9 "Standard"-Groups: "light", "shadow", "climate", "audio", "video", "security", "access", "white-ware", "joker" (in dSS they are encoded by the marketing-given colors: "yellow", "gray", "blue", "cyan", "violet", "red", "green", "white" and "black") 

Each Zone has up to 54 "User"-Groups.

Each Zone has a individual 16-Bit ZoneID.

ZoneID "0" is reserved as broadcast-address, so it represents all zones in a installation

Each Group, regardless of a "Standard" or "User"-group has multipe devices, and is member of one Zone.

Each Group has a property "last scene call", which represens the current state of a Group in a Zone.

GroupID "0" is reserved as broadcast-address, so it represents all devices in a zone.

h2. dSM-API

One Command for a dSM is a dS485 Telegram with (beside typical Headerinformation) one 8-Bit MessageID for identifying the command and up to 7 16-Bit Parameter.

From all possible commandtypes, in the api only "request", "response" and "event" is important, all other commandtypes for dS485 are mainly for bus-handling purposes.

The commands can be separeted in some differend kinds:

* data-model (read out the dSM,Devices,Zones,Groups and administate it)

* action requests (scene-calls, direct setting output value, dSLink-commands)

* events (new devices found, devices lost, getting HW-event which the dSM can't handle because no behavior model has been provided of a specific functionID of the sending device)

* sensoric / measurement (powerconsumption dSM, powerconsumption device, sensoric data)

(details comming soon)

h2. typical Usecases for dSM-API

h3. fire a action request

A typical actionrequest can be a scene-call or a direct setting of the outputvalue. The best way is to issue a scenecall to a group of a zone, that request should be send as a broadcast to all dSMs. All dSM receives the command at the same time and will send the command throught powerline when he is member of that zone. The group-call is set on powerline as a singular command and not as a series of commands for each devices which are members of that group, so a scenecall to Zone/Group is the best and well optimized way of issuing a command. The system is optimized for calls to virtual addressing though zones and groups.

You can also call individual devices which is not so optimized, so it can take up to 4 times longer. 

You can also set a defined output value, which naturally overrides the scene-logic of a device and is also not in the focus of optimization, so it would also take more responce-time than the scene-calls.

Be aware, that addressing of multiple devices or broadcasting is possible and can be very efficient. Zone xy and Group 0 is the fastet way to make a call to all Devices in a Zone; Zone 0 and Group 1 is the fastet way to turn on lighting in the whole installation; Zone 0 and Group 0 targets all Devices in a installation.

h3. query actual powerconsumption

The powerconsumption of a dSM is stored internally with a one-second precision, so you can get the powerconsumption of the last second. Querying that value from one dSM cost one comlete token-roundtrip, so if you want to get only one value, querying one dSM is ok. If you want the powerconsumption of all dSM, it would be wise to issue a singular broadcast request. all dSM will answer as soon as they get the token, so the receiver can gather all information while waiting for getting the token. if you call the dSM individual, each singular request must wait for a complete token-roundtrip.