Domotz Agent – Raspberry Pi

1.Getting started

This section contains a few tips and tricks on how to get started with the Domotz Agent on your Raspberry Pi. We’ll go through what you need to get going with a brand new Raspberry Pi, so if you already have Raspbian installed, you can skip straight to section 3. The Agent is compatible with all Raspberry Pi platforms to date, as of February 2016.

If you bought a Raspberry Pi or pre-configured memory card from Domotz, please proceed to section 4, after connecting your Raspberry Pi to a power adapter and your network.

Note that your Raspberry Pi needs to have a network interface of some kind, or the Domotz Agent won’t be able to detect the devices on your network.

2.Installing Raspbian

Installing the Domotz agent on your Raspberry Pi is a a lot more involved than installing it on a NAS, due to the fact that the Raspberry Pi needs to have an OS installed on it. First, there are some pre-requisites and we’ll take you through everything you need here if you’re starting from scratch.

In addition to your Raspberry Pi board you’ll need a micro SD card onto which you need to install an operating system. We’d recommend getting a Class 10 or faster memory card, as it’ll make the install quicker. Another option is to buy a ready made micro SD card from the Raspberry Pi foundation. If you bought one of these, then you can skip to section 3.

You’ll also need either a USB cable or a USB power adapter so you can power your Raspberry Pi, and ideally a screen of some kind with HDMI input, an HDMI cable, a mouse, a keyboard and a network cable.

Once you have the above things, let’s get the operating system installed. We’d recommend using NOOBS if you’re not familiar with Linux and you can download it from the Raspberry Pi foundation by going here – Click on NOOBS and download the “Offline and network install”.

The following guide explains how copy the files onto your micro SD card and how to install Raspbian – This is when that monitor or TV comes into play, as once you’ve prepared the micro SD card according to the instructions, you need to plug your Raspberry Pi into the monitor and connect a keyboard and a mouse to it. After a few seconds, you should see a screen that will ask you to install the OS, simply click on Raspbian followed by Install and the OS should be installed.

Once the installation is done and your Raspberry Pi has rebooted, you’ll see a setup screen. You can configure some options here and we’d recommend enabling to boot into the graphical user interface. Once you’re done, simply select Finish to boot into the Raspbian desktop environment.  Now you need to connect your Raspberry Pi to your network via a network cable, so we can continue with installing the Domotz Agent.

Note that if you don’t make any changes in the setup menu, you can start the graphical user interface by typing “startx” and hitting enter.

3.Installing the Domotz Agent

You’re now at the point where you need to download and install the Domotz Agent on your Raspberry Pi.

1. Make sure your Raspberry Pi is connected to the internet

We recommend to use a network cable and connect your Raspberry Pi directly to your router.

2. Download the latest Domotz Agent for Raspberry Pi

If you uses the built in web browser in Raspbian, go to the Domotz Community to download the latest Domotz Agent. The file should  automatically end up in the /usr/home/Downloads

If you have a headless setup (no screen, keyboard or mouse connected), you can login to your Raspberry Pi via SSH using a terminal software such as PuTTY or Tera Term in Windows, or the built in options in OS X or Linux. The default user name is pi and the password is raspberry. Then simply type the following commands to start the download:

cd Downloads

wget <file-path-as-specified-on-the-domotz-portal>

3. Install the Agent

Click on Menu, Accessories, Terminal. A command line window with some green and blue text should appear on the screen. In case of  headless installation, just login to your Raspberry Pi via a terminalGo to the download directory (if you’re not already there) by typing cd Downloads and hitting enter.

Type the following command to install the Domotz Agent. Note that in place of <package name> you need to type the name of the file you downloaded. As Raspbian is a Linux based OS, you can simply type the first couple of letters of the file name and then hit the tab key on your keyboard and the rest of the text will be automatically filled in for you.

sudo dpkg -i <package name>
Note: To list files in Linux, type ls and hit enter and you’ll see the files in the current directory.

The installer for the Domotz Agent should now be running. The installation will take anything between five and 15 minutes, as the installer is downloading parts of the software and installing it onto your memory card.

Once the installation has finished, the Agent will be automatically started and you’ll see a link that you can either double click to open in a browser, or copy and paste into your browser to continue the setup.

