christian mock <cm@tahina.priv.at> 2007/2008			-*- text -*-
The whole project is hereby released under the GPL version 2.

Credits
-------

Based on:

- obdev's AVRUSB firmware-only USB implementation
  (http://www.obdev.at/products/avrusb/index.html) and remote sensor
  project (http://www.obdev.at/products/avrusb/remotesensor.html)

- Andreas Weber's driver for the RFM12 modules
  (http://www.tech-chat.de/files/rf12.tar.gz)

Web page at http://www.tahina.priv.at/electronics.html

License
-------

This project is licensed under the GNU GPL v2, which can be found in
the file "COPYING".

What is it?
-----------

It's a system to send measurement data from sensor boards to a PC over
a radio link and USB, using Atmel AVR microcontrollers, Hoperf
(www.hoperf.com) radio modules, and obdev's AVRUSB firmware-only USB
implementation. 

My only sensor at the moment is a temperature and humidity sensor
based on Sensirion's SHT11 chip (www.sensirion.com), powered by 2 AA
cells. See sensor-v2.{png,sch} for the schematic, and the directory
firmware/sensor for the firmware.

The receiver board forwards the packets received on the radio to the
PC via USB, and on the PC a daemon (linux only, but if you want to
port it to windows, feel free) logs the data and prepares it for
graphing tools like cricket (cricket.sourceforge.net). See
receiver-v2.{sch,png} for the schematic, and the directory
firmware/receiver for the firmware. The PC software is in host/.

Additionally, a kind-of spectrum analyzer is provided, which runs on
the receiver and PC, scans the whole frequency band that the radio
module is capable of tuning, and tries to find the signal level there.
Due to the limitations of the radio module, this is not very accurate.
To use it, flash the spectrum analyzer firmware to the receiver board
(make burn-spectrum in firmware/receiver), and run "spectrum" from the
host/ directory.


Indicator LEDs
--------------

The receiver board has 3 indicator LEDs, red, yellow and green.

During startup, those flash in the sequence red-yellow-green. When the
board is ready, the green LED lights. The green LED flashes for USB
activity and the yellow LED for radio activity. The red LED indicates
that data packets are waiting for the host to pick them up.

Antenna
-------

On the sensor module, I use a "coil" antenna as seen in
http://www.mikrocontroller.net/attachment/29379/STE_190008_1.PDF .
On the receiver, it's just a 8cm piece of wire.

Message formats
---------------

The sensor setup aims at being extensible, i.e. it should be able to
handle all kinds of sensors. The message formats are the same on the
air and on the USB, so the receiver can be rather stupid, it just has
to handle the framing of packets for the radio link and doesn't care
about the message contents.

Overall message format:

+-----------------------------+ \
| sender                      |  \
+-----------------------------+    message header
| seq                         |  /
+-----------------------------+ /
| sensor reading header #1    |
+-----------------------------+
| sensor reading data #1      |
+-----------------------------+
| sensor reading header #2    |
+-----------------------------+
| sensor reading data #2      |
+-----------------------------+
| ...                         |


Message header:

struct message_header {
  uint8_t sender;
  uint8_t seq;
};

"sender" is the sending module's ID.

"seq" is the sequence number of the message; the module increments it
after each message it sends, but not for retransmissions of the same
message (messages are sent multiple times by the sensors to increase
reliability; no bidirectional protocol for acknowledging is used).
It's the host software's responsibility to handle duplicates and
missing packets.


Sensor readings:

struct reading_header {
  uint8_t len: 2;  // number of bytes - 1
  uint8_t type: 6; // type
};

"len" gives the length of this sensor reading; actually, it contains
length-1, so readings can be 1-4 bytes long.

"type" is the type of the sensor reading, see below for a list.

The next byte(s) in the message (according to len) are the sensor
reading. 

There can be multiple sensor readings per packet, up to a total
(theoretical) packet size of 255 bytes (due to the one-byte length
field in the radio framing). 

Note that the actual maximum message size in use is defined at the top
of firmware/receiver/receiver.c (currently 16 bytes), since the
receiver keeps 4 message buffers for when the host is slow in
receiving messages.

Since both the radio link and the USB link provide a length value, no
"end of packet" or similiar framing is needed.


Reading types:

len type  name      comment
4   0	  SHT_RAW   SHT11 raw temperature + humidity readings,
		    14/12bit resolution, on word boundaries. These two
		    readings must be treated as one since humidity
		    depends on temperature etc.
2   0	  VCC_BG_11 voltage: 10bit ADC reading measuring the bandgap reference
		    against VCC, for a bandgap voltage of 1.1V (e.g. Tinyx5)

2   1	  VCC_BG_13 voltage: as above, for a bandgap voltage of 1.3V (e.g.
		    Mega8)

2   2	  TEMP_100  (signed) Temperature in 1/100 C

1   0     POWER_OUT power output (heating furnace) in %
