openHAB Core is a framework of OSGi bundles, not the product you install

A framework that a distribution picks up

openHAB Core contains the core bundles of the openHAB runtime, and the second paragraph of the readme is the one that tells you what the repository is for.

Please note that openHAB Core is not a product itself, but a framework to build solutions on top. It is picked up by the main openHAB distribution, which means that what you build is primarily an artifact repository of OSGi bundles that can be used within smart home products.

So the relationship is a dependency inversion. The thing most people install, the openHAB distribution, is assembled from the artefacts this repository produces. If you want an openHAB installation, this is the wrong repository. If you want to build a product that embeds the openHAB runtime, or a bundle that runs inside it, this is exactly the right one.

The OSGi framing is the other important detail, and it explains the shape of the code. OSGi is a module system for the JVM, where a runtime resolves bundles at runtime rather than at build time. That is what makes a smart home platform able to add a device driver without rebuilding the whole thing, and it is why the repository produces a set of bundles rather than a single artefact.

The implementation is Java, the licence is EPL-2.0, the project is at openhab.org, and the last push was on 2026-10-19. There are no GitHub releases, since the artefacts are published to a Maven repository rather than tagged in git.

Java 21 and Maven, and nothing else

The build infrastructure is based on Maven, and the readme is unusually relaxed about it. If you know Maven already then there will not be any surprises for you, and if you have not worked with Maven yet, just follow the instructions and everything will miraculously work.

The requirements are two lines. Java SE Development Kit 21, and Maven 3, with a link to the download page. And you should make sure that the mvn command is available on your path.

The checkout step is the standard one.

git clone https://github.com/openhab/openhab-core.git

That is the whole setup, and it is short enough to be worth reading carefully for what it implies. There is no separate toolchain to install, no native library to build, and no code generation step to run before the build. For a project of this size, that is unusual, and it is a consequence of the OSGi model: the bundles are plain Java that Maven compiles and publishes.

The one thing that is not in the repository is the version of the platform the bundles target, because that is negotiated with the rest of the openHAB ecosystem through the Maven repository, and the directory listing shows a bom/ directory, which is the usual Maven way of publishing a bill of materials so that consumers align their dependency versions.

The build, and the three ways to make it faster

The build section gives the normal command and then three progressively more aggressive alternatives, and reading them together tells you what the CI does and what a developer does under time pressure.

The normal path is to set MAVEN_OPTS to -Xms512m -Xmx1024m, change into the openhab-core directory, and run the following to compile and package all sources.

mvn clean spotless:apply install

The spotless:apply step is the interesting one, and it is not optional in that command. Spotless is a code formatter integrated into the build, and applying it before the build means the code is formatted as part of your local loop rather than failing a check later. The install goal then puts the artefacts in your local Maven repository, which is how a dependent project picks them up.

The first alternative is for flaky local failures. If there are tests that are failing occasionally on your local build, run this instead to skip them.

mvn -DskipTests=true clean install

The second is the fast one.

mvn clean install -T1C -DskipChecks -DskipTests -Dspotless.check.skip=true

The -T1C flag tells Maven to build with one thread per processor core, which is the parallelism the build is designed for, and the three property flags turn off the checks, the tests and the formatting verification respectively.

So the trade is explicit. The full command formats and tests. The quick command does neither and finishes in a fraction of the time, at the cost of the exact things that catch a mistake before it reaches a pull request. For a developer iterating on one bundle that is a reasonable trade, and it is not a reasonable trade for the build that produces a release.

The repository layout is a Maven multi-module project

The top level listing describes a conventional Maven reactor with a few additions.

There is pom.xml at the root, which is the parent POM, with .mvn/ for the Maven wrapper configuration, and mvnw and mvnw.cmd for the wrapper launchers. There is a bundles/ directory, which is the bulk of the code, and it is where the OSGi bundles live.

Then there are the parts that make it a platform rather than a library. The features/ directory holds the feature definitions, which in OSGi terms is how you declare a set of bundles and their dependencies as a single installable unit, and it is how the runtime knows what to load at startup. The itests/ directory holds the integration tests, which is a separate suite from the unit tests because an OSGi runtime resolving bundles at runtime is exactly the kind of behaviour that unit tests cannot check. The bom/ directory is the bill of materials, and there is a tools/ directory for the build tooling itself.

The rest of the files are governance. There is a CODEOWNERS file, which tells the review tooling who owns which path, a CONTRIBUTING.md, a NOTICE file alongside the LICENSE for the EPL-2.0 terms, and a crowdin.yml for the translations.

That last one is worth a sentence. A framework whose user facing strings are translated through Crowdin is a framework whose users are international, and a large part of the work of running a home automation platform is the text in the UI and the logs.

Two CI systems, a JavaDoc build and a translation workflow

The badges at the top of the readme describe four separate pipelines, and each one exists for a reason.

There is a GitHub Actions build status for the ci-build workflow on the main branch, and a Jenkins build status for the openHAB-Core job on ci.openhab.org. Running both is unusual, and it is a transitional arrangement rather than a redundancy: the Jenkins instance is the long standing build server with history and the GitHub Actions workflow is where newer work is landing.

There is a separate JavaDoc build status, which is a build in its own right. For a framework whose public API is consumed by people writing bundles, the API documentation is a deliverable, not a byproduct, and having its own pipeline means a broken Javadoc comment can be caught.

And there is a Crowdin badge for the localised strings, pointing at the project on Crowdin. The file that configures it is crowdin.yml at the root of the repository, and it is the marker that the translation workflow is wired into the build.

The EPL-2.0 licence badge sits among them, and the licence text is the EPL-2.0, which is a good fit for a framework of this kind: it is permissive enough to be embedded in a commercial product and it has the file level copyleft that keeps modifications to the bundles open.

Contributing means reading two documents first

The contributing section is four lines and it points at two documents on the openHAB site, one about contributing and one about guidelines.

If you want to become a contributor to the project, please read about contributing and check the guidelines first.

It is worth noting that the repository itself does not contain the substantive guidance. The contributing guide and the guidelines live on the project website, which means the rules for a pull request here are maintained in a different place from the code they apply to, and a new contributor has to be told where to look rather than finding it in a CONTRIBUTING.md.

That is a small thing, and it is not criticism. The project has a CONTRIBUTING.md file in the repository as well, and the repository root has a CODEOWNERS file, which is the mechanism for routing a change to the right reviewer.

So the practical picture of the project is a framework repository that publishes OSGi bundles to a Maven repository, built with Maven against Java 21, tested with unit and integration suites, documented with JavaDoc, translated through Crowdin and built on two CI systems, with a defined place in the wider openHAB distribution for whoever wants to ship it inside a product.

That is what the readme means when it says the project is a framework to build solutions on top.

Editorial conclusion

Adopt openhab-core if you are building a smart home product that embeds the openHAB runtime, because it is the framework layer and the artifact repository the distribution consumes. Do not clone it expecting to run an openHAB installation, because the readme states plainly that the project is not a product itself and is picked up by the main openHAB distribution. Verify first that you have Java 21 and Maven 3, and that you understand what the three build escape hatches skip, since the fast build turns off the checks, the tests and the formatting verification in one command.

Frequently asked questions

Official sources

1. Issues
2. License: EPL-2.0
3. openhab/openhab-core on GitHub
4. Project website
5. README