Skip to content

Naming of devices, channels, and data points

This is a description how naming is handled in AIO Homematic, there are additional rules applied for HA entities and devices.

This document explains how human-readable names are constructed for devices, channels, data points (including events and custom data points), and when unique IDs are used as a fallback.

The logic lives primarily in aiohomematic/model/support.py and relies on names stored in the CCU (device and channel names) plus some auto-generation helpers when no explicit names are available.

Terminology

For a complete terminology reference, see the Glossary.

  • Device: The physical device (e.g., HmIP-BROLL) identified by a device address (e.g., 000A1B2C3D4E00).
  • Channel: A sub-unit of a device identified by a channel address (e.g., 000A1B2C3D4E00:1). Channels may have a user-editable name in the CCU.
  • Data point: A parameter on a channel (e.g., LEVEL, STATE). These become entities in upper layers.
  • Address separator: : used between device address and channel number.

Device names

Function: get_device_name(central, device_address, model)

  • If a custom name was set in the CCU for the device address, that name is used.
  • Otherwise, an auto-generated name is returned: <model>_<device_address>.

Examples:

  • CCU has a name: "Livingroom Blind Controller" → returned as is.
  • No CCU name: model HmIP-BROLL, address 000A1B2C3D4E00 → HmIP-BROLL_000A1B2C3D4E00.

Channel names

Helpers: get_channel_name_data(channel) and _get_base_name_from_channel_or_device(channel)

  • If the channel has a custom name in the CCU and it differs from the default ("<model> <channel_address>"), that CCU channel name is used.
  • Otherwise a base name is derived from the device name:
  • If the channel has a channel number (channel.no not None), the base becomes <device_name>:<channel_no>.
  • If there is no channel number, the base is just <device_name>.

The returned ChannelNameData contains:

  • device_name: the resolved device name (see above)
  • channel_name: the channel part without the leading device name duplicated
  • full_name: <device_name> <channel_name> (when channel_name is not empty), otherwise just device_name
  • sub_device_name: equals the original channel name when present, otherwise device_name

Examples:

  • CCU channel name: "Livingroom Blind Controller:1" → device_name="Livingroom Blind Controller", channel_name=":1", full_name="Livingroom Blind Controller :1".
  • No CCU channel name: device name HmIP-BROLL_... and channel 1 → base HmIP-BROLL_...:1, which yields the same fields as above.

Note about channel number detection:

  • _check_channel_name_with_channel_no(name) returns true when the name contains exactly one : and the part after : converts to an integer.

Data point names (regular)

Function: get_data_point_name_data(channel, parameter) Steps:

  1. Resolve a channel_name via _get_base_name_from_channel_or_device as described above. If there is none, we cannot construct a human-readable name and fall back to unique IDs elsewhere.
  2. Build a human-friendly parameter name: parameter.title().replace("_", " ") (e.g., LEVEL → Level, WINDOW_STATE → Window State).
  3. If the channel name includes a numeric channel suffix (<something>:<int>):
  4. Use the part before : as the channel base (c_name).
  5. When the same parameter exists on multiple channels of the device, append a channel marker to the parameter: " ch<channel_no>" (omitted for channel 0 or None). Determination uses central.paramset_descriptions.is_in_multiple_channels(...).
  6. Example full name: <device_name> <c_name> <Parameter>[ chX].
  7. Otherwise, use the entire channel name plus parameter.

DataPointNameData contains:

  • device_name, channel_name, parameter_name and a computed name which is the channel+parameter without repeating the device name at the front. full_name is <device_name> <name>.

Examples:

  • Channel name "Livingroom Blind Controller:1", parameter LEVEL → name="Livingroom Blind Controller Level ch1", full_name="Livingroom Blind Controller Livingroom Blind Controller Level ch1" after de-duplication yields "Livingroom Blind Controller Level ch1".
  • Channel name "Window Contact", parameter STATE → name="Window Contact State".

Event names

Function: get_event_name(channel, parameter)

  • Similar to get_data_point_name_data, but when a numeric channel suffix is present, the channel part in the name becomes just " ch<channel_no>" (or empty for channel 0/None), followed by the human-friendly parameter name.
  • Otherwise the full channel name plus parameter is used.

Custom data point names

Function: get_custom_data_point_name(channel, is_only_primary_channel, ignore_multiple_channels_for_name, usage, postfix="")

  • If a numeric channel suffix is present and either the current channel is the only primary channel or multiple channels should be ignored for naming, the name uses the channel base (before :) and appends the provided postfix as the parameter name.
  • If a numeric channel suffix is present and the above condition is not met, the name uses the channel base and a generated parameter marker:
  • "ch<no>" for DataPointUsage.CDP_PRIMARY
  • "vch<no>" for others
  • Otherwise, if there is no numeric channel suffix, the channel name alone is used.

Hub data point names

Function: get_hub_data_point_name_data(channel_or_none, legacy_name, central_name)

  • If no channel is supplied, the full name becomes <central_name> <legacy_name>.
  • If a channel is supplied, the legacy name is cleaned (removing address/id parts) and used together with the resolved channel name, again trimming :<no> when present.

Fallback to unique IDs

When a readable name cannot be constructed (e.g., no device/channel name information is present), the code logs a debug message and the UI is expected to use a unique ID instead. Unique IDs are built by:

  • generate_unique_id(central, address, parameter=None, prefix=None) for data points.
  • generate_channel_unique_id(central, address) for channels.

