avr: added documentation about COM2 lines and protocol.

avr/modules/com2/README

@@ -0,0 +1,86 @@
+This is the inter-node communication protocol.
+
+Hardware
+========
+
+AqHome uses asynchronous serial communication, nodes are connected via a 4 lines:
+- 5V
+- GND
+- DATA (0V/3.3V)
+- ATTN (0V/3.3V)
+
+DATA and ATTN are only pulled low by nodes on the bus, never pulled high, this allows for multi-master
+mode. Every node sends data at will.
+
+
+5V, GND
+-------
+Power line 5V, mcu nodes use a voltage regulator to locally provide stable 3.3V.
+
+
+DATA
+----
+TTL-UART communication line (3.3V, 19200 Baud, 1 startbit, 8 databits, one stopbit, no parity bit->19200N1).
+
+
+ATTN
+----
+Whenever a node wants to send data it has to first check whether this line is HIGH. If it is, the sending
+node must pull down this line to GND to inform other nodes about the intent to send. This is used by mcu nodes
+as an interrupt source thus waking each node as soon as a message is to appear on the bus.
+After sending data via the DATA line the sending node has to release this line which is then automatically pulled
+HIGH by the logic on the power supply board.
+
+
+
+Protocol
+========
+
+The protocol is simple to reduce overhead and to keep the code size inside the mcu nodes small.
+There is no generic request-reply protocol. Messages a not repeated on the lowlevel layer. However,
+if a message can't be transmitted it might get retried later by the sending node (e.g. when reporting
+sensor data). Also, some operations consist of a request and a reply, but that's on a higher level (e.g. remotely setting a
+specific value in a node). The maximum size of a message is 24 bytes (max. 21 bytes payload).
+
+
+Basic Message Format
+--------------------
+
+Nodes communicate via messages. The first byte of every message is the destination node address, so every node can determine
+after the first byte whether it is interested in the following message. All nodes but the destination can immediately go back
+to sleep after receiving the first byte (they will be awoken again by ATTN going low for the next message).
+The next byte is the length of the remainder of the message (if any). The last byte is a CRC8 checksum byte.
+
+Offset Length Meaning
+---------------------------------------------------------
+     0      1 destination address
+     1      1 remaining message length
+---------------------------------------------------------
+     2      n payload data
+---------------------------------------------------------
+     2+n    1 CRC8 byte
+
+
+Command Messages
+----------------
+
+Command messages are an extension to the Basic Message Format specifying the first two bytes of the payload.
+The first byte of the payload is a command code (e.g. "100" for report of sensor data), followed by the
+bus address of the sender. The remainder of the payload is defined by the type of message(i.e. the message code).
+
+
+Offset Length Meaning
+---------------------------------------------------------
+     0      1 destination address
+     1      1 remaining message length
+---------------------------------------------------------
+     2      1 command code
+     3      1 source address
+---------------------------------------------------------
+     4      n payload data (depending on command code)
+---------------------------------------------------------
+     4+n    1 CRC8 byte
+
+
+
+