User Manual

BTicz Documentation

Full guide to installing, configuring and using the app.

What is BTicz

BTicz is a free, multi-platform app that lets you monitor and control your Domoticz home automation system straight from your phone, tablet or desktop — wherever you are.

The app connects directly to your Domoticz installation over your local network or the internet, with no cloud middleman, for better privacy and speed.

💡 Note: BTicz doesn't require an account, sign-up or subscription. It's completely free.

Requirements

Device

  • Android 8.0 (Oreo) or later
  • Linux (Ubuntu 20.04+, Debian 11+, Fedora 36+)
  • Windows 10 / 11 (64-bit)
  • iOS / macOS — coming soon

Domoticz

  • Domoticz version 2020.x or later
  • JSON API enabled (on by default)
  • Domoticz reachable from your device's network

Quick Start

Follow these steps to be up and running in under 5 minutes.

1

Download and install BTicz

Go to the Download page and grab the version for your operating system. Follow the platform-specific install instructions.

2

Open the app and go to Settings

On first launch, the app uses demo (mock) data. Open the side menu (☰) and go to Settings.

3

Add your Domoticz

In the Backend section, tap "Add Domoticz" and enter the IP address and port of your Domoticz server.

4

Test the connection and save

Press "Test Connection" to check that the details are correct, then save. BTicz will connect to your Domoticz automatically.

5

Explore your devices

Go back to Home to see your favourites, or open the Dashboard to see every device.

Android install

  1. Download the .apk file from the Download page.
  2. On your Android device, go to Settings → Security and enable Unknown sources (or Install unknown apps on newer versions).
  3. Open the downloaded APK from your file manager and follow the install prompts.
  4. Once installed, the app shows up in your app list.
⚠ Note: If Android shows a security warning, that's normal for apps not installed from the Play Store. BTicz doesn't contain malware.

Linux install

BTicz is distributed as a .tar.gz archive with an automatic install script.

💡 Headless server / Raspberry Pi: no browser? Download it straight over SSH with wget — add --content-disposition so wget picks up the real filename instead of naming it after the URL: 
# Download the archive (amd64/x64 — use ?f=linux-arm64 for Raspberry Pi / ARM servers)
wget --content-disposition "https://bticz.ballini.it/download.php?f=linux-x64"

# Extract it (the * matches whatever version you just downloaded) — this
# creates a folder with everything needed to install
tar -xf BTicz-v*-linux-x64.tar.gz
cd BTicz-v*-linux-x64

# Install (requires sudo)
sudo ./install-linux.sh

The install script is bundled inside the archive alongside the binary, icon and desktop entry — no separate download needed.

The script installs:

  • Binary → /usr/local/bin/BTicz
  • Icon → /usr/share/pixmaps/bticz.png
  • Menu entry → /usr/share/applications/BTicz.desktop

After installing, launch BTicz from your app menu or from a terminal with the BTicz command.

Uninstalling

sudo rm /usr/local/bin/BTicz
sudo rm /usr/share/pixmaps/bticz.png
sudo rm /usr/share/applications/BTicz.desktop

Windows install

BTicz for Windows is a standalone executable, no installer needed:

  1. Download the .zip file from the Download page.
  2. Extract the zip to a folder of your choice (e.g. C:\Program Files\BTicz\).
  3. Double-click BTicz.exe to launch the app.
  4. If Windows Defender SmartScreen shows a warning, click "More info" then "Run anyway".

Adding Domoticz

To connect BTicz to your Domoticz server:

  1. Open the side menu (☰ icon at the bottom left).
  2. Go to Settings.
  3. In the Backend section, tap "Add Domoticz".
  4. Fill in the form:
Field Description Example
NameDisplay name for the connectionHome
Host / IPIP address or hostname of the Domoticz server192.168.1.100
PortDomoticz's listening port8080
UsernameUsername (if authentication is enabled)admin
PasswordPassword (if authentication is enabled)—
💡 Tip: Use the "Test Connection" button before saving to make sure the details are correct.

Once saved, the backend shows up in the list. It's automatically set as active if it's the first one you configure.

SSL/HTTPS connection

If your Domoticz is set up with HTTPS (recommended for remote access):

  • Enable "Use HTTPS/SSL" in the configuration form.
  • If you use a self-signed certificate, also enable "Ignore certificate verification".
  • The typical HTTPS port is 443 or 8443.
⚠ Warning: Disabling certificate verification reduces security. Only use it on trusted local networks with self-signed certificates.

General settings

