This page is part of archived documentation for openHAB 4.0. Go to the current stable version
# Bundle Management
The console offers various commands to manage bundles, among other things. Most of these commands are not needed in the normal (non-developer) use of openHAB. However some basic console commands may be needed when dealing with certain advanced user situations, such as when testing a newly developed or patched binding.
# List Bundles
The bundle:list command returns a list of all currently installed bundles and their states, names, and versions. The core openHAB system is composed of many bundles. There will also be a bundle for each add-on, such a binding, that you have installed. A state of "Active" means the bundle is running.
openhab> bundle:list
START LEVEL 100 , List Threshold: 50
ID | State | Lvl | Version | Name
-----------------------------------------------------------------------------------------------------
22 │ Active │ 80 │ 2.10.3 │ Jackson-annotations
23 │ Active │ 80 │ 2.10.3 │ Jackson-core
24 │ Active │ 80 │ 2.10.3 │ jackson-databind
25 │ Active │ 80 │ 2.10.3 │ Jackson-dataformat-YAML
26 │ Active │ 80 │ 2.10.3 │ Jackson datatype: JSR310
27 │ Active │ 80 │ 2.8.2.v20180104-1110 │ Gson: Google Json Library for Java
...
209 | Active | 80 | 3.0.0 | openHAB Add-ons :: Bundles :: Network Binding
# Start/Stop Bundles
Stopping a bundle is done using the command stop and the ID of the bundle:
openhab> bundle:stop 209
openhab> bundle:list
...
209 | Resolved | 80 | 3.0.0 | openHAB Add-ons :: Bundles :: Network Binding
Starting a bundle is done using the start command and the ID of the bundle:
openhab> bundle:start 209
openhab> bundle:list
...
209 | Active | 80 | 3.0.0 | openHAB Add-ons :: Bundles :: Network Binding
# Installing or Updating Bundles
The process depends on the reason why the bundle or from where the bundle is retrieved. Scenarios could be that a new version is not yet available via the currently running openHAB release but via a URI or via a file that would provide some already special required feature or a bug fix or just because that new version needs to be tested.
# Using bundle:install and bundle:update
A general introduction on how to install or uninstall a bundle via the UI can be found under Installation of Add-ons
Generally the approach with bundle:install / bundle:update is the recommended way to install/update bundles (this also works for core-bundles). The drawback is that updated bundles MAY revert to the originally installed version if another add-on is installed.
In case the bundle is available via a URI:
openhab> bundle:install https://github.com/myrepy/my-binding/raw/main/org.openhab.binding.my-3.4.0-SNAPSHOT.jar
openhab> bundle:list | grep My
303 | Active | 80 | 3.4.0 | openHAB Add-ons :: Bundles :: My Binding
openhab> bundle:update 303 https://github.com/myrepy/my-binding/raw/main/org.openhab.binding.my-3.4.1-SNAPSHOT.jar
In case the bundle is available on a file location, e.g. on the openHAB server (a reason could be that it was self-compiled by a developer and copied to the server), the "file:///" can be used within the URI. Make sure that file location is not within the addons-folder.
openhab>bundle:update 303 file:///localhost/srv/openhab-sys/org.openhab.binding.my-3.4.0-SNAPSHOT.jar
Note: using uninstall for a bundle will most probably NOT work, because all add-ons bundles are part of a feature and as long as the feature is installed, the bundle will likely be reinstalled.
# Installation via the addons-folder
If it’s just about add-ons, it’s also fine to uninstall it and then put the .jar in the addons-folder. A restart of openHAB is not required.
The procedure should be as follows:
- It is highly recommended to uninstall the bundle first (e.g. via the UI or bundle:uninstall) as it would otherwise lead to two bundles of the same type to be active at the same time where no one can clearly say what happens if two versions of the same bundle coexist.
- Wait until uninstall has completed,
- then drop the new file in the addons-folder
It is possible to run into problems in this case if the add-on depends on some non-standard feature (e.g. knx depends on the feature openhab-transport-serial). These features are automatically installed if you install an add-on (via UI or addons.cfg) and are also uninstalled if there is not add-on using it. If that is the case, it is necessary to install the feature manually with feature:install, e.g. openhab-transport-serial (preferred way) OR drop the required bundles in the addons-folder, too.
# Naming Convention For Bundles
Bundles are named according to the following convention:
<prefix>.<type>.<id>
where
- prefix is the first element to categorize the bundle.
For add-ons this is
org.openhab. - type is the add-on type, e.g. "binding", "persistence", or "ui"
- id is the identifier for this bundle
These bundle names are used in many places in openHAB, such as in various configuration files.
Logging also makes extensive use of this package namespace.
You can see these names listed as the Symbolic names of bundles by using the -s option of bundle:list:
openhab> bundle:list -s
ID | State | Lvl | Version | Symbolic name
----------------------------------------------------------------------------------------------
...
209 | Active | 80 | 3.0.0 | org.openhab.binding.network