Naming convention for channels?

Does any formal or informal naming convention exist for naming channels? System channel types are named with lowercase and dashes, like system.low-battery. However, in bindings I’ve seen this as well as camel case, with underscores etc.:

  • lowBattery
  • low-battery
  • battery_low

Is there any preferred/recommended naming?

I introduced some new channels recently and would like to rename them before 3.2, if needed for compliance, in order to not do breaking changes after that.

Best regards,
Jacob Laursen

You’re right on this topic. IIRW dev guideline states that channel names should be camelCase, while on the other hand system channel are dash-separated.
On my side, I find it easier to read in UI with dashes but you’ll find a mix of it amongst bindings.
So, when I work on an existing binding, I use its convention - when creating a new one, I use dash-separated.

1 Like

camelCase is preferred but seems that if someone submits a binding with dash-separated it may still get merged. If you use the constant class that the skeleton script creates, you can keep the channel ID out of your code so that if you need to change it, then it only needs to change in the xml and the BindingIdConstants class file.

@matt1 - do you know if it is documented anywhere that camelCase is preferred?

Secondary question: Since renaming a channel is a breaking change, I’m wondering if it’s possible in code to dynamically check if any items are linked to a specific channel that doesn’t exist? That would make it possible to dynamically create the channel for backwards compatibility if needed, and otherwise avoid creating it.

If this is not possible, it might be worth to introduce a property in the framework for marking channels as deprecated, so the UI could hide them when there are no linked items, and otherwise show them with a deprecation warning.

1 Like

It is documented here

I have seen a way in the framework to mark things as hidden/ not listed.They will then not be shown to be added via the UI but will keep working if someone has already added them.

For channels not sure if something similar exists.

However I believe the stance for a non merged binding will be that until it is merged it should be considered as Beta and doing a breaking change to keep the code cleaner is probably what will be wanted.

Some bindings have been merged with non camelCase for various reasons, but if there is no reason to do otherwise then camelCase is preferred and encouraged.

1 Like

Thanks @matt1. So I think I’ll create an issue with a proposal for adding listed="false" for channels. I’m asking in context of already merged code as I would like to get rid of some old channel:

Also, as a binding evolves, many new channels might be introduced, and at some point it might make sense to introduce channel groups for sake of overview. However, this is also a breaking change. So there are multiple use-cases for being able to deprecate channels:

  • Misspelled or misleading names.
  • Functionality behind them no longer supported.
  • Refactoring like dividing into channel groups or conforming to naming conventions.
1 Like

Remains the case of system channels, that are not camel cased.

If it is a merged binding then use whatever convention that the binding is already using to keep changes as low as possible. With people using textual files think how annoying it is if the binding changes or has mixed conventions.

For people that use the UI to auto create equipment, the label is important as the label goes into the items names. Labels should be 2-3 words long, be descriptive and each word start with a capital.

I was trying to do something like this when migrating from channel without channel group (e.g. 25539) to channel linked to a channel group (e.g. scenes#25539) which seems like a normal migration path as a binding evolves:

ChannelGroupUID channelGroupUid = new ChannelGroupUID(thing.getUID(), HDPowerViewBindingConstants.CHANNEL_GROUP_SCENES);
for (Scene scene : scenes) {
    String channelId = Integer.toString(scene.id);
    ChannelUID channelUid = new ChannelUID(getThing().getUID(), channelId);
    String description = translationProvider.getText("dynamic-channel.scene-activate.deprecated.description", scene.getName());
    Channel channel = ChannelBuilder.create(channelUid, CoreItemFactory.SWITCH).withType(sceneChannelTypeUID)
            .withLabel(scene.getName()).withDescription(description).build();
    logger.debug("Creating deprecated channel for scene {} to probe for linked items", scene.id);
    updateThing(editThing().withChannel(channel).build());
    if (this.isLinked(channelUid)) {
        logger.warn("Created deprecated channel for scene {} ('{}'), please link items to '{}' instead",
                scene.id, scene.getName(), new ChannelUID(channelGroupUid, channelId).getId());
    } else {
        logger.debug("Removing deprecated channel for scene {} since no linked items", scene.id);
        updateThing(editThing().withoutChannel(channelUid).build());
    }
}

I had five items linked to the new channels (with group) and one item linked to old channel without group (also linked to one with group). Unexpectedly the new channels were detected as linked as it seems group is not considered in this scenario:

Switch PowerViewHub_Scene_Private {channel="hdpowerview:hub:hub:scenes#25539", autoupdate="false"}
Switch PowerViewHub_Scene_Private_Legacy {channel="hdpowerview:hub:hub:25539", autoupdate="false"}

So item configured as linked to channel without group is not linked to channel if same name belonging to group. Seems correct.

But item configured as linked to channel with group is linked also to channel of same name without group. Bug or feature?

Best regards,
Jacob Laursen