doc:jroboplc:modules:jrbustcp-eng

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		 Previous revision
doc:jroboplc:modules:jrbustcp-eng [2026/01/21 20:00] – created denisdoc:jroboplc:modules:jrbustcp-eng [2026/01/21 20:06] (current) – denis
Line 5: Line 5:
 JRBusTCP is a proprietary binary communication protocol designed for efficient, deterministic data exchange between JRobo / JRoboPLC instances and client applications. The protocol operates over TCP/IP and is optimized for: JRBusTCP is a proprietary binary communication protocol designed for efficient, deterministic data exchange between JRobo / JRoboPLC instances and client applications. The protocol operates over TCP/IP and is optimized for:
  
-* High-frequency data exchange +  * High-frequency data exchange 
-* Minimal bandwidth usage +  * Minimal bandwidth usage 
-* Deterministic behavior suitable for automation and PLC-like systems +  * Deterministic behavior suitable for automation and PLC-like systems 
-* Explicit control over data serialization and transport+  * Explicit control over data serialization and transport
  
 The protocol follows a request/response model with client-initiated communication. All messages are framed, version-agnostic at transport level, and protected by CRC32 checksums. The protocol follows a request/response model with client-initiated communication. All messages are framed, version-agnostic at transport level, and protected by CRC32 checksums.
Line 18: Line 18:
 ===== 2. Transport Layer ===== ===== 2. Transport Layer =====
  
-* Transport protocol: **TCP** +  * Transport protocol: **TCP** 
-* Connection model: persistent TCP connection +  * Connection model: persistent TCP connection 
-* Byte order: **Big Endian** (network byte order) +  * Byte order: **Big Endian** (network byte order) 
-* Encoding for strings: **UTF-8**+  * Encoding for strings: **UTF-8**
  
 JRBusTCP does not define connection establishment beyond TCP. Session state (authentication, tag list, update state) is maintained per TCP connection. JRBusTCP does not define connection establishment beyond TCP. Session state (authentication, tag list, update state) is maintained per TCP connection.
Line 49: Line 49:
 ==== 3.2 Field Description ==== ==== 3.2 Field Description ====
  
-* **size** (2 bytes): Total message size in bytes, from `header` through `crc` inclusive +  * **size** (2 bytes): Total message size in bytes, from `header` through `crc` inclusive 
-* **header** (2 bytes): Constant magic value `0xABCD` +  * **header** (2 bytes): Constant magic value `0xABCD` 
-* **reqId** (4 bytes): Request identifier (int32, signed). Generated by client +  * **reqId** (4 bytes): Request identifier (int32, signed). Generated by client 
-* **cmd** (1 byte): Command code +  * **cmd** (1 byte): Command code 
-* **body** (variable): Command-specific payload +  * **body** (variable): Command-specific payload 
-* **crc** (4 bytes): CRC32 calculated over `[reqId..body]`+  * **crc** (4 bytes): CRC32 calculated over `[reqId..body]`
  
 ==== 3.3 Request Identifier (reqId) ==== ==== 3.3 Request Identifier (reqId) ====
  
-* Generated by the client +  * Generated by the client 
-* Initial value SHOULD be random +  * Initial value SHOULD be random 
-* Incremented by 1 for each subsequent request +  * Incremented by 1 for each subsequent request 
-* Server MUST return the same `reqId` value unchanged +  * Server MUST return the same `reqId` value unchanged 
-* Client MUST verify response `reqId` matches request+  * Client MUST verify response `reqId` matches request
  
 Server does not validate or interpret `reqId`. Server does not validate or interpret `reqId`.
Line 92: Line 92:
 Initializes tag list and session parameters. Initializes tag list and session parameters.
  
-==== Request ==== <code>+==== Request ====  
 +<code>
 cmd        : 0x01 cmd        : 0x01
 flen       : 1 byte flen       : 1 byte
Line 102: Line 103:
 ==== Flags Bitmask ==== ==== Flags Bitmask ====
  
