Custom Component: Nikobus

ErikHomeSir · January 20, 2026, 4:46pm

Hey, Nice feature.

I tried to name a few Switches with the entity_type: “light” but it does not work for me (yet)
perhaps I am doing something wrong
example:

            "description": "Switch Module S3",
            "model": "05-000-02",
            "address": "38AB",
            "channels": [
                {"description": "Plug Q29 Basement S3-01", "led_on":"", "led_off":""},
                {"description": "Basement Climbing S3-02", "entity_type": "light"},
                {"description": "WIC Spots S3-03", "led_on":"", "led_off":""},
                {"description": "Pink Bedroom Plugs S3-04", "led_on":"", "led_off":""},
                {"description": "Nightlights S3-05", "led_on":"", "led_off":""},
                {"description": "Livingroom Wall S3-06", "led_on":"", "led_off":""},
                {"description": "Kitchen Wall S3-07", "led_on":"", "led_off":""},
                {"description": "Basement Heatpump High=Off S3-08", "led_on":"", "led_off":""},
                {"description": "Stairs Laundry Spot S3-09", "led_on":"", "led_off":""},
                {"description": "Basement Boiler S3-10", "led_on":"", "led_off":""},
                {"description": "Basement Winecellar S3-11", "led_on":"", "led_off":""},
                {"description": "Basement Workbench S3-12", "led_on":"", "led_off":""}
            ]
        },
        {

S3-02 is now not findable anymore. perhaps I am missing something.
thank you for the awesome work with this integration btw!

fdebrus · January 20, 2026, 8:00pm

Could you share a debuglog ? enable debuglog in the integration, restart to have the startup of the nikobus integration in the log. share it.

“Basement Climbing S3-02” was defined as a switch by default, now with the upgrade and the usage of entity_type the switch.basement_climbing_s3_02 no longer exists and being replaced by light.basement_climbing_s3_02

btw, you can clean led_on / led_off if not used, not mandatory fields

Required vs optional fields

Required (module level): description, model, address, and channels.
Required (per channel): description.
Optional (per channel):
- led_on / led_off: Feedback LED addresses (case-sensitive, format like 8AA8FA).
- operation_time: For roller outputs, the time in seconds to fully open/close. If omitted, the cover will still work but uses a default timing, which may reduce position accuracy.
- entity_type: Override the default entity type (see matrix below).

ErikHomeSir · January 21, 2026, 6:22pm

Thanks fdebrus,

I have a debugging log but can’t seem to upload it?
I also have cleaned up my config file but the switches are stil not there as light they are gone althogeter.

I would like to share my config file and debuginglog but I don’t know how sorry.

goofyke · January 26, 2026, 2:26pm

Hello,

I added an automation in Home Assistant using a Sonoff motion detector or door contact as a trigger, which controls a light from a switch module. This works fine.

The problem is that other lights are also turning on or off even though they’re not part of the automation at all. They’re being triggered somehow.

Has anyone else had this happen or does anyone know how this could happen?

my configuration:

HA on Raspberry Pi
I send 10 smart plugs from Ikea, 6 motion detectors, 4 temperature sensors and 2 door contacts from sonoff via E-dongle zigbee sonoff
Nicobus

05-000-02	Switching module	4
2 Roller shutter module	05-000-03
1 Dimcontroller	05-000-04
7 Bus push button, 2 control points	05-000-05
25 Bus push button, 4 control points	05-000-06
1 PC-Link	05-000-07
1 PC-Logic used as ‘master’	05-000-08
1 Feedback Module with Touch Screen (05-096)	05-000-09

fdebrus · January 27, 2026, 8:01am

Nikobus Switch Modules – Why State Sync in Home Assistant Is Critical

While working on the Nikobus integration, I ran into an architectural constraint that can easily cause unexpected output changes if HA and Nikobus are not perfectly in sync.

This post explains the behavior so others understand the risk and the design implications.

Hardware Context

Example device:

Nikobus switch module with 12 outputs (channels 1–12)

Nikobus does not allow writing a single output independently.

Outputs can only be written in blocks of 6 channels

So internally the module behaves as:

Group 1: Channels 1–6
Group 2: Channels 7–12

Any write operation to one channel in a group rewrites all 6 channels in that group.

Initial State

Assume this is the real state in Nikobus and the last known state in HA:

Channel	1	2	3	4	5	6
State	ON	OFF	OFF	OFF	OFF	OFF

HA stores this as:

ON OFF OFF OFF OFF OFF

Now You Change One Output

You turn Channel 6 → ON from Home Assistant.

Because of Nikobus protocol rules, HA cannot send:

Set channel 6 = ON

Instead it must send the full block:

Channels 1–6 = ON OFF OFF OFF OFF ON

Where Things Go Wrong

Let’s say Channel 1 was turned OFF physically (wall button), but HA has not refreshed yet.

Real state in Nikobus:

OFF OFF OFF OFF OFF OFF

HA still thinks:

ON OFF OFF OFF OFF OFF

Now you turn Channel 6 ON via HA.

HA builds the frame from its internal state:

ON OFF OFF OFF OFF ON

Result: Channel 1 turns back ON, even though the user turned it OFF.

This is not a bug in Nikobus, it’s a consequence of:

grouped writes
HA using stored state to rebuild full output frames

Key Concept

For Nikobus switch modules, HA state is not just display data, it is used to reconstruct write commands.

If HA is out of sync, it will reapply stale states during the next grouped write.

How Sync Is Maintained

The integration uses two mechanisms:

Periodic Refresh

HA polls module state at intervals.

Problem: There is always a time window where HA may be wrong.

Button-Triggered Refresh (Important)

The integration keeps a button mapping file that defines which modules are affected by each button.

When a button press is detected:

The impacted module(s) are refreshed immediately
HA does not wait for the periodic cycle

This reduces (but does not eliminate) desync windows.

Summary

Nikobus switch behavior implies:

You never change one output
You always rewrite six outputs at once
If HA state is stale → you overwrite real changes
Periodic polling alone is not sufficient
Event-based refresh on button activity is essential

fdebrus · January 27, 2026, 8:03am

Your automation is correct.
The issue is that HA builds the 6-output command from its internal state, and that state can be wrong.

Example

Someone turns a light OFF physically (wall button).
HA has not refreshed yet, so it still believes that light is ON.
Your motion automation turns another light ON (same module group).
HA sends the whole group state based on its stored values.
That previously turned-off light is sent as ON again → it turns back on.

So HA unintentionally restores old states while trying to change only one output.

Probable root cause; Ensure button mappings are configured, so button presses trigger immediate refresh.

Are your nikobus_button_config.json file fully complete and updated ?

wimu · February 3, 2026, 4:54pm

It is not exactly clear to me where I can find the button mapping file to define the impacted modules.

goofyke · February 3, 2026, 8:35pm

Hi,

I think so, but I’m not sure. Could you take a look at the file to see if there’s an error?

How should I send you the file? Can I copy the text and paste it here?

Would it be helpful if I sent you my module_config.json?

What country are you from? Belgium?

Kind regards, Dave.

fdebrus · February 4, 2026, 10:58am

Read this section, I will provide guidance and further example later today

fdebrus/Nikobus-HA

goofyke · February 4, 2026, 3:29pm

Hi,

Below is a short excerpt from the module_config.json

Are you from Belgium?¨

Kind regards, Dave.

{
“nikobus_button”: [
{
“description”: “DISCOVERED - Nikobus Button #N86B01E”,
“address”: “86B01E”,
“impacted_module”: [
{
“address”: “”,
“group”: “”
}
]
},
{
“description”: “DISCOVERED - Nikobus Button #N9F28EE”,
“address”: “9F28EE”,
“impacted_module”: [
{
“address”: “”,
“group”: “”
}
]
},
{

fdebrus · February 4, 2026, 5:56pm

So you need to manualy update the button_config file

Example

{
“description”: “DISCOVERED - Nikobus Button #N86B01E”,
“address”: “86B01E”,
“impacted_module”: [
{
“address”: “”,
“group”: “”
}
]
},

You have a Nikobus physical button with address N86B01E when this button is pressed, let’s say it turn on a light from a Nikobus switch module for the example.

You have to find the Switch Module address, eg C5D9 (see your module_config file) and the output where the light is connected being a number between 1 and 12 for a 12 outputs module.
So the Nikobus buttton N86B01E turn on/off light on output 5 of switch module C5D9 then your config shall be updated to

{
“description”: “<Free text to describe your button>”,
“address”: “86B01E”,
“impacted_module”: [
{
“address”: “C5D9”,
“group”: “1”
}
]
},

“group” is 1 for module outputs 1 to 6 and 2 for 7 to 12

Have a try, revert if you need more guidance.

and yes, from Belgium

goofyke · February 5, 2026, 1:20pm

Hi Fdebrus,

I have 32 switches with 114 separate push buttons (A, B, C, D). I assume that HA, in its Discover tool, assigns a separate address to each push button for a push button with 2 or 4 push buttons (#N86B01E). I can find the addresses of the modules and the switches (2 or 4 push buttons) in the Niko software. But I can’t find the addresses listed in the button_config (#N86B01E) by HA.

How can I find the addresses of the push buttons (A, B, C, D) in the Niko or HA software so that I can link the push button (e.g., #N86B01E) to the correct module (e.g., C5D9) in the button_config?

Can I also post here in Dutch, or do I need to translate it into English?

Can I also contact you through another channel?

Kind regards, Dave.

fdebrus · February 5, 2026, 5:32pm

I cannot read dutch and the forum is englich only…

To your question, the easier is to remove all button, push one button at a time (so you know the one that has been pushed) update it in the config, move on to the next button and repeat.

Warn the familly not to push any button while you are busy

an alternative is the nikobus address calculator that I’ve uploaded to the repo, the zip is here: fdebrus/Nikobus-HA

fdebrus · February 5, 2026, 5:50pm

Very experimental, your could also instead run the discovery from HA developer tools, it ‘should’ populate button address from discovered button

Discovery_info will be added to the button_config file

            "description": "BT_GF_Living_Sofa_Wall_Light_Up",
            "address": "004E2C",
            "impacted_module": [
                {
                    "address": "0E6C",
                    "group": "1"
                }
            ],
            "discovered_info": [
                {
                    "type": "IR Button with 4 Operation Points",
                    "model": "05-348",
                    "address": "0D1C80",
                    "channels": 4,
                    "key": "1C"
                }
            ],

goofyke · February 5, 2026, 8:30pm

Thanks in advance for the two options!

Should I run the Nikobus address calculator if I also have the Nikobus software open and connected to the PC link? Or does it work on its own?

When I try to start the query module inventory, HA gives the following message: “Unknown action selected?”

What am I doing wrong?

fdebrus · February 5, 2026, 8:32pm

Yes, standalone “calculator”

fdebrus · February 5, 2026, 8:33pm

Yeap, not stable yet…

goofyke · February 6, 2026, 9:05pm

Hello,

I’ve adjusted the button_config. Hopefully, only the lights that need to be on will now turn on. Wow, it was worth the effort to get this right. I used the Nikobus address calculator because the query module inventory scan isn’t working yet. I noticed that HA found many more buttons than are programmed into my Nikobus installation. How is this possible?

Does the 12-channel dimming module also work with groups 1 and 2? What about a 6-channel roller shutter model? Only group 1?

I have a SONOFF SNZB-06P motion detector. It also has a light sensor. I want to create an automation with the motion detector as a trigger. The light shouldn’t turn on when it’s light, but should turn on when it’s dark. Unfortunately, I can’t select this option in HA, even though it does indicate it.

I also have a Sonoff camera. I can open the stream in VLC, but I can’t open it in HA. I keep getting the message “timeout” with both gen-camera and onvif.

Do you have any ideas how I can solve these two problems?

Regards, Dave

fdebrus · February 7, 2026, 2:18pm

Is your pclink module second hand ? It might have not been cleared from the previous install. Will look at your other question later. Busy weekend

fdebrus · February 7, 2026, 8:58pm

Only group 1