mbggpscap.c

Go to the documentation of this file.

/**************************************************************************
 *
 *  $Id: mbggpscap.c 1.14 2018/11/15 12:12:36 martin TRASH $
 *
 *  Description:
 *    Main file for mbggpscap program which demonstrates how to access
 *    a Meinberg device via IOCTL calls and read entries from the time
 *    capture FIFO buffer.
 *
 *    Please note that this may only work with devices which provide
 *    time capture input(s).
 *
 * -----------------------------------------------------------------------
 *  $Log: mbggpscap.c $
 *  Revision 1.14  2018/11/15 12:12:36  martin
 *  Individual MBG_MICRO_VERSION codes are now obsolete.
 *  Revision 1.13  2018/01/10 13:36:35  martin
 *  Use current API mbg_get_serial_settings() to check
 *  serial settings. Don't change configuration but just  warn
 *  if capture events might be spit out via a serial port.
 *  Added some doxygen comments.
 *  Revision 1.12  2017/11/29 12:49:31  martin
 *  Added feature to log capture events to a file.
 *  Revision 1.11  2017/07/05 18:59:14  martin
 *  New way to maintain version information.
 *  Support build under Windows.
 *  Improved code execution paths.
 *  Improved reading capture events arriving at a high rate.
 *  Support validation of capture signals arriving at a constant rate.
 *  Fixed a bug when displaying the capture event status. TTM and
 *  PCPS_HR_TIME are using different sets of status flags.
 *  New option -r which displays raw timestamps and raw status.
 *  New option -o which forces usage of old API.
 *  New command line option to clear buffer.
 *  Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC.
 *  Use more functions from common library modules.
 *  Use codes and inline functions from mbgerror.h.
 *  Proper return codes and exit codes.
 *  Revision 1.10  2009/09/29 15:02:15  martin
 *  Updated version number to 3.4.0.
 *  Revision 1.9  2009/07/24 09:50:08  martin
 *  Updated version number to 3.3.0.
 *  Revision 1.8  2009/06/19 12:38:51  martin
 *  Updated version number to 3.2.0.
 *  Revision 1.7  2009/03/19 17:04:26  martin
 *  Updated version number to 3.1.0.
 *  Updated copyright year to include 2009.
 *  Revision 1.6  2008/12/22 12:00:55  martin
 *  Updated description, copyright, revision number and string.
 *  Use unified functions from toolutil module.
 *  Accept device name(s) on the command line.
 *  Don't use printf() without format, which migth produce warnings
 *  with newer gcc versions.
 *  Revision 1.5  2007/07/24 09:32:26  martin
 *  Updated copyright to include 2007.
 *  Revision 1.4  2006/02/22 15:29:17  martin
 *  Support new ucap API.
 *  Print an error message if device can't be opened.
 *  Revision 1.3  2004/11/08 15:47:10  martin
 *  Using type cast to avoid compiler warning.
 *  Revision 1.2  2003/04/25 10:28:05  martin
 *  Use new functions from mbgdevio library.
 *  New program version v2.1.
 *  Revision 1.1  2001/09/17 15:08:22  martin
 *
 **************************************************************************/

// include Meinberg headers
#include <mbgdevio.h>
#include <deviohlp.h>
#include <toolutil.h>  // common utility functions
#include <str_util.h>

// include system headers
#include <stdio.h>
#include <stdlib.h>
#include <time.h>


#define USLEEP_INTV  10000  // [microseconds]


#define MBG_FIRST_COPYRIGHT_YEAR   2001
#define MBG_LAST_COPYRIGHT_YEAR    0     // use default

static const char *pname = "mbggpscap";


static int continuous;
static double nom_cap_intv;    // nominal capture interval to check [s]
static double max_cap_jitter;  // max allowed jitter [s]
static int raw;
static int force_old_api;
static int clear_buffer;
static const char *log_fn;

static int has_been_called;
static int must_check_intv;
static int query_only;
static ulong err_cnt;
static PCPS_HR_TIME prv_ucap;



