How to install HKontrol?

0. Install ser2net

• At present HKontrol can not use a serial port directly but can merely establish TCP connections. So you need the help of a program like ser2net that allow tcp sessions to be established with serial ports.

  If your receiver is connected to the first serial port of your computer, a working ser2net configuration line for /etc/ser2net.conf might be:
  localhost,2005:raw:600:/dev/ttyS0:38400 8DATABITS NONE 1STOPBIT LOCAL

1. Unpack the tarball

• If you downloaded the source tarball unpack it:
  tar xvzf hkontrol-src-{version}.tar.gz

2. Compile the source code

• Make the project's root directory your current working directory:
  cd hkontrol-{version}
• Either use an IDE like eclipse or the following command:
  javac -sourcepath src -d classes -cp lib/xpp3-*.jar `find src -name \*.java`

3. Configure HKontrol

• Copy the contributed hkontrol.conf as a start:
  cp contrib/hkontrol.conf /etc/
• Change /etc/hkontrol.conf to suit your needs:

  <?xml version="1.0" ?>
  <HKontrolConfiguration>
  
    <!-- Configure the log level to use.
            Valid levels:
               OFF, SEVERE, WARNING, CONFIG, INFO, FINE, FINER, FINEST, ALL
    -->
    <Logging level="INFO" />
  
    <!-- Define a tcp connection to port 2005 of server "localhost" and
            name it "receiverConnection".
    -->
    <Connection name="receiverConnection" type="TCP" host="localhost" port="2005" />
  
    <!-- Tell HKontrol we need a module named "hk" which shall use above
            defined connection.
    -->
    <Module name="hk" connection="receiverConnection" />
  
    <!-- Amongst others, module "hk" reads the bottom display line the connected A/V receiver
            and announces it with the key "hk.display.bottom". If this value matches the
            regex "^LOGIC 7 5CH.*$", the action "hk.action.Logic7" shall be executed which
            switches the receiver's surround mode to a 7.1 configuration.
    -->
    <Rule action="hk.action.Logic7" connection="receiver">
      <Match key="hk.display.bottom" value="^LOGIC 7 5CH.*$" />
    </Rule>
  
  </HKontrolConfiguration>
  

4. Run HKontrol

• java -cp classes:lib/xpp3-*.jar hkontrol.HKontrol /etc/hkontrol.conf

5. Test it

• If it's not doing what you expect it to do, go back to step 3.

6. Have fun

• Watch your receiver automatically skipping surround modes you never want to use. It's fun!