naming conventions for topics

[Robert Poor]

Is there a general convention for naming topics?  In particular, consider these three cases in a device that has a set of relays.  Note that the relays may not change at the moment that they are asked to:

1. payload contains a request to set the relays to a given state.
2. payload contains the current state of the relays
3. payload is empty, message is a request to report the current state of the relays

What would you name the topic for the three cases above?  Without knowing any of the conventions, I would imagine something like:

1. relay/set_state
2. relay/state
3. relay/request_state

... but I defer to folks on this list more deeply steeped in the MQTT lore.  Thanks!

- rdp

[Matt Lloyd]

My personal convention would be {collection}/{item}/[set | state]

So for a collection of `relays` a single `id` or `name` for one relay of a possible many, then `set` and `state` topics and use a retained publish onto state topic, then there is no need to request it since any new connection would be told the last known state

relays/{relay id/name}/set

relays/{relay id/name/state (retained)

Matt

--
To learn more about MQTT see https://mqtt.org
---
You received this message because you are subscribed to the Google Groups "MQTT" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mqtt+uns...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/mqtt/69e9f9db-fc6f-45a5-8010-d89cad2ecadfn%40googlegroups.com.

[Robert Poor]

Matt:

Looks good .  (And yes, we could wild-card the relay_id if we want all the relays).

You are right about not needing "request_state" if state is retained by the broker.  In our specific case (for obscure reasons) our broker may not be able to retain that state.  

Many thanks.

[Robert Poor]

Matt: P.S. I cross posted my question on stackoverflow:

   https://stackoverflow.com/questions/73452333/naming-conventions-for-mtt-topics

If you're active on stackoverflow, please post your answer there so I can mark it as the accepted answer.  (And so other people can learn from your answer).  Thanks!

[Greg Troxel]

Robert Poor <rdp...@gmail.com> writes:

> Is there a general convention for naming topics? In particular, consider
> these three cases in a device that has a set of relays. Note that the
> relays may not change at the moment that they are asked to:
>

> 1. payload contains a request to set the relays to a given state.
> 2. payload contains the current state of the relays
> 3. payload is empty, message is a request to report the current state of
> the relays

You are running into "While MQTT is a protocol, saying 'use MQTT' is not
a protocol specification, even though people act like it is."

It sounds like you are writing code for both sides, so you can of course
do anything you want.

I would suggest looking into home automation projects and aligning with
what they do. That's useful because their scheme has almost certainly
worked for a lot of people, and because you might want to integrate with
such a program.

You are talking about a set of relays, so one obvious question is if you
want a single logical entity with a bit vector of relays, or a set of
entities each with one relay. If the relays can get hooked up to
different things, vs being intrinsically linked, I would suggest
modeling them as separate entities.

I use Home Assistant (HA), and the concept that matches a relay is
"switch". Note that when reading the HA docs the "switch" is the
logical entity in HA, and it represents the physical entity.
One can create an "MQTT switch" device with homegrown code, or with
things like ESPhome or ESPeasy.

https://www.home-assistant.io/integrations/switch.mqtt/

In my case, I have a switch entity which is not in the same place as the
HA instance. It's good to think about what happens as the control or
the device is restarted and with or without power independently when
designing your control protocol.

Physically, the switch is an ESP8266 with a GPIO hooked to the control
outlet of a power strip with a relay, and there's a light plugged into
the power strip. The ESP8266 runs nodemcu with a bit of hand-written
Lua code. My config* is literally (with real name switched to foo):

switch:
# FOO
- platform: mqtt
name: "Foo main light"
state_topic: "sensor/foo/main/light"
command_topic: "sensor/foo/main/light/set"
#availability_topic: "sensor/foo/main/online"
retain: true

* This is out of date; now one uses top-level mqtt and then switch, but
that's irrelevant to the present discussion.

The device accepts commands on ../light/set and reports state to
../light.

This sets retain so that messages to ../set have the retain flag. That
means that if the ESP8266 powers up or reconnects after the light has
been turned on or off, it will be in the right state. Retained topics
are useful, but you can't tell when the device is gone vs when it just
hasn't said anything in a long time. The ESP8266 sets retain on status
messags.

The ../online topic is ON if the ESP8266 is connected to the broker;
it's not about the relay. The point, were it enabled, is to have the
light control in HA greyed out if the ESP8266 is offline. This is done
by posting ON on connect and setting a lwt to post OFF.

Another thing to look is ESPHome, which is code to do what I'm doing
where you just configure it rather than writing code. It has native HA
integration, not on point here, and MQTT where it also publishes
metadata for autoconfig. What's useful for this discussion is the
topic protocol it uses.

https://esphome.io/components/mqtt.html#mqtt-component-base-configuration

I quote:

state_topic (Optional, string): The topic to publish state updates
to. Defaults to
<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state.

command_topic (Optional, string): The topic to subscribe to for
commands from the remote. Defaults to
<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/command.


so this uses foo/state and foo/command, whereas I am using foo and
foo/command. That's close, though.

(There is complexity about availability topics. One can use ON/OFF like
main entities, or online/offline. I prefer to use ON/OFF as I view the
availability_topic as first a binary sensor for "is the device
connected" and secondarily to grey out the child entities of the
device.)

All in all I would suggest you align with ESPHome if there isn't a good
reason to do otherwise. It probably has the biggest mindshare in
defining this admittedly arbitrary convention.

[Ivan Mari]

I think you should check SparkPlugB: https://sparkplug.eclipse.org/

--
To learn more about MQTT see https://mqtt.org
---
You received this message because you are subscribed to the Google Groups "MQTT" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mqtt+uns...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/mqtt/rmi4jy3e0b5.fsf%40s1.lexort.com.

[Bob Frankston]

In a sense, MQTT is like email -- just a relay and nothing more. So asking for content standards is a separate issue among consenting communities. Personally I would see standardizing on JSON bundles for application families is an interesting topic in it's own right across MQTT, HTTP,, and other paths.

[Robert Poor]

Greg:

| On Tue, Aug 23, 2022 at 3:12 AM Greg Troxel  <g...@lexort.com> wrote:

| …

| availability_topic: "sensor/foo/main/online"

I’m glad to see the “availability” topic-many IoT developers fail to include a means to identify the point of failure: was it the sensor? The microcontroller? The wifi link?  The router?  The cloud?  Etc.  Good stuff. 

On Tue, Aug 23, 2022 at 3:12 AM Greg Troxel <g...@lexort.com> wrote:

[Robert Poor]

Bob : 

Short note (difficult on an iPhone) just to say it’s nice to see you here.  RSVP if you want a longer rant about how MQTT does too much, or not enough, depending on how you define it. 

-rdp

You received this message because you are subscribed to a topic in the Google Groups "MQTT" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/mqtt/5Bdc9hDaG9Y/unsubscribe.
To unsubscribe from this group and all its topics, send an email to mqtt+uns...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/mqtt/4d10897b-0a72-4df0-84fa-6c891e6fe454n%40googlegroups.com.

[Greg Troxel]

Ivan Mari <ivan...@gmail.com> writes:

> I think you should check SparkPlugB: https://sparkplug.eclipse.org/

It looks like something you have to join and the resources tab does not
have a protocol specfication or other public-facing nerd-readable
documents. Am I missing something?

[Ivan Mari]

Here is the spec: https://www.eclipse.org/tahu/spec/Sparkplug%20Topic%20Namespace%20and%20State%20ManagementV2.2-with%20appendix%20B%20format%20-%20Eclipse.pdf

[Arlen Nipper]

The Sparkplug spec is completely open source.

You can join the Slack channel as well.

The Eclipse Tahu GitHub also contains reference implementation code in Java, Python, Javascript and C:

https://github.com/eclipse/tahu

-Arlen

--
To learn more about MQTT see https://mqtt.org
---
You received this message because you are subscribed to the Google Groups "MQTT" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mqtt+uns...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/mqtt/CAO4C7t%3DwLbnaQvW_KfL6EqD3sSg--Lo5Ecj5YXKV_uytFYhooQ%40mail.gmail.com.

[Bob Frankston]

Spark seems to be a very specific use case. Also, these days, JSON bundles are best practice rather than wiring in MQTT-specific data formats.

[Sumeet Puri]

my 2c:

Topic describes the event (and given that network today is faster/has more bandwidth than disk, we can transfer state via events, rather than just notifications). 

Topics (and REST URLs, JMS topics, AMQP topics, MQTT Topics) should follow a taxonomy convention so that your enterprise over time just gets used to them, and interoperability network protocols can be seamless.

With these principles, a topic naming convention should contain 3 sections - Noun (object) + Verb (action) + meta data (for filtering, and routing). 

Noun could be one or more segments, use as "relay" in your case. Verb would be "start, stop, reset" - state changes. Meta data would have domain, location, version etc. 

Here is a very detailed article about topic best practices across a few industries, including OT/connected car for MQTT at the bottom of the page. 

https://docs.solace.com/Messaging/Topic-Architecture-Best-Practices.htm

But to keep things simple, Noun + Verb + Meta data has stood the test of time.

Regards,

Sumeet.

To view this discussion on the web visit https://groups.google.com/d/msgid/mqtt/3521ffab-72fa-48cd-b494-de59bf7ffe00n%40googlegroups.com.