search

fdebrus / Nikobus-HA

4 stars 1 forks source link

readme

Nikobus Integration for Home Assistant (2024.7.5)

This integration enables the control of Nikobus systems via Home Assistant, allowing you to manage various Nikobus modules directly from your Home Assistant platform.

Supported Modules

Important Note: The integration maintains in sync with Nikobus using two methods:

a. Any physical button must be included in the button_config file. This ensures that when the button is pressed, it triggers a refresh of the impacted module(s) and immediately updates Home Assistant (HA).

b. Refresh mechanism, which can be either integration-based with a custom refresh rate or Feedback Module-based with Nikobus's internal refresh rate.

The later might introduce a delay, meaning the integration will not retrieve the module status until the next refresh cycle. As a result, HA and Nikobus might be out of sync until the subsequent refresh cycle. By accurately defining all physical buttons in method (a), HA will remain consistently synchronized; otherwise, delays might occur if relying solely on method (b).

Both methods are complementary, but for the best experience, ensure your button configuration file is fully completed.

Connectivity

Only one client on the Nikobus at a time, do not connect anything else in parallel of this integration.

It is supported through direct connections, such as /dev/ttyUSB0

or over the network using an IP address and port, for example, 192.168.2.50:9999.

Network connectivity can be achieved by adding a bridge. This could come handy is your Nikobus installation is distant from your HA server.

TCP Server
TCP Server TCP Server

Automation Example

The integration will emit different messages on the Home Assistant bus:

Any press duration above 500ms will be considered long press, you can adapt to your needs by updating the value in the const.py file from the integration custom directory and restart HA.

LONG_PRESS_THRESHOLD_MS = 500 # Time in ms to detect a long press (>= LONG_PRESS_THRESHOLD_MS)

You can choose to use these events with or without specifying the button address. Without the button address, the automation will trigger for any button press. With the address, the automation will be specific to the button associated with that address.