-* b0: Client supports tag descriptions +  * b0: Client supports tag descriptions 
-* b1: Client supports tag status in READ +  * b1: Client supports tag status in READ 
-* b2: Exclude tags with `external` flag +  * b2: Exclude tags with `external` flag 
-* b3: Include tags with `hidden` flag+  * b3: Include tags with `hidden` flag
  
-==== Response ==== <code>+==== Response ====  
 +<code>
 cmd        : 0x81 cmd        : 0x81
 listsize   : 3 bytes (uint24) </code> listsize   : 3 bytes (uint24) </code>
Line 119: Line 121:
 Retrieves tag metadata in chunks. Retrieves tag metadata in chunks.
  
-==== Request ==== <code>+==== Request ====  
 +<code>
 cmd   : 0x02 cmd   : 0x02
 index : 3 bytes (uint24) </code> index : 3 bytes (uint24) </code>
  
-==== Response ==== <code>+==== Response ====  
 +<code>
 cmd      : 0x82 cmd      : 0x82
 index    : 3 bytes index    : 3 bytes
Line 130: Line 134:
 [tag entries] </code> [tag entries] </code>
  
-==== Tag Entry Format ==== <code>+==== Tag Entry Format ====  
 +<code>
 type    : 1 byte type    : 1 byte
 nlen    : 1 byte nlen    : 1 byte
Line 151: Line 156:
 Checks for tag value changes. Checks for tag value changes.
  
-==== Request ==== <code>+==== Request ====  
 +<code>
 cmd : 0x03 </code> cmd : 0x03 </code>
  
-==== Response ==== <code>+==== Response ====  
 +<code>
 cmd        : 0x83 cmd        : 0x83
 quantity   : 3 bytes quantity   : 3 bytes
Line 160: Line 167:
 liststate  : 1 byte </code> liststate  : 1 byte </code>
  
-* 0x00: tag list unchanged +  * 0x00: tag list unchanged 
-* 0xFF: tag list changed; client MUST re-run INIT + LIST+  * 0xFF: tag list changed; client MUST re-run INIT + LIST
  
 --- ---
Line 169: Line 176:
 Reads tag values. Reads tag values.
  
-==== Request ==== <code>+==== Request ====  
 +<code>
 cmd   : 0x04 cmd   : 0x04
 index : 3 bytes </code> index : 3 bytes </code>
  
-==== Response ==== <code>+==== Response ====  
 +<code>
 cmd      : 0x84 cmd      : 0x84
 index    : 3 bytes index    : 3 bytes
Line 182: Line 191:
 ==== Index Blocks ==== ==== Index Blocks ====
  
-* 0xFE: Next tag index, uint16 +  * 0xFE: Next tag index, uint16 
-* 0xFF: Next tag index, uint24+  * 0xFF: Next tag index, uint24
  
 ==== Value Encodings (Compact) ==== ==== Value Encodings (Compact) ====
  
-* 0xF0: false / zero +  * 0xF0: false / zero 
-* 0xF1: true / one +  * 0xF1: true / one 
-* 0xF2: 1-byte integer +  * 0xF2: 1-byte integer 
-* 0xF3: 2-byte integer+  * 0xF3: 2-byte integer
  
 ==== Value Encodings (Full) ==== ==== Value Encodings (Full) ====
  
-* 0xF8: int32 (4 bytes) +  * 0xF8: int32 (4 bytes) 
-* 0xF9: int64 (8 bytes) +  * 0xF9: int64 (8 bytes) 
-* 0xFA: double (8 bytes) +  * 0xFA: double (8 bytes) 
-* 0xFB: string (2-byte length + UTF-8 bytes)+  * 0xFB: string (2-byte length + UTF-8 bytes)
  
 Status bit: b4 of first value byte (if INIT.flags.b1 = 1) Status bit: b4 of first value byte (if INIT.flags.b1 = 1)
  
-* 1 = Good +  * 1 = Good 
-* 0 = Bad+  * 0 = Bad
  
 --- ---
