Welcome to HKontrol!

About HKontrol
Again, what it is all about?
How is HKontrol structured?
Which Modules are available?
How can I create new Modules and Actions?
How to obtain HKontrol

1. About HKontrol

HKontrol is a rule based home automation software originally written to ease the operation of harman kardon A/V receivers which are equipped with a serial interface. It is organized in a modular way and thus easily extendible to fulfil other automation challenges.

2. Again, what it is all about?

HKontrol supports the simple operation of harman kardon's serial interface equipped A/V receivers. The problem with these receivers is that you can't disable surround modes you never use. If you for instance want to switch from "Dolby PLII MOVIE 5.1" to "Dolby PLIIx MOVIE 7.1" you have to push about eight(!) times the Dolby button on the remote control skipping a lot of unused multi channel modes. Unfortunately the receivers keep switching back to "Dolby PLII MOVIE 5.1" in case the digital audio source changes. The serial interface however can be used bidirectional. It provides exactly the information that is visible on the receiver's display. In addition commands, each acting like key presses on the remote control, can be sent over it to control the receiver. With a set of configurable rules like "send the dolby command when the display shows an unwanted Dolby mode" it is possible to automatically skip surround modes you never use.

3. How is HKontrol structured?

HKontrol consists mainly of three parts: An application core, modules and a configuration file.

The Core

HKontrol's core merely provides a framework that implements a data model in a model-view-controller architecture (MVC). Based on the user provided configuration it notifies the modules about model (i.e. status) changes.

The Modules

On the one hand, modules act as the controller part of the MVC. They collect status information about a device or a running application and let the core know about it. On the other hand, modules implement actions which can be executed on status changes.

The Configuration

In the configuration file the user defines which connections, modules and rules shall be used by HKontrol. The rules act as the glue between the runtime status and the executed actions.

You can find a configuration example in the installation instructions.

4. Which Modules are available?

hk
Retrieves status information about harman kardon A/V receivers and provides actions to control the receivers. The actions reflect the keys of the shipped remote control. This module allows you to switch on and off your receiver, change the current surround mode, and the like.
host
Checks the reachability of one or more hosts on the network. This can be useful if your Blu-ray Disc player is equipped with a network interface and its power chord connected to the receiver. Your don't want to switch off the receiver as long as the BD-player is powered on.
timer
Provides arbitrary timers that can also be used as watchdog timers. At home I'm using this to automatically switch off my receiver if it's not in use for thirty minutes.
mythtv
Can retrieve the current state of the PVR software MythTV. Together with the hk module, we can automatically switch the audio receiver's mode depending on MythTV's state.
remotecontrol
Opens a TCP port where you can telnet to and query and change HKontrol's data structures. By defining appropriate rules, you can even control MythTV or any other HKontrol-supported software or device.
debug
Prints out status information. Using HKontrol's standard action mechanism, the output can be triggered by any status change, which is highly useful for module development and rule testing.

5. How can I create new Modules and Actions?

Creating and using new modules is quite simple. The full API documentation can be helpful, but a short recipe is depicted here. To create and use a new module, you have to do only a few things:

Create a new package named "hkontrol.module.<mymodule>"
Create a subclass from "hkcontrol.core.AbstractModule" named "hkontrol.module.<mymodule>.Module"
Configure the module in "hkontrol.conf":
```
    <Module name="<mymodule>" />
    
```

To create and use new actions is just as simple:

Create a new package named "hkontrol.module.<mymodule>.action"
Create a subclass from "hkcontrol.core.AbstractAction" named "hkontrol.module.<mymodule>.action.<MyAction>"

Configure a rule for using the newly created action:

  <Rule action="<mymodule>.action.<MyAction>">
    <Match key="some.key.to.match" value="some value to match" />
  </Rule>