Skip to content

AGENTS.md

Latest commit

 

History

History
171 lines (125 loc) · 6.56 KB

AGENTS.md

File metadata and controls

171 lines (125 loc) · 6.56 KB

AGENTS.md - openHAB Add-ons Development Guide

Overview

This repository contains the add-ons for the openHAB smart-home project, featuring approximately 500 different extensions located in the bundles folder.

Key Resources:

Project Structure

repo root folder
├── bundles/           # ~500 different extensions
├── itests/           # Integration tests
├── CODEOWNERS        # Maintainer assignments
└── ...

Important: This add-ons repository depends on the openhab-core repository, which defines the base system and APIs.

Development Standards

Java Version

  • Target: Java 21
  • Use modern language features, but stay within Java 21 bounds
  • Avoid preview features or experimental APIs

Code Style & Documentation

Comments and Documentation

Import Organization

  • Sort imports alphabetically
  • Group imports logically (standard library, third-party, openHAB)

Formatting

  • Use mvn spotless:apply to fix formatting issues
  • POM sections should be sorted

Key Concepts to Understand

Before developing, familiarize yourself with these core openHAB concepts:

File-Specific Guidelines

pom.xml Files

When upgrading Maven dependencies:

  1. Check version consistency across:

    • features.xml files for hardcoded version numbers
    • *.bndrun files for hardcoded version numbers

  2. After updates:

    • Run mvn spotless:apply to fix formatting
    • Consider running full Maven build with -DwithResolver option

*.bndrun Files

OH-INF/i18n/*_xx.properties

AGENTS.md

There might be AGENTS.md files in subfolders. Consider them when files from that binding are open in the editor:

  • bundles/org.openhab.*/AGENTS.md

CODEOWNERS File

  • Located at repository root
  • Maps GitHub usernames to binding responsibilities
  • Automatically updated by binding creation scripts
  • Format: path/to/binding @github-username

Creating New Bindings

Prerequisites

  1. Read the binding development guide: https://www.openhab.org/docs/developer/#develop-a-new-binding
  2. Choose a unique binding name following naming conventions

Naming Conventions

  • Binding Name: Must be CamelCase matching pattern [A-Z][A-Za-z]*
  • GitHub Username: Must match pattern [a-z0-9]*
  • Author Name: Can contain spaces (use quotes when scripting)

Declare Connnection

Creation Process

Important: Run all the following commands from repo root folder.

Check the documentation for how to create new bindings: https://www.openhab.org/docs/developer/#develop-a-new-binding

Ask the user to name the binding and use the supplied name. It needs to be in CamelCase and match [A-Z][A-Za-z]*.

Make sure that bindings/org.openhab.binding. does not exist.

Do not create folder contents on your own. Run the script create_openhab_binding_skeleton at project root directory with sh or powershell to create. authorname needs to be in "" as it can contain spaces. githubusername is [a-z0-9]*. The authorname may be deduced from git config.

Run mvn spotless:apply in the new folder. Make sure you don't run this at top directory but in the binding folder to avoid long runtime.

Important Notes

  • Never create binding folders manually - always use the provided scripts
  • The creation script will automatically update the CODEOWNERS file
  • Author names containing spaces must be quoted in script parameters

Testing

Integration Tests

  • Located in itests/ directory
  • Use bndrun configurations to define test environments
  • Test against realistic OSGi runtime scenarios

Build Validation

# Format code
mvn spotless:apply

# Run tests with dependency resolution
mvn clean install -DwithResolver

# Build and run tests for a single specific binding
mvn clean install -pl org.openhab.binding.bindingname

After building, the directory target inside org.openhab.binding.bindingname contains several test reports.

  • target/code_analysis/report.html for results of the static code analysis
  • target/site/jacoco/index.html contains code coverage (only if available for a specific binding)

Common Pitfalls

  1. Dependency Management: Always check features.xml and *.bndrun files when updating dependencies
  2. Manual Creation: Don't create binding structures manually - use the skeleton scripts
  3. Import Order: Unsorted imports will fail style checks
  4. Java Version: Stay within Java 21 - newer features will break CI/CD

Getting Help

Quick Reference

Task Command
Format code mvn spotless:apply
Create binding sh create_openhab_binding_skeleton.sh
Full build mvn clean install
Build with resolver mvn clean install -DwithResolver
Build a specific binding mvn clean install -pl org.openhab.binding.bindingname