Available from Menu → Settings → General section:

  • Language — English or Italian. Requires an app restart.
  • Theme — Light, Dark, or follow the system.
  • Refresh interval — how often the app reloads data (in seconds).
  • Card size — Normal (3 per row) or Large (2 per row) on mobile.
  • Check for updates — automatic daily check for new versions, see Update checks below.

Update checks

Once a day, BTicz checks in the background whether a newer version is available. If one is found, a dialog shows the new version number, its release date and a short changelog — dismiss it to keep using your current version, or tap "See what's new" to open the download page.

You can control this from Menu → Settings → General section:

  • Check for updates automatically — turn this off if you don't want the daily background check (e.g. on a metered connection).
  • Check now — runs a check immediately, regardless of the toggle above or when the last automatic check happened.
💡 The automatic check fails silently if you're offline — it never shows an error or interrupts what you're doing, and simply tries again on the next launch.

BTicz uses a collapsible side menu:

  • Tap the ☰ (hamburger) icon at the bottom left to open or close it.
  • Menu items take you to the app's different sections.
  • The Refresh button in the footer reloads the current page's data.

Home — Favourites

The Home page shows the devices you've marked as favourites in Domoticz. It's the fastest way to reach the devices you use the most.

💡 To add a device to your favourites, do it from the Domoticz web interface. The app picks it up automatically.

Dashboard

The Dashboard shows every device in your Domoticz, grouped by type. You can scroll through the list and interact with each device.

Switches

The Switches page filters just the switch, light and actuator devices. For each device you can:

  • Turn it on/off — tap the button on the card.
  • See its state — On/Off with a colour indicator.
  • Open its history — tap the chart icon.

Temperatures & sensors

The Temperatures page shows all your temperature, humidity and other environmental sensors. Values refresh according to the configured interval.

Alarm panel

If your Domoticz has an alarm panel configured, you can manage it from BTicz. The alarm dialog lets you:

  • Arm Home — arms the outer perimeter.
  • Arm Away — arms the whole system.
  • Disarm — turns the alarm off.

Sensitive actions require entering your PIN code.

💡 While the panel is armed (Home or Away) or in alert, any device that changes state has its status text highlighted in that device's accent colour — a quick way to spot what triggered or changed after you armed the system. It clears automatically the next time you arm or disarm.
⚠ Android tip: if the on-screen keyboard is open when you tap Arm/Disarm, the first tap may only close the keyboard — a known Android quirk, not a malfunction. Tap the button again to actually send the command.

Device history

For any device, tap the chart icon (📈) on its card to open its event history. History shows the most recent events or values recorded by Domoticz.

FAQ — Frequently asked questions

The app won't connect to Domoticz. What do I do?

Check that:

  • The IP and port are correct (try opening http://<IP>:<port> in your browser).
  • The device running BTicz and the Domoticz server are on the same network.
  • Domoticz's or your router's firewall isn't blocking the port.
  • If you use SSL, that the certificate is valid or "Ignore verification" is enabled.

I don't see my favourite devices on Home

Favourites are synced from Domoticz. Make sure you've marked at least one device as a favourite from the Domoticz web interface, then tap Refresh in the app.

How do I change the language?

Go to Settings → General → Language, pick the language you want and save. The app will ask you to restart to apply the change.

Does the beta version expire?

Yes, the beta version has an expiry date. You'll get a warning a few days before it expires. Keep the app up to date by downloading new releases from the Download page.

How do I know if a new version is available?

BTicz checks automatically once a day and shows a dialog when it finds an update. You can also check manually anytime from Settings → General → Check now. See Update checks for details.

Is my configuration data (password) safe?

Yes. Credentials are stored securely in the operating system's keystore (Android Keystore on Android, protected credential storage on desktop). They're never sent to any external server.

Troubleshooting

White screen or app won't start (Linux)

Check that you have the OpenGL drivers installed. On Debian/Ubuntu:

sudo apt install libgl1-mesa-dri libgl1-mesa-glx

"Invalid SSL certificate" error

You have two options:

  • Use a valid certificate (e.g. Let's Encrypt) on your Domoticz.
  • In BTicz's backend configuration, enable "Ignore SSL certificate verification".

The app is slow to refresh data

Check the Refresh interval setting in General Settings. A low value (e.g. 5 seconds) reloads data more often, but uses more battery.

Contact and support

Couldn't find an answer to your issue? Get in touch:

💡 Always include the app version, your operating system, and a description of the issue in your message. It helps us respond faster.
Next → Download page