Document all MQTT JSON objects (payload)

[tukusejssirs]

Okay, now to the MQTT payloads and topics. Note that I tested this on a single machine. Note that this would be useful to document somewhere (like in the docs/ folder within the repo), where I’d move all the fanuc-driver documentation (even from README.md).

TL;DR

Document all MQTT JSON objects. I could not find any in depth documentation of payload object (there’s a bit of it in README.md, but it isn’t much).

DISCO

1. The first topic is $SYS/{broker_id}/new/clients. Its payload contains 2e58c25b4bb14c9ba7b86efb0c1838b1—what is it for? I could not find it anywhere else in the payloads.

2. brokerCounter can be used to make sure no messages are omited and that they are processed in order, right?

3. Please describe the contents of payload in fanuc/DISCO.

   a. At first I though that added and seen are timestamps (UNIX epoch), but they are not and they are same in every fanuc/DISCO topic.

   b. Why do we have machineId when the whole object is named as the machine ID?

   c. What is the purpose of arrivalTopic and changeTopic? Again they are all the same in every fanuc/DISCO topic.

4. I understand that qos is quality of service and is used for message prioritisation.

5. As I understand the docs, when retain is set to true, those topics are changes to the previous machine state (and there the downstream apps should process it).

6. dup (I presume it stands for duplicate) which is always set to false in my output. Is there any situation when dup is set to true?

Order of topics

7. What is used order of messages/topics? From what I can see, it is something like this:

   a. First topic is always $SYS/{broker_id}/new/clients.

   b. Second topic is always fanuc/DISCO. This topic always comes before any other topics.

   c. Third topic is always fanuc/{machine_id}/connect.

8. What is the different between fanuc/{machine-id} and fanuc/{machine-id}-all? From my tests, both contain/broadcast the same data.

Deltas

Related: MQTT Payload Structure - Suggested

9. As I understand it, first delta objects of each (let’s say) type contains all information of that particular type, but all subsequent deltas contain only the changes to that particular type, right? However, there are some exceptions to this rule, which always contain the same data, for example:

• fanuc/{machine_id}/connect, where it always contains the time since (?) fanuc-driver start and if it was successfully connected;
• fanuc/{machine_id}/cnc_id, where it always contains the time since (?) fanuc-driver start and cncid;
• fanuc/{machine_id}/cnc_id, where it always contains the time since (?) fanuc-driver start, minute and msec.

Anyway, I have no idea why fanuc/{machine_id}/connect and fanuc/{machine_id}-all/connect have different time values.

That said, I don’t think that the above-mentioned exceptions above should be called the deltas. I suggest to rename it to something like metadata or status (or whatever else). Usually, a delta is a difference between the previous version and current version, but the above information is not a delta in this sense.

[MRIIOT]

Okay, now to the MQTT payloads and topics. Note that I tested this on a single machine. Note that this would be useful to document somewhere (like in the docs/ folder within the repo), where I’d move all the fanuc-driver documentation (even from README.md).

TL;DR

Document all MQTT JSON objects. I could not find any in depth documentation of payload object (there’s a bit of it in README.md, but it isn’t much).

DISCO

1. The first topic is $SYS/{broker_id}/new/clients. Its payload contains 2e58c25b4bb14c9ba7b86efb0c1838b1—what is it for? I could not find it anywhere else in the payloads.

$SYS is MQTT broker internal stuff.

2. brokerCounter can be used to make sure no messages are omited and that they are processed in order, right?

Don't know.

3. Please describe the contents of payload in fanuc/DISCO.

Discovery topic is there for discovery of what machines are online and their relevant topics. Disco is controlled by:

broker:
      publish_disco: !!bool true
      disco_base_topic: fanuc

a. At first I though that added and seen are timestamps (UNIX epoch), but they are not and they are same in every fanuc/DISCO topic.

Data is published to discovery whenever a Fanuc controller is interrogated with a Focas call.

b. Why do we have machineId when the whole object is named as the machine ID?

True. It is redundant.

