File content as of revision 17:0b241aa1f5b6:

#ifndef TRIAL_H_
#define TRIAL_H_

#include "task.h"
#include "arraylist.h"
#include "random.h"

typedef int trialtime_t;

namespace TrialFlags {
    // nothing
    const char Clear     = 0x00;
    // flags if the auditory cue is there during the trial
    const char Cues      = 0x01;
    // flags if any "response" is detected during the response window
    const char Responded = 0x02;
    // flags if licking event is detected during the preparatory/pre-response window
    const char Licked    = 0x04;
}

namespace Responses {
    const char Hit     = 0x03; // cues && responded
    const char Miss    = 0x01; // cues && ~responded
    const char Catch   = 0x02; // ~cues && responded
    const char Reject  = 0x00; // ~cues && ~responded
    const char Reset   = 0x04; // invalid lick
    const char NA      = 0x08; // default
}

struct Trial {
    /**
    * whether the animal whisked during the cue.
    * + whether the animal waited for the cue.
    */
    char          response;
    /**
    * the timestamp when the trial started.
    */
    trialtime_t   starting;
    /**
    * the timestamp when the cue started
    */
    trialtime_t   cuestarting;
    /**
    * the total waiting period for the animal during this trial before the cue.
    */
    unsigned long waiting;   // used for calculation of waiting period
    /**
    * the duration of the delay period for this trial.
    */
    uint16_t      delay_dur_ms;
    
    // (passive) visual cue-related params
    uint16_t      vis_onset_us;
    uint16_t      vis_dur_us;
    
    uint64_t      aud_ticker_cycle;
    
    /**
    *   a buffer for recording licking events during the trial.
    */
    ArrayList<trialtime_t>  licking_events;
    
    /**
    *   a buffer for recording whisking events during the trial.
    */
    ArrayList<trialtime_t>  whisking_events;
    
    /**
    *   initialize the trial parameters according to the given Task parameter set.
    *   typically called from one of the automaton states.
    */
    void reset(const Task& task);
    
    /**
    *   a helper function to assign onset & duration randomly for the (passive) visual cue.
    *
    *   the `onset` will distribute exponentially from `0` to `auddur - respdur - mindur`.
    *   the `duration` will distribute uniformly from `mindur` to `phasedur - onset`.
    */
    void assignRandomStim(const Task& task);
    
    /**
    *   a callback mechanism for marking (timestamping) the start of the trial.
    *   called from one of the automaton states.
    */
    void markTrialStart();
    
    /**
    *   a callback mechanism for marking (timestamping) the end of the waiting period of the trial.
    *   called from one of the automaton states.
    */
    void markEndOfWait();
    
    /**
    *   a callback mechanism for marking (timestamping) the end of the trial.
    *   called from one of the automaton states.
    */
    void markTrialEnd();
    
    /**
    *   output the result of a trial into a serial port through the IO mechanism.
    *   typically called from one of the automaton states.
    */
    void writeToSerial();
};

#endif