1.\" $OpenBSD: nmea.4,v 1.28 2019/01/27 07:15:57 jmc Exp $ 2.\" 3.\" Copyright (c) 2006, 2007 Marc Balmer <mbalmer@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: January 27 2019 $ 18.Dt NMEA 4 19.Os 20.Sh NAME 21.Nm nmea 22.Nd NMEA 0183 timedelta sensor 23.Sh SYNOPSIS 24.Cd "pseudo-device nmea" Op Ar count 25.Sh DESCRIPTION 26This line discipline interfaces NMEA devices, 27such as GPS receivers attached to a serial or USB port. 28.Pp 29The line discipline is enabled by the following sequence: 30.Bd -literal -offset indent 31#include <sys/ioctl.h> 32int ldisc = NMEADISC, fildes; ... 33ioctl(fildes, TIOCSETD, &ldisc); 34.Ed 35.Pp 36The byte stream is unaltered by the line discipline which 37maintains timedelta and position sensors using the NMEA data. 38The sensors will appear as nmea* in the list. 39The timedelta (nanoseconds difference between the received time 40information and the local time), position (calculated latitude 41and longitude in degrees), altitude and speed can be accessed 42through the 43.Xr sysctl 8 44interface. 45.Pp 46The 47.Nm 48line discipline decodes the following NMEA 0183 sentences: 49.Bl -tag -width "RMCXX" 50.It RMC 51Recommended Minimum Specific GPS/TRANSIT Data. 52The time and date information, position and speed are extracted. 53The warning indication is used to provide the sensor status (see below). 54If the attached device sends the RMC message in the 13-field format, 55the operation mode of the GPS device is reported in the sensor description. 56The sensor timestamp is copied from the tty timestamp if a device with PPS 57is being used and tty timestamping has been turned on. 58Otherwise the sensor timestamp is taken when the initial `$' character of 59a message block is received from the NMEA device. 60.It GGA 61Current fix data. 62The altitude in meters is extracted. 63.El 64.Pp 65Messages source are recognised by the first two characters of the NMEA 66sentence according to the following prefixes: 67.Pp 68.Bl -tag -width "XXXXX" -offset indent -compact 69.It GP 70GPS 71.It GA 72Galileo 73.It BD 74BeiDou 75.It GL 76Glonass 77.It GN 78Generic GNSS 79.El 80.Sh SENSOR STATES 81The quality of the timedelta is reported as the sensor status: 82.Bl -tag -width "CRITICALXX" -offset indent 83.It OK 84The time information and position are valid. 85The timedelta is safe to use for applications like 86.Xr ntpd 8 . 87.It WARN 88The attached GPS receiver has been indicating a warning condition 89for at least the last ten minutes. 90The timedelta should be used with care. 91.It CRITICAL 92tty timestamping has been turned on but there is no PPS signal present or the 93GPS receiver indicated a warning condition for at least the last twenty 94minutes. 95Check your hardware. 96Some GPS units need PPS to be manually turned on. 97.El 98.Pp 99The status of a second sensor is used to report the status of the 100device itself: 101.Bl -tag -width "CRITICALXX" -offset indent 102.It OK 103The clock is synchronized, e.g. a GPS receiver has a fix. 104.It WARN 105The device issued a warning condition, e.g. a GPS receiver has no fix. 106.El 107.Sh SEE ALSO 108.Xr tty 4 , 109.Xr ldattach 8 , 110.Xr ntpd 8 , 111.Xr sysctl 8 112.Sh HISTORY 113The 114.Nm 115interface first appeared in 116.Ox 4.0 . 117.Sh AUTHORS 118The 119.Nm 120line discipline was written by 121.An Marc Balmer Aq Mt mbalmer@openbsd.org . 122