ha_services

Helpers to send periodic information via MQTT to Home Assistant

• https://pypi.org/project/ha-services/

Use by:

• https://github.com/jedie/tinkerforge2mqtt
• https://github.com/jedie/victron-ble2mqtt
• https://github.com/jedie/energymeter2mqtt
• https://github.com/jedie/pysmartmeter

Validation of device/state classes and units

Home Assistant supports only a defined combination of device-, state-classes and units.

see: https://www.home-assistant.io/integrations/sensor/#device-class

hs-services contains a validation of these combinations. We collect the valid combinations from Home Assistant source code.

Update of these data is done by: ./dev-cli.py update-ha-data

A Sensor inheriting from ha_services.mqtt4homeassistant.components.sensor.Sensor will be validated.

Validation can be disabled by setting validate=False in the constructor of the Sensor.

start development

At least uv is needed. Install e.g.: via pipx:

apt install pipx
pipx install uv

Clone the project and just start the CLI help commands. A virtual environment will be created/updated automatically.

~$ git clone https://github.com/jedie/ha-services.git
~$ cd ha-services
~/ha-services$ ./cli.py --help
~/ha-services$ ./dev-cli.py --help

dev CLI

usage: ./dev-cli.py [-h] {coverage,install,lint,mypy,nox,pip-audit,publish,shell-completion,test,update,update-ha-data,update-readme-history,update-test-snapshot-files,version}



╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ -h, --help     show this help message and exit                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                                                           │
│   • coverage   Run tests and show coverage report.                                                                   │
│   • install    Install requirements and 'ha_services' via pip as editable.                                           │
│   • lint       Check/fix code style by run: "ruff check --fix"                                                       │
│   • mypy       Run Mypy (configured in pyproject.toml)                                                               │
│   • nox        Run nox                                                                                               │
│   • pip-audit  Run pip-audit check against current requirements files                                                │
│   • publish    Build and upload this project to PyPi                                                                 │
│   • shell-completion                                                                                                 │
│                Setup shell completion for this CLI (Currently only for bash shell)                                   │
│   • test       Run unittests                                                                                         │
│   • update     Update dependencies (uv.lock) and git pre-commit hooks                                                │
│   • update-ha-data                                                                                                   │
│                Update Home Assistant data files for custom components. Creates a venv in /tmp/, installs             │
│                `homeassistant` package and runs a script to collect data.                                            │
│   • update-readme-history                                                                                            │
│                Update project history base on git commits/tags in README.md Will be exited with 1 if the README.md   │
│                was updated otherwise with 0.                                                                         │
│                                                                                                                      │
│                Also, callable via e.g.:                                                                              │
│                    python -m cli_base update-readme-history -v                                                       │
│   • update-test-snapshot-files                                                                                       │
│                Update all test snapshot files (by remove and recreate all snapshot files)                            │
│   • version    Print version and exit                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

DEMO app CLI

usage: ./cli.py [-h] {edit-settings,info,print-settings,publish-loop,shell-completion,systemd-debug,systemd-logs,systemd-remove,systemd-setup,systemd-status,systemd-stop,test-mqtt-connection,update-readme-history,version,wifi-info}



╭─ options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ -h, --help        show this help message and exit                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ subcommands ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ (required)                                                                                                           │
│   • edit-settings                                                                                                    │
│                   Edit the settings file. On first call: Create the default one.                                     │
│   • info          Publish data once and display information about all registered components.                         │
│   • print-settings                                                                                                   │
│                   Display (anonymized) MQTT server username and password                                             │
│   • publish-loop  Publish data via MQTT for Home Assistant (endless loop)                                            │
│   • shell-completion                                                                                                 │
│                   Setup shell completion for this CLI (Currently only for bash shell)                                │
│   • systemd-debug                                                                                                    │
│                   Print Systemd service template + context + rendered file content.                                  │
│   • systemd-logs  List and follow logs of systemd service. (May need sudo)                                           │
│   • systemd-remove                                                                                                   │
│                   Write Systemd service file, enable it and (re-)start the service. (May need sudo)                  │
│   • systemd-setup                                                                                                    │
│                   Write Systemd service file, enable it and (re-)start the service. (May need sudo)                  │
│   • systemd-status                                                                                                   │
│                   Display status of systemd service. (May need sudo)                                                 │
│   • systemd-stop  Stops the systemd service. (May need sudo)                                                         │
│   • test-mqtt-connection                                                                                             │
│                   Test connection to MQTT Server                                                                     │
│   • update-readme-history                                                                                            │
│                   Update project history base on git commits/tags in README.md Will be exited with 1 if the          │
│                   README.md was updated otherwise with 0.                                                            │
│                                                                                                                      │
│                   Also, callable via e.g.:                                                                           │
│                       python -m cli_base update-readme-history -v                                                    │
│   • version       Print version and exit                                                                             │
│   • wifi-info     Just display the WiFi info                                                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Backwards-incompatible changes

v2.10.0

For new validation the main loop should catch InvalidStateValue exceptions, log it as warning and continue the loop. See ha_services.example.publish_forever() for an example ;)

v2.0.0

Complete refactor of mqtt4homeassistant module. New usage, see: ha_services/example.py

History

• v2.15.4
  • 2026-04-10 - Add method to cleanup of global registry #103
• v2.15.3
  • 2026-04-10 - fix code style
  • 2026-04-10 - Update requirements
  • 2026-04-08 - Bump cryptography from 46.0.6 to 46.0.7
  • 2026-03-30 - Bump pygments from 2.19.2 to 2.20.0
  • 2026-03-29 - Bump cryptography from 46.0.4 to 46.0.6
• v2.15.2
  • 2026-02-08 - Apply manageprojects updates: Use "uv" direct and update requirements
  • 2025-12-09 - Update requirements
• v2.15.1
  • 2025-10-25 - Update requirements and fix CI tests
  • 2025-10-25 - Apply manageprojects updates
  • 2025-10-25 - Enhance logging in WifiInfo2Mqtt if "iwconfig" not found