avr: added docu

avr/devices/all/README

@@ -0,0 +1,48 @@
+
+Functions
+
+AqHome knows these driver/module/app functions:
+- INIT: initialize the driver
+- RUN:  called on every loop
+- MSGRECEIVED: called whenever a message has been received
+- EVERY100MS:  called every 100ms (the system timer tick)
+- EVERY1S:     called every second
+- EVERY1M:     called every minute
+- EVERY1H:     called every hour
+- EVERY1D:     called every day
+
+
+Modules and Apps
+
+Modules are lowlevel drivers for specific hardware (like for the environment
+sensor SI7021).
+
+Apps on the other hand are kind of sub-programs running in parallel on the
+microprocessor. E.g. there are apps for networking, motion-activated-light, statistics
+reporting and sensor value reporting.
+
+
+Modules
+
+If your driver/module implements those functions they need to be added
+to the appropriate files:
+- include instructions to the file "modules_include.asm"
+- calls to INIT function to        "modules_init.asm"
+- calls to RUN function to         "modules_run.asm"
+- calls to MSGRECEIVED function to "modules_msg.asm"
+- calls to EVERY100MS function to  "modules_100ms.asm"
+- calls to EVERY1S function to     "modules_1s.asm"
+- calls to EVERY1M function to     "modules_1m.asm"
+- calls to EVERY1H function to     "modules_1h.asm"
+- calls to EVERY1D function to     "modules_1d.asm"
+
+Only implemented routine calls need to be added, e.g. if a driver doesn't need
+the RUN functionality it doesn't need to be implemented.
+
+
+Apps
+
+The same rules apply to apps. The only difference is the prefix of the files calls and
+include directives need to be added (using "apps_xxx.asm" instead of "modules_xxx.asm").
+
+

doc/OS

@@ -0,0 +1,66 @@
+
+Aquamaniac Home Control System (AqHCS) uses a minimalistic operating system.
+
+That OS doesn't use devicer driver object structures due to RAM contraints, it just defines a few
+callback labels which need to be provided by drivers, apps and the main code.
+
+Main routines for drivers are:
+- Init
+- Fini (not used for now)
+- Run
+- OnEvery100ms
+- OnMessageReceived
+
+This system is event driven. There is one single main loop which uses some defined labels as callbacks.
+
+Basically the main loop works like this:
+
+--------------------------------------------------------------------------------------------------------X8
+loop:
+  - sleep (waiting to be awakended by interrupt)
+  - call RUN routines of every active driver
+  - call onEveryLoop
+  - goto loop
+--------------------------------------------------------------------------------------------------------X8
+
+
+The main RUN routine consists of a number of calls to RUN functions of used drivers and apps, e.g.:
+
+--------------------------------------------------------------------------------------------------------X8
+RunDrivers:
+    call BaseTimer_Run   ; main clock event source
+#ifdef MODULES_TTYONUART1
+    call TtyOnUart1_Run
+#endif
+#ifdef MODULES_COM2WI
+    call COM2WI_Run
+#endif
+    ret
+--------------------------------------------------------------------------------------------------------X8
+
+This means new drivers have their RUN functions registered by adding them to the RunDrivers routine with
+"#ifdef" clauses around them. That way you only need to add the line "#define MODULES_TTYONUART1" in your main
+application to have the driver automatically used.
+
+
+The main driver of the system is the BaseTimer module. It is supplied by interrupt of an AVR timer circuit.
+Its RUN routine then calls some other routines in the main app like "onEverySecond" etc.
+
+
+Required labels for the main application are:
+
+- onSystemStart:     called first after system start
+- onMessageReceived: called for every network package received
+- onEvery100ms:      called every 100ms which is the base clock for all other functions
+- onEverySecond:     called every second
+- onEveryMinute:     called every minute
+- onEveryHour:       called every hour
+- onEveryDay:        called every day
+- onEveryLoop:       called on every main loop
+
+These callbacks must all be defined in the main source file but callbacks for functionality not provided or used by the main 
+system might just execute a "ret" instruction.
+
+
+
+