EMMA/Docu/datalog_format

* DATA LOG FORMAT FILES

  TSV format is used to separate data types in files.

** FILENAME
   
   Due to the FAT32 library using filename must be of 
   10 characters [1]. The filename format I'm going to use is:
   
   DATE.l (contains human readeable information)
   DATE.r (contains RAW [2] output from sensors)
   
   It is a total of 10 characters per filename.
   .l comes form "log"
   It cannot be .tsv yet because of the length [1].

*** File .l (log human readeable)
  
   This type of file (.l extension) contains the sensors response
   information *after* being processed by the Microcontroller,
   it is *human readeable information*.

   Some sensors send their readings as RAW so it is not human
   readeable, The microcontroller does the calculations to
   present the sensor's response as human readeable information.

   The loggin format goes this way:

   BT   PHYSICAL_PHEN_1   UNITS1      PHYSICAL_PHEN_2   UNITS2
   TIME    SENSOR_N1   ...   SENSOR_NM      SENSOR_R1   ...   SENSOR_RS
   TIME1   DATA1_N1   ...   DATA1_NM      DATA1_R1   ...   DATA1_RS
   TIME2   DATA2_N1   ...   DATA2_NM      DATA2_R1   ...   DATA2_RS
   ...
   ...
   TIMEQ   DATAQ_N1   ...   DATAQ_NM      DATAQ_R1   ...   DATAQ_RS
   
   *Every 3 blank spaces represents a TAB '\t' character*
   *BT* = 8 ' ' (blank spaces) for time column

   Notice that there may be many sensors and everyone is calssified
   according to the physical pehnomenon it measures, a TAB separates 
   each cell and to keep different physical phenomenon separated *two TAB characters* are used.

   Every time a row is filled with a complete row of the sensor's response.

*** File .r (RAW sensors response)

   This type of file (.r extension) contains the RAW sensors
   response.

   Not every sensor send their data as RAW, for the ones that 
   do it, that RAW response is stored in this file.

   If a sensor does not respond RAW data, then the RAW data
   corresponding to the sensor is blank.

   The logging format is the same as in .l format (see below), the only
   difference is that DATA is the RAW response of each sensor.

** DATE

   DD-MM-YY

   day-month-year

   In the file the DATE is logged only once a day.

** PHYSICAL PHENOMENA
   
   Specifies the physical phenomena being measured, for instance
   temperature, relative humidity, wind speed, etc.

** UNITS

   The measurement units being used, for instance Celcius, 
   percent, rpm, etc.

** SENSOR

   Each column specifies the sensor's name.

** TIME
  
   HH:MM:SS

   hours:minites:seconds

   The time interval when the data was taken.

** DATA

   Each column is a sensor's reading corresponding to the name
   in the column.

** RAW_DATA

   Each contains the correspondig sensor RAW response.

** EXAMPLE

   IF you open any logging file using a calc sheet software
   like libreoffice calc or excel, follow this steps:
   
   1. Open the file logged file and tell the software to create
      tables from a TSV file.
   2. Select the columns from TIME to the last SENSOR to see
   the data properly.
   3. Press the button to create a graphic.
   4. Use the first column as a label.
   5. Use the first row as a label.
   6. Use data series in columns.

   You'll get a graphic showing data logged as time has passed.
   Here how it will look the table for three different sensors:

   Time	        DHT11	LM35	DSXX
   11:16:32	12,33	13,2	12,46
   11:17:32	12,34	13,4	12,48
   11:18:32	12,55	13,6	12,67
   11:19:32	12,41	13,5	12,61
   11:20:32	12,29	13,4	12,39


   After following the steps below the graphic will look like:
   	 ^  
         |          |          | B        |          |          |
    13.5 |          |          |          | B        |          |
         |          | B        |          |          | B        |
         |          |          |          |          |          |
         | B        |          |          |          |          |
      13 |          |          |          |          |          |
         |          |          |          |          |          |
         |          |          | C        |          |          |
         |          |          |          | C        |          |
    12,5 |          |          | A        |          |          |
         | C        | C        |          | A        |          |
         | A        | A        |          |          | C        |
         |          |          |          |          | A        |
      12 |          |          |          |          |          |
     ----|----------|----------|----------|----------|----------|->
         | 11:16:32 | 11:17:32 | 11:18:32 | 11:19:32 | 11:20:32 |

   Where A, B, C are representing points int he graphic 
   corresponding to sensors DHT11, LM35 and DS1308.
   
   - The Y axis is the *temperature* in celsius.
   - The X axis is the time when a temperature sample was taken.

** Extra Notes

   When logging a file, the system will first establish the filename
   which is DATE.l or DATE.r.
   If that file already exists in the SD_card then new data is appended.
   
   A file is never overwriten or deleted, the system only adds up
   new data.

* Footnotes

[1] Filename is a string of 10 characters only because '\0' counts
as a character and it indicates end of string. (It seems to be
like that in FAT32 library, because of a normal short filename )

[2] RAW, generally shows the voltage sensor response or other 
not preprocessed data.