Configuration

Description

Configuration is done through config.yml The parent folder of the file can be specified with -c PATH or --config PATH. If nothing is specified the file config.yml is searched in the subdirectory HABApp in

• the current working directory

• the venv directory

• the user home

If the config does not yet exist in the folder a blank configuration will be created

Example

directories:
    logging: log    # If the filename for the logfile in logging.yml is not absolute it will be placed in this directory
    rules: rules    # All *.py files in this folder (and subfolders) will be loaded. Load order will be alphabetical by path.
    params: params  # Optional, this is the folder where the parameter files will be created and loaded from
    config: config  # Folder from which configuration files for openHAB will be loaded
    lib: lib        # Custom modules, libraries and files can be placed there.
                    # (!) Attention (!):
                    # Don't create rule instances in files inside the lib folder! It will lead to strange behaviour.


# Specify the location where your HABApp instance is running
location:
    # The coordinates are used to calculate the Sunrise/Sunset etc
    latitude: 0.0
    longitude: 0.0
    elevation: 0.0
    # The country and optional subdivision is used to calculate the holidays
    country: DE       # ISO 3166-1 Alpha-2 country code - here Germany
    subdivision: BE   # ISO 3166-2 Subdivision code or alias - here Berlin


openhab:
    ping:
        enabled: true        # If enabled the configured item will show how long it takes to send an update from HABApp
                             # and get the updated value back in milliseconds
        item: 'HABApp_Ping'  # Name of the NumberItem that will show the ping
        interval: 10         # Seconds between two pings

    connection:
        url: http://localhost:8080
        user: ''
        password: ''

    general:
        listen_only: False  # If True  HABApp will not change any value on the openHAB instance.
                            # Useful for testing rules from another machine.
        wait_for_openhab: True   # If True HABApp will wait for items from the openHAB instance
                                 # before loading any rules on startup


mqtt:
    connection:
        identifier: HABApp
        host: ''
        port: 8883
        user: ''
        password: ''
        tls:
          enabled: false   # Enable TLS for the connection
          insecure: false  # Validate server hostname in server certificate
          ca cert: ''      # Path to a CA certificate that will be treated as trusted
                           # (e.g. when using a self signed certificate)

    subscribe:         # Changes to Subscribe get picked up without restarting HABApp
        qos: 0         # Default QoS for subscribing
        topics:
        - '#'               # Subscribe to this topic, qos is default QoS
        - ['my/topic', 1]   # Subscribe to this topic with explicit QoS

    publish:
        qos: 0          # Default QoS when publishing values
        retain: false   # Default retain flag when publishing values

    general:
        listen_only: False # If True  HABApp will not publish any value to the broker.
                           # Useful for testing rules from another machine.

It’s possible to use environment variables and files (e.g. docker secrets) in the configuration. See the easyconfig documentation for the exact syntax and examples.

Configuration Reference

All possible configuration options are described here. Not all entries are created by default in the config file and one should take extra care when changing those entries.

settings ApplicationConfig

Structure that contains the complete configuration

field directories: DirectoriesConfig [Optional]

field habapp: HABAppConfig [Optional]

field location: LocationConfig [Optional]

field mqtt: MqttConfig [Optional]

field openhab: OpenhabConfig [Optional]

Directories

settings DirectoriesConfig

Configuration of directories that are used

field config: Path | None = 'config'

Folder from which configuration files (e.g. for textual thing configuration) will be loaded

field lib: Path | None = 'lib'

Folder where additional libraries can be placed

field logging: Path = 'log'

Folder where the logs will be written to

field params: Path | None = 'params'

Folder from which the parameter files will be loaded

field rules: Path = 'rules'

Folder from which the rule files will be loaded

Location

settings LocationConfig

location where the instance is running. Is used to calculate Sunrise/Sunset and holidays.

field country: str = ''

ISO 3166-1 Alpha-2 country code

field elevation: float = 0.0

field latitude: float = 0.0

field longitude: float = 0.0

field subdivision: str = ''

The subdivision (e.g. state or province) as a ISO 3166-2 code or its alias

MQTT

settings MqttConfig

MQTT configuration

field connection: Connection [Optional]

field general: General [Optional]

field publish: Publish [Optional]

field subscribe: Subscribe [Optional]

Connection

settings Connection

field host: str = ''

Connect to this host. Empty string (“”) disables the connection.

field identifier: str = 'HABApp-yiCuZsugllmxs'

Identifier that is used to uniquely identify this client on the mqtt broker.

field password: str = ''

field port: int = 1883

field tls: TLSSettings [Optional]

field user: str = ''

TLS

settings TLSSettings

field ca cert: Path = ''

Path to a CA certificate that will be treated as trusted

