Skip to content

# Initial Configuration

Now that we have terminology covered, let's do some initial configuration and get our first home automation gateway/hub connected.

## Reactor Configuration Files

Reactor configuration files can either be JSON or YAML formatted data. In most cases where humans are expected to routinely read or edit the data, YAML is the selected default. I won't go into the details of their format here, as there are plenty of good tutorials on the Internet. While you're getting the feel for them, though, it's easy to "break" them and make them unreadable/unusable, so be sure to make backup copies as you work. The other important thing to keep in mind is don't use tabs. Indenting in YAML must be done with spaces, and indentation is part of document structure, not just disposable whitespace.

User configuration files are located in the `config` subdirectory. These are the only configuration files that you should edit. The system's configuration mechanism provides for overrides and extensions to system configuration by editing or adding files here, rather than editing system files wherever they may live. This helps ensure that site-specific configurations are preserved in upgrades.

Tip

The distribution (default) versions of the configuration files can be found in the `dist-config` subdirectory. If you run into formatting trouble, you can use these as a reference, or start over by copying the generic/distribution version into `config`.

The "main" Reactor configuration file is called `reactor.yaml`. You will do most of your configuration work in this file, but there are currently two notable exceptions: `notification.yaml` in which you configure your notification methods (for the Notify action), and `logging.yaml` in which you can raise or lower the log levels for system facilities (this is often needed when troubleshooting).

Plain Text Editors Only!

It is vital that you only use a plain text editor to edit your configuration files. Using tools such as Word or LibreOffice Writer will get you into trouble very quickly. Appropriate editors for Linux include `vi`, `emacs` and `nano` (for text sessions), or Geany, Eclipse, or Sublime in a desktop GUI (to name a few; not an exhaustive list). For Windows, Notepad++ is recommended; the included NotePad or the ancient WordPad should not be used. Also, if you are on Windows editing a Linux file via a network share, be aware that Windows and Linux have different line endings (Windows is CR/LF while Linux uses LF alone), and this may make files unreadable as well. You will need to "train" your editor to use the proper line endings for Linux if that is where Reactor is running (Notepad++ can do this).

## Configuring the System Units

By default, Reactor will show US imperial measurement units for all values. If you'd like to change the measurement system, you can edit `reactor.yaml` (in the `config` subdirectory) and change the `units` line in the `reactor` section. Currently supported values are `imperial`, `metric` and `uk` (for Great Britain's particular mix of both systems).

If you'd like to individually override the units for particular uses, there is some additional granularity of control available that won't be covered here. See Configuring System Units for those details.

## Configuring Your First HA Gateway/Hub

When first installed, Reactor does not know of any home automation controllers or other devices. To begin, let's make a few more changes to the global system configuration and then set up the first gateway/hub:

1. Open the file `reactor.yaml` in the plain-text editor of your choice;
2. In the `reactor` section, find the `baseurl` entry, and make sure the IP address in the URL is the main address of your host system; edit if/as needed;
3. Edit the `location` fields and set sensible values for your location. If you are outside the US, comment out the `state` field and uncomment the `province` field, if needed;
4. In the `controllers` section of the file, you will find an example/skeleton configuration for each of the available Home Automation controllers/hubs currently supported, as well as the default controllers for system and weather data. Find the entry that matches the HA controller you will first use with Reactor, and modify the IP address in the `source` key of that entry. Then change the `enabled` key to `true`. If your controller requires an access token or other authentication data and you don't know how/where that is found, refer to the section in Controller Configuration that applies to your controller;
5. Restart Reactor:
   - If Reactor is running in the foreground of your terminal window (e.g. still in trial mode from installation), press `Ctrl`+`C` once and wait for it to stop. Then type `node app.js` to start it again in trial mode.
   - Use the "Restart Reactor" button under "Tools" in Reactor's UI.
   - If Reactor is running under `systemd` as a Linux service: `sudo systemctl restart reactor`
   - If you are using a Docker container-ized Reactor, restart the container as you would any other.
6. Open a browser and go to the `baseurl` URL you specified in step 2. This should immediately open the Reactor UI. If you already have a browser open on the UI, refresh the page.

Browse the Entities list and see what Reactor has discovered automatically about your controller's devices. Don't worry if some devices are missing or seem to have incomplete capabilities, attributes or actions. These things can be tuned later.

Migrating from Vera

If you are a user of Reactor for Vera, you can import your existing ReactorSensor logic into Reactor.

Updated 2021-Oct-13