# Upgrade Process
Stop room-assistant on the machine, then run
sudo npm i --global --unsafe-perm room-assistant to download and install the latest version.
If you're using images with specific version tags you can just exchange the tag with the new version. For
beta you need to pull the image again to retrieve the latest version. Then just recreate your container with the latest image version - e.g. with docker-compose
docker-compose stop && docker-compose up.
# Home Assistant OS
Upgrade the room-assistant add-on from the Supervisor Add-on Store panel. Note that the Home Assistant OS release is slightly delayed to the other releases and may not immediately be visible.
# Major Upgrades
# 0.x or 1.x to 2.x
room-assistant 2.0 is another rewrite of the software to bring it up-to-par with current standards and keep it maintainable. Due to this, many things have changed although all core functionality has been kept. A fresh installation of room-assistant is recommended.
# Installation process
The installation process has changed and is not git-based anymore when running room-assistant directly with NodeJS. Instead, you now need to install the room-assistant binary directly with npm. See the installation guide for detailed information. You can delete the old cloned folder - but keep a copy of your old config for reference.
For Docker-based installations note that on Linux systems you should also mount the
/var/run/dbus folder into the container now to make use of the auto-discovery features.
The Home Assistant OS addon has changed its ID from
room_assistant to comply with the standard and therefore needs to be reinstalled as a different add-on.
Instead of installing dependencies when starting, room-assistant now just tries to install everything right away. This makes the start much quicker and less confusing. Integration-specific dependencies are marked as optional - they may fail to install initially. Make sure you fulfill the documented requirements and then run the installation command once more to get missing dependencies.
# Config format
You can still use JSON as your config format like you did before, however YAML is now also accepted and the preferred method. The config is loaded from
<working-dir>/config. For Docker you can either choose to mount config files into
/room-assistant/config or fill the
NODE_CONFIG environment variable with your config in JSON format. Individual environment variables for the options have been removed.
Note that the layout of the config has changed, even if the naming is similar. It is recommended that you just start a fresh configuration file and copy the previous values over while consulting the configuration and integration documentation.
# 1.0.x to 1.1.x
npm install to get the latest versions of the dependencies.
If you used the gpio or shell service:
In room-assistant 1.1.x we integrated the MQTT auto discovery feature. If you do not want to use this you do not need to change anything.
If you do, please restructure the configuration of your room-assistant AND Home Assistant Core instances to support this feature.
If you used the prometheus service:
The api service is not needed anymore and was removed. You should remove it from your configured list of services as well. Furthermore you need to rename the
api setting in JSON to
prometheus. If you use Docker you need to rename the
API_PORT environment variable to
PROMETHEUS_PORT. Note that the default port changed to
3030, as documented here (opens new window).
# 0.x.x to 1.0.x
Version 1.0 of room-assistant was rewritten from scratch to achieve a cleaner and more stable codebase. This means that there are a few breaking changes you should take care of when upgrading. Please work through the sections applicable to your setup.
After downloading the newest codebase with
git pull remove the
node_modules directory completely to get a clean start. Also make sure that your current setup is ideally NodeJS 8 or higher and npm 5.7.1 or higher and run upgrades for those if needed. Then you can run
npm install --production to get the new base dependencies. The service specific components will be installed on startup now.
You will have to redo your configuration (opens new window) as the schema changed slightly. For Docker installations you may also use the new options for configuring via environment variables now.
Start by backing up your current configuration and making a copy of
config/default.json as your new
config/local.json (or use the environment variable syntax). You will need to change two main variables:
servicesshould be an array of service IDs that had
enabled: truein your previous configuration
roomis equivalent to the old
Support for the
unsafe mode and
logging to the filesystem has been removed.
The MQTT component remains unchanged, except for the removal of
topic in favor of the above described setting
Console output does not have its own configuration settings anymore and just needs to be enabled in
# Bluetooth Low Energy and iBeacons
The BLE and iBeacon components have been merged into one. The configuration options have been changed accordingly:
use_macis now called
max_distanceis now called
update_frequencyis now called
updateFrequencyand measured in seconds instead of milliseconds
blacklisthas been removed in favor of just a
processIBeaconnow determines whether iBeacon advertisement data should be processed or ignored, set to
falseif previously only using the BLE component
onlyIBeaconnow determines whether only iBeacons should be published, set to
trueif previously only using the iBeacon component
system_noisehas been removed
measurement_noisehas been removed
# Temper USB Sensors
Support for Temper sensors has been removed. If this is an issue for you, please open a new issue on Github.
The GPIO component has been changed to watch for changes instead of polling for them. The options are also now provided in array form and can all be changed for each device. What you previously had configured under
gpio.ports should now be the content for
gpio directly. Specifically this means:
portis now called
pinand references to the BCM number (opens new window) instead
retaincan now be set for each pin
intervalhas been removed, as the component now watches for changes instead of polling
only_send_updateshas been removed and is now default behavior
qoshas been removed
The shell component is largely the same, but has also been adapted to make all options available per command. You should move the contents of
shell.commands directly to
shell. More specifically the options were changed as follows:
intervalhas been removed in favor of
cron, a cron pattern (opens new window) with accuracy up to seconds determining the execution pattern - if your
60000your cron setting should now be
0 * * * * *
floatis now called
retaincan now be set for each command separately
qoshas been removed