The Dog Gateway Files

Starting Dog2.x (Standalone Version)

To start Dog2.x, first check if a Java 1.6 JRE (www.java.com) is installed on your PC and if the corresponding path has been added to the system command path.

Then:

• on Microsoft Windows:
  double click on start_dog.bat for the Ontology-based version (the most powerful)
  double click on start_dog_simple.bat for the XML-based version (the simplest one)
• on Unix-like systems:
  execute on a terminal window the bash script ./start_dog.sh for the Ontology-based version (the most powerful)
  execute on a terminal window the bash script ./start_dog_simple.sh for the XML-based version (the simplest one)

Testing Dog2.x (Standalone Version)

When Dog is up and running you see an osgi> prompt on the terminal window from which the Dog2 script has been launched.
This prompt belongs to the OSGi console and will display information about Dog2, allowing, at the same time, to type framework and platform commands.

Type ss at the OSGi prompt for retrieving the status of all Dog2 bundles when Dog is working. All the bundles should be ACTIVE (only the SemanticHouseModel can be LAZY).
Type help for others useful commands.

How to put Dog in the kennel, i.e., how to shut Dog2.x down
Dog2 is quite obedient, so type close at the OSGi prompt and it will gracefully shut down and quit the OSGi console.

Programming for Dog2.x

Setting up the Dog2.x development environment in Eclipse
0) Download and install Eclipse for RCP and RAP Developers (Dog has not been tested with the Indigo 3.7.x version)
1) Download the Dog2.x sources from either the http://domoticdog.sourceforge.net web site or from git
2) Import the Dog2.x sources in a new (or existing) Eclipse RCP workspace (as a set of Existing projects)
3) For clearness sake, create a new working space named Dog2 (or else) (File > New > Java Working Set) and add all the Dog2 projects to it
4) In Eclipse, open (double click) the project Dog2Docs
5) In Eclipse, open (double click) the folder OSGi Libraries, under the Dog2Docs project folder
6) Copy the osgi.cmpn.jar and osgi.core.jar files in the eclipse Plugin folder (inside the Eclipse application folder)
7) Restart Eclipse

If Eclipse (this issue is typical of the Helios release) reports "access" errors in sources (see the "Problems" tab), set "Forbidden reference" to Warning (in Eclipse Preferences > Java > Compiler > Errors/Warnings > Deprecated and restricted API); rebuild the workspace if necessary.
If Eclipse reports "Missing API Baseline" errors (or warnings), set eclipse as default baseline (in Eclipse Preferences > Plugin development > API Baseline > Add Baseline... > add a name of your choice and press Reset).

Running Dog2
To run Dog2.x, select Run Configurations in the Run menu and create a new OSGi framework configuration (if does not exist yet). Select all the bundles in the workspace, deselect all the bundles under "Target Platform" and click on "Add Required Bundles" (on the right of the run configuration window).
Click on Apply and then Run, Dog2.x shall start without any problem.

Connecting Real Plants

In order to connect Dog2.x to a real plant (e.g., KNX or BTicino MyHome) some further steps must be accomplished:
1) Create a configuration folder, for example DogConfig
2) Add the VM parameter in the OSGi launcher parameter:
2.1) Run -> Run configurations...
2.2) Select the project launcher, for example Dog 2.x SimpleHome
2.3) Select the (x) argument tab
2.4) add the "-DconfigFolder=<your configuration folder>" string to the VM parameter

KNX networks
The KNX network configuration is defined by the KnxNetworkDriver.config file.

1) Change the "houseIP" parameter to the IP address of the KNX/IP gateway you want to connect to
2) Join the multicast address 239.192.39.238 (this may already work in your default PC setting)
a) Type netstat -rn on the command line terminal (Windows cmd or Linux bash)
b) Look at the routing table, if no entry is provided for the above address, add it. (in Windows this corresponds to write the command
route -p ADD 239.192.39.238 MASK 240.0.0.0 <your gateway IP address>
c) Check that your firewall is accepting UDP multicast connections on the port 51000
3) Change the "myIP" parameter to the IP address of your PC

BTicino networks
The BTicino network configuration is defined by the BTicinoNetworkDriver.config file.
1) Change the "houseip" parameter to the IP address of the BTicino gateway you want to connect to
2) Make sure that the IP address of your PC is in the MyHome gateway trusted addresses (see BTicino documentation for more information)
3) [Firewall Suse -> Allowed Services / Advanced] Open IP protocols 92 (Multicast Transport Protocol)

Configuration parameters for other supported technologies are located in their .config files or in the XML-based configuration file