If you want to check that everything is working properly from the command line, you can run sudo /etc/init.d/domotz status to get a status message
If you want to uninstall your Domotz Agent, simply type sudo dpkg –purge domotz and hit enter in the terminal.

4.First time setup

The next step is to configure your Domotz Agent. To do so, make sure you’ve downloaded an installed the Domotz App on your mobile device. Then simply tap on the drawer menu button and tap on “Find New Agents” towards the bottom of the menu. This will automatically detect any new Domotz Agents on your network, as long as your mobile device is connected to the same network as your Domotz Agent. You can then proceed to configuring your Domotz Agent following the steps below on your mobile device without having to know the IP address of your Domotz Agent.

Alternatively, you can type in the IP address and port shown in the Domotz App in a web browser on your PC. For example, if the IP address was you type and then hit enter. You should now see the Domotz Agent webpage.

At this point, you’ll be asked to create an account if you don’t already have one. Please follow the on-screen instructions.

If you’re running any other web service on your Raspberry Pi that uses port 3000, the Domotz Agent will automatically use the next available port, i.e. 3001.




Once you’ve created your account, the Domotz Agent will proceed to scanning your network for devices. This will take anything from a few minutes up to 15 minutes depending on how many devices you have on your network.



This also means that it’ll take some time before all of your devices appears in the Domotz App on your smartphone or tablet. Once the scan has finished, click/tap Done to continue the to the Domotz Agent web UI.

Note that the setup of the Domotz Agent will fail if the time and date isn’t set correctly on your Raspberry Pi. To fix this, simply update the time and date on your Raspberry Pi and you’ll be able to proceed with the setup.

5.Agent web UI features

The Domotz Agent has its own web UI and although it has a limited scope of features right now, we are actively adding more more features to it. The sections below describe the functionality of the features available in the Agent web UI.

5.1.Agent Info

Agent Info

Once logged in to the web UI you’ll see a page called Agent Info. It should show the status of your Domotz Agent as active if everything is working properly. You’ll also see the name of your Agent here, as well as the time zone and location. There’s also an option to reset your agent here, but more on that below.


5.2.Network info

Network info

The Network Info tab displays some potentially handy information such as your public (internet facing) IP address, your network gateway, DNS and DHCP server.


5.3.Internet route analyzer

Internet route analyzer

The Internet route analyser allows you to send test packets to any website and measure packet loss in percent, as well as round-trip delays.


This can be useful to understand where bottlenecks and issues reside in communicating with an external web service. You can simply type in a website URL or an IP address to start the analysis, then select if you want to send 10, 20 or 50 packets. We’d recommend that you start with 10 packets. Once you’ve selected your options, simply click/tap on Start to start the test.

You’ll see a graphical representation of the route and once the test is finished, you’ll see how long it took and if there were any obvious issues in the router. You can click/tap on “See raw data” to get a full breakdown of the entire route. To start a new test, simply click/tap on Done and you’ll be taken back to the screen where you can enter a new URL or IP address.

This feature is based on MTR, a program that combines the functionality of traceroute and ping. It’s licenced under the terms of GNU General Public License Version 2 (

5.4.Internet speed test

Internet speed test

The Internet speed test allows you to perform upload/download speed tests from your Domotz Agent to the nearest perfSonar server.


The speed test is based on NDT (Network Diagnostic Tool) which provides a sophisticated speed and diagnostics test. It relies on perfSonar, a global, widely-deployed test and measurement infrastructure composed of thousands of servers maintained and used by science institutions around the world, of which many are available for public use as well.

To run a test, simply click/tap on Start and your Domotz Agent will automatically detect the nearest server and run the test.

Please note that the Raspberry Pi features a 10/100Mbps Ethernet port, so if you have an internet connection that exceeds 100Mbps, the speed test result will not be accurate.

You can find a list of perSonar test servers here:

For more information about perfSonar, please see:

For more information about NDT, please see:

NDT is copyright of the University of Chicago and is used by Domotz in accordance to the terms of the NDT licence (

5.5.Agent Reset

Agent Reset

If for some reason you’d like to wipe all the data off your Domotz Agent, you can do this via the Agent Reset button under Agent Info.


You’ll see a warning message and then be asked to confirm that you want to perform a reset.


Finally, you’ll have to enter your Domotz account email address and password to perform the reset.


Once done, you’ll be taken back the Domotz Agent login screen.

Suggest Edit