room-assistant

room-assistant is a simple Node.js server for tracking presence and other things on a per-room basis. It pairs well with the mqtt_room component of Home Assistant.

Upgrading from room-assistant 0.x? Please review the upgrade guide.

What can room-assistant do for you?

Motion sensors for home automation pose an issue: they require constant motion to stay activated. This will inevitably lead to a lot of frantic hand waving in front of the sensors when you're working on something and the light goes out. This piece of software can help you by scanning for Bluetooth tags in each room that it is placed in and estimating their distance. Just throw on a compatible beacon or smart watch and Home Assistant will always know where you are in your home. You can even customize the light settings or thermostat preferences based on who is in the room.

Additionally to the presence tracking room-assistant also comes with a few components to make your automations even smarter. It can handle GPIO components like motion sensors to augment your Bluetooth presence tracking and even execute shell commands for complete flexibility. A list of all the modules and their options is available in the wiki.

Installation

Running with NodeJS

Requirements

Please make sure you have a recent version of NodeJS installed, as the one provided by Raspbian is outdated. For room-assistant we recommend using:

NodeJS 8.0 or higher
npm 5.7.1 or higher

If you want to run any Bluetooth related components you will also need some additional packages:

sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev libusb-1.0-0-dev

Setting up

You can install room-assistant into a directory of your choice by cloning the git repository and installing the main dependencies:

git clone https://github.com/mKeRix/room-assistant.git
cd room-assistant
npm install --production

Once you have your configuration in place you can start the service manually:

npm start

Any additional dependencies of the services you selected will be downloaded before the software starts.

Making it a service

To make sure your room-assistant is always running you should setup a service for it. On newer systems this can be done easily using systemd. Create the file /etc/systemd/system/room-assistant.service with your favorite editor and fill it with the following data:

[Unit]
Description=Room Assistant service

[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/home/pi/room-assistant
Restart=always
RestartSec=10
User=pi

[Install]
WantedBy=multi-user.target

Save the file, then enable and start the service using the following commands:

sudo systemctl enable room-assistant.service
sudo systemctl start room-assistant.service

You can now check the service status by running:

systemctl status room-assistant.service

Updating

To update room-assistant you simply need to pull the new version from GitHub and update the dependencies:

git pull
npm install --production

Running with Docker

Currently two images are provided, a regular amd64 one and an arm32 based version. If you are running a Linux board like the Raspberry Pi you will most likely need the arm32 version. Find the available version tags on Docker Hub.

Configuration can be done by providing your container with the needed environment variables as described in the wiki examples.

Example amd64

docker run --network=host --restart=unless-stopped -d --name room-assistant -e SERVICES=ble,console mkerix/room-assistant

Example arm32, e.g. Raspberry Pi

docker run --network=host --restart=unless-stopped -d --name room-assistant -e SERVICES=ble,console mkerix/room-assistant:latest-arm32

Example docker-compose.yml

version: '2'
services:
  room-assistant:
    image: mkerix/room-assistant
    restart: always
    network_mode: host
    environment:
      SERVICES: 'ble,console'
      ROOM: 'docker-room'

Running with Hass.io

To run on Hass.io please add my addon repository to your installation as described. You should then be able to select room-assistant from the add-on store and configure it with the normal JSON based syntax.

Configuration

You can find detailed information about all available services and options in the wiki.

Troubleshooting

If you are running into issues, please consult the FAQ section and search through the issues before creating a new one.

idfxken/room-assistant