From 5d8db10fbf0822dc79facb25cd9b09d2d0bf60ae Mon Sep 17 00:00:00 2001
From: john30 <ebusd@ebusd.eu>
Date: Tue, 26 Nov 2019 20:57:20 +0100
Subject: [PATCH] updated to next generation of enhanced protocol

---
 docs/enhanced_proto.md | 90 ++++++++++++++++++++++++++----------------
 1 file changed, 55 insertions(+), 35 deletions(-)

diff --git a/docs/enhanced_proto.md b/docs/enhanced_proto.md
index cf4d7f53..cc9503de 100644
--- a/docs/enhanced_proto.md
+++ b/docs/enhanced_proto.md
@@ -1,50 +1,70 @@
+## Transfer speed
+
+In order to compensate potential overhead of transfer encoding, the transfer speed is set to 9600 Baud with 8 bits, no parity, and 1 stop bit.
+
+
 ## Protocol
+Data bytes with a value below 0x80 can be transferred as is.
 
-Every communication in either direction is prefixed with at most one byte indicating the kind of action/result.
+Data bytes with value above or equal to 0x80 are split up into two bytes, each one with the highest bit set to 1.
+The second bit indicates whether it is the first or second byte of a split transfer. This way protocol errors can easily be detected.
+The bits in the two bytes look like this:
 
-### from ebusd to device
- * initialization (after connect)  
-   `<INIT>`  
-   This is not yet implemented in ebusd and supposed to be enhanced by another byte requesting certain features.
- * send request  
-   `<SEND> <symbol>`  
-   Requests the specified symbol to be sent to the eBUS.
+```
+first    second
+76543210 76543210
+11ccccdd 10dddddd
+```
+4 bits in `c` are used for indicating a special purpose and is set to one of the command request/response symbols as stated below.  
+8 bits in `d` are the data byte to be transferred (might also be unused).
+
+### Command request/response symbols
+
+#### from ebusd to device
+ * initialization request  
+   `<INIT> <features>`  
+   Requests an initialization of the device and requests special features in the data byte (tbd).
+ * send data request  
+   `<SEND> <data>`  
+   Requests the specified data byte in `d` to be sent to the eBUS.  
+   For data byte values <0x80, the short form without the `<SEND>` prefix is allowed as well.
  * arbitration start request  
-   `<START> <master address>`  
-   Requests the start of the arbitration process with the specified master address after the next received `<SYN>` symbol.
+   `<START> <master>`  
+   Requests the start of the arbitration process after the next received `<SYN>` symbol with the specified master address in `d`.
 
-### from device to ebusd
-  * initialization (after re-connect)  
-    `<RESETTED>`  
-    Indicates a reboot or an initial ebusd connection on the device.  
-    This is actually desired to be enhanced by another byte in future indicating availability of certain features (like full message sending instead of arbitration onnly).
-  * symbol received from eBUS  
-    `<RECEIVED> <symbol>`  
-    Indicates that the specified symbol was received from the eBUS.
-  * arbitration start succeeded  
-    `<STARTED>`  
-    Indicates that the last arbitration request was successful (arbitration was won).
+#### from device to ebusd
+  * initialization response  
+    `<RESETTED> <features>`  
+    Indicates a reboot or an initial ebusd connection on the device and is expected to be returned after an `<INIT`> request.  
+    The data byte `d` indicates availability of certain features (like full message sending instead of arbitration only, tbd).
+  * receive data notification  
+    `<RECEIVED> <data>`  
+    Indicates that the specified data byte in `d` was received from the eBUS.  
+    For data byte values <0x80, the short form without the `<RECEIVED>` prefix is allowed as well.
+  * arbitration start succeeded
+    `<STARTED> <info>`  
+    Indicates the the last arbitration request succeeded (arbitration was won).  
+    The data byte in `d` may contain additional information (tbd).
   * arbitration start failed  
-    `<FAILED>`  
-    Indicates that the last arbitration request failed (arbitration was lost or sending failed).
+    `<FAILED> <master>`  
+    Indicates that the last arbitration request failed (arbitration was lost or sending failed).  
+    The data byte in `d` contains the address of the master that won the arbitration.
 
 
 ## Symbols
 
 These are the predefined symbols as used above.
 
-### Generic
+### Bus symbols
  * SYN 0xAA
 
-### From ebusd to device
- * INIT 0x00
- * SEND 0x01
- * START 0x02
-
-### From device to ebusd
- * RESETTED 0x00
- * RECEIVED 0x01
- * STARTED 0x02
- * FAILED 0x82
-
+### Command request symbols (from ebusd to device)
+ * INIT 0x0
+ * SEND 0x1
+ * START 0x2
 
+### Command response symbols (from device to ebusd)
+ * RESETTED 0x0
+ * RECEIVED 0x1
+ * STARTED 0x2
+ * FAILED 0xa