Malawi_001.ino

Go to the documentation of this file.

/**
 * @file    Malawi_001.ino
 * @author     Nico Verduin
 * @date      30-12-2013
 *
 * @mainpage Malawi_001
 * This project measures time between pulses generated from a photo sensor. The time between each
 * rising and falling edge is measured as well as the time between the falling and rising edge.
 * The time measured in both cases is stored on an SD Card.
 * \n\n
 * The given estimations of the HIGH time vs LOW time is 150 milli Seconds (variation = 120-170) and
 * 30 milli seconds (variation = 10-50).
 *
 * @par Important information
 * SD cards are sold in different qualities. The most important is the so called latency time
 * This can influence the delay on the write operation.
 *
 * @par Workings
 * An interrupt service routine (ISR) is called every time the edge changes. The difference between
 * the time now and the time before is the time between edges. \n
 * These values are stored in an array. Each array can contain a maximum of BUFFER_ENTRIES (=max 100) bytes.\n
 * The program has 2 buffers once a buffer is full, the buffer pointer is switched to the other allowing
 * the ISR to keep storing data. \n
 * Meanwhile the filled buffer is written to the SD card as a 2 column CSV format with a Long and short pulse time.
 *
 * @par Usage instructions
 * a) Make sure a standard FAT32 formatted SD card is inserted in the card Holder\n
 * b) Switch the Arduino on\n
 * c) The LED should light constant\n
 * d) recording will start as soon as pulses arrive from the Opto
 *
 * @par LED flashes
 * a) 2 seconds on / 2 seconds off : There is no SD card inserted or card not usable\n
 * b) 1 seconds on / 2 seconds off : The card already contains 99 MALAWIxx files. Either clean up the card or use another\n
 * c) 250 milliseconds on / 250 milliseconds off : a buffer overrun has happened.\n
 * In all cases above recording has terminated or not even started\n
 * \n
 * If a very short flash happens once every 3-4 seconds the data is being recorded on the card and the system is operating perfectly.
 *
 * @par Version Control
 * $Revision: 5 $
 * $Author: Nico $
 * $Date: 2013-12-31 14:55:38 +0100 (di, 31 dec 2013) $
 *
 * @par License info
 *
 * Malawi_001 measuring time between pulses
 *
 * Copyright (C) 2013  Nico Verduin
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * Program : Malawi_001  Copyright (C) 2013  Nico Verduin
 * This is free software, and you are welcome to redistribute it.
 *
 */

#include "Arduino.h"

#include <SD.h>                        // SD Card functions
//
// file name specifics
//
char fileName[13];                       // we will use msDos files here(8 + . + 3 +\0)
char fileType[]         = ".csv";        // just plain text file
char fileNameStart[]    = "MALAWI";      // files will start with MALAWI
File dataFile;                           // file object to write to

//#define DEBUG                          // DEBUG purposes
#define    FIELD_SEPARATOR    ";"        // for CSV file
//
// Pin definitions
//
#define LED                6             // LED turns on if no buffer full
#define CS                 10            // Chip select for SD card
#define INTERRUPT_INPUT    2             // digital pin for interrupt 0
//
// variables used between the ISR and the loop
//
#define BUFFER_ENTRIES     50                            // currently we have 50 entries per buffer
#define FLASH_OVERRUN    150                            // flash on/off every 150 milli seconds buffer overrun
#define FLASH_CARD        2000                        // flash on/off every 2000 milli seconds no Card
#define FLASH_100        1000                        // flash on/off every 1000 milli seconds no Card
#define NO_CARD            1                            // no card inserted or unreadable
#define OVERRUN            2                            // buffer overrun
#define FILE100            3                            // we have reached a 100 files

volatile bool            firstValue = true;            // ignore the first value as we need 2 values to start with
volatile unsigned long   oldValue;                    // contains the previous millis value
volatile unsigned long   currentValue;                // current millis value
volatile int             buffer[2][BUFFER_ENTRIES];    // we use 2 buffer for writing (each is 512 bytes in size)
volatile int             *ptrBuffer;                    // points to first empty address in buffer
volatile uint8_t         bufferIndex;                // references correct buffer
volatile unsigned int    entryIndex;                    // keeps track of entry in buffer
volatile boolean         bufferFull;                    // indicates if a buffer can be written to SD card
volatile unsigned int    error = 0;                    // an error occured

/**
 * @name flash(unsigned long flashTime)
 * @param flashTime    sets the time the LED is on and off
 * flashes the Led
 */
void flash(unsigned long flashTime) {

    unsigned long flashCtr;

    flashCtr = millis() + flashTime;          // set the timer
    digitalWrite(LED, !digitalRead(LED));     // flip the LED
    while (millis() < flashCtr){};            // wait until done
}
/**
 * @name HandleEdgeChange()
 * This is the Interrupt Service Routine called every time the pulse edge changes
 */
