From ab0922ed39267caac3d563ee8b0356b31f823506 Mon Sep 17 00:00:00 2001 From: Norman To Date: Mon, 19 Jun 2023 21:59:45 -0400 Subject: [PATCH 1/5] EMB-27360: Add enum for SubAck and ClearSubsAck. --- src/hardware/addon-protocols/rs232-usb.md | 26 +++++++++++++---------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/src/hardware/addon-protocols/rs232-usb.md b/src/hardware/addon-protocols/rs232-usb.md index 15edb7ae0..65d69543c 100644 --- a/src/hardware/addon-protocols/rs232-usb.md +++ b/src/hardware/addon-protocols/rs232-usb.md @@ -598,16 +598,16 @@ Messages sent from the IOX to the GO is represented by IoxToGo Messages sent from the GO to the IOX is represented by IoxFromGo example of building protobuf in python: - +``` iox_to_go=iox_messaging_pb2.IoxToGo() iox_to_go.pub_sub.sub.topic = 1 #TOPIC_ACCEL iox_to_go_seralized = iox_to_go.SerializeToString() - +``` After the protobuf is built, we will get payload "0a040a020801" The content of complete .proto is as below. - +``` // Possible subscription topics // Includes status data IDs enum Topic { @@ -652,7 +652,9 @@ message SubAck { // Unsubscribe fails if the topic has not been subscribed to SUB_ACK_RESULT_TOPIC_NOT_SUBBED = 5; // Unsubscribe fails if the subscription belongs to another IOX. - SUB_ACK_RESULT_SUBSCRIPTION_NOT_AVAILABLE = 6; + SUB_ACK_RESULT_UNAVAILABLE = 6; + // IOX Pub/Sub is not enabled by Master Switch. + SUB_ACK_RESULT_DISABLED = 7; } Result result = 1; Topic topic = 2; @@ -671,13 +673,15 @@ message TopicInfoList { repeated TopicInfo topics = 1; } -message ClearSubAck { +message ClearSubsAck { enum Result { - CLEAR_SUB_ACK_RESULT_UNSPECIFIED = 0; - // Unsubscribe succeeded - CLEAR_SUB_ACK_RESULT_SUCCESS = 1; - // Unsubscribe fails if the subscription belongs to another IOX. - CLEAR_SUB_ACK_RESULT_FAILED = 2; + CLEAR_SUBS_ACK_RESULT_UNSPECIFIED = 0; + // Clear subscription succeeded + CLEAR_SUBS_ACK_RESULT_SUCCESS = 1; + // Clear subscription failed: The subscription is owned by another IOX. + CLEAR_SUBS_ACK_RESULT_UNAVAILABLE = 2; + // Clear subscription failed: Pub/Sub is not enabled by Master Switch. + CLEAR_SUBS_ACK_RESULT_DISABLED = 3; } Result result = 1; } @@ -769,5 +773,5 @@ message IoxFromGo { PubSubFromGo pub_sub = 1; } } - +``` From 237877ef2112416c41968839f52b95bda3e308ad Mon Sep 17 00:00:00 2001 From: Norman To Date: Tue, 20 Jun 2023 10:49:50 -0400 Subject: [PATCH 2/5] EMB-27360: Describe the behaviour when Iox Pub/Sub is not enabled. --- src/hardware/addon-protocols/rs232-usb.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/hardware/addon-protocols/rs232-usb.md b/src/hardware/addon-protocols/rs232-usb.md index 65d69543c..a2ef76934 100644 --- a/src/hardware/addon-protocols/rs232-usb.md +++ b/src/hardware/addon-protocols/rs232-usb.md @@ -774,4 +774,8 @@ message IoxFromGo { } } ``` - +Note: The IOX Pub/Sub is controlled by a Master-Switch. When IOX Pub/Sub is not enabled: +* Request to subscribe/unsubscribe a topic will be responded with SUB_ACK_RESULT_DISABLED. +* Request to clear the subscription will be responded with CLEAR_SUBS_ACK_RESULT_DISABLED. +* Request to list the subscription will be responded with an empty list. +* Request to list all available topics will be responded with an empty list. From 2f803c15424dffe15c7121848e1f63bff7cba6c9 Mon Sep 17 00:00:00 2001 From: Norman To Date: Wed, 21 Jun 2023 12:02:49 -0400 Subject: [PATCH 3/5] EMB-27360: Link message 0x26 and 0x8C to Appendix D. --- src/hardware/addon-protocols/rs232-usb.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/hardware/addon-protocols/rs232-usb.md b/src/hardware/addon-protocols/rs232-usb.md index a2ef76934..9df5e6b75 100644 --- a/src/hardware/addon-protocols/rs232-usb.md +++ b/src/hardware/addon-protocols/rs232-usb.md @@ -247,7 +247,7 @@ The information includes a payload containing data encoded in the protobuf forma | Checksum | 2 | 3+x | | ETX (0x03) | 1 | 5+x | -The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Please see Appendix D for the payload details. +The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Refer to [Appendix D: IOX Pub/Sub protobuf data packets in message type 0x8C, 0x26](#Appendix-D:-IOX-Pub/Sub-protobuf-data-packets-in-message-type-0x8C,-0x26). ### Msg Type 0x27: Add-On protocol version to external device @@ -445,7 +445,7 @@ Sent by the external device to subscribe to various topics/information. The GO d | ETX (0x03) | 1 | 5 + x | | Reply: Protobuf data packet ([Msg Type 0x26](#msg-type-0x26-Protobuf-data-packet)) | -The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Please see Appendix D for the payload details. +The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Refer to [Appendix D: IOX Pub/Sub protobuf data packets in message type 0x8C, 0x26](#Appendix-D:-IOX-Pub/Sub-protobuf-data-packets-in-message-type-0x8C,-0x26). ## Messages from MyGeotab @@ -592,7 +592,7 @@ This is an example of binary data packets for image data transferred using the M | Checksum | 2 | 12+x | | ETX (0x03) | 1 | 14+x | -### Appendix D: Using protobuf Messages to Communicate by using 0x8C, 0x26 +### Appendix D: IOX Pub/Sub protobuf data packets in message type 0x8C, 0x26 Messages sent from the IOX to the GO is represented by IoxToGo Messages sent from the GO to the IOX is represented by IoxFromGo From a2b58aa179205936e7b4bdf10808f0721ea6e91a Mon Sep 17 00:00:00 2001 From: Norman To Date: Wed, 21 Jun 2023 12:34:53 -0400 Subject: [PATCH 4/5] EMB-27360: Fix the links. --- src/hardware/addon-protocols/rs232-usb.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/hardware/addon-protocols/rs232-usb.md b/src/hardware/addon-protocols/rs232-usb.md index 9df5e6b75..1ce5332c2 100644 --- a/src/hardware/addon-protocols/rs232-usb.md +++ b/src/hardware/addon-protocols/rs232-usb.md @@ -247,7 +247,7 @@ The information includes a payload containing data encoded in the protobuf forma | Checksum | 2 | 3+x | | ETX (0x03) | 1 | 5+x | -The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Refer to [Appendix D: IOX Pub/Sub protobuf data packets in message type 0x8C, 0x26](#Appendix-D:-IOX-Pub/Sub-protobuf-data-packets-in-message-type-0x8C,-0x26). +The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Refer to [Appendix D: IOX PubSub protobuf data packets in message type 0x8C, 0x26](#appendix-d-iox-pubsub-protobuf-data-packets-in-message-type-0x8c-0x26). ### Msg Type 0x27: Add-On protocol version to external device @@ -428,7 +428,7 @@ Sent by the external device when requesting the add on protocol version number. | Message Body Length = 0 | 1 | 2 | | Checksum | 2 | 3 | | ETX (0x03) | 1 | 5 | -| Reply: Third-Party version Ack Reply ([Msg Type 0x27](#msg-type-0x27-add-on-version-to-external-device)) | +| Reply: Third-Party version Ack Reply ([Msg Type 0x27](#msg-type-0x27-add-on-protocol-version-to-external-device)) | ### Msg Type 0x8C: Protobuf data packet @@ -445,7 +445,7 @@ Sent by the external device to subscribe to various topics/information. The GO d | ETX (0x03) | 1 | 5 + x | | Reply: Protobuf data packet ([Msg Type 0x26](#msg-type-0x26-Protobuf-data-packet)) | -The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Refer to [Appendix D: IOX Pub/Sub protobuf data packets in message type 0x8C, 0x26](#Appendix-D:-IOX-Pub/Sub-protobuf-data-packets-in-message-type-0x8C,-0x26). +The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Refer to [Appendix D: IOX PubSub protobuf data packets in message type 0x8C, 0x26](#appendix-d-iox-pubsub-protobuf-data-packets-in-message-type-0x8c-0x26). ## Messages from MyGeotab @@ -592,7 +592,7 @@ This is an example of binary data packets for image data transferred using the M | Checksum | 2 | 12+x | | ETX (0x03) | 1 | 14+x | -### Appendix D: IOX Pub/Sub protobuf data packets in message type 0x8C, 0x26 +### Appendix D: IOX PubSub protobuf data packets in message type 0x8C, 0x26 Messages sent from the IOX to the GO is represented by IoxToGo Messages sent from the GO to the IOX is represented by IoxFromGo From 3483c9003993709360235dd04138c1308c811815 Mon Sep 17 00:00:00 2001 From: Norman To Date: Wed, 21 Jun 2023 15:36:24 -0400 Subject: [PATCH 5/5] EMB-27360: Moved Master switch description into message 0x26. --- src/hardware/addon-protocols/rs232-usb.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/hardware/addon-protocols/rs232-usb.md b/src/hardware/addon-protocols/rs232-usb.md index 1ce5332c2..651b4b48b 100644 --- a/src/hardware/addon-protocols/rs232-usb.md +++ b/src/hardware/addon-protocols/rs232-usb.md @@ -236,6 +236,14 @@ Issued by the GO device on receipt of Binary Data of 256 bytes or more from the Available with add-on protocol version >= 1.2. Issued by the GO device in response to Msg Type 0x8C. Also issued by the GO device to publish information for the topics (defined in Appendix D) subscribed by the third party device. +

+**Note:** The IOX Pub/Sub is controlled by a Master-Switch. When IOX Pub/Sub is not enabled: +* Request to subscribe/unsubscribe a topic will be responded with SUB_ACK_RESULT_DISABLED. +* Request to clear the subscription will be responded with CLEAR_SUBS_ACK_RESULT_DISABLED. +* Request to list the subscription will be responded with an empty list. +* Request to list all available topics will be responded with an empty list. +

+ The information includes a payload containing data encoded in the protobuf format. | | Bytes | Position | @@ -774,8 +782,3 @@ message IoxFromGo { } } ``` -Note: The IOX Pub/Sub is controlled by a Master-Switch. When IOX Pub/Sub is not enabled: -* Request to subscribe/unsubscribe a topic will be responded with SUB_ACK_RESULT_DISABLED. -* Request to clear the subscription will be responded with CLEAR_SUBS_ACK_RESULT_DISABLED. -* Request to list the subscription will be responded with an empty list. -* Request to list all available topics will be responded with an empty list.