/* STEREO IMPACT SEP SEPT 
** 
** L1 Data Processing
**
** (C) Copyright 2005-2006 Stephan I. Böttcher, CAU Kiel - IEAP
**
** Stephan I. Böttcher     <boettcher@physik.uni-kiel.de>
** Reinhold Müller-Mellin  <mueller-mellin@physik.uni-kiel.de>
**
** $Id: sept_l1.h,v 1.6 2006/12/22 07:16:07 bottcher Exp $
** $Log: sept_l1.h,v $
** Revision 1.6  2006/12/22 07:16:07  bottcher
** change sept_time_t from unsigned int to double
**
** Revision 1.5  2006/10/26 09:34:53  bottcher
** change interface to use copied l0 data, instead of pointer
**
** Revision 1.4  2006/10/13 06:36:50  bottcher
** turn line ends to Unix
**
** Revision 1.3  2006/03/22 15:46:39  bottcher
** init_called for automatic initialization
** verbosity added
**
** Revision 1.2  2006/03/22 12:58:55  bottcher
** Usage documentation added
**
** Revision 1.1  2005/12/27 22:35:38  bottcher
** Initial commit, feature complete.
**
*/

/*
**  Usage:
**
**    Before any packet processing, call the function
**
**         sept_level1_init();
**
**    without arguments, to read the calibration data file, and 
**    setup the calibration data structures.  The function returns 0 when
**    successfull, or an error code when not.
**    The name of the SEPT calibration file may be specified as, listed 
**    in decreasing priority:
**
**    1.) Store a char * pointer in the global variable  
**
**            const char *sept_level1_calibration_file;
**
**        for example, from commandline processing. 
**
**    2.) Provide the filename in the environment variable SEPT_LEVEL1_CALIB
**
**    3.) Put the file in the current working directory, with the name
**
**            "sept_level1_calibration.txt"
**
**    Change 2006-03-22: sept_level1() will call sept_level1_init() if 
**    it wasn't called before.
**
**
**
**    For each SEPT packet, call
**
**         sept_level1(level0, level1);
** 
**    struct sept_raw_packet *level0;       is the level 0 input,
**    struct sept_science_level1 *level1;   is the level 1 output.
**
**    The function returns 0 when successfull, or an error code when not.
**    
**    level0->apid;   must be 600 (SEPT-NS) or 601 (SEPT-E).
**    level0->s_c;    shall be even for S/C A, or odd for S/C B.
**    level0->time;   shall be the ccsds packet time, in the notation 
**                    as it shall appear in the Level1 data.  Change 
**                    the typedef sept_time_t as required.
**    level0->data;   shall be the CCSDS packet data without headers, i.e.,
**                    261 bytes.  Actually, only 255 bytes are required.
**
**    level1 must point to a buffer sizeof(struct sept_science_level1).
**    The contents of that structure is documented below.
**
**
**    The global variable 
**
**         int sept_level1_verbose = 2;
**
**    controls the verbosity of sept level 1 processing:
**
**      sept_level1_verbose < 0 : absolute silence
**      sept_level1_verbose >= 0: errors while parsing calibration file
**      sept_level1_verbose >= 1: warnings while parsing calibration file
**      sept_level1_verbose >= 2: infos while initializing
**      sept_level1_verbose >= 3: warnings while processing packets
**      sept_level1_verbose >= 4: infos while processing packets
**      sept_level1_verbose >= 9: sept_level1_print() for each packet
**
**   The messages are sent to stderr.
*/

typedef double sept_time_t;

struct sept_raw_packet
{
  unsigned int   apid; /* packet APID, 600: SEPT-NS, 601: SEPT-E */
  unsigned int   s_c;  /* Spacecraft, 0: Ahead, 1: Behind */
  sept_time_t    time; /* Packet time */
  unsigned char  data[261]; /* Packet data, without headers */
};

typedef double sept_science_count_t;

enum sept_mode
  {
    SEPT_MODE_OFF      = 0, /* Telescope is turned off/dead   */
    SEPT_MODE_ALIVE    = 1, /* Telescope did answer */
    SEPT_MODE_SCIENCE  = 2, /* Telescope is running nominally */
    SEPT_MODE_MIPS     = 3, /* Coincidence mode, penetrating particles */
    SEPT_MODE_ITPG     = 4, /* Inflight Test Pulse Generator is on */
    SEPT_MODE_UNKNOWN  = 7  /* Unknown mode */ 
  };

struct sept_science_level1
{
  unsigned int         version;
  unsigned char        s_c;                 /* 0: Ahead, 1: Behind        */
  unsigned char        inst;                /* 0: N/S, 1: E               */
  sept_time_t          time;                /* packet time stamp          */
  sept_science_count_t spec[4][32];         /* counts/sec/sr/cm^2/MeV     */
  double               timer[2];            /* seconds                    */
  unsigned char        single_counter_id;   /* 0..7                       */
  double               single_counter_rate; /* counts/sec                 */
  unsigned int         interrupts;          /* source: SEPT FPGA          */
  unsigned char        pdfe[3][4];          /* source: PDFE               */
  unsigned char        pulser;              /* source: SEPT FPGA          */
  unsigned char        filter;              /* source: SEPT FPGA          */
  enum sept_mode       alive[2];            /* what kind of data is here  */
  unsigned char        sequence;            /* source: SEP Central        */
  unsigned char        state;               /* source: SEP Central        */
  unsigned char        status;              /* source: SEP Central        */
  int                  temperature[2];      /* °C                         */
  unsigned char        heater;              /* source: SEP Central        */
};

#include <stdio.h>

int sept_level1(const struct sept_raw_packet *, struct sept_science_level1 *);
int sept_level1_init();
int sept_level1_print(FILE *f, const struct sept_science_level1 *l1);
extern int sept_level1_verbose;
extern const char *sept_level1_calibration_file;