⬆ Level up


A home automation system for your Raspberry PI and your Android smartphone.

Install server on RaspberryPI



I can't do those for you.

  • Setup a MariaDB or Mysql database (may run directly on your Rasperry PI or anywhere else), see here
    • If the database is running on the raspberry:
      • Run mysql -p to connect, enter your password. When connected execute:
        • CREATE DATABASE homecontrol;
        • CREATE USER 'homecontrol'@'localhost' IDENTIFIED BY 'chooseSomePassword';
        • GRANT ALL PRIVILEGES ON homecontrol.* TO 'homecontrol'@'localhost';
    • For other cases:
      • Run the above commands from phpMyAdmin once it's setup.
  • Setup phpMyAdmin. You will definitely need it.
    • On raspbian that's easy: sudo apt-get install phpmyadmin
  • Make sure you have a running jdk (verison 8!!!) installed (dpkg --list|grep -i jdk). If not -> install it (using sudo apt-get install openjdk-11-jdk
  • Install mariadb-client (mysqldump command is required for backups before application upgrades): sudo apt-get install mariadb-client
  • If you want encryption (if you want to connect when you're not at home you definitely want this!!) you need to
    • setup a CA (here), pay for one or use something like CAcert. However practically viewed they can only issue ones for you if you use the application with a public domain.
    • create certificates
    • However you need to put those files into a keystore. I've dedicated a small chapter about this at the bottom of this page.
  • If you want to use the cheap 433 MHz switchable power sockets from hardware stores you need to provide your Raspberry PI with a radio module. Setup a 433 MHz emitter as described here (I know itís in German, use Google to translate, the images and commands shown are english. But I havenít found an English tutorial that is as straight forward as this one).
  • Setup infrared transceiver as described here.


Settings are stored in two different places: Read the following reference, you will need it during the installation.

Settings in local config file

Setting nameExample value(s)Explanation
nodeNamehomecontrolXIn individual node name for the raspberry.
homecontrolX |
In individual node hostname or its ip address.
usePlaintrue | falseListen for unencrypted connections.
useSsltrue | falseListen for encrypted connections. I suggest you do not use encryption for initial testing, but activate it later after the general setup is working.
sslDebugtrue | falseIn case of SSL problems where you don't know the reason, activate this.
listenPortPlain36735The port where the daemon is supposed to listen for incoming unencrypted connections.
listenPortSsl36736The port where the daemon is supposed to listen for incoming encrypted connections.
keystoreFilenamekeystore.jksThe filename of the java keystore. Only required if SSL is used anywhere.
keystorePasswordkeystorePasswordThe password of the java keystore.
DEPRECATED - Use databaseServerNames now -
The servername or IP address where the Mysql database is running.
databaseServerNamesservername1;servername2The servername or IP address where the Mysql database is running. Separate multiple servers with semikolons. If you use multiple servers you need to take care of data sync yourself!
databasePort3306The database port.
databaseNamehomecontrolThe name of the database.
databaseUsernamehomecontrolDatabase username.
databasePasswordpasswordDatabase password.
true | false
Do you have sensors attached?
Enter sensors in the database now (table "sensors"). If you had sensors in your config file during update they have been migrated to the database. - Device type, gpio pin, watch for rising/falling

Settings in database

Setting nameExample value(s)Explanation
authenticationModeldap | localAuthentication source
databaseVersionnumberDatabase version. You should not change this value yourself. The upgrade routine routine will take care of that.
dateFormatdd.MM.yyyy HH:mm:ss:SSSSDateformat, especially for logs. Consult this page for documentation.
encryptionKeychangemeAn encryption key that is used to communicate with sensor nodes.
ldapBasePathCN=Users,DC=my,DC=domain,DC=nameLDAP base path
ldapCacheRefresh60Because the connection to an LDAP server can take a moment that'll delay login time the server will remember a user's credentials in memory for a couple of minutes. After that time has passed it'll check if they are still correct. If not the next login attempt of that user will take a moment longer because the LDAP server will be contacted again. Set this value to 0 to deactivate caching.
ldapDomaindomain nameLDAP windows domain, will be linked with user name.
ldapHostsdc1.mydomain:389;dc2.mydomain:389List of LDAP servers with port. Separate multiple ones with semikolons.
ldapMailAttributemailMail attribute for a user in LDAP database
ldapMemberGroupCN=HomeControl,CN=Users,DC=my,DC=domain,DC=nameLDAP path of usergroup that is allowed to connect to Homecontrol
ldapUserAttributesamAccountNameLDAP attribute that holds the user's username
ldapUseSsltrue | falseUse SSL for connections to LDAP servers? Remember to check the port in the server list of you change this. Keep in mind the root CA's certificate that signed your LDAP server's certificate needs to be in a keystore.
logLevel1-5Log level, the higher the more details will be logged.
1 = basic information like daemon start/stop, also all critical errors
2 = actions like devices switched or users logged on
3 = details about actions
4 = network communication
5 = SQL related events
logMaxSizenumberMaximum size of log file in megabytes.
maximumLoggedInUsers20Maximum amount of simultaneous incoming connections.
true | false
Send mail notifications
, see notificationsEnabled now.
mqttClientEnabledtrue | falseMQTT client enabled.
mqttClientPasswordpasswordPassword used to connect to MQTT server.
mqttClientServerHostnamemqtt.domain.comHostname of MQTT server.
mqttClientServerPortusually 1883Port of MQTT server.
mqttClientUseAuthenticationtrue | falseUse authentication for MQTT client.
mqttClientUsernameusernameUsername used to connect to MQTT server.
mqttClientUseSsltrue | falseUse SSL to connect to MQTT server.
notificationAuthenticatetrue | falseUse authentication (username/password) to send emails.
notificationsEnabled (used to be mail)true | falseSend emails in case of events? Not in use, yet.
notificationFromAddressemail@provider.orgSender address for notifications.
notificationMailServersmtp.provider.orgMailserver used for admin notifications. In general for email settings start the server with the -testEmailNotification parameter to test email notifications.
notificationMailServerPort25Port of notification mail server. Encrypted is currently not supported, yet. Please wait for the next version.
notificationEncryptionTypeNONE | STARTTLS | TLS | SSLEncryption type used in smtp connection.
notificationPasswordpasswordPassword of notification mail server.
notificationToAddressemail@provider.orgRecepient address for notifications.
notificationUsernameusernameUsername of notification mail server.
notificationVerbosity1 - 5The higher the more notifications will be sent.
openWeatherMapApiKeypasswordYour individual openWeatherMap API key. Generate your's at https://openWeatherMap.org/
pushNotificationApiKeypasswordYour individual Firebase API key. Generate your's at https://console.firebase.google.com/
s20watchdogInterval10000Amount of milliseconds between watchdog checks.
s20useWatchdogtrue | falseApplies only if you're using Orvibo S20 devices: Enable watchdog. This will keep an eye on S20 devices and check their switching status. It could be that they have been triggerd from outside the application.
sensorUdpWatchPortnumberSpecifiy a port to listen on and receive UDP messages from potential sensor nodes. Keep in mind homecontrol runs as a non-privileged user by default. So ports <= 1024 cannot be used.
serverRelaytrue | falseRelay commands to other servers
serverRelayAutoDisconnectTime60000Time in ms after which to disconnect from other nodes. Connection will be kept open for this amount of milliseconds in case the client sends more commands than just one.
serverRelayClientTimeout5000Timeout in ms for relay connection attempts.
serverRelayPskasdlfkjsadkfjsldfjlskdjfPassword that server nodes use to authenticate each other.
serverRelayUseSsltrue | falseDecides if RelayConnections will be established using SSL (if you have multiple nodes). Remember to enter all nodes into "nodes" table and set the correct ports.
switchAttempts1 - 5The amount of attempts to switch devices.
switchRoomDelay0If you send mass commands (like switch all devices in a room) and multiple nodes send commands at almost the same time I've noticed problems which may be because of signal collisions. A node will wait a random fraction of this number of milliseconds before sending commands.
temperatureUnitC | FCelsius or Fahrenheit
voiceInterfaceEnabledtrue | falseVoice integration enabled or not
voiceInterfaceIntentMqttPathhermes/intent/#MQTT path to listen for snips messages
nohup ssh pi@jarvis /home/pi/.nvm/versions/node/v12.10.0/bin/node /home/pi/lite_js/ledPattern.js &
OPTIONAL: A command to run for LED responses on the voice hardware node
/usr/bin/ssh pi@jarvis /home/pi/speakText.sh ''
OPTIONAL: The command to give TTS responses
OPTIONAL: ssh pi@jarvis aplay -D sysdefault:CARD=ALSA
OPTIONAL: The command for sound responses like confirmation or error
voiceInterfaceTyperhasspy | snipsThe type of voice software you're running

General installation


Semi-automatic installation:

  1. Download install script from here to your raspberry.
  2. Store it on your raspberry: wget http://server47.de/homecontrol/install.sh and go to the directory where you stored it.
  3. Make sure it's executable after download: chmod 770 install.sh
  4. Run install.sh: sudo ./install.sh

Manual installation (if automatic fails):

    Unknown request.
  1. Download archive from here to your raspberry.
  2. Store it on your raspberry and go to the directory where you stored it.
  3. mkdir -p /home/pi
  4. tar xzvf homecontrol_v5.tar.gz\ -C /home/pi
  5. cd /home/pi/HomeControl
  6. java -jar HomeControl.jar -generateConfig
  7. Edit the configuration file: nano HomeControl-settings.ini
  8. java -jar HomeControl.jar -setupDatabase
  9. Install start/stop script: sudo ln -s /home/pi/HomeControl/homecontrol /etc/init.d/homecontrol
  10. Setup for automatic start (init): sudo update-rc.d homecontrol defaults
  11. Setup for automatic start (systemd): sudo systemctl enable homecontrol
  12. Export entire inventory in XML format: java -jar HomeControl.jar -exportInventory

After either method:

  • Go to your phpMyAdmin page from the prerequisites.
    • If you didn't/couldn't import the SQL file from the command line go to the database you created. Go to "Import", select the "homecontrol.sql". If you don't have the file at hand you can download it again from here.
    • Then go to the settings table in the database. Edit them according to the documentation above.
  • Then If you want to use Mysql for user management consult the user management chapter.
  • Afterwards start the daemon with this: sudo service homecontrol start

Automatic updates:

  • There is an "update.sh" script inside the HomeControl folder. Simply running that (./update.sh) should be all you need to do.
  • For your convenience you may choose to have it run every night by crontab:
    1. Run sudo crontab -e (it definitely needs to run as root because the service will need to be stopped and started)
    2. Add the following lines (including the beginning hash tag):

      # Run homecontrol updater every night at 4:30am
      30 4 * * * /home/pi/HomeControl/update.sh

Manual updates:

  • Stop the daemon: sudo service homecontrol stop
  • Go to /home/pi on your raspberry.
  • Download the latest version: wget http://server47.de/homecontrol/download/homecontrol_v5.tar.gz
  • Extract it: tar xzvf homecontrol_v5.tar.gz -C /home/pi
  • Run a database update in case one needs to be performed: java -jar HomeControl.jar -updateDatabase
  • Start the daemon: sudo service homecontrol start

User management

You have two general choices:
  • Use the Mysql database.
    • Usernames have to be a minimum of 4 characters, passwords 8 characters.
    • Run java -jar HomeControl.jar with one of those parameters:
      • -createUser username password emailAddress
      • -changeUser username newUserName newEmailAddress
      • -changeUserPassword username oldPassword newPassword
      • -deleteUser username
  • Use LDAP. I tested it only with Active Directory.
    • The settings for this are stored in the database.
    • If you want the connection to the LDAP server to be encrypted this requires some additional effort as you have to equip the LDAP server with a certificate. In an Active Directory the LDAP server (=domain controller) usually has one any way. But it needs to be signed by your CA. And this CA needs to be in your keystore.

User location

You can change a user's location easily from your phone by triggering a URL like this:
home: https://:36738/interface.html?objectType=user&objectName=home&desiredState=true
gone: https://:36738/interface.html?objectType=user&objectName=home&desiredState=false
You will be asked for authentication. Use a program like Automation to trigger those URLs automatically based on your location.


The application supports those sensors:
  • Motion
  • TemperatureHumidty
  • Brightness (via connected chip MCP 3008)
To configure them open phpMyAdmin and go to the sensors table:
  • Sensor type:
    • 1 - motion sensor
    • 2 - temperature/humidty
    • 3 - brightness
  • Sensor name: Choose one
  • Responsible node: The database ID of the responsible node (look it up in the nodes table)
  • Connected pin: However it depends on sensor type how the pin specified. That results in different application being executed in the background.
  • Frequency: The frequency in minutes how often the sensor querried. Does not apply to motion sensors, leave it at NULL there.
  • Direction: rising or falling, depending on how you configured your motion sensor. Only applies to motion sensors. Leave at NULL for other esnsors.

Motion sensor

This one is fairly easy. Get a sensor like these: http://www.electrodragon.com/product/pir/, model name may be something like HC-SR501. Attach it with 5V and ground. The 3rd pin goes to one of your GPIO pins. Specify it in the config, it'll then be monitored.

The setting rising/falling means: If your sensor will output a higher voltage in case of motion then use rising, if it'll go down in case of motion then use falling.

Temperature and humidty sensor

Get a DHT11 sensor. Then set it up like described in https://learn.adafruit.com/dht-humidity-sensing-on-raspberry-pi-with-gdocs-logging/wiring. If the execution works integrate it into the config.

IMPORTANT: The script needs to be available at /home/pi/Adafruit_Python_DHT/examples/AdafruitDHT.py

  • Download source code from from: https://github.com/adafruit/Adafruit_Python_DHT/releases
  • sudo apt install python3-pip
  • pip3 install Adafruit-DHT
  • cd Adafruit_Python_DHT
  • sudo python3 setup.py install

Brightness sensor

Since the raspberry can only read digital inputs by default, you'll need some help getting more info than 0 and 1. Otherwise you could only distinguish between dark and bright, nothing else. So you'll need a converter like the MCP3008 to transfer the different values over the SPI bus.

Here's a very nice walkthrough on interfacing the chip with your raspberry. However I chose to switch the left two cables (3.3V and ground). So the measured value will rise the brighter it is. I found that more intuitive. Use the script from the website to test your installation. However HomeControl will bring its own script to read the value as I need a more machine-readable output.

Power sensor

If you have a TP Link HS110 socket a related power usage sensor will be created/changed/deleted.

Door/window sensor

Currently supported over zigbee2mqtt.

Creating a java keystore

This step is only necessary if you want to connect to the server using encryption (what I strongly recommend if you intent to use this software over the internet). This chapter can only cover managing a java keystore. It does not explain how asymetric encryption is working in general. You create only 1 keystore, so the keystore filename should always be the same.

You have two general choices:

  1. The graphical tool named Keystore Explorer. This is probably the preferred solution.
    1. Download Keystore Explorer: http://www.keystore-explorer.org/downloads.html
  2. Command line - this may have several challenges due to parameter issues and different versions.
    1. Go to your HomeControl directory. Do all steps from there!
    2. Generate a Java keystore and key pair (feel free to increase the keysize at the end):
      • keytool -genkey -alias "a-name-for-your-key-e-g-homecontrol1" -keyalg RSA -keystore keystore-filename -keysize 4096
    3. Generate a certificate signing request (CSR):
      • keytool -certreq -alias "a-name-for-your-key-e-g-homecontrol1-same-name-like-above!" -keystore keystore-filename -file filenameOfRequestFile.csr
    4. Get your request signed by your CA. Put the response in a file and run:
      • keytool -import -trustcacerts -alias "a-name-for-your-key-e-g-homecontrol1-same-name-like-above!" -file filename-with-CA-response -keystore keystore-filename
    5. Get the root certificate that signed your key and put it in your HomeControl directory. Import it using this command:
      • keytool -import -alias "specifiy-a-short-root-certificate-name" -file "root-certificate-filename" -keystore keystore-filename -storetype BKS
    6. There may be situations where did does not work. You may need to use the Bouncy Castle provider (Would you like to know more?). Download the file from
      • here or copy the download link from the webpage and download it to your raspberry using
        • wget --link--
      • Then try again with this additional parameter:
        • keytool -import -alias "specifiy-a-short-root-certificate-name" -file root-certificate-filename -keystore keystore-filename -storetype BKS -provider org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath bcprov-jdk15on-146.jar
    7. If you would like to read more I've found a very nice overview of keytool commands here.

Zigbee support

Basically HomeControl can catch on to your MQTT server that is from the other end fed from a working installation of Zigbee2MQTT. You can get it at https://www.zigbee2mqtt.io. Keep it mind you also need to purchase some hardware which is relatively inexpensive though.
  • To get this working your need to:
    • create devices / and or sensors.
    • Setup the MQTT parameters in general settings.

Snips voice Assistant

HomeControl can be used with Snips voice assistant. Keep in mind snips has been more or less discontinued since the company was bought by Sonos.
  • To get this working your need to:

Rhasspy voice Assistant

HomeControl can be used with Rhasspy voice assistant.
  • To get this working your need to:


It's rather simple. Start/Stop script is installed if the installation was successfull.
  • Start the daemon: sudo service homecontrol start OR on systemd: sudo systemctl start homecontrol
  • Stop the daemon: sudo service homecontrol stop OR on systemd: sudo systemctl stop homecontrol
  • Restart the daemon: sudo service homecontrol restart OR on systemd: sudo systemctl restart homecontrol

Inject commands

You can execute commands to a running server with the -sendCommand parameter. For example you can utilize this to automate stuff using other application.
  • Chapter under construction

Command line reference

Here is a list of available startup parameters along with links to a closer description.
  • "-generateConfig":See here
  • "-setupDatabase":See here
  • "-updateDatabase":See here
  • "-createUser":See here
  • "-changeUser":See here
  • "-deleteUser":See here
  • "-changeUserPassword":See here
  • "-getVersion":Print program version
  • "-testEmailNotification":See here
  • "-sendCommand":See here


Here are some of the most common problems along with possible solutions.
  1. In case your installation is generally working, but stops every now and then (e.g. because of memory problems) you could schedule a regular restart.
    • Edit crontab: sudo crontab -e
    • Enter a new line: 0 3,15 * * * /home/pi/HomeControl/distributeAndRestartHC.sh
    • This will restart the daemon twice a day at 3:00 and 15:00.
  2. Could not start server socket: java.net.SocketException: java.security.NoSuchAlgorithmException: Error constructing implementation (algorithm: Default, provider: SunJSSE, class: sun.security.ssl.SSLContextImpl$DefaultSSLContext)
    • The keystore you are using may have the wrong format. Verify it is JKS.
      • Open the store in KeyStore Explorer
      • Tools -> Change Keystore Type -> JKS
    • Also verify your private key inside the keystore is encrypted using the same password as the enclosing keystore.
      • Right-click your certificate/privateKey
      • Set password
  3. Local temperature sensors cease to work after you've updated Raspbian.

Script examples

Here are examples for scripts that can be integrated into rules:
  • An example on how to download an image from a webcam. Duckduckgo for your camera to find the image path of your specific model: scriptCameraImage.txt

HomeControl - Copyright by Jens Schröder, 2015 - 2023