1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!--
3This file is Copyright (c) 2016 by the GPSD project
4SPDX-License-Identifier: BSD-2-clause
5-->
6<!DOCTYPE refentry PUBLIC
7   "-//OASIS//DTD DocBook XML V4.1.2//EN"
8   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
9<refentry id='ppscheck.8'>
10<refentryinfo><date>28 Jul 2016</date></refentryinfo>
11<refmeta>
12<refentrytitle>ppscheck</refentrytitle>
13<manvolnum>8</manvolnum>
14<refmiscinfo class="source">The GPSD Project</refmiscinfo>
15<refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
16</refmeta>
17<refnamediv id='name'>
18<refname>ppscheck</refname>
19<refpurpose>tool to check a serial port for PPS</refpurpose>
20</refnamediv>
21<refsynopsisdiv id='synopsis'>
22
23<cmdsynopsis>
24  <command>ppscheck</command>
25	<arg choice='opt'>-h </arg>
26	<arg choice='opt'>-V </arg>
27 	<arg choice='plain'><replaceable>device</replaceable></arg>
28</cmdsynopsis>
29</refsynopsisdiv>
30
31<refsect1 id='description'><title>DESCRIPTION</title>
32
33<para>ppscheck watches a specified serial port for transitions that
34might be PPS.  It looks for changes in handshake lines CD, RI, and CTS
35by running ioctl(...., TIOCMIWAIT, ...) in a loop.  When it sees a state
36change it emits a timestamped line of output dumping the state of the
37handshake signals. It's useful for checking whether a device is emitting
38PPS.</para>
39
40<para>To check the first serial port do this:</para>
41
42<programlisting>
43ppscheck /dev/ttyS0
44</programlisting>
45
46<para>ppscheck is not intended for routine use, but rather for
47diagnostic purposes. Once you have verified a particular device can
48output PPS signals you will never need to use it again on that device.
49</para>
50
51<para>The program accepts the following options:</para>
52<variablelist remap='TP'>
53<varlistentry>
54<term>-h</term>
55<listitem><para>Display help message and terminate.</para></listitem>
56</varlistentry>
57<varlistentry>
58<term>-V</term>
59<listitem>
60<para>Dump version and exit.</para>
61</listitem>
62</varlistentry>
63</variablelist>
64
65<para>The "device" argument should be the pathname of a device. It will
66be the device monitored. </para>
67
68<para>Each output line is the second and nanosecond parts of a timestamp
69followed by the names of the handshake signals then asserted.  Off
70transitions may generate lines with no signals aserted. </para>
71
72<para>If you don't see output within a second, use gpsmon or some other
73equivalent tool to check that your device has a satellite lock and is
74getting 3D fixes before giving up on the possibility of PPS. </para>
75
76<para>Check your cable. Cheap DB9 to DB9 cables such as those issued
77with UPSes often carry TXD/RXD/GND only, omitting handshake lines such
78as DCD.  Suspect this especially if the cable jacket looks too skinny to
79hold more than three leads! </para>
80
81<para>Most GPS that have built in USB do not support PPS.  When in doubt,
82contact the vendor for confirmation that your device does supply PPS.
83</para>
84
85</refsect1>
86
87<refsect1 id='exit_status'><title>RETURN VALUES</title>
88
89<para>1 if the device counld not be opened. 0 otherwise</para>
90
91</refsect1>
92
93<refsect1 id='see_also'><title>SEE ALSO</title>
94<para>
95<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
96</para>
97</refsect1>
98
99<refsect1 id='maintainer'><title>AUTHOR</title>
100
101<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para>
102</refsect1>
103</refentry>
104