minor improvements + example

git-svn-id: https://svn.spreadspace.org/mur.sat@22 7de4ea59-55d0-425e-a1af-a3118ea81d4c

1 files changed, 50 insertions, 21 deletions

diff --git a/doc/protocols/ihu-cpu.txt b/doc/protocols/ihu-cpu.txt
index 6cd9b74..fad1ffa 100644
--- a/doc/protocols/ihu-cpu.txt
+++ b/doc/protocols/ihu-cpu.txt
@@ -5,14 +5,14 @@ Protocol Definition between IHU and CPU
 Introduction
 ------------
 
-The two controllers use SPI to communicate with each other. In 
+The two controllers use SPI to communicate with each other. In
 addition to the 4 Lines needed for SPI there are 2 extra connections
 between IHU and CPU. One is for the IHU to reset the CPU. Holding
 this pin low prevents the CPU from running and therefore keeps
 power consumption at a minimum, after a low to high transition the CPU
 has to perform a hardware reset.
-The second line is used by the CPU to inform the IHU that it wishes 
-to communicate. After this line goes high the IHU has to start the 
+The second line is used by the CPU to inform the IHU that it wishes
+to communicate. After this line goes high the IHU has to start the
 communication by starting the SPI clock.
 
 
@@ -21,24 +21,27 @@ Frames
 
 The following chart shows a single frame which is used for communication
 
-Fieldlength:   1      1      1        LEN          1
+Field-length:  1      1      1        LEN          1
             +------+------+------+--------------+------+
 Name        | 0xAA | MSG  | LEN  |    DATA      | CS   |
             +------+------+------+--------------+------+
 
-Every message frame starts with 0xAA followed by a message code and 
-the length of the following data. The length field might be zero if the 
-message doesn't need any additional data. The last byte of every frame
-contains a checksum. It is calculated by XORing every byte of the message.
+Every message frame starts with 0xAA followed by a message code and
+the length of the following DATA field. The length field might be zero
+if the message doesn't need any additional data. The last byte of every
+frame contains a checksum. It is calculated by XORing every variable byte
+of the message. In a message N bytes long, where Byte 1 is the first and Byte
+N the last Byte, CS is calculated starting with Byte 2 (MSG) and ending
+with Byte N-1 (last DATA Byte)
 The minimum frame length is 4 Bytes and the maximum is 260 Bytes.
 The bytes have to be sent LSB first. Multi byte fields have to be sent
-in little endian format.
+in Little-Endian format.
 
 
 Messages
 --------
 
-Messages are seperated in request and responses. Requests use upper case 
+Messages are separated in request and responses. Requests use upper case
 letters and replies use lower case.
 
  'F' - Finish up (IHU -> CPU)
@@ -47,18 +50,18 @@ letters and replies use lower case.
  Sent by the IHU.
 
  This command tells the CPU that the IHU is planning to shut down
- the CPU after ?? ms. The CPU has to write pending flash pages and put 
+ the CPU after ?? ms. The CPU has to write pending flash pages and put
  payload hardware into deep sleep. After finishing everything up the CPU
- has to go into power down. 
+ has to go into power down.
  This command doesn't send any data.
 
  Expected response: 'f'
- 
+
 
  'P' - Ping, Time and Power Budget (IHU -> CPU)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 
- Thic command is sent by the IHU every minute (??) and contains the
+
+ This command is sent by the IHU every minute (??) and contains the
  following data:
 
   2Bytes Power Budget (see Power Management for details)
@@ -70,7 +73,7 @@ letters and replies use lower case.
  'T' - Get Time (CPU -> IHU)
  ~~~~~~~~~~~~~~
 
- This command requests the current time. 
+ This command requests the current time.
 
  Expected response: 't'
 
@@ -79,18 +82,44 @@ letters and replies use lower case.
  'f' - Ack to finish up (CPU -> IHU)
  ~~~~~~~~~~~~~~~~~~~~~~
 
- Sent as an aknowledge to a preceding 'F'.
+ Sent as an acknowledge to a received 'F'.
 
 
  'p' - Ack to finish up (CPU -> IHU)
  ~~~~~~~~~~~~~~~~~~~~~~
 
- Sent as an aknowledge to a preceding 'P'.
+ Sent as an acknowledge to a received 'P'.
+
 
- 
  't' - Get Time (IHU -> CPU)
  ~~~~~~~~~~~~~~
 
- Sends the current timestamp after a preceding 'T' request.
- This message sends the 4 Byte timestamp (seconds since EPOCH)
+ Sends the current Timestamp after receiving a 'T' request.
+ This message sends the 4 Byte Timestamp (seconds since EPOCH)
  as data.
+
+
+Example Communication
+---------------------
+
+IHU sends a Ping to CPU, telling it that the current power
+budget is 2424 units of power and the current time is
+1305501574 seconds since epoch. The CPU acknowledges the
+message.
+
+IHU->CPU:  0xAA 'P' 0x06 0x09 0x78 0x4d 0xd0 0x5f 0x86 0x63
+CPU->IHU:  0xAA 'p' 0x00 0x70
+
+
+Power Management
+----------------
+
+FIXME
+
+
+
+Notes
+-----
+
+EPOCH is the arbitrary point in time where Timestamp is 0x00000000.
+(depending on choice of RTC, probably 1970-01-01 00:00)