Rules for IDs:

  • : and - are replaced with _.
  • Optional parameter and prefix are appended with underscore separators.
  • For CCU-internal addresses (PROGRAM, SYSVAR, INT000..., or virtual remote addresses), the central ID is prepended to ensure global uniqueness.
  • IDs are always returned in lowercase.

Worked examples

Below are end-to-end examples showing inputs (model, addresses, CCU names, channel numbers, parameters) and the produced names.

  1. Device names

  2. Input: model HmIP-BROLL, address 000A1B2C3D4E00, CCU device name = "Livingroom Blind Controller"

  3. Output device_name: Livingroom Blind Controller
  4. Fallback, if device name is not readable:

  5. Input: model HmIP-BROLL, address 000A1B2C3D4E00, CCU device name = none

    • Output device_name: HmIP-BROLL_000A1B2C3D4E00

  6. Channel names

  7. Input: device_name HmIP-SWDO_00112233445566, channel address ...:0, CCU channel name = default ("HmIP-SWDO ...:0")

  8. Base: HmIP-SWDO_00112233445566:0
  9. ChannelNameData.full_name: HmIP-SWDO_00112233445566 :0
  10. Input: CCU channel name explicitly set to "Window Contact" (no ":")
  11. ChannelNameData:
    • device_name: <resolved device name>
    • channel_name: Window Contact
    • full_name: <device_name> Window Contact
  12. Fallback, if channel name is not readable:

  13. Input: device_name Livingroom Blind Controller, channel address ...:1, CCU channel name = none

    • Base: Livingroom Blind Controller:1
    • ChannelNameData:
    • device_name: Livingroom Blind Controller
    • channel_name: :1
    • full_name: Livingroom Blind Controller :1
    • sub_device_name: Livingroom Blind Controller:1

  14. Data point names (regular)

  15. Input: channel base Window Contact (no ":"), parameter WINDOW_STATE

  16. Parameter friendly: Window State
  17. DataPointNameData.name: Window Contact Window State
  18. full_name: <device_name> Window Contact Window State
  19. Input: channel base HmIP-WTH-2_ABCDEF01234567:0, parameter present only on channel 0
  20. Because parameter is not in multiple channels, no ch0 is appended; name will be based on base without suffix logic.
  21. Input: channel base Livingroom Blind Controller:1, parameter LEVEL, parameter appears on multiple channels
  22. Parameter friendly: Level
  23. ch marker: ch1

  24. DataPointNameData:

    • name: Livingroom Blind Controller Level ch1
    • full_name: Livingroom Blind Controller Livingroom Blind Controller Level ch1 → effectively shown as Livingroom Blind Controller Level ch1

  25. Event names

  26. Input: channel base HmIP-WGC_99887766554433:2, parameter MOTION

  27. Event friendly parameter: Motion
  28. Numeric suffix present → channel part becomes ch2
  29. DataPointNameData.name: ch2 Motion
  30. full_name: <device_name> ch2 Motion
  31. Input: channel base Doorbell (custom channel name), parameter PRESS
  32. DataPointNameData.name: Doorbell Press

  33. full_name: <device_name> Doorbell Press

  34. Custom data point names

  35. Input: channel base Kitchen Light:3, usage = CDP_PRIMARY, only_primary_channel = false, ignore_multiple_channels_for_name = false

  36. Numeric suffix present → use base Kitchen Light and parameter marker ch3
  37. DataPointNameData.name: Kitchen Light ch3
  38. full_name: <device_name> Kitchen Light ch3
  39. Input: channel base Kitchen Light:3, usage = CDP_SECONDARY (not primary), only_primary_channel = false
  40. Marker becomes vch3
  41. full_name: <device_name> Kitchen Light vch3
  42. Input: channel base Kitchen Light:3, only_primary_channel = true, postfix = Brightness

  43. Name uses base and postfix: DataPointNameData.name: Kitchen Light Brightness

  44. Hub data point names

  45. Input: no channel, central_name CCU-Main, legacy_name program_trigger

  46. HubNameData.full_name: CCU-Main program_trigger
  47. Input: channel base System:0, legacy_name INT0001_PROGRAM_STATE_ABC (contains address/id fragments)
  48. Cleaned legacy name: PROGRAM STATE ABC
  49. Numeric suffix trimmed from channel → channel_name becomes System

  50. HubNameData.full_name: System PROGRAM STATE ABC

  51. Unique ID fallbacks

  52. Input: address ABCDEF12345678:4, parameter LEVEL

  53. generate_unique_id → abcdef12345678_4_level
  54. Input: address PROGRAM, parameter STATE, central_id ccu-main
  55. generate_unique_id → ccu-main_program_state
  56. Input: virtual remote address BidCos-RF:1, central_id ccu-main
  57. generate_channel_unique_id → ccu-main_bidcos_rf_1

Where to find the code

  • Main implementation: aiohomematic/model/support.py
  • Device name: get_device_name
  • Channel names: get_channel_name_data, _get_base_name_from_channel_or_device, _check_channel_name_with_channel_no
  • Data point names: get_data_point_name_data, get_event_name, get_custom_data_point_name, get_hub_data_point_name_data
  • Unique IDs: generate_unique_id, generate_channel_unique_id