https://github.com/h4de5/home-assistant-vimar
VIMAR by-me integration into home-assistant.io
https://github.com/h4de5/home-assistant-vimar
home-assistant home-automation homeassistant homeassistant-integration vimar vimar-platform
Last synced: 4 months ago
JSON representation
VIMAR by-me integration into home-assistant.io
- Host: GitHub
- URL: https://github.com/h4de5/home-assistant-vimar
- Owner: h4de5
- License: gpl-3.0
- Created: 2020-06-03T22:11:31.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2026-01-24T16:39:41.000Z (5 months ago)
- Last Synced: 2026-01-25T05:54:25.848Z (5 months ago)
- Topics: home-assistant, home-automation, homeassistant, homeassistant-integration, vimar, vimar-platform
- Language: Python
- Homepage:
- Size: 495 KB
- Stars: 51
- Watchers: 14
- Forks: 9
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/h4de5/home-assistant-vimar/actions/workflows/validate.yml)
[](https://github.com/h4de5/home-assistant-vimar/actions/workflows/hassfest.yml)
[](https://github.com/h4de5/home-assistant-vimar/releases)
[](https://github.com/h4de5/home-assistant-vimar/releases)
[](https://github.com/h4de5/home-assistant-vimar/issues)
[](https://github.com/h4de5/home-assistant-vimar/pulls)
# VIMAR By-Me / By-Web Hub
This is a home-assistant integration for the VIMAR By-me / By-web bus system.
## WARNING - BEFORE YOU UPGRADE
If you upgrade from a version earlier of May 2021 - please be aware:
The integration name has changed from `vimar_platform` to `vimar` - this requires changes in your configuration and it may effect your current dashboards as well.
In order to keep all dashboard layouts, automations and groups intact, you may want to follow this upgrade guide:
- DO NOT update the files in your `custom_components` directory right away
- stop home-assistant
- find and backup the file: `.storage/core.entity_registry` within your home-assistant config directory
- open that file in a proper text-editor
- replace all `vimar_platform` occurrences to `vimar` (only replace with that exact notation)
- save that file in it's original place
- open your configuration.yaml and replace `vimar_platform:` with `vimar:` as well
- remove the directory `custom_components/vimar_platform/` and checkout the source under `custom_components/vimar/`
- start up home-assistant again
## Vimar requirements
Hardware:
- [Vimar - 01945 - Web server By-me](https://www.vimar.com/de/int/catalog/obsolete/index/code/R01945)
or
- [Vimar - 01946 - Web server Light By-me](https://www.vimar.com/en/int/catalog/product/index/code/R01946)
Software:
- [By-me Web Server Firmware](https://www.vimar.com/de/int/catalog/product/index/code/R01945)
I have only tested it with the firmware version v2.5 to v2.8 - if you plan to update the firmware of your web server, please make sure you have a full backup of your vimar database (complete db and exported xml file) ready.
## home-assistant requirements
See installation guides [Home-Assistant.io](http://home-assistant.io/)
### installation
- Use [HACS](https://hacs.xyz/) !
- 
- Otherwise, download the zip from the latest release and copy `vimar` folder into your custom_components folder within your home-assistant installation.
You will end up with something like this:
- on docker/hassio: `/config/custom_components/vimar/`
- on hassbian/virtualenv: `/home/homeassistant/.homeassistant/custom_components/vimar/`
### configuration
After you installed the custom component either via HACS or by extracting the release zip into your `custom_components` folder you should be able to select **Vimar By-Me Hub** from the list of integration in the Home-Assistant GUI.
From there simply follow the instructions.
Any previous setup made in your configuration.yaml will be taken over to the GUI and can be removed afterwards.
#### credentials
`username` and `password` are those from the local vimar webserver reachable under `host`. `schema`, `port`, and `certificate` is optional - if left out, the integration will use https calls on port 443 to the given host. The `certificate` can be a writeable filename. If there is no file found, the integration will download the current CA certificate from the local vimar webserver and save it under that given file name for sub sequent calls. (e.g. `certificate: rootCA.VIMAR.crt`). `timeout` will allow to tweak the timeout for connection and transmition of data to the webserver (default 6 seconds). if only some platforms should be added to home-assistant you list them in the `ignore` area.
The hostname or the IP has to match the settings screen on the vimar web server:
## limitations
The integration can currently list and control all lights, rgb dimmers, audio devices, energie guards, covers/shades, fans, switches, climates and scenes. Other devices are not yet implemented. The python module behind the communication mimics the http calls to the webserver that are usually made through the By-me Webinterface. Generally speaking: **THIS IS A BETA VERSION** Use at your own risk. So far I could only test it on a single installation, which is my own. If you want to try it out, and need help, please create a "Request Support" ticket.
## Command line usage
You can use the vimarlink library standalone (without Home Assistant) to test connectivity and control devices:
```bash
# Create and activate Python 3.13 virtual environment
cd /path/to/home-assistant-vimar
python3.13 -m venv .venv
source .venv/bin/activate
# Install minimal dependencies (NO Home Assistant required)
pip install requests
# Setup credentials
cd examples
cp credentials.cfg.dist credentials.cfg
# Edit credentials.cfg with your VIMAR server details:
# host=
# username=
# password=
# certificate= (leave empty to skip SSL verification for expired certs)
# Set PYTHONPATH and run
export PYTHONPATH=../custom_components/vimar
# List all available platforms and device counts
python example.py
# List all devices for a specific platform
# Valid platforms: light, cover, switch, climate, media_player, scene, sensor
python example.py --platform light
python example.py --platform cover
python example.py --platform climate
# Show help
python example.py -h
# Control a device (example: set cover position)
python example.py --platform cover --device 721 "up/down=0"
# Change a specific status on a device
python example.py --platform light --device 123 --status on/off --value 1
```
## contribution
If you want to help see some examples of how to read out data for new devies in [contribution](CONTRIBUTING.md).
## troubleshooting
**When you install, update or uninstall the integration, you need to restart Home Assistant.**
Enable more logging for vimar - add to your `configuration.yaml`:
logger:
default: warning
logs:
custom_components.vimar: debug
have a look into your home-assistant log files - usually named `home-assistant.log` in the directory where your `configuration.yaml` is located.
WARNING (MainThread) [homeassistant.loader] You are using a custom integration for vimar which has not been tested by Home Assistant. This component might cause stability problems, be sure to disable it if you experience issues with Home Assistant.
> the Vimar platform code and the configuration was found. The warning is been shown for all custom components. This is GOOD!
ERROR (MainThread) [custom_components.vimar] Could not connect to Vimar Webserver home-assistant
> Vimar By-me Webserver was not found under the given address.
ERROR (MainThread) [homeassistant.setup] Setup failed for vimar: Integration not found
> You have put the content of this repository into the wrong directory - see above for an example.
ERROR (SyncWorker_4) [custom_components.vimar.vimarlink] Other error occurred: SSLError(MaxRetryError('HTTPSConnectionPool(host='***', port=443): Max retries exceeded with url: /vimarbyweb/modules/system/user_login.php?sessionid=&username=***&password=***&remember=0&op=login (Caused by SSLError(SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')])")))'))
> There seems to a problem with the SSL connection. Try if it works with the config setting `certificate: ` (empty certificate option)
ERROR (SyncWorker_5) [custom_components.vimar.vimarlink] Error parsing XML: TypeError("a bytes-like object is required, not 'bool'")
> This message paired with a web server that needs manual restarting: You may have too many devices connected to the installation.
Some entities are listed as "not available" with a red exclamation mark in the entity list.
> See the explanation and the fix in: https://github.com/h4de5/home-assistant-vimar/issues/15#issuecomment-665635305
When you enable the integration in home-assistant you can no longer use the vimar web server gui.
> Please create a separate user on your VIMAR webserver for this integration. At some point the web server does not allow to be logged in with the same user from different locations and simple drops one connection. This may have strange side effects.
## thanks
thanks to everybody who was helping me developing and testing this integration. special thanks to user @felisida for his endless patience ;)