Line 210: Line 219:
 Writes tag values. Writes tag values.
  
-==== Request ==== <code>+==== Request ====  
 +<code>
 cmd      : 0x05 cmd      : 0x05
 index    : 3 bytes index    : 3 bytes
Line 216: Line 226:
 [data blocks] </code> [data blocks] </code>
  
-==== Response ==== <code>+==== Response ====  
 +<code>
 cmd : 0x85 </code> cmd : 0x85 </code>
  
Line 225: Line 236:
 Returns CRC32 checksum of all tag values after last UPDATE. Returns CRC32 checksum of all tag values after last UPDATE.
  
-==== Request ==== <code>+==== Request ====  
 +<code>
 cmd : 0x06 </code> cmd : 0x06 </code>
  
-==== Response ==== <code>+==== Response ====  
 +<code>
 cmd : 0x86 cmd : 0x86
 crc : 4 bytes </code> crc : 4 bytes </code>
Line 236: Line 249:
 ===== 11. Authentication ===== ===== 11. Authentication =====
  
-==== AUTH_INIT (0x07) ==== <code>+==== AUTH_INIT (0x07) ====  
 +<code>
 request: request:
 cmd      : 0x07 cmd      : 0x07
Line 250: Line 264:
 Status: Status:
  
-* 0x00 OK +  * 0x00 OK 
-* 0x01 FAILED +  * 0x01 FAILED 
-* 0x02 DISABLED+  * 0x02 DISABLED
  
-==== AUTH_SUBMIT (0x08) ==== <code>+==== AUTH_SUBMIT (0x08) ====  
 +<code>
 request: request:
 cmd      : 0x08 cmd      : 0x08
Line 266: Line 281:
 Status: Status:
  
-* 0x00 ACCEPTED +  * 0x00 ACCEPTED 
-* 0xFF DENIED+  * 0xFF DENIED
  
 --- ---
Line 273: Line 288:
 ===== 12. Error Responses ===== ===== 12. Error Responses =====
  
-* 0xFE: UNAUTHENTICATED +  * 0xFE: UNAUTHENTICATED 
-* 0xFF: UNKNOWN+  * 0xFF: UNKNOWN
  
 --- ---
Line 280: Line 295:
 ===== 13. Session Lifecycle ===== ===== 13. Session Lifecycle =====
  
-1. TCP connect +  1. TCP connect 
-2. AUTH_INIT / AUTH_SUBMIT (optional) +  2. AUTH_INIT / AUTH_SUBMIT (optional) 
-3. INIT +  3. INIT 
-4. LIST (paged) +  4. LIST (paged) 
-5. UPDATE +  5. UPDATE 
-6. READ / WRITE +  6. READ / WRITE 
-7. CRC (optional) +  7. CRC (optional) 
-8. TCP disconnect+  8. TCP disconnect
  
 --- ---
Line 293: Line 308:
 ===== 14. Design Notes ===== ===== 14. Design Notes =====
  
-* Protocol favors deterministic binary layout +  * Protocol favors deterministic binary layout 
-* Compact encodings reduce bandwidth +  * Compact encodings reduce bandwidth 
-* Explicit pagination avoids oversized frames +  * Explicit pagination avoids oversized frames 
-* reqId enables async request matching +  * reqId enables async request matching 
 + 
 --- ---
  
Line 308: Line 323:
 ===== 16. Diagrams ===== ===== 16. Diagrams =====
  
-==== 16.1 Typical Session Sequence ==== <code>+==== 16.1 Typical Session Sequence ====  
 +<code>
 Client                          Server Client                          Server
 |                                 | |                                 |
Line 330: Line 346:
 |                                 | </code> |                                 | </code>
  
-==== 16.2 Binary Layout: READ Response ==== <code>+==== 16.2 Binary Layout: READ Response ====  
 +<code>
 +---------+------+---------+-----------+-----------+----------------+ +---------+------+---------+-----------+-----------+----------------+
 | reqId   | cmd  | index   | quantity  | next      | data blocks    | | reqId   | cmd  | index   | quantity  | next      | data blocks    |
