Recent changes to Quickstart

Quickstart modified by Georg Neugschwandtner

Georg Neugschwandtner — Tue, 05 Aug 2014 18:49:35 -0000

--- v6
+++ v7
@@ -5,39 +5,64 @@

 This page helps you to get started with Calimero quickly. Its focus is to convince you that Calimero is suitable as communication layer for your KNX project. Since Calimero is a library for communicating with KNX devices from Java, do not expect fancy GUI applications that are ready for end-user consumption. The tools being described here are merely tech demos that show the capabilities of the library and prove that it does what is expected to do.

-## Install and Build ##

-It is assumed that you use the Eclipse IDE for Java for your development. The latest source from the [Calimero repository at GitHub](https://github.com/calimero-project/) is used for building. If you want to skip this step, you can use the JARs `calimero-2.0.4.jar` and `examples/calimero-tools-2.0.2.jar` from the distribution package.

-Please note the [different licenses]([License]) for the Github code and the Sourceforge distribution package. 
+## Project Structure ##

-### Clone the reposiory ###
+The project is structured into several repositories. Calimero Core is the main Java library. Being a library, you can not "start" or "run" it like an ordinary application. (To do this, you might refer to the Calimero Tools or the GUI). The library contains functionality to be invoked by user applications. It requires KNX capable endpoints and some UI/task. Nevertheless, the library contains a method `main` (`tuwien.auto.calimero.Settings.main`). It is used to show information about the library itself, like a header and version, which can also be queried directly through methods of class Settings. To run applications which just use the Calimero library, only calimero-x.jar is required.

-* Open the perspective "Git Repository"
-* Choose "Clone a Git Repository" from the "Git Repositories" view.
-* Enter the URI of the Calimero main repository: https://github.com/calimero-project/calimero.git
-* Choose the "master" branch
-* Click finish
+Show information about the library in the terminal:

-* Proceed the same way with the Calimero-tools repository at https://github.com/calimero-project/calimero-tools.git
+~~~~~
+$ java -cp "calimero-x.jar" tuwien.auto.calimero.Settings
+~~~~~

-You end up with two local repository clones "calimero" and "calimero-tools" in the "Git Repositories" view.
+## Setup ##

-### Check out ###
+For running Java programs, you need a Java Runtime Environment (JRE), together with any other third party libraries you might want to use. For details how to set up Java, refer to dedicated SDK installation sites, for example the [Java installation guide](http://docs.oracle.com/javase/7/docs/webnotes/install/index.html).

-Now you are ready to check out the projects from your local repository clone into the workspace.
+Put the Calimero `*.jar` files (or the extracted class folders) into the classpath searched by the Java class loader or into the current working directory. One way to extract a `jar` file into your working directory using the terminal:

-* Select the "calimero" repository.
-* Choose "Import Projects" from the context menu.
-* Proceed with the "Import existing projects" option.
-* Choose the project "calimero" from the next page and
-* Finish the checkout.
+~~~~~
+$ jar -xf my-library.jar
+~~~~~

-* Repeat the steps with the "calimero-tools" repository and import the project "calimero-tools" from there.
+Alternatively, [import the Calimero source code into your development environment and build it](EclipseQuickstart).

-You should end up with two projects in your Eclipse workspace. Eclipse should now already have compiled the code so that you can immediately try it out.
+When using KNXnet/IP and network interfaces, make sure that
+
+* you configured the network interfaces correctly,
+* you are using the intended network interface,
+* firewall settings don't block KNXnet/IP traffic.
+
+The first two points are especially relevant on multi-homed computers, i.e., those having several installed network interfaces. Take care with NAT (Network Address Translation) and IPv6 addresses, because KNXnet/IP works with IPv4 by default.
+
+  **!** | Giving preference to IPv4 using `-Djava.net.preferIPv4Stack=true` as Java VM argument can avoid address assignment problems on some operating systems.
+  ------------- | -------------
+    |
+
+Please refer to dedicated documentation for your particular execution environment.
+
+
+## Usage ##
+
+Calimero tools are executed in the terminal. Starting a search for KNXnet/IP devices is done via (replace `x` with your version):
+
+~~~~~
+$ java -cp "calimero-x.jar;calimero-tools-x.jar" tuwien.auto.calimero.tools.Discover -s
+~~~~~
+
+  **!** | On Windows, the classpath entries of `-cp` are separated by a `;`, on Linux `:` is used.
+  ------------- | -------------
+    |
+

 ## Try it out ##
+
+The following steps assume that you have the Calimero Core and Tools JAR files (e.g., `calimero-2.0.4.jar` and `examples/calimero-tools-2.0.2.jar`) available, either because you [built them yourself](EclipseQuickstart) or because you got them from the distribution package.
+
+ 
+

 ### Discover your KNX network ###

@@ -84,6 +109,9 @@

 This roughly means, that a "KNX IP Router 750" was found with KNX hardware address "1.1.0" that can be contacted through IP address "192.168.178.23" on port "3671". The information about the local address (which identifies the interface that was used for communication) is currently not printed (see [Ticket #21]([#21])). However, if your local machine has multiple network interfaces, it is essential to pass this information to the tools expained in the following steps.

+ 
+
+
 ### Low-level listening to the KNX network ###

 The tool `java tuwien.auto.calimero.tools.NetworkMonitor` allows to listen on the KNX bus in a low-level fashion. It has the following options:
@@ -111,6 +139,8 @@
 ~~~~~
 java tuwien.auto.calimero.tools.NetworkMonitor -localhost 192.168.178.73 -p 3671 192.168.178.23
 ~~~~~
+
+ 

 ### Take control over your components ###

@@ -161,3 +191,4 @@
    192.168.178.23  write ucount 128 1/3/7
 ~~~~~

+

Quickstart modified by Bernhard Haumacher

Bernhard Haumacher — Thu, 17 Oct 2013 19:28:21 -0000

--- v5
+++ v6
@@ -8,6 +8,8 @@
 ## Install and Build ##

 It is assumed that you use the Eclipse IDE for Java for your development. The latest source from the [Calimero repository at GitHub](https://github.com/calimero-project/) is used for building. If you want to skip this step, you can use the JARs `calimero-2.0.4.jar` and `examples/calimero-tools-2.0.2.jar` from the distribution package.
+
+Please note the [different licenses]([License]) for the Github code and the Sourceforge distribution package. 

 ### Clone the reposiory ###

@@ -142,20 +144,20 @@

 ~~~~~
 java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
-   -p 3671 192.168.178.23 write bool true 1/1/5
+   192.168.178.23 write bool true 1/1/5
 ~~~~~

 If the device supports reading out the current actuator state, using the same group address, you can determine the current state of the light by issuing a read command:

 ~~~~~
 java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
-   -p 3671 192.168.178.23 write read bool 1/1/5
+   192.168.178.23 write read bool 1/1/5
 ~~~~~

 In the same way, you can move shutters or position heating valves by sending integer values to the bus. The following example sends the value `128` to the group address `1/3/7`. If a shutter actuator uses the address for the position, the shutter would go down to 50%:

 ~~~~~
 java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
-   -p 3671 192.168.178.23  write ucount 128 1/3/7
+   192.168.178.23  write ucount 128 1/3/7
 ~~~~~

Quickstart modified by Bernhard Haumacher

Bernhard Haumacher — Sat, 12 Oct 2013 20:43:35 -0000

--- v4
+++ v5
@@ -102,7 +102,7 @@
   -medium -m          KNX medium [tp0|tp1|p110|p132|rf] (default tp1)
 ~~~~~

-Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the `NetworkMonitor` cannot be used, since a router is not able to provide low-level listening access to the network, see [Ticket #22}([#22]). 
+Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the `NetworkMonitor` cannot be used, since a router is not able to provide low-level listening access to the network, see [Ticket #22]([#22]). 

 Using the information from the discovery run above, you can start the NetworkMonitor using the following command line (with addresses and ports adjusted to the results from the discovery run above). If your local machine has multiple IP interfaces (such as LAN and WLAN, etc.) make sure to pass in the option `-localhost` to identify the network interface to use for communication. Using the wrong interface, the connection would simply time out, otherwise.

Quickstart modified by Bernhard Haumacher

Bernhard Haumacher — Sat, 12 Oct 2013 20:42:39 -0000

--- v3
+++ v4
@@ -80,7 +80,7 @@
 S/N 0x00c5010012d1
 ~~~~~

-This roughly means, that a "KNX IP Router 750" was found with KNX hardware address "1.1.0" that can be contacted through IP address "192.168.178.23" on port "3671". The information about the local address (which identifies the interface that was used for communication) is currently not printed (see Ticket #21). However, if your local machine has multiple network interfaces, it is essential to pass this information to the tools expained in the following steps.
+This roughly means, that a "KNX IP Router 750" was found with KNX hardware address "1.1.0" that can be contacted through IP address "192.168.178.23" on port "3671". The information about the local address (which identifies the interface that was used for communication) is currently not printed (see [Ticket #21]([#21])). However, if your local machine has multiple network interfaces, it is essential to pass this information to the tools expained in the following steps.

 ### Low-level listening to the KNX network ###

@@ -102,7 +102,7 @@
   -medium -m          KNX medium [tp0|tp1|p110|p132|rf] (default tp1)
 ~~~~~

-Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the `NetworkMonitor` cannot be used, since a router is not able to provide low-level listening access to the network, see Ticket #22. 
+Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the `NetworkMonitor` cannot be used, since a router is not able to provide low-level listening access to the network, see [Ticket #22}([#22]). 

 Using the information from the discovery run above, you can start the NetworkMonitor using the following command line (with addresses and ports adjusted to the results from the discovery run above). If your local machine has multiple IP interfaces (such as LAN and WLAN, etc.) make sure to pass in the option `-localhost` to identify the network interface to use for communication. Using the wrong interface, the connection would simply time out, otherwise.

Quickstart modified by Bernhard Haumacher

Bernhard Haumacher — Sat, 12 Oct 2013 20:39:03 -0000

--- v2
+++ v3
@@ -80,7 +80,7 @@
 S/N 0x00c5010012d1
 ~~~~~

-This roughly means, that a "KNX IP Router 750" was found with KNX hardware address "1.1.0" that can be contacted through IP address "192.168.178.23" on port "3671". The information about the local address (which identifies the interface that was used for communication) is currently not printed (see [Ticket #21]([#21])). However, if your local machine has multiple network interfaces, it is essential to pass this information to the tools expained in the following steps.
+This roughly means, that a "KNX IP Router 750" was found with KNX hardware address "1.1.0" that can be contacted through IP address "192.168.178.23" on port "3671". The information about the local address (which identifies the interface that was used for communication) is currently not printed (see Ticket #21). However, if your local machine has multiple network interfaces, it is essential to pass this information to the tools expained in the following steps.

 ### Low-level listening to the KNX network ###

@@ -102,7 +102,7 @@
   -medium -m          KNX medium [tp0|tp1|p110|p132|rf] (default tp1)
 ~~~~~

-Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the `NetworkMonitor` cannot be used, since a router is not able to provide low-level listening access to the network, see [Ticket #22]([#22]). 
+Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the `NetworkMonitor` cannot be used, since a router is not able to provide low-level listening access to the network, see Ticket #22. 

 Using the information from the discovery run above, you can start the NetworkMonitor using the following command line (with addresses and ports adjusted to the results from the discovery run above). If your local machine has multiple IP interfaces (such as LAN and WLAN, etc.) make sure to pass in the option `-localhost` to identify the network interface to use for communication. Using the wrong interface, the connection would simply time out, otherwise.

@@ -112,6 +112,50 @@

 ### Take control over your components ###

+It's time to switch your lights on, `tuwien.auto.calimero.tools.ProcComm` demonstrates how to do. The following command line options are supported:

+~~~~~
+java tuwien.auto.calimero.tools.ProcComm -help

-## Further steps ##
+usage: ProcComm [options] 
+options:
+  -help -h                show this help message
+  -version                show tool/library version and exit
+  -verbose -v             enable verbose status output
+  -localhost          local IP/host name
+  -localport      local UDP port (default system assigned)
+  -port -p        UDP port on  (default 3671)
+  -nat -n                 enable Network Address Translation
+  -routing                use KNX net/IP routing (always on port 3671)
+  -serial -s              use FT1.2 serial communication
+  -medium -m          KNX medium [tp0|tp1|p110|p132|rf] (default tp1)
+Available commands for process communication:
+  read             read from group address
+  write     write to group address
+Additionally recognized name aliases for DPT numbers:
+  switch (1.001), bool (1.002), string (16.001)
+  float (9.002), ucount (5.010), angle (5.003)
+completed, null
+~~~~~
+
+Assuming that an actuator is listening for group address `1/1/5` for switching a light, you can switch it on using the following command (assuming the same communication parameters as above):
+
+~~~~~
+java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
+   -p 3671 192.168.178.23 write bool true 1/1/5
+~~~~~
+
+If the device supports reading out the current actuator state, using the same group address, you can determine the current state of the light by issuing a read command:
+
+~~~~~
+java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
+   -p 3671 192.168.178.23 write read bool 1/1/5
+~~~~~
+ 
+In the same way, you can move shutters or position heating valves by sending integer values to the bus. The following example sends the value `128` to the group address `1/3/7`. If a shutter actuator uses the address for the position, the shutter would go down to 50%:
+
+~~~~~
+java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
+   -p 3671 192.168.178.23  write ucount 128 1/3/7
+~~~~~
+

Quickstart modified by Bernhard Haumacher

Bernhard Haumacher — Sat, 12 Oct 2013 20:22:08 -0000

--- v1
+++ v2
@@ -39,6 +39,10 @@

 ### Discover your KNX network ###

+The first tool to check is `tuwien.auto.calimero.tools.Discover`. Its purpose is to find the route to the gateway to the KNX network from the local PC it is running on. The result Discover returns is required for invoking any other tools. 
+
+Discover has the followig options:
+
 ~~~~~
 java tuwien.auto.calimero.tools.Discover -help

@@ -57,12 +61,57 @@
  -serverport -p  server UDP port for description (default 3671)
 ~~~~~

+The option -search starts a discovery run:
+
 ~~~~~
 java tuwien.auto.calimero.tools.Discover -search
 ~~~~~

-### Listen to your KNX network ###
+This command searches all interfaces of your local computer for connnection to a KNX/IP gateway. If the search is successful, it returns something like the following (depending on your actual hardware):
+
+~~~~~
+local address /192.168.178.73
+control endpoint IPv4 UDP host 192.168.178.23 port 3671
+device 1.1.0 "KNX IP Router 750"
+KNX medium TP1
+installation 0 project 0 (project installation ID 0)
+routing multicast address /224.0.23.12
+MAC address 00-24-6d-00-39-04
+S/N 0x00c5010012d1
+~~~~~
+
+This roughly means, that a "KNX IP Router 750" was found with KNX hardware address "1.1.0" that can be contacted through IP address "192.168.178.23" on port "3671". The information about the local address (which identifies the interface that was used for communication) is currently not printed (see [Ticket #21]([#21])). However, if your local machine has multiple network interfaces, it is essential to pass this information to the tools expained in the following steps.
+
+### Low-level listening to the KNX network ###
+
+The tool `java tuwien.auto.calimero.tools.NetworkMonitor` allows to listen on the KNX bus in a low-level fashion. It has the following options:
+
+~~~~~
+java tuwien.auto.calimero.tools.NetworkMonitor -help
+
+2013-10-12 22:04:15,453 always, tools: usage: NetworkMonitor [options] 
+options:
+  -help -h                show this help message
+  -version                show tool/library version and exit
+  -verbose -v             enable verbose status output
+  -localhost          local IP/host name
+  -localport      local UDP port (default system assigned)
+  -port -p        UDP port on host (default 3671)
+  -nat -n                 enable Network Address Translation
+  -serial -s              use FT1.2 serial communication
+  -medium -m          KNX medium [tp0|tp1|p110|p132|rf] (default tp1)
+~~~~~
+
+Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the `NetworkMonitor` cannot be used, since a router is not able to provide low-level listening access to the network, see [Ticket #22]([#22]). 
+
+Using the information from the discovery run above, you can start the NetworkMonitor using the following command line (with addresses and ports adjusted to the results from the discovery run above). If your local machine has multiple IP interfaces (such as LAN and WLAN, etc.) make sure to pass in the option `-localhost` to identify the network interface to use for communication. Using the wrong interface, the connection would simply time out, otherwise.
+
+~~~~~
+java tuwien.auto.calimero.tools.NetworkMonitor -localhost 192.168.178.73 -p 3671 192.168.178.23
+~~~~~

 ### Take control over your components ###

+
+
 ## Further steps ##

Quickstart modified by Bernhard Haumacher

Bernhard Haumacher — Wed, 09 Oct 2013 21:40:20 -0000

Calimero Contents

Home
Documentation
Support
Miscellaneous
Links

Calimero Quickstart

Calimero Quickstart

This page helps you to get started with Calimero quickly. Its focus is to convince you that Calimero is suitable as communication layer for your KNX project. Since Calimero is a library for communicating with KNX devices from Java, do not expect fancy GUI applications that are ready for end-user consumption. The tools being described here are merely tech demos that show the capabilities of the library and prove that it does what is expected to do.

Install and Build

It is assumed that you use the Eclipse IDE for Java for your development. The latest source from the Calimero repository at GitHub is used for building. If you want to skip this step, you can use the JARs calimero-2.0.4.jar and examples/calimero-tools-2.0.2.jar from the distribution package.

Clone the reposiory

Open the perspective "Git Repository"
Choose "Clone a Git Repository" from the "Git Repositories" view.
Enter the URI of the Calimero main repository: https://github.com/calimero-project/calimero.git
Choose the "master" branch
Click finish
Proceed the same way with the Calimero-tools repository at https://github.com/calimero-project/calimero-tools.git

You end up with two local repository clones "calimero" and "calimero-tools" in the "Git Repositories" view.

Check out

Now you are ready to check out the projects from your local repository clone into the workspace.

Select the "calimero" repository.
Choose "Import Projects" from the context menu.
Proceed with the "Import existing projects" option.
Choose the project "calimero" from the next page and
Finish the checkout.
Repeat the steps with the "calimero-tools" repository and import the project "calimero-tools" from there.

You should end up with two projects in your Eclipse workspace. Eclipse should now already have compiled the code so that you can immediately try it out.

Try it out

Discover your KNX network

java tuwien.auto.calimero.tools.Discover -help

usage: Discover [options]
options:
 -help -h                show this help message
 -version                show tool/library version and exit
 -localport <number>     local UDP port (default system assigned)
 -nat -n                 enable Network Address Translation
 -timeout -t             discovery/description response timeout
 -search -s              start a discovery search
 -interface -i <IF name | host name | IP address>
      local multicast network interface for discovery or
      local host for self description (default system assigned)
 -description -d <host>  query description from host
 -serverport -p <number> server UDP port for description (default 3671)

java tuwien.auto.calimero.tools.Discover -search