Skip to content

shv serial link layer

Jump to bottom
Fanda Vacek edited this page Jun 19, 2023 · 26 revisions

SHV serial link layer

TCP/IP / Stream

RPC communication is checked by TCP protocol. The socket is closed in the case of an error on the client or server side, and the whole communication is re-established. The error is also raised when no byte is received for 5 seconds on an incomplete message.

+--------+------+
| length | data |
+--------+------+

data consist of two parts

  • protocol_type - 1 byte
    • 01 - Chainpack
    • 02 - Cpon (deprecated)
    • 03 - Json (deprecated)
  • RpcData - RpcMessage encoded according to protocol type, ChainPack in most cases.

UDP

+------+
| data |
+------+

protocol_type and data have the same meaning like in stream case.

CAN-FD (DRAFT)

data is split to N frames. There are 4 types of frame

Scenarios:

  1. SFM frame is lost
    • receiver doesn't get message
    • sender will timeout waiting for response
  2. MFM_START frame is lost
    • receiver will not get START message, so it cannot start session
    • receiver will ignore all CONT and END messages, because there is not session SRC active
    • sender will timeout waiting for response
  3. MFM_CONT frame is lost
    • receiver will get END message with invalid CRC
    • receiver will cancel active session
    • sender will timeout waiting for response
  4. MFM_END frame is lost
    • receiver will not get END message
    • receiver will timeout and cancel active session
    • sender will timeout waiting for response
  5. MFM_END frame has invalid CRC
    • receiver will get END message with invalid CRC
    • receiver will cancel active session
    • sender will timeout waiting for response
  6. More senders will send MFM simultaneously to one receiver
    • will receive first START message and starts receive session for sender with SRC address
    • receiver will ignore all messages with senders with different SRC than one from current session
    • first sender will send message
    • othert senders will timeout waiting for response
  7. Receiver has active session and MFM_START message is received
    • receiver can parse first frame and decode SHV request ID. Then it can create RPC response device bussy and reply with RPC Exception. This can avoid waiting till timeout on the sender side. Sender also will know that receiver is connected and alive, what is more information than the tomeout can provide.

Priorities:

  1. SFM has highest priority, they should be used for notification
  2. MFM_START should have higher priority than MFM_CONT to enable other client to start new session in paralel with existing session
  3. MFM_CONT should have the lowest priority
  4. MFM_END should have higher priority, than MFM_CONT to allow finishing session when other long message is sent.
  5. MFM_END should have higher priority, than MFM_START to allow finishing session before new one is started.
  6. Having this priorities we can transmit 2 frame long message (START + END) whilst other very long session is active.
  7. When 2 long sessions run in paralel, then CONT messages from device with lower ID wil be delivered first.
Frame type Value Priority Note
SFM 0 0 Single frame message, highest priority
MFM_START 2 2 First frame of multi frame message, higher priority than CONT
MFM_CONT 3 3 Next frame(s) of multi frame message
MFM_END 1 1 Last frame of multi frame message with CRC32

CAN ID structure

+---------------+----------------+---------------------------+
| 1 bit channel | 2 bit priority | 8 bit src device address  |
+---------------+----------------+---------------------------+
  • priority
  • src device address - address of sender device.

Frames

  • frame type
    • SFM - Single frame message. SFM does not need CRC, since it is part of CAN frame already
    • MFM - Multi frame message, consisting of MFM_START + MFM_CONT* + MFM_END 
SFM
+---------------------------+------------------------+----------------------+ 
| 8 bit dest device address | 8 bit frame type (SFM) | 8 bit payload length |
+---------------------------+------------------------+----------------------+ 
+----------------------+
| 0 - 61 bytes payload |
+----------------------+

MFM_START
+---------------------------+------------------------------+
| 8 bit dest device address | 8 bit frame type (MFM_START) |
+---------------------------+------------------------------+
+------------------+
| 62 bytes payload |
+------------------+

MFM_CONT
+---------------------------+-----------------------------+----------------------+ 
| 8 bit dest device address | 8 bit frame type (MFM_CONT) | 8 bit payload length |
+---------------------------+-----------------------------+----------------------+ 
+-----------------------+
| 58 - 61 bytes payload |
+-----------------------+

MFM_END
+---------------------------+----------------------------+----------------------+ 
| 8 bit dest device address | 8 bit frame type (MFM_END) | 8 bit payload length |
+---------------------------+----------------------------+----------------------+ 
+----------------------+
| 4 - 61 bytes payload |
+----------------------+
+------------+
| 32 bit CRC |
+------------+

CRC32 must not be split between frames.

TODO: MFM_CONT needs some counter to prevent frames duplicates due to packet duplication. TODO: We need some packet that signals device overload (no ability to press new messages for some time)

USB HID (DRAFT)

HID profile supports Control and Interrupt messages only. The Interrupt ones are used.

SFM
+---+---+----------+------------------------+
| 8 bit frame type | 0 - 1023 bytes payload |
+---+---+----------+------------------------+

MFM_START
+---+---+----------+--------------------+
| 8 bit frame type | 1024 bytes payload |
+---+---+----------+--------------------+

MFM_CONT
+---+---+----------+-------------------------+
| 8 bit frame type | 1023-1024 bytes payload |
+---+---+----------+-------------------------+

MFM_END
+---+---+----------+----------------------+---------------+
| 8 bit frame type | 0-1022 bytes payload | 4 bytes CRC32 |
+---+---+----------+----------------------+---------------+

RS485 Fatek (DRAFT)

image

  • Slave notifications are not supported as the RS485 is single-master and slave cannot initiate communication. We can implement it in future, when the bus master will periodically poll clients with PING command code TODO. If the slave will have data to send, then it reply with data containing notification data
  • Frames have the same structure as for USB HID
  • Command code 47(Write to continuous registers) will be used for frames transfer
  • Frames data will be coded as HEX
  • Max payload length is 127B
  • If the message sent to slave is RPC request then the response data must be send in immediate Fatek response to this message. If the slave cannot create the response as quickly, then it must be polled using PING command.

RS232 / Serial

+-----+------+-----+-------+
| STX | data | ETX | CRC32 |
+-----+------+-----+-------+
  • STX start of message 0xA2
  • ETX end of the message 0xA3
  • ESTX escapd STX code 0xA4
  • EETX escaped ETX code 0xA5
  • ESC escape 0xAA
    • STX in data will be coded as ESC ESTX
    • ETX in data will be coded as ESC EETX
    • ESC in data will be coded as ESC ESC
  • data - escaped message data (RPC message coded in chainpack)
  • CRC32 - escaped BigEndian CRC32 of data (POSIX CRC32)

The message is considered invalid when no bytes are received for 5 seconds.

Special messages defined:

  • STX ETX CRC - reset socket
Clone this wiki locally