c. What is the purpose of arrivalTopic and changeTopic? Again they are all the same in every fanuc/DISCO topic.

arrivalTopic - data is published whether it changed or not.
changeTopic - data is published only when it has changed.

Controlled with:

broker:
      publish_status: !!bool true
      publish_arrivals: !!bool true
      publish_changes: !!bool true

publish_status: publish heartbeat to fanuc/machineid/PING

Most of these configuration settings are relevant to l99.driver.fanuc.handlers.Native, fanuc handler.

4. I understand that qos is quality of service and is used for message prioritisation.

qos is used for message delivery. qos 0 - fire/forget, qos 1 - require that broker acks, qos 2 - require that a receiving client acks... if i remember correctly.

5. As I understand the docs, when retain is set to true, those topics are changes to the previous machine state (and there the downstream apps should process it).

The purpose of retain is that the last message hangs out at the broker forever (or configurable in MQTT5), so when a new client connects and subscribes, it receives that message, instead of hanging around until a publisher sends a new message.

6. dup (I presume it stands for duplicate) which is always set to false in my output. Is there any situation when dup is set to true?

ahhh, I forget.

Order of topics

1. What is used order of messages/topics? From what I can see, it is something like this:
   a. First topic is always $SYS/{broker_id}/new/clients.
   b. Second topic is always fanuc/DISCO. This topic always comes before any other topics.
   c. Third topic is always fanuc/{machine_id}/connect.
2. What is the different between fanuc/{machine-id} and fanuc/{machine-id}-all? From my tests, both contain/broadcast the same data.

You will see that fanuc/{machine-id}-all receives more messages. All Focas responses are published there every single sweep. This is not the case with fanuc/{machine-id}. Messages there are only published when Focas responses change.

Deltas

Related: MQTT Payload Structure - Suggested

1. As I understand it, first delta objects of each (let’s say) type contains all information of that particular type, but all subsequent deltas contain only the changes to that particular type, right? However, there are some exceptions to this rule, which always contain the same data, for example:

• fanuc/{machine_id}/connect, where it always contains the time since (?) fanuc-driver start and if it was successfully connected;
• fanuc/{machine_id}/cnc_id, where it always contains the time since (?) fanuc-driver start and cncid;
• fanuc/{machine_id}/cnc_id, where it always contains the time since (?) fanuc-driver start, minute and msec.

Yeah, delta would be the "difference". Maybe a better name here would be "state" ?

Anyway, I have no idea why fanuc/{machine_id}/connect and fanuc/{machine_id}-all/connect have different time values.

Because fanuc/{machine_id}/connect "reports by exception" or "on state change" or "on data change". In which case:

"data" { "success" : true }

is the same as the previous sweep of the series of Focas calls.

fanuc/{machine_id}-all/connect reports every second (or whatever the interval is set to) regardless of data changes.

That said, I don’t think that the above-mentioned exceptions above should be called the deltas. I suggest to rename it to something like metadata or status (or whatever else). Usually, a delta is a difference between the previous version and current version, but the above information is not a delta in this sense.

Correct, 'state' makes more sense. delta.time or state.time is the interval between status.data changes.

"delta": {
    "time": "00:00:01.2500674",
    "data": {
      "success": true
    }
  }

"state": {
    "time": "00:00:01.2500674",
    "data": {
      "success": true
    }
  }

[MRIIOT]

At first I though that added and seen are timestamps (UNIX epoch), but they are not and they are same in every fanuc/DISCO topic.

It is, ms since 1970.

[tukusejssirs]

Related to #28. Sorry for issue duplication, my memory does not serve me well at times. 😉

[tukusejssirs]

Once you told me that you want keep the dynamic typing (as opposed to static typing). I think that within the code (internal stuff), do as you wish, however, the user facing stuff (API, MQTT payload, …) should be strongly typed.

[MRIIOT]

Once you told me that you want keep the dynamic typing (as opposed to static typing). I think that within the code (internal stuff), do as you wish, however, the user facing stuff (API, MQTT payload, …) should be strongly typed.

Should, it takes more time. And as you can see, the payloads are forever changing.