'\" t
.\"     Title: ppscheck
.\"    Author: Eric S. Raymond
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2023-01-10
.\"    Manual: GPSD Documentation
.\"    Source: GPSD, Version 3.25
.\"  Language: English
.\"
.TH "PPSCHECK" "8" "2023-01-10" "GPSD, Version 3.25" "GPSD Documentation"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
ppscheck \- tool to check a serial port for PPS
.SH "SYNOPSIS"
.sp
\fBppscheck\fP [\-?] [\-\-help] [\-p] [\-\-pps] [\-\-version] [\-h] [\-V]
.sp
\fBppscheck\fP [\-m] device
.SH "DESCRIPTION"
.sp
\fBppscheck\fP watches a specified serial port for transitions that might be
PPS. It looks for changes in handshake lines CD, CTS, DSR, and RI by running
ioctl(...., TIOCMIWAIT, ...) in a loop. When it sees a state change it
emits a timestamped line of output dumping the state of the handshake
signals. It\(cqs useful for checking whether a device is emitting PPS.
.sp
\fBppscheck\fP can run as a normal user, but that user must have permissions
to read the target device.  Running under \fBsudo\fP may, or may not, work.
Running as root will always work.
.sp
To check the first serial port do this:
.sp
.if n .RS 4
.nf
.fam C
# ppscheck /dev/ttyS0
.fam
.fi
.if n .RE
.sp
As a side effect, \fBppscheck\fP will try to create the matching /dev/ppsX
by setting the tty line discipline (ldisc) to N_PPS (18).  You should then
have a device /dev/pps0.  Note that not all serial devices support
ldisc N_PPS.
.sp
You can now use \fBppscheck\fP to see if the KPPS (RFC 2783) interface
is working:
.sp
.if n .RS 4
.nf
.fam C
# ppscheck /dev/pps0
.fam
.fi
.if n .RE
.sp
\fBppscheck\fP is not intended for routine use, but rather for diagnostic
purposes. Once you have verified a particular device can output PPS
signals you will never need to use it again on that device.
.SH "OPTIONS"
.sp
The program accepts the following options:
.sp
\f(CR\-?, `\-h, `\-\-help\fP
.RS 4
Print help message, then exit.
.RE
.sp
\f(CR\-m, `\-\-match\fP
.RS 4
Find PPS device that matches \fIdevice\fP.
.RE
.sp
\f(CR\-p, `\-\-pps\fP
.RS 4
Print active PPS devices, then exit.
.RE
.sp
\f(CR\-V, `\-\-version\fP
.RS 4
Dump version, then exit.
.RE
.sp
\f(CR\fB\-x SEC\fP, \fB\-\-seconds SEC\fP\fP
.RS 4
Exit after delay of SEC seconds.
.RE
.SH "ARGUMENTS"
.sp
The \fIdevice\fP argument should be the pathname of a device. Such as
/dev/ttyS0 or /dev/pps0. It will be the device monitored.
.sp
For a tty device, each output line is the second and nanosecond parts
of a timestamp followed by the names of the handshake signals then
asserted. Off transitions may generate lines with no signals asserted.
.sp
For a pps device, each output line will contain the assert and clear
times last detected by KPPS.
.sp
If you don\(cqt see output within a second, use \fBcgps\fP, \fBxgps\fP, or some
other equivalent tool to check that your device has a satellite lock and
is getting 3D fixes before giving up on the possibility of PPS.
.sp
Check your cable. Cheap DB9 to DB9 cables such as those issued with
UPSes often carry TXD/RXD/GND only, omitting handshake lines such as
CD. Suspect this especially if the cable jacket looks too skinny to
hold more than three leads!
.sp
Most GPS that have built in USB do not support PPS. When in doubt,
contact the vendor for confirmation that your device does supply PPS.
.SH "RETURN VALUES"
.sp
0
.RS 4
OK
.RE
.sp
1
.RS 4
if the device counld not be opened, or some other failure
.RE
.SH "SEE ALSO"
.sp
\fBcgps\fP(1), \fBxgps\fP(1), \fBgpsd\fP(8)
.SH "RESOURCES"
.sp
\fBProject web site:\fP \c
.URL "https://gpsd.io/" "" ""
.SH "COPYING"
.sp
This file is Copyright 2013 by the GPSD project
.br
SPDX\-License\-Identifier: BSD\-2\-clause
.SH "AUTHOR"
.sp
Eric S. Raymond