HomeControl

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


Back to main page


Install server on RaspberryPI

Contents

Prerequisites:

I can't do those for you.

  • 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.
  • Setup a 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';
        • FLUSH PRIVILEGES;
    • 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 oracle-java8-jdk
  • 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.


Settings


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.
networkNameOrAddresshomecontrolX | 192.168.0.55In 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.
databaseServerName
servername
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.
sensorsExisting
true | false
DEPRECATED -
Do you have sensors attached?
sensorArray
MotionDetector/1/rising
DEPRECATED -
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 | mysqlAuthentication source
dateFormatdd.MM.yyyy HH:mm:ss:SSSSDateformat, especially for logs. Consult this page for documentation.
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.
ldapBasePathCN=Users,DC=my,DC=domain,DC=nameLDAP base path
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.
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.
maximumLoggedInUsers20Maximum amount of simultaneous incoming connections.
notificationsEnabled (used to be mail)true | falseSend emails in case of events? Not in use, yet.
notificationVerbosity)1 - 5The higher the more notifications will be sent.
notificationFromAddressemail@provider.orgSender address for notifications.
notificationToAddressemail@provider.orgRecepient 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.
notificationAuthenticatetrue | falseUse authentication (username/password) to send emails.
notificationUsernameusernameUsername of notification mail server.
notificationPasswordpasswordPassword of notification mail server.
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.

General installation

FINISH PREREQUISITES FIRST!!!

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):

  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_v4.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: sudo update-rc.d homecontrol defaults

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_v4.tar.gz
  • Extract it: tar xzvf homecontrol_v4.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.


Sensors

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

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.



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.


Starting/stopping

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


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
  • "-testEmailNotification":See here
  • "-sendCommand":See here


Troubleshooting

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


Back to main page


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