void HandleEdgeChange() {
    //
    // get the time in any case
    //
    currentValue = millis();
    //
    // check if this is the first value
    //
    if (firstValue) {
        //
        // we start with the rising edge
        //
        if (digitalRead(INTERRUPT_INPUT) == LOW) {
            //
            // this is the start
            //
            oldValue     = currentValue;           // first value will be 0
            firstValue   = false;                  // we will do this only once
        }
    } else {
        //
        // calculate the difference
        //
        *ptrBuffer = currentValue - oldValue;      // calculate the difference and put it in the buffer
        ptrBuffer++;                               // pointer to next integer position
        //
        // now increment the Entry index and check for buffer full. if not we are done
        //
        entryIndex++;
        if (entryIndex == BUFFER_ENTRIES) {
            //
            // buffer is full so switch to other buffer but first check if other buffer is empty
            //
            if (bufferFull) {
                //
                // not emptied yet so set error flag
                //
                error = OVERRUN;
            }
            bufferIndex = !bufferIndex;             // index can only be 0 or 1
            entryIndex  = 0;                        // reset the entry ctr
            ptrBuffer   = &buffer[bufferIndex][0];  // pointer to first entry in current buffer
            bufferFull  = true;                     // previous buffer can be written
        }
    }
    //
    // save the current value as old for the next interrupt
    //
    oldValue = currentValue;
}

/**
 * @name writeBuffer(uint8_t index)
 * @param index    pointer to writable buffer
 * Writes a buffer of integer values to the file
 */
void writeBuffer(uint8_t index) {
    //
    // copy the data to the file in readable format
    //
#ifdef DEBUG
    Serial.print("Write Buffer");
    unsigned long start = millis();                        // needed to determine writing time
#endif
    for (unsigned int i = 0; i < BUFFER_ENTRIES; i++) {

        dataFile.print(buffer[index][i]);
        dataFile.print(FIELD_SEPARATOR);
        i++;
        dataFile.println(buffer[index][i]);
    }
    dataFile.flush();

#ifdef DEBUG
    Serial.print("Duration = ");
    Serial.println(millis() - start);
#endif
}

/**
 * @name setup()
 * initialize the program
 */
void setup()
{
#ifdef DEBUG
    Serial.begin(9600);                // for debug purposes
#endif

    //
    // setup inputs and outputs
    //
    pinMode(LED    , OUTPUT);          // Led will indicate if Buffer is empty
    pinMode(CS    , OUTPUT);           // SD card select
    //
    // turn LED off
    //
    pinMode(LED, HIGH);
    //
    // initialize buffers and pointers
    //
    ptrBuffer         = &buffer[0][0]; // Points to first index in first buffer
    entryIndex        = 0;             // references first entry in buffer
    bufferIndex       = 0;             // references the first buffer
    bufferFull        = false;         // nothing to write yet

    //
    // Initialize the SD card
    //
    if (!SD.begin(CS)) {
#ifdef DEBUG
        Serial.println("Card failed, or not present");
#endif
        //
        // set error code
        //
        error = NO_CARD;
        return;
    }
#ifdef DEBUG
    Serial.println("card initialized.");
#endif

    //
    // find the first free file name to use
    //
    strcpy(fileName, fileNameStart);
    //
    // currently set for max 999 files
    //
    for (unsigned int i = 1; i < 99; i++) {
        //
        // build the number range
        //
        sprintf(&fileName[sizeof(fileNameStart)-1], "%02d", i);
        strcat(fileName, fileType);

        if (SD.exists(fileName)) {
#ifdef DEBUG
            //
            // just let us know the file was created earlier
            //
            Serial.print(fileName);
            Serial.println(" Exists");
#endif
            //
            // No more files allowed on this card
            //
            if (i == 99) {
                error = FILE100;
                break;
            }
        } else {
            //
            // create the new file and let us know
            //
            dataFile = SD.open(fileName, FILE_WRITE);
#ifdef DEBUG
            Serial.print(fileName);
            Serial.println(" Created");
#endif
            //
            // we found the file so exit loop
            //
            i = 100;
        }
    }
    //
    // print a dummy to dataFile as the first write takes about 10x as long as normal
    //
    dataFile.println("Short;Long");
    dataFile.flush();
    //
    // now attach the interrupt to the ISR so it can respond to pulses
    //
    attachInterrupt(0, HandleEdgeChange, CHANGE);
}

/**
 * @name loop()
 * main loop of program and runs endlessly
 */
void loop()
{
    //
    // first check if there is an error
    //
    if (error != 0) {
        //
        // remove interrupt vector, no use continuing
        //
        detachInterrupt(0);
        //
        // flash determined on error type
        //
        switch (error) {

        case NO_CARD:                // no card detected or unusable
            flash(FLASH_CARD);
            break;

        case OVERRUN:                // buffer overrun
            flash(FLASH_OVERRUN);
            break;

        case FILE100:                // we have 99 files from this sketch on the SD card
            flash(FLASH_100);
            break;

        default:
            break;
        }
    } else {
        //
        // write to the SD card only if there is something to write
        //
        if (bufferFull) {
            //
            // we have to write a buffer away
            //
            digitalWrite(LED, !bufferFull);           // if buffers are empty, it is a false so reverse it
            writeBuffer(!bufferIndex);                // we have to write the other buffer as this one
                                                      // is filling
            bufferFull = false;
        }
        //
        // check if buffers are still empty
        //
        digitalWrite(LED, !bufferFull);                // if buffers are empty, it is a false so reverse it
    }
}