Line 336: Line 353:
 +---------+------+---------+-----------+-----------+----------------+ </code> +---------+------+---------+-----------+-----------+----------------+ </code>
  
-==== 16.3 Binary Layout: WRITE Request ==== <code>+==== 16.3 Binary Layout: WRITE Request ====  
 +<code>
 +---------+------+---------+-----------+----------------+ +---------+------+---------+-----------+----------------+
 | reqId   | cmd  | index   | quantity  | data blocks    | | reqId   | cmd  | index   | quantity  | data blocks    |
Line 348: Line 366:
 ==== 17.1 Why Not JSON / Protobuf ==== ==== 17.1 Why Not JSON / Protobuf ====
  
-* Determinism: binary layouts provide predictable parsing cost +  * Determinism: binary layouts provide predictable parsing cost 
-* Zero allocations: no intermediate object trees required +  * Zero allocations: no intermediate object trees required 
-* Bandwidth efficiency: compact numeric encodings outperform JSON +  * Bandwidth efficiency: compact numeric encodings outperform JSON 
-* Schema stability: no dependency on external IDL or runtime reflection+  * Schema stability: no dependency on external IDL or runtime reflection
  
 ==== 17.2 Why TCP and Not UDP ==== ==== 17.2 Why TCP and Not UDP ====
  
-* Guaranteed delivery and ordering +  * Guaranteed delivery and ordering 
-* Built-in congestion control +  * Built-in congestion control 
-* Simplified client/server implementations +  * Simplified client/server implementations 
-* NAT/firewall friendly+  * NAT/firewall friendly
  
 --- ---
Line 364: Line 382:
 ===== Appendix A: Examples ===== ===== Appendix A: Examples =====
  
-==== A.1 INIT Request (hex dump) ==== <code>+==== A.1 INIT Request (hex dump) ====  
 +<code>
 00 1A AB CD 00 00 00 01 01 00 1A AB CD 00 00 00 01 01
 05 2E 2A 00 06 4A 52 6F 62 6F 05 2E 2A 00 06 4A 52 6F 62 6F
Line 370: Line 389:
 A1 B2 C3 D4 </code> A1 B2 C3 D4 </code>
  
-==== A.2 READ Response (single INT32 value) ==== <code>+==== A.2 READ Response (single INT32 value) ====  
 +<code>
 00 14 AB CD 00 00 00 05 84 00 14 AB CD 00 00 00 05 84
 00 00 01 00 00 01 00 00 00 00 00 01 00 00 01 00 00 00
Line 382: Line 402:
 ==== B.1 Latency ==== ==== B.1 Latency ====
  
-* Typical RTT dominated by TCP latency +  * Typical RTT dominated by TCP latency 
-* Binary parsing cost negligible +  * Binary parsing cost negligible 
-* Suitable for polling rates up to several kHz on LAN+  * Suitable for polling rates up to several kHz on LAN
  
 ==== B.2 Batching ==== ==== B.2 Batching ====
  
-* READ/WRITE support bulk operations +  * READ/WRITE support bulk operations 
-* Clients SHOULD batch contiguous tag indices +  * Clients SHOULD batch contiguous tag indices 
-* Server SHOULD maximize quantity per response until size limit reached+  * Server SHOULD maximize quantity per response until size limit reached
  
 ==== B.3 UPDATE Polling Strategy ==== ==== B.3 UPDATE Polling Strategy ====
  
-* Poll UPDATE at fixed interval (e.g., 10–100 ms) +  * Poll UPDATE at fixed interval (e.g., 10–100 ms) 
-* Issue READ only when quantity > 0 +  * Issue READ only when quantity > 0 
-* Use CRC command to validate full state synchronization when needed+  * Use CRC command to validate full state synchronization when needed
  
  • doc/jroboplc/modules/jrbustcp-eng.1769014802.txt.gz
  • Last modified: 2026/01/21 20:00
  • by denis