doc.cpp

using namespace dss;

/**
\mainpage digitalStrom Server

\image html digitalSTROM_small.png

\section overview Overview

The dSS consists of several subsystems as shown in the following image:

\image html block.png "System overview"
\image latex block.eps "System overview" height=10cm

Every subsystem can be enabled or disabled by the commandline or in the configuration.
The center piece of the dSS is its DataModel. It provides the API that allows a developer manipulate as well as rearrange devices, zones and groups.
Built on that foundation there is a SOAP interface to make the API accessible to the outside world. In addition to the SOAP interface there is a JSON interface that interacts with JavaScript running in a webbrowser.

The DS485Proxy is responsible of controlling the physical and simulated devices. It converts abstract commands from the DataModel an converts them to one or several DS485 frames. These frames will then be sent either to a simulated dSM or put on the wire depending on the frame's destination.

The simulated dSM may be extended by plugins. An example is a simulated dSID that controlls a VLC (mediaplayer) instance remotely using its telnet interface.

\section config Configuration

There are several configuration files which define the behaviour of the dSS and its simulation. Most of the things can be manipulated at runtime through the property system.

\section properties Property system

The property system is a tree based configuration and information tool. It is populated by the subsystems at startup. The whole system is accessible at http://yourdss:8080/browse/. Properties can be specified on the command-line like that:
\verbatim
dss --prop:/path/to/property=value
\endverbatim

\subsection config_general General

The main config file is located at data/config.xml. It will get loaded on
startup and patched into the property system.

\verbatim
<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
<properties version="1">
  <property name="config">
    <property name="subsystems/DS485Proxy/rs485devicename" type="string">
      <value>/dev/ttyUSB0</value>
    </property>
    <property name="subsystems/Webserver/webroot" type="string">
      <value>/mnt/sdcard/webroot</value>
    </property>
    <property name="subsystems/Metering/enabled" type="boolean">
      <value>false</value>
    </property>
  </property>
</properties>
\endverbatim

Each subsystem has an entry in the config subtree with at least two entries \c loglevel and \c enabled. If a subsystem is not enabled it won't get started. The loglevel (0 - 5) defines the verbosity with 0 being the most verbose.

\subsection config_apartment Apartment

The Apartment config resides in data/apartment.xml. It contains everything that won't be stored in the dSMs such as device names that are longer than 20 characters.

\verbatim
<?xml version='1.0' encoding='utf-8'?>
<config version="1">
  <apartment>
    <name>Sim Residence</name>
  </apartment>
  <devices>
    <device dsid="3504175fe0000000ffc00011">
      <name>Bulb 1</name>
      <location>
        <x>1.1</x>
        <y>2.5</y>
        <z>0</z>
      </location>
    </device>
    <device dsid="3504175fe0000000ffc00006">
      <name>Bell</name>
      <location>
        [...]
      </location>
    </device>
  </devices>
  <zones>
    <zone id="1">
      <name>Zone 1</name>
    </zone>
    [...]
  </zones>
</config>
\endverbatim

All items are bound to a dsid so if a user moves a bulb from one zone to another it will still be named "Bulb 1". Note that this file will be generated by the dSS each time a name or location changes.

\subsection config_sim Simulation

The simulation has it's own configuration:

\verbatim
<?xml version="1.0"?>
<sim>
  <dsMeter busid="70" dsid="10">
    <zone id="1"> <!-- id can be omitted, in fact zone may be omitted if there's only one zone -->
      <device dsid="1" busid="1" type="standard.switch" />
      <device dsid="2" busid="2" type="example.vlc_remote" />
      <device dsid="4" busid="4" type="standard.simple"/>
      <group id="1">
        <device busid="4" />
      </group>
      <group id="4">
        <device busid="2" />
      </group>
    </zone>
    <zone id="2">
      <device dsid="3" busid="3" type="standard.switch"/>
      <device dsid="5" busid="5" type="standard.simple" />
      <group id="1">
        <device busid="5" />
      </group>
    </zone>
  </dsMeter>
  <dsMeter ...>
  </dsMeter>
</sim>
\endverbatim

The \c sim tag encloses multiple dsMeters. In the \c dsMeter tag the dsMeters busid (as in DS485 bus address) as well as its dsid get specified. The dsid as it's written there is actually expanded in the loader to be a "simulation" address and thus prefixed with 3504175fe0000000ffc. This applies for all dsids in this config file.

The device-type defines what object gets instanciated by the simulated dSM. There are two built-in dSIDs "standard.simple" a device that behaves like a light bulb and "standard.switch" which simulates a 9 button switch.
If the type of a device is not specified it defaults to "standard.simple".

It's possible to write custom dSIDs with the use of the plugin API. The standard location of the plugins is at "data/plugins". For each file there a couple of checks (such as comparing the API version) are performed to ensure the stability of the dSS. The plugin is then asked for it's name and registered in the plugin factory, ready to use.

To form groups inside a zone a group tag containing references to the devices must be inserted. At the moment it's not possible to define devices inside a group tag.

\section compiling Compiling

This section should give some hints about compiling the dSS.

\subsection prerequisites Prerequisites

The following libraries and their development headers have to be present on the system:

\li libxml
\li boost
\li poco
\li gsoap
\li libical
\li spidermonkey

\subsection building Building

Building should be as easy as:

\verbatim
cd dss/build
cmake ..
make
\endverbatim

There are several compile time options that can be passed to cmake:

\li \c -DWITH_DATADIR=path specifies the default location of the data directory.
\li \c -DCMAKE_BUILD_TYPE=[Release|Debug]

If you're creating backtraces for error reporting, please use \c -DCMAKE_BUILD_TYPE=Debug.

\section sets Sets

The following section will show the use of the dSS Model API. One of the most important element of the API is the Set.

Every \a dss::deviceContainer can deliver its \a dss::devices as a \a dss::set. A Set can be manipulated by adding and removing devices as well as being combined with other sets. Since a Set implements \a dss::iDeviceInterface it can receive commands like TurnOn() as it would be a single Device.

\subsection working_with_sets Working with sets

\code
Apartment apt;

Device& dev1 = apt.allocateDevice(1);
Device& dev2 = apt.allocateDevice(2);
Device& dev3 = apt.allocateDevice(3);
Device& dev4 = apt.allocateDevice(4);

// Get a set containing all devices
Set allDevices = apt.getDevices();

// Create a set containing only dev1
Set setdev1 = Set(dev1);

// Create a set of all devices excluding dev1
Set allMinusDev1 = allDevices.remove(setdev1);

// Create a set of all device by combining the sets created above
Set allRecombined = allMinusDev1.combine(setdev1);

// Turn on all devices
allRecombined.turnOn();

// Turn on all lights
Set allLights = allDevices.getByGroup("yellow");
allLights.turnOn();

\endcode

\section websites Default websites

All websites present on the dSS reside in \c data/webroot. They may be viewed by pointing a browser to http://localhost:8080/. To create zones or regroup devices there is a very basic interface at \c http://localhost:8080/structure.html. The server-port is announced over mDNS (Bonjour) using the service name \c _dssweb._tcp.

\section plugins Simulation plugins

Each plugin has to meet a certain API. This API is located at "core/sim/include/dsid_plugin.h". Each function has to be present in order to function correctly.

The first function to be called is:

\code
  int dsid_getversion();
\endcode

It has to return DSID_PLUGIN_API_VERSION as defined in dsid_plugin.h. This number will change with each major API change.
One of the next calls is to:
\code
  const char* dsid_get_plugin_name();
\endcode

This call should return a pointer to the plugins name. It has to be unique on the system. The prefered naming scheme is company.product if a plugin simulates the behaviour of a specific device.

If the plugin name comes up in sim.xml an instance of the plugin is created by calling:
\code
  int dsid_create_instance();
\endcode

The result of dsid_create_instance is a handle that identifies the newly created instance. This is done to allow multiple instances of a simulated dSID.

After allocating an the dSS needs a way to talk to the instance. This is done through a structure wich contains several function pointers. This structure is returned by:
\code
  struct dsid_interface* dsid_get_interface();
\endcode

The structure looks like that:
\code
  struct dsid_interface {
    double (*get_value)(int _handle, int _parameterNumber);
    void (*set_value)(int _handle, int _parameterNumber, double _value);
    void (*increase_value)(int _handle, int _parameterNumber);
    void (*decrease_value)(int _handle, int _parameterNumber);
    void (*call_scene)(int _handle, int _sceneNr);
    void (*save_scene)(int _handle, int _sceneNr);
    void (*undo_scene)(int _handle, int _sceneNr);
    void (*enable)(int _handle);
    void (*disable)(int _handle);
    void (*get_group)(int _handle);

    void (*start_dim)(int _handle, int _directionUp, int _parameterNumber);
    void (*end_dim)(int _handle, int _parameterNumber);
    int (*get_group_id)(int _handle);
    int (*get_function_id)(int _handle);

    const char* (*get_parameter_name)(int _handle, int _parameterNumber);

    void (*set_configuration_parameter)(int _handle, const char* _name, const char* _value);
    int (*get_configuration_parameter)(int _handle, const char* _name, char* _value, int _maxLen);
  };
\endcode

The first parameter to each function is the instance identifier or handle to the instance.

The plugin has to be compiled as a shared-object. Here is an example of a makefile:

\verbatim
all:    vlc_remote.so install

vlc_remote.so2: vlc_remote.o
        #g++ -lPocoNet -lpthread -shared -Wl,-soname,vlc_remote.so -o vlc_remote.so *.o
        g++ -shared -o vlc_remote.so *.o


vlc_remote.so:  vlc_remote.cpp ../../../core/sim/plugin/pluginbase.cpp ../../../core/sim/plugin/pluginmedia.cpp ../../../core/sim/include/dsid_plugin.h
                g++ -g3 -O0 -Wall -fPIC -shared vlc_remote.cpp ../../../core/sim/plugin/pluginbase.cpp ../../../core/sim/plugin/pluginmedia.cpp -o vlc_remote.so

install:        vlc_remote.so
        cp vlc_remote.so ../../../data/plugins/
\endverbatim

Ensure that -fPIC is present, else it won't generate position independent code and is thus unsuitable for a shared-object.

\subsection plugin_example Example

The source of the dSS comes with an example implementation of a simulated dSID. This dSID simulates a mediaplayer device and controls a running VLC player. Its source can be found at "examples/plugins/vlc_remote". To try it out start a vlc instance with the following line:

\verbatim
vlc --rc-host localhost:4212
\endverbatim

\section notice Legal notice

Copyright (c) 2009 digitalSTROM.org, Zurich, Switzerland
Copyright (c) 2009 futureLAB AG, Zurich, Switzerland

  This file is part of digitalSTROM Server.

  digitalSTROM Server is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

digitalSTROM Server is provided by the copyright holders and contributors “as is” and any expressed or implied warranties, including but not limited to the implied warranties of merchantability and fitness for a particular purpose are disclaimed.  In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary or consequential damages (including but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or Tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. Because some states do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you. In such states, digitalSTROM.org liability is limited to the greatest extent permitted by law

*/