static /*HDR*/
void show_ucap_event( const PCPS_HR_TIME *ucap )
{
  char ws[80];
  char s[400];
  int n;

  // Print converted date and time to a string:
  mbg_snprint_hr_time( ws, sizeof( ws ), ucap, raw );

  // Print the time stamp, ucap->signal contains the channel number:
  n = snprintf_safe( s, sizeof( s ), "New capture: CH%i: %s", ucap->signal, ws );

  if ( must_check_intv && has_been_called )
  {
    int jitter_exceeded;
    double abs_delta;
    double d = ucap->tstamp.sec - prv_ucap.tstamp.sec;
    d += ( (double) ucap->tstamp.frac - prv_ucap.tstamp.frac ) / MBG_FRAC32_UNITS_PER_SEC;

    n += snprintf_safe( &s[n], sizeof( s ) - n, " %+.6f", d );

    abs_delta = d - nom_cap_intv;

    if ( abs_delta < 0.0 )
      abs_delta = -abs_delta;

    jitter_exceeded = 0;

    if ( abs_delta > max_cap_jitter )
    {
      jitter_exceeded = 1;
      err_cnt++;
    }

    if ( err_cnt )
      n += snprintf_safe( &s[n], sizeof( s ) - n, " %lu%s", err_cnt, jitter_exceeded ? " <<" : "" );
  }

  // status bit definitions can be found in pcpsdefs.h.

  if ( raw )
    n += snprintf_safe( &s[n], sizeof( s ) - n, ", st: 0x%04X", ucap->status );

  if ( ucap->status & PCPS_UCAP_OVERRUN )     // capture events have occurred too fast
    n += snprintf_safe( &s[n], sizeof( s ) - n, " << CAP OVR" );

  if ( ucap->status & PCPS_UCAP_BUFFER_FULL ) // capture buffer has been full, events lost
    n += snprintf_safe( &s[n], sizeof( s ) - n, " << BUF OVR" );

  prv_ucap = *ucap;
  has_been_called = 1;

  printf( "%s\n", s );

  if ( log_fn )
  {
    FILE *fp = fopen( log_fn, "at" );

    if ( fp )
    {
      fprintf( fp, "%s\n", s );
      fclose( fp );
    }
    else
    {
      fprintf( stderr, "** Failed to open file %s for writing: %s\n",
               log_fn, strerror( errno ) );
      log_fn = NULL;
    }
  }

}  // show_ucap_event



static /*HDR*/
void show_gps_ucap( const TTM *ucap )
{
  printf( "New capture: CH%i: %04i-%02i-%02i  %2i:%02i:%02i.%07li",
          ucap->channel,
          ucap->tm.year,
          ucap->tm.month,
          ucap->tm.mday,
          ucap->tm.hour,
          ucap->tm.min,
          ucap->tm.sec,
          (ulong) ucap->tm.frac
        );

  if ( raw )
    printf( ", st: 0x%04lX", (ulong) ucap->tm.status );

  printf( "\n" );

}  // show_gps_ucap



static /*HDR*/
void check_serial_mode( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev )
{
  RECEIVER_INFO ri;
  RECEIVER_PORT_CFG rpcfg;
  int i;
  int must_warn = 0;

  int rc = mbg_setup_receiver_info( dh, p_dev, &ri );

  if ( mbg_cond_err_msg( rc, "mbg_setup_receiver_info" ) )
    return;

  if ( ri.n_com_ports == 0 )   // The device provides no serial port
    return;                    // so there's nothing to check.

  // read the clock's current serial port settings
  rc = mbg_get_serial_settings( dh, p_dev, &rpcfg, &ri );

  if ( mbg_cond_err_msg( rc, "mbg_get_serial_settings" ) )
    return;


  // Check if one of the serial ports uses STR_AUTO mode.
  for ( i = 0; i < ri.n_com_ports; i++ )
  {
    PORT_SETTINGS *p = &rpcfg.pii[i].port_info.port_settings;

    if ( p->mode == STR_AUTO )
    {
      must_warn = 1;
      break;
    }
  }

  if ( must_warn )
    fprintf( stderr,
             "ATTENTION: At least one of the device's serial ports has been\n"
             "configured to send time strings automatically, which can remove\n"
             "capture events from the on-board FIFO, so they are unavailable\n"
             "to this application\n"
             "\n"
             "Please change the configuration of the serial port(s) in a way that\n"
             "none of the serial ports sends a capture event string automatically.\n"
             "\n"
             "For example, use the \"mbgctrl\" program to let the serial ports\n"
             "transmit the Meinberg standard time string once per second.\n"
             "\n"
             "See \"mbgctrl -?\" for details.\n"
             "\n" );

}  // check_serial_mode



