From 240624c727bff5ca73f9d1f215daae5e0fb57868 Mon Sep 17 00:00:00 2001 From: Martin Preuss Date: Sun, 26 Apr 2026 12:47:14 +0200 Subject: [PATCH] avr: added README. --- avr/modules/network/README | 83 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 avr/modules/network/README diff --git a/avr/modules/network/README b/avr/modules/network/README new file mode 100644 index 0000000..6b4f1ba --- /dev/null +++ b/avr/modules/network/README @@ -0,0 +1,83 @@ +This is the inter-node communication protocol. + +Hardware +======== + +AqHome uses synchronous serial communication, nodes are connected via 4 lines: +- 5V +- GND +- DATA (0V/3.3V) +- ATTN (0V/3.3V) + +DATA and ATTN are only pulled low by nodes on the bus, pulled high only by a single node in the network via pull-up +resistor. This allows for multi-master mode. Every node sends data at will (after checking for free line). +In most cases the pull-up resistors are installed on the node with the 5V power supply. + + +5V, GND +------- +Power line 5V, mcu nodes use a voltage regulator to locally provide stable 3.3V. + + +DATA +---- +Data line, normally high, bits are sampled on the rising edge. + + +CLK +---- +Clock line, normally high. Pulled down at the beginning of a transmission, held low for a short time to let +other nodes on the network discover this state. After that data is clocked out on the DATA line at the rising edge +of the CLK line. + + + +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 are not repeated on the lowlevel layer. However, +if a message can't be transmitted because of a busy line 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. The last byte is a CRC8 checksum byte although this +is for historical reasons not a real CRC8 checksum (due to an implementation error in early versions). + +Offset Length Meaning +--------------------------------------------------------------- + 0 1 destination address + 1 1 remaining message length (excluding the CRC byte) +--------------------------------------------------------------- + 2 n payload data +--------------------------------------------------------------- + 2+n 1 CRC 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 remaining payload data (depending on command code) +---------------------------------------------------------------- + 4+n 1 CRC byte + + +