emqx/apps/emqx_bridge_syskeeper/doc/protocol_v1.md

# Table of Contents

1.  [Packet Format](#orgb2a43d1)
2.  [Common Header](#org5ca4c69)
    1.  [Types](#org240efb3)
    2.  [Shared Flags](#org804fcce)
3.  [Handshake Packet](#org6a73ea8)
4.  [Forward Packet](#org39c753e)
    1.  [Flags](#org5177d26)
    2.  [Payload](#orgb29cbd7)
        1.  [Message Content map structure](#org75acfe6)
5.  [Heartbeat Packet](#org388b69a)


<a id="orgb2a43d1"></a>

# Packet Format

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;bytes&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;0&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;1&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;2&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;3&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;6&nbsp;..&nbsp;end&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td colspan="4" align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;variable&nbsp;length&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;common&nbsp;header&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;payload&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
</table>

The length of the remaining part(common header + payload) is indicated by the Length Header of each packet


<a id="org5ca4c69"></a>

# Common Header

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;bits&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;0&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;1&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;2&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;3&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;4&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;5&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;6&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;7&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td colspan="4" align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;packet&nbsp;type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td colspan="4" align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;shared&nbsp;flags&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
</table>


<a id="org240efb3"></a>

## Types

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;type&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;usage&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;handshake&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;forward&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;heartbeat&nbsp;
    </td>
  </tr>
</table>


<a id="org804fcce"></a>

## Shared Flags

The usage of each bit is determined by the type of packet


<a id="org6a73ea8"></a>

# Handshake Packet

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;bytes&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;common&nbsp;header&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;version&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
</table>


<a id="org39c753e"></a>

# Forward Packet

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;bits&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;0&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;1&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;2&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;3&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;4&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;5&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;6&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;7&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;...&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td rowspan="2" align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td colspan="4" rowspan="2" align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />
      &nbsp;&nbsp;packet&nbsp;type&nbsp;&nbsp;<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td colspan="3" align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;ACK&nbsp;
    </td>
    <td rowspan="2" align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br />
      &nbsp;&nbsp;payload&nbsp;&nbsp;<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td colspan="4" align="left" valign="top">
      &nbsp;&nbsp;forward&nbsp;flags&nbsp;&nbsp;
    </td>
  </tr>
</table>


<a id="org5177d26"></a>

## Flags

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;flag&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;usage&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;ACK&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;This&nbsp;packet&nbsp;need&nbsp;a&nbsp;ACK&nbsp;response&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
</table>


<a id="orgb29cbd7"></a>

## Payload

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;bytes&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;0&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;..&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;n&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;n+1&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;..&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;x&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td colspan="3" align="left" valign="top">
      &nbsp;&nbsp;Content&nbsp;Length&nbsp;&nbsp;&nbsp;
    </td>
    <td colspan="3" align="left" valign="top">
      &nbsp;Message&nbsp;Content&nbsp;
    </td>
  </tr>
</table>

-   Content length is a variable length number.
-   Message content is a list in an opaque binary format whose element is a map structure


<a id="org75acfe6"></a>

### Message Content map structure

    {
      id: "0006081CCFF3D48F03C10000058B0000", // unique message id
      qos: 1,
      flags: {dup: false, retain: false},
      from: "clientid",
      topic: "t/1",
      payload: "hello, world",
      timestamp: 1697786555281
    }


<a id="org388b69a"></a>

# Heartbeat Packet

<!-- This HTML table template is generated by emacs 29.0.92 -->
<table border="1">
  <tr>
    <td align="left" valign="top">
      &nbsp;bytes&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
  </tr>
  <tr>
    <td align="left" valign="top">
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    </td>
    <td align="left" valign="top">
      &nbsp;common&nbsp;header&nbsp;
    </td>
  </tr>
</table>