{"id":28458520,"url":"https://github.com/pfink/nuimo-openhab-python","last_synced_at":"2025-08-24T17:47:47.752Z","repository":{"id":91878892,"uuid":"91174777","full_name":"pfink/nuimo-openhab-python","owner":"pfink","description":"Use your Nuimo as a UI for openHAB!","archived":false,"fork":false,"pushed_at":"2024-10-24T16:47:11.000Z","size":158,"stargazers_count":20,"open_issues_count":8,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-07T00:11:37.900Z","etag":null,"topics":["bluetooth-low-energy","bluez","linux","nuimo","openhab","openhab2","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pfink.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-13T13:02:54.000Z","updated_at":"2024-10-24T16:47:15.000Z","dependencies_parsed_at":"2024-02-27T19:27:47.213Z","dependency_job_id":"30b4a8d4-c897-48c2-96b1-f5aa15970976","html_url":"https://github.com/pfink/nuimo-openhab-python","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/pfink/nuimo-openhab-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfink%2Fnuimo-openhab-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfink%2Fnuimo-openhab-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfink%2Fnuimo-openhab-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfink%2Fnuimo-openhab-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfink","download_url":"https://codeload.github.com/pfink/nuimo-openhab-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfink%2Fnuimo-openhab-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263111451,"owners_count":23415457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth-low-energy","bluez","linux","nuimo","openhab","openhab2","python3"],"created_at":"2025-06-07T00:11:25.791Z","updated_at":"2025-07-02T09:31:36.908Z","avatar_url":"https://github.com/pfink.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nuimo openHAB Integration\n\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![Join the chat at https://gitter.im/nuimo-openhab-python/Lobby](https://badges.gitter.im/nuimo-openhab-python/Lobby.svg)](https://gitter.im/nuimo-openhab-python/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![codebeat badge](https://codebeat.co/badges/7cf5a386-927c-4df9-b5e0-738637d9bb0c)](https://codebeat.co/projects/github-com-pfink-nuimo-openhab-python-master)\n\nAn application based on [getsenic/nuimo-linux-python](https://github.com/getsenic/nuimo-linux-python) to use your Nuimo as a UI for [openHAB](https://www.openhab.org/)!\n\n## Installation (Linux only)\n\n1. Make sure bluez version 5.43 or higher  is installed. Normally, you can check your bluez version by executing this command: `bluetoothd --version`.\n1. Download the latest release to your machine: `git clone --recurse-submodules https://github.com/pfink/nuimo-openhab-python -b latest-release`\n1. Create a copy of *config.example.yml* with the name *config.yml*: `cd nuimo-openhab-python \u0026\u0026 cp config.example.yml config.yml`\n1. Install dependencies (the following commands are examples for a Debian-based system, they may differ on other Linux distributions):\n    1. `apt-get install python3-pip python3-dbus python3-gi python3-yaml python3-cryptography libssl-dev`\n    1. `python3 -m venv nuimo-python-venv --system-site-packages`\n    1. `source nuimo-python-venv/bin/activate`\n    1. `pip3 install --upgrade pip` \n    1. `pip3 install -r requirements.txt`\n    \nOptionally, you can move config.yml to another location (e.g. */etc/nuimo-openhab/config.yml*). If you do so, you have to specify that path via the environment variable `NUIMO_OPENHAB_CONFIG_PATH`.\n\n### Setup a systemd service\n\nTo automatically run this app on system boot, you could optionally set it up in your init service. Most modern linux distributions use systemd as their init service (e.g. Debian/Raspbian since Jessie, Ubuntu since 15.04). To setup this app as a systemd service, you can put the following file to `/etc/systemd/system/nuimo-openhab.service`:\n\n```\n[Unit]\nDescription=Nuimo openHAB Integration Service\nRequires=network-online.target bluetooth.service\nAfter=network-online.target bluetooth.service rsyslog.service\n\n[Service]\nExecStart=/usr/bin/python3 /YOUR_PATH_TO_THIS_APP/main.py\nType=simple\nSyslogIdentifier=nuimo-openhab\n\n[Install]\nWantedBy=multi-user.target\n````\n\nAfterwards, run\n\n```\nsystemctl daemon-reload\nsystemctl enable nuimo-openhab\n```\n\nto reload your configuration and activate auto-start on every boot.\n    \n### Upgrade an existing installation\n\n1. Run `git pull --recurse-submodules \u0026\u0026 git submodule update --recursive --remote` to upgrade to the latest version of this app\n1. Run `pip3 install --upgrade -r nuimo-openhab-python/requirements.txt` to update all dependencies\n1. You may have to merge the newest version of `config.example.yml` to your `config.yml`\n1. Consider the release notes whether more actions are required\n\n### Test the latest development version\n\nIf you'd like to test the latest (not yet released) development version, run `git checkout master` and then follow the [Upgrade an existing installation](#upgrade-an-existing-installation) guide. To get back to the stable track, just run `git checkout latest-release`.\n\n## Application / Nuimo Configuration\n\nThe configuration of this application is done via **[config.yml](config.example.yml).**  To get started, usually just the following parameters have to be checked and adjusted:\n\n- `openhab_api_url`\n- `nuimo_mac_address`\n- `bluetooth_adapter`\n\nAll other parameters have adequate default values which do not have to be changed to get started.\nAnyway, you have extensive possibilities to change the applications behavior.\nNormally, the descriptions and examples within  **[config.example.yml](config.example.yml)** are a sufficient documentation\nof the available options. Exception: For the option `key_mapping` which is more complex, you can find a comprehensive documentation [here](examples/keymaps).\n\n## openHAB Configuration\n\nBefore you start the App, you have to configure the openHAB-side to define which items you want to control with your Nuimo.\n\n### Getting started\n\n1. Create a [sitemap](https://docs.openhab.org/configuration/sitemaps.html) with the name *nuimo* on your openHAB instance (in case you have multiple Nuimo's, you can change the name of\n   sitemap used within your config.yml).\n1. Add elements / items you want to control with the Nuimo to that sitemap. As the possibilities of the Nuimo serving as a \n   UI are limited, only a small subset of [element types](https://docs.openhab.org/configuration/sitemaps.html#element-types) is supported:\n   - `Switch`: Is used to map the Nuimo buttons to specific items / commands.\n   - `Slider`: Is used to bind the Nuimo wheel to specific items.\n   - `Text`: Is used to aggregate items to several \"apps\" among those you can navigate with the Nuimo.\n   - `Default`: Partially supported. It works as long as it is internally resolved to a `Switch` or `Slider` element\n     which is true for some item types (e.g. `Switch`, `Dimmer`, `Player`).\n   - `Frame`: This element type is allowed, but ignored. Aggregation is done with `Text` elements because they're\n   more flexible, especially they can be nested.\n   \n   All other element types are *not* allowed and the application won't start if they're used.\n   \n   [Blocks](https://docs.openhab.org/configuration/sitemaps.html#concepts) are only allowed (and mandatory) on `Frame` and `Text` elements. Nesting is supported without any limitations.\n   \n   [Mappings](https://docs.openhab.org/configuration/sitemaps.html#mappings) are supported. Please find all details how\n   to use mappings [below](https://github.com/pfink/nuimo-openhab-python#mappings--custom-switch-configuration).\n   \n   Labels are supported in the way that error messages thrown by this application usually contain the label of the affected item.\n1. Make sure that each `Text` element defines a 9x9 LED icon (as well as `Switch`, `Slider` and `Default` elements\n   if they're not a child of a `Text` element). There are two ways of defining such an icon for an item:\n    1. Add the name of a [predefined icon](https://gist.github.com/pfink/7a468eb906644dc570cc28acb7c4d2b7) with the `icon` parameter of the sitemap element or the `\u003cicon\u003e` tag of the bound item.\n    1. Alternatively, you can use labels to define the icons showed on the 9x9 Nuimo LED matrix. The label have to be a \n       string of the length of 81 chars (9x9) and consist of asterisks(`*`) for led=on and spaces (` `) for led=off.\n       In case you create custom icons, it would be great if you contribute them so that the number of predefined icons\n       grows! Just leave a comment with your icon [here](https://gist.github.com/pfink/7a468eb906644dc570cc28acb7c4d2b7#comments).\n1. Before using your sitemap with the Nuimo, always test if it's properly working with openHAB's [Basic UI](https://www.openhab.org/docs/configuration/ui/basic/). This will speed up the troubleshooting process and prevent you to look for error causes on the wrong side.\n\n### Example Sitemap Configuration\n\n```\nsitemap nuimo label=\"Nuimo\"\n{\n    Text label=\"Multiroom Audio System\" icon=\"music\" {\n        Switch item=AllRooms_Player mappings=[TOGGLE=BUTTON_CLICK]\n        Slider item=AllRooms_Volume\n        \n        Text label=\"Audio Bedroom\" icon=\"letterB\" {\n            Default item=Bedroom_Player\n            Slider item=Bedroom_Volume\n        }\n        Text label=\"Audio Guest Room\" icon=\"letterG\" {\n            Default item=GuestRoom_Player\n            Slider item=GuestRoom_Volume\n        }\n    }\n    Slider item=Simple_Light icon=\"light\"\n    \n    Text label=\"Simple Light\" icon=\"letterO\" {\n        Switch item=Simple_Light\n        Slider item=Simple_Light\n    }\n}\n```\n\nThis configuration defines 3 _apps_ on root level between those you can navigate:\n- A multiroom audio system where you can control the music (Play/Pause) and volume of all rooms.\n  In addition, you can jump into a sub-menu that you can use to control the music of the single rooms (here: _Bedroom_ and _Guest Room_)\n- A light that you can only control with the wheel of the nuimo\n- The same light again, but with a different configuration: Here you can use the wheel AND the button to control the light.\n\nSome noteworthy details about this example configuration:\n- For `Bedroom_Player` and `Guestroom_Player` (both are `Player` items), the `Default` element is used.\n  This causes openHAB to create a Switch with a mapping for PLAY/PAUSE and PREVIOUS/NEXT controls. This application\n  is already preconfigured so that not only PLAY/PAUSE can be used, but also PREVIOUS/NEXT (by swiping left/right).\n- For `AllRooms_Player`, the `Switch` element is used instead which will suppress the special mapping so that just\n  `ON`/`OFF` commands are sent. This can be useful e.g. to suppress the possibility for previous/next commands because\n  they'll maybe executed multiple times when different rooms are grouped together.\n\nAll explanations refer to the default keymap configuration within `config.example.yml`. Limitations or differences may apply to deviant keymap configurations.\n\n### Mappings / Custom Switch Configuration\n\n[Mappings](https://docs.openhab.org/configuration/sitemaps.html#mappings) can be used to customize the mapping from\nNuimo gesture to openHAB command for each item so you're able to create customized keymaps on item level. Mappings\nshould always have the structure: `[OPENHAB_COMMAND1=NUIMO_GESTURE1, OPENHAB_COMMAND2=NUIMO_GESTURE2, ..]`\n\nSome examples: \n```\nSwitch MyCustomPlayer mappings=[TOGGLE=BUTTON_CLICK, NEXT=SWIPE_RIGHT, PREVIOUS=SWIPE_LEFT, REWIND=TOUCH_LEFT, FASTFORWARD=TOUCH_RIGHT]\nSwitch MyCustomLight mappings=[OFF=SWIPE_LEFT, ON=SWIPE_RIGHT]\nSwitch MyCustomDimmer mappings=[INCREASE=FLY_LEFT, DECREASE=FLY_RIGHT]\n```\n\nYou can find a list of all available Nuimo gestures [here](https://github.com/getsenic/nuimo-linux-python/blob/0.3.6/nuimo/nuimo.py#L398).\nAdditionally, `BUTTON_HOLD`, `BUTTON_CLICK`, `BUTTON_DOUBLE_CLICK` and `BUTTON_TRIPLE_CLICK` are available.\n\n### Reading the Battery Level\n\nIf you like to track the battery level of your Nuimo within openHAB, you can simply create the following item:\n\n```\nNumber Nuimo_BatteryLevel \"Nuimo Battery Level [%d]\"\n```\n\nIn case this item is present, this app will automatically update it with the current battery level accordingly.\nIf you like to use a different name for this item, you can change it [within the config.yml](config.example.yml#L6).\n\n## Start the application\n\nPlain (without systemd or another init service):\n```\ncd nuimo-openhab-python\npython3 main.py\n```\n\nWith systemd setup:\n\n```\nsystemctl start nuimo-openhab\n```\n\n## Usage\n\nUsage depends on which [keymap](examples/keymaps) you use.\n\n**Default Keymap:** You can navigate between apps with swipes as well as with the wheel **only as long as you hold the button**.\nSwipe up+down: Go up or down the hierarchy. Wheel / Swipe left+right: Navigate between apps on the same hierarchy. When\nthe button is not hold, by default a short button click sends a TOGGLE command to switches while the wheel will control\nthe Slider elements.\n\n**Simple Keymap:** \nSwipe up+down: Navigate between apps (hierarchies / nexted `Text` elements are NOT supported by this keymap).\nA short button click sends a TOGGLE command to switches while the wheel will control the Slider elements.\n\nThis short introduction video gives a hands-on overview on the usage:\n\n[![How to use the Nuimo openHAB integration](https://img.youtube.com/vi/QGt0zuFNhH0/3.jpg)](https://www.youtube.com/watch?v=QGt0zuFNhH0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfink%2Fnuimo-openhab-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfink%2Fnuimo-openhab-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfink%2Fnuimo-openhab-python/lists"}