static /*HDR*/
int do_mbggpscap( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev )
{
  int rc;
  int this_clear_buffer = clear_buffer;

  must_check_intv = continuous && ( nom_cap_intv != 0 );
  has_been_called = 0;
  err_cnt = 0;


  if ( !_pcps_has_ucap( p_dev ) && !_pcps_is_gps( p_dev ) )
  {
    printf( "This device type does not provide time capture inputs.\n" );
    return 0;
  }

  check_serial_mode( dh, p_dev );

  printf( "Be sure the card has been properly configured to enable capture inputs.\n" );

  // There's an older API which has been introduced with the first GPS boards
  // and uses the TTM structure to return the capture events. However, that
  // API call is slow and not very flexible, so a new set of API calls has been
  // introduced to handle capture events.
  // The new API calls are supported by all supported by all newer boards which
  // provide user capture inputs, and also for older boards with a firmware update.

  if ( !force_old_api && _pcps_has_ucap( p_dev ) )  // check if the new API is supported
  {
    // The new API provides the following functions:
    //   mbg_clr_ucap_buff()     clear the on-board FIFO buffer
    //   mbg_get_ucap_entries()  get the max number of FIFO entries, and the current number of entries
    //   mbg_get_ucap_event()    read one entry from the FIFO

    PCPS_UCAP_ENTRIES ucap_entries;

    // retrieve and print information of the maximum number of events that can
    // be stored in the on-board FIFO, and the number of events that are currently
    // stored
    rc = mbg_get_ucap_entries( dh, &ucap_entries );

    if ( rc == MBG_SUCCESS )
    {
      // Cards report they could save one more capture event
      // than they actually do save, so adjust the reported value
      // for a proper display.
      if ( ucap_entries.max )
        ucap_entries.max--;

      printf( "\nOn-board FIFO: %u of %u entries used\n\n",
              ucap_entries.used, ucap_entries.max );
    }

    if ( this_clear_buffer )
    {
      printf( "Clearing on-board FIFO buffer\n" );
      mbg_clr_ucap_buff( dh );
      this_clear_buffer = 0;
    }

    // If the program is not to run continuously and no
    // capture events are available then we're through.
    if ( query_only || ( !continuous && ucap_entries.used == 0 ) )
      return 0;


    printf( ( ucap_entries.used == 0 ) ?
            "Waiting for capture events:\n" :
            "Reading capture events:\n"
          );

    if ( must_check_intv )
      if ( max_cap_jitter == 0.0 )
        max_cap_jitter = 0.1e-6;

    // Now read out all events from the FIFO and wait
    // for new events if the FIFO is empty.
    for (;;)
    {
      PCPS_HR_TIME ucap_event;

      rc = mbg_get_ucap_event( dh, &ucap_event );

      if ( mbg_cond_err_msg( rc, "mbg_get_ucap_event" ) )
        break;  // an error has occurred

      // If a user capture event has been read then it
      // has been removed from the card's FIFO buffer.

      // If the time stamp is not 0 then a new capture event has been retrieved.
      if ( ucap_event.tstamp.sec || ucap_event.tstamp.frac )
      {
        show_ucap_event( &ucap_event );
        continue;
      }

      usleep( USLEEP_INTV );   // sleep, then try again
    }
  }
  else    // use the old API
  {
    printf( "Checking for capture events using the old API:\n" );

    for (;;)
    {
      TTM ucap_ttm;

      rc = mbg_get_gps_ucap( dh, &ucap_ttm );

      if ( mbg_cond_err_msg( rc, "mbg_get_gps_ucap" ) )
        break;  // an error has occurred


      // If a user capture event has been read then it
      // has been removed from the card's FIFO buffer.

      // If a new capture event has been available then
      // the ucap.tm contains a time stamp.
      if ( _pcps_time_is_read( &ucap_ttm.tm ) )
        show_gps_ucap( &ucap_ttm );

      if ( !continuous )
      {
        printf( "No capture event available!\n" );
        break;
      }

      usleep( USLEEP_INTV );   // sleep, then try again
    }
  }

  return 0;

}  // do_mbggpscap

static MBG_DEV_HANDLER_FNC do_mbggpscap;



static /*HDR*/
void usage( void )
{
  mbg_print_usage_intro( pname,
    "This example program reads time capture events from a card.\n"
    "This works only with cards which provide time capture inputs."
  );
  mbg_print_help_options();
  mbg_print_opt_info( "-c", "run continuously" );
  mbg_print_opt_info( "-C", "clear capture buffer" );
  mbg_print_opt_info( "-i val", "check interval between captures events [s]" );
  mbg_print_opt_info( "-j val", "max allowed jitter of capture interval [s]" );
  mbg_print_opt_info( "-q", "query FIFO buffer status only" );
  mbg_print_opt_info( "-r", "show raw (hex) timestamp and status)" );
  mbg_print_opt_info( "-o", "force usage of old API (for testing only)" );
  mbg_print_device_options();
  puts( "" );

}  // usage



int main( int argc, char *argv[] )
{
  int rc;
  int c;

  mbg_print_program_info( pname, MBG_FIRST_COPYRIGHT_YEAR, MBG_LAST_COPYRIGHT_YEAR );

  // check command line parameters
  while ( ( c = getopt( argc, argv, "cCi:j:l:oqrh?" ) ) != -1 )
  {
    switch ( c )
    {
      case 'c':
        continuous = 1;
        break;

      case 'C':
        clear_buffer = 1;
        break;

      case 'i':
        nom_cap_intv = atof( optarg );
        break;

      case 'j':
        max_cap_jitter = atof( optarg );
        break;

      case 'l':
        log_fn = optarg;
        break;

      case 'o':
        force_old_api = 1;
        break;

      case 'q':
        query_only = 1;
        break;

      case 'r':
        raw = 1;
        break;

      case 'h':
      case '?':
      default:
        must_print_usage = 1;
    }
  }

  if ( must_print_usage )
  {
    usage();
    return MBG_EXIT_CODE_USAGE;
  }

  if ( nom_cap_intv != 0.0 )
  {
    printf( "Nominal capture interval: %f s\n", nom_cap_intv );
    printf( "Maximum allowed capture jitter: %f s\n", max_cap_jitter );
  }

  // Handle each of the specified devices.
  rc = mbg_handle_devices( argc, argv, optind, do_mbggpscap, 0 );

  return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL;
}