Help understanding devices vs entities vs ConfigEntries

I’m trying to write my first integration. The device is an immersion heater thermostat, which supports a simple UDP protocol, including discovery. I have this working well with each device creating a single climate entity. The code is here.

I now want to add a second entity (a binary sensor) for each device to report on the state of the heating relay. I understand that I now need to switch to using a DataUpdateCoordinator so that a single UDP request to the device can fetch the necessary data for both entities, but I’m struggling to understand how this fits together, and specifically where I should do discovery, and the relationship between a ConfigEntry and a device.

Should I end up with one ConfigEntry for each device, and if so, how does ConfigEntry a config entry get created from the discovery process? I’ve been staring at the docs, but can’t quite figure out how to apply them to this setup.

Any help would be greatly appreciated, or even just a pointer to a comparable existing integration that I could use as a code sample.

Have you tried asking on the Home Assistant Discord chat? I’ve had a lot more success with issues asking in the relevant channel :slight_smile:

OK, hopefully this pointer will help you.

  1. You do not need to use a DataUpdateCoordinator but it is recommended to have a class that controls updating data from your devices and your entities get their data from that. A DataUpdateCoordinator is probably the easiest to use but it is optional.

  2. A ConfigEntry is unique to the instance of an integration. I think in your case, you have 1 instance picking up multiple devices. As such, you should only have a single configEntry.

Have a look at this.

it is similar to your use case but not exacly. However, it shows how to use a coordinator and how to link entities to devices based on using the same device_info to do that.

Thanks for the reply, that’s very helpful.

The bit that I don’t quite get is that I think that I want to end up with multiple coordinators, one for each device, so that each device is polled independently, and if one device were to go offline, timeouts waiting for data from that device wouldn’t interfere with online devices.

All the examples I can find seem to use one coordinator per config entry, so I’m wondering if I should move to having one instance of the integration per device. At the moment I’m not saving any info in the config entry - it just (re)discovers all devices when the integration is loaded.

I finally found an existing component which seems similar, and which fires off multiple co-ordinators from a single config entry - the gree component - and I’ve now got something similar working in my code.

I suspect that the reason this arrangement is uncommon is because it’s a custom discovery mechanism, but there’s no auth or other config needed, so no need to store anything in the ConfigEntry.