field enabled: bool = True

Enable TLS for the connection

field insecure: bool = False

Validate server hostname in server certificate

Subscribe

settings Subscribe

field qos: Literal[0, 1, 2] = 0

Default QoS for subscribing

field topics: tuple[str | tuple[str, Literal[0, 1, 2]], ...] = ('#', 'topic/with/default/qos', ('topic/with/qos', 1))

get_topic_qos()

Return type:

Generator[tuple[str, Literal[0, 1, 2]], None, None]

Publish

settings Publish

field qos: Literal[0, 1, 2] = 0

Default QoS when publishing values

field retain: bool = False

Default retain flag when publishing values

General

settings General

field listen_only: bool = False

If True HABApp does not publish any value to the broker

Openhab

settings OpenhabConfig

field connection: Connection [Optional]

field general: General [Optional]

field ping: Ping [Optional]

Connection

settings Connection

field password: str = ''

field url: str = 'http://localhost:8080'

Connect to this url. Empty string (“”) disables the connection.

field user: str = ''

field verify_ssl: bool = True

Check certificates when using https

field websocket: Websocket [Optional]

Options for the websocket connection which is usedto connect to the openHAB event bus.

settings Websocket

field event filter: WebsocketEventFilter [Optional]

Configuration of server side event filters which will be applied to the websocket connection.

field maximum message size: ByteSize = '4Mib'

Maximum message size for a websocket message. Increase only if you get error messages or disconnects e.g. if you use large images.

field ping interval: int | float = 7

Interval for ping messages in seconds

Constraints:

• gt = 0

settings WebsocketEventFilter

field type: EventTypeFilterEnum = EventTypeFilterEnum.AUTO

Configure the event type filter. “OFF” to allow all events, “AUTO” to allow the recommended events or “CONFIG” to use the event types from the “types allowed” field.

field types allowed: tuple[str, ...] = ()

List of event types that will be allowed

Ping

settings Ping

field enabled: bool = True

If enabled the configured item will show how long it takes to send an update from HABApp and get the updated value back from openHAB in milliseconds

field interval: int | float = 10

Seconds between two pings

Constraints:

• ge = 0.1

field item: str = 'HABApp_Ping'

Name of the Numberitem

General

settings General

field listen_only: bool = False

If True HABApp does not change anything on the openHAB instance.

field min_start_level: int = 70

Minimum openHAB start level to load items and listen to events

Constraints:

• ge = 0

• le = 100

field min_uptime: int = 60

Minimum openHAB uptime in seconds to load items and listen to events

Constraints:

• ge = 0

• le = 7200

field wait_for_openhab: bool = True

If True HABApp will wait for a successful openHAB connection before loading any rules on startup

HABApp

settings HABAppConfig

HABApp internal configuration. Only change values if you know what you are doing!

field debug: DebugConfig [Optional]

field logging: LoggingConfig [Optional]

field thread pool: ThreadPoolConfig [Optional]

ThreadPool

settings ThreadPoolConfig

field enabled: bool = True

When the thread pool is disabled HABApp will become an asyncio application. Use only if you have experience developing asyncio applications! If the thread pool is disabled using blocking calls in functions can and will break HABApp

field threads: Annotated[int] = 10

Amount of threads to use for the executor

Constraints:

• ge = 1

• le = 32

Logging

settings LoggingConfig

field flush every: float = 0.5

Wait time in seconds before the buffer gets flushed again when it was empty

Constraints:

• ge = 0.1

field use buffer: bool = True

Automatically inject a buffer for the event log

Debug

settings DebugConfig

Debugging options for HABApp

field periodic traceback: PeriodicTracebackDumpConfig [Optional]

field traceback on shutdown signal: bool = False

Dump the traceback of all currently running threads into a file when receiving a shutdown signal. Not available on Windows!

field watch event loop: WatchEventLoopConfig [Optional]

settings PeriodicTracebackDumpConfig

Periodically dump the traceback of all currently running threads into a file

field delay: timedelta = 'PT30M'

Initial delay before the first traceback dump

Constraints:

• gt = 0:00:00

field enabled: bool = False

Enable or disable functionality

field interval: timedelta = 'PT1H'

Interval to dump the traceback

Constraints:

• gt = 0:00:00

settings WatchEventLoopConfig

Watch the asyncio event loop. If the loop is blocked dump the traceback of all running threads and shut down HABApp

field enabled: bool = False

Enable or disable functionality

field reset every: timedelta = 'PT1M'

Reset interval for the timeout

Constraints:

• gt = 0:00:00

field timeout: timedelta = 'PT2M30S'

Timeout after which HABApp will shut down

Constraints:

• gt = 0:00:00