search

openlcb / documents

The OpenLCB specification: standards, recommended practices and other documentation.
3 stars 7 forks source link

The Message Standard is a little inconsistent in language around OIR contents #99

Closed bobjacobsen closed 2 weeks ago

bobjacobsen commented 5 months ago

Section 3.3.4 of the Message Standard says about the content of the Optional Interaction Rejected (OIR) message:

The data contents are, in order:

  • Two bytes of error code.
  • Two bytes of MTI. If the frame transport only delivered part of the MTI3, that content is returned with the rest of the MTI bits set to zero.
  • Any extra bytes that the node wishes to include. There can be zero or more of these, to a maximum of 64 bytes. These shall be described in the node documentation.

Unfortunately, section 3.5.1 which defines the OIR interaction references the fields in a different order:

it shall send an Optional-Interaction Rejected (OIR) message addressed to the originating node, with the original MTI in the message content to indicate that the MTI is not recognized or not implemented by this node. The OIR message content may also contain a reason code and a data value, as defined by the protocol

This order and the "may contain a reason code" language is a bit confusing, and has resulted in at least two implementations putting the MTI before the error code.

I would prefer that the relevant part of 3.5.1 be cleaned up by referring back to the single definition of the content, e.g.

it shall send an Optional-Interaction Rejected (OIR) message addressed to the originating node. This shall contain the fields defined in section 3.3.4.

dpharris commented 5 months ago

Bob et al. --

Thanks for this. While I do not think that Section 3.5.1 specifies any order, but simply lists the contents absent any specific order, eg "the original MTI in the message content" -- this just says it's there but does not indicate its position. Section 3.3.4 is definitive.

I do agree with your suggested change, as that should clarify the matter.

David

On Tue, Feb 13, 2024 at 2:03 PM Bob Jacobsen @.***> wrote:

Section 3.3.4 of the Message Standard says about the content of the Optional Interaction Rejected (OIR) message:

The data contents are, in order:

  • Two bytes of error code.
  • Two bytes of MTI. If the frame transport only delivered part of the MTI3, that content is returned with the rest of the MTI bits set to zero.
  • Any extra bytes that the node wishes to include. There can be zero or more of these, to a maximum of 64 bytes. These shall be described in the node documentation.

Unfortunately, section 3.5.1 which defines the OIR interaction references the fields in a different order:

it shall send an Optional-Interaction Rejected (OIR) message addressed to the originating node, with the original MTI in the message content to indicate that the MTI is not recognized or not implemented by this node. The OIR message content may also contain a reason code and a data value, as defined by the protocol

This order and the "may contain a reason code" language is a bit confusing, and has resulted in at least two implementations putting the MTI before the error code.

I would prefer that the relevant part of 3.5.1 be cleaned up by referring back to the single definition of the content, e.g.

it shall send an Optional-Interaction Rejected (OIR) message addressed to the originating node. This shall contain the fields defined in section 3.3.4.

— Reply to this email directly, view it on GitHub https://github.com/openlcb/documents/issues/99, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAEDQSQXOY4RSJFAPFQ4IALYTPPJZAVCNFSM6AAAAABDHH56CKVHI2DSMVQWIX3LMV43ASLTON2WKOZSGEZTGMRQGAYDQNQ . You are receiving this because you are subscribed to this thread.Message ID: @.***>