Address shall be the one referenced in your nikobus_button_config.json, 004E2C in this example

    "nikobus_button": [
        {
            "description": "BT_GF_Living_Sofa_Wall_Light_Up",
            "address": "004E2C",
            "impacted_module": [
                {
                    "address": "0E6C",
                    "group": "1"
                }
            ]
        }
alias: "React to Nikobus Button Push"
description: "Perform actions when a Nikobus button is reported as pressed."
trigger:
  - platform: event
    event_type: nikobus_button_pressed
    event_data:
      address: "specific_button_address"  # Optional: Specify to react to a specific button
action:
  - service: homeassistant.toggle
    entity_id: light.example_light

Setup Process

  1. Install the custom integration using HACS. Use the custom link below, or copy the repository to custom_repository/nikobus

Add to HACS

  1. Navigate to custom_repository/nikobus.
  2. Copy nikobus_module_conf.json.default to your Home Assistant configuration directory, remove the .default extension.
  3. Update the file to reflect your specific installation settings.
  4. Add Nikobus under Settings/Devices & services - Add Integration
  5. You will be asked for a USB port or IP:PORT
  6. "Has Feedback Module installed and connected over PC-Link ?" If you have a feedback module installed AND you connect over PC-Link, check this option. If you connect to feedback module without PC-Link or you have no feedback module, leave this unchecked and specify a custom refresh rate on the next screen.
  7. Depending on previous selected option, you will get a screen to specify a custom refrresh rate.

Module Configuration

Make sure to record your modules addresses as they are displayed in the nikobus software.

You can begin by locating the example file in the integration directory after installation via HACS. This file will be available in your HA installation at /config/custom_components/nikobus/nikobus_module_config.json.default. Copy this file to the /config directory and rename it to nikobus_module_config.json.

The description field is free text and can include anything that helps you identify the module. For example: "description": "Switch Module S1"

The model should reflect the Nikobus reference of the module. For example: "model": "05-000-02"

Each channel can have a free text description to help you identify them. Ensure that these descriptions are unique both within the module and across different modules to avoid duplicates in the integration entities.

If you are using the Feedback Module with an LED button, register a button address for each entry to turn the LED on or off, respectively. The button address reference is case-sensitive and should follow this format: "8AA8FA". If you do not have a Feedback Module or no LED status to link with a particular module output, leave both the led_on and led_off values blank.

{
    "switch_module": [
        {
            "description": "Switch Module S1",
            "model": "05-000-02",
            "address": "C9A5",
            "channels": [
                {"description": "S1 Output 1", "led_on":"259B02", "led_off":"659B02"},
                {"description": "S1 Output 2", "led_on":"", "led_off":""},
                {"description": "S1 Output 3", "led_on":"", "led_off":""},,
                {"description": "S1 Output 4", "led_on":"", "led_off":""},
                {"description": "S1 Output 5", "led_on":"", "led_off":""},
                {"description": "S1 Output 6", "led_on":"", "led_off":""},
                {"description": "S1 Output 7", "led_on":"", "led_off":""},
                {"description": "S1 Output 8", "led_on":"", "led_off":""},...
    "dimmer_module": [
        {
            "description": "Dimmer Module D1",
            "model": "05-007-02",
            "address": "0E6C",
            "channels": [
                {"description": "D1 Output 1", "led_on":"", "led_off":""},
                {"description": "D1 Output 2", "led_on":"", "led_off":""},
                {"description": "D1 Output 3", "led_on":"", "led_off":""},
                {"description": "D1 Output 4", "led_on":"", "led_off":""},
                {"description": "D1 Output 5", "led_on":"", "led_off":""},...

Entries that define roller output include an additional argument, operation_time, which specifies the total time (in seconds) that a shutter takes to fully open or close. Update this value to reflect your shutter's actual operation time. This parameter is crucial as it allows the integration to simulate setting the shutter position, a feature not natively supported by Nikobus, by operating the shutter for a calculated period.

    "roller_module": [
        {
            "description": "Rollershutter Module R1",
            "model": "05-001-02",
            "address": "9105",
            "channels": [
                {"description": "R1 Output 1", "operation_time": "40", "led_on":"", "led_off":""},
                {"description": "R1 Output 2", "operation_time": "40", "led_on":"", "led_off":""},
                {"description": "R1 Output 3", "operation_time": "40", "led_on":"", "led_off":""},
                {"description": "R1 Output 4", "operation_time": "40", "led_on":"", "led_off":""},
                {"description": "R1 Output 5", "operation_time": "40", "led_on":"", "led_off":""},
                {"description": "R1 Output 6", "operation_time": "40", "led_on":"", "led_off":""}
            ]
        }
    ]

To avoid setting up entries and entities for unused module outputs, prefix any output description with "not_in_use" so it will not be imported into the integration. For example:{"description": "not_in_use output_10"}

Button Configuration

Upon button press, buttons will be discovered and registered in nikobus_button_conf.json in your home assistant /config folder. If the file does not exist, it will be created. Next the file needs manual updates:

How does it work...

nkbconnect

Connects Home Assistant to Nikobus over a user-defined TCP/IP socket or USB port and performs a handshake to instruct Nikobus to echo commands on the bus..

nkbconfig

It is responsible for reading configuration files created by the user. Since the inventory cannot be directly obtained from the bus yet, the user must define files for all modules and buttons. The configuration is then stored for further processing by the integration. Button file does not need to be created but updated, each time a button is physically pressed, its address will be added to the button file (file will be created by first button pressed and be placed in your HA /config directory).

Next you need to update the name to your preference, and list the impacted module(s) so the integration will refresh status of this(those) module(s) to reflect the change of state in HA wuthout having to wait for the next module(s) refresh cycle.

Discovered button will look like

        {
            "description": "DISCOVERED - Nikobus Button #N4ECB1A",
            "address": "4ECB1A",
            "impacted_module": [
                {
                    "address": "",
                    "group": ""
                }
            ]
        }

You have to update it to

        {
            "description": "Kitchen Light On",
            "address": "4ECB1A",
            "impacted_module": [
                {
                    "address": "4707",
                    "group": "1"
                }
            ]
        }

or if multiples modules impacted by the same button

        {
            "description": "Kitchen Light On",
            "address": "4ECB1A",
            "impacted_module": [
                {
                    "address": "4707",
                    "group": "1"
                },
                {
                    "address": "C9A5",
                    "group": "2"
                }
            ]
        }

For the changes to be reflected, re-start HA

nkblistener

It creates a continuous loop to listen for messages on the Nikobus. Upon receiving a message, it submits the message to the handle_message function for processing. The handle_message function determines the appropriate action based on the initial characters of the message and identifies whether:

nkbcommand

It established a command processing queue, which is essential for handling a rapid sequence of commands. For instance, if you use HomeKit to send a command to close all shutters, this generates a rapid series of commands to close each shutter individually. Without queuing, Nikobus cannot manage the speed at which these commands are sent. The queue will introduce a 0.3-second pause between every consecutive commands.

To read from the bus, it employs a three-strike approach, waiting for the expected data from the bus. Since the bus can be busy, it may be necessary to wait for the signal that corresponds to our command.

It has also all logic needed to send and receive data on Nikobus.

Issues/Discussion

For discussions/general requests, please refer to this thread in HA community.

Gallery

During the integration setup, you will be asked to provide your connection string, which can be either an IP or a USB port. If your setup includes a Nikobus Feedback Module and you are connected to Nikobus over the PC-Link interface, check the box. In this case, the integration will refresh based on the Feedback Module's refresh cycle and feedback data instead of the custom refresh rate.

image

If you do not have a Nikobus Feedback Module, leave the box unchecked. You will then be presented with another screen to set up your custom integration refresh rate. Avoid setting the refresh interval too low to prevent excessive traffic on the bus.

image

You can always revisit these options after setup by selecting the "CONFIGURE" option from the integration menu.

image

image

Buy Me A Coffee