sys/man/8/gpsfs

   1 .TH GPSFS 8
   2 .SH NAME
   3 gpsfs, gpsevermore \- GPS time and position service
   4 .SH SYNOPSIS
   5 .B aux/gpsfs
   6 [
   7 .B -d
   8 .I device
   9 ]
  10 [
  11 .B -b
  12 .I baud
  13 ]
  14 [
  15 .B -s
  16 .I srvname
  17 ]
  18 [
  19 .B -m
  20 .I mntpt
  21 ]
  22 .PP
  23 .B aux/gpsevermore
  24 [
  25 .B -d
  26 .I device
  27 ]
  28 [
  29 .B -b
  30 .I baud
  31 ]
  32 [
  33 .B -n
  34 .I baud
  35 ]
  36 [
  37 .B -l
  38 .I location
  39 ]
  40 .SH DESCRIPTION
  41 .B Aux/gpsfs
  42 reads an NMEA-compatible serial GPS (Global Positioning System)
  43 device and provides time and position
  44 through a file system, by default mounted on
  45 .B /mnt
  46 and implementing
  47 .BR /mnt/gps .
  48 .PP
  49 It implements four files in the
  50 .B gps
  51 directory:
  52 .BR position ,
  53 .BR time ,
  54 .BR satellites ,
  55 and
  56 .BR raw .
  57 .PP
  58 The read-only
  59 .B position
  60 file contains one line of information in 9 tab-separated fields:
  61 .TF "\fImagnetic deviation
  62 .PD
  63 .TP
  64 .I "fix quality
  65 0 means position data invalid, 1 means a 2D position is available, 2 means a 3D position is available.
  66 The value is 8, 9, or 10, respectively, when the fix data comes from a file rather than an actual GPS.
  67 .TP
  68 .I "zulu time
  69 universal coordinated time encoded as hhmmss followed by the character 'Z'.
  70 .TP
  71 .I "system time
  72 time and date converted to the format of
  73 .IR time (2).
  74 .TP
  75 .I longitude
  76 in degrees, east of Greenwich is positive, west negative.
  77 .TP
  78 .I latitude
  79 in degrees, positive is north, negative south of the equator.
  80 .TP
  81 .I altitude
  82 above sea level, in meters.
  83 .TP
  84 .I course
  85 degrees, clockwise from true north.
  86 .TP
  87 .I "ground speed
  88 in km/h
  89 .TP
  90 .I "magnetic deviation
  91 (not provided by all GPSs), in degrees, positive is westerly, negative easterly.
  92 .PP
  93 The read-only
  94 .B time
  95 file contains one line of information in 4 tab-separated fields:
  96 .TF "\fIsystem time
  97 .PD
  98 .TP
  99 .I "gps time
 100 in
 101 .IR time (2)
 102 format.
 103 .TP
 104 .I "gps time
 105 in
 106 .I nsec
 107 (see
 108 .IR time (2))
 109 format (ms accuracy).
 110 .TP
 111 .I "system time
 112 in
 113 .I nsec
 114 format.  This is the system time at the time of the
 115 .I "gps time
 116 sample.  The difference between this and the previous field is used in clock
 117 synchronization.  See
 118 .IR timesync (8).
 119 .TP
 120 .I validity
 121 the character
 122 .B A
 123 meaning sample valid and usable for clock synchronization.  The other values are
 124 not usable for clock sync:
 125 .B B
 126 means valid sample from file playback,
 127 .B V
 128 means invalid sample, and
 129 .B W
 130 means invalid playback sample.
 131 .PP
 132 The read-only
 133 .B satellites
 134 file contains information about the current satellite constellation.  It consists
 135 of one line of general information, followed by zero or more lines, one for each satellite in use.
 136 The first line contains two fields:
 137 .TF "\fIsatellites in view
 138 .PD
 139 .TP
 140 .I "fix quality
 141 same as in the
 142 .B position
 143 file.
 144 .TP
 145 .I "satellites in view
 146 number of satellites above the horizon
 147 .PP
 148 Subsequent lines have four fields:
 149 .TF "\fIelevation
 150 .PD
 151 .TP
 152 .I prn
 153 satellite ID
 154 .TP
 155 .I elevation
 156 above the horizon, degrees.
 157 .TP
 158 .I azimuth
 159 direction, degrees from true north
 160 .TP
 161 .I snr
 162 Signal to noise ratio, 0 - 99 dB
 163 .PP
 164 The contents of these files are refreshed once per second when reading from an actual GPS,
 165 and once per 100 ms (giving a speed up of a factor 10) when playing back from file.
 166 .PP
 167 The read-only
 168 .B raw
 169 file can be read to obtain a copy of the raw NMEA GPS output.
 170 .I Gpsfs
 171 keeps an internal buffer of 8KB, so the reader must keep up with the output
 172 (typically 500 or so bytes per second).
 173 .PP
 174 The
 175 .B \-d
 176 flag establishes the device the GPS samples are read from.  If the device file is not
 177 a serial interface,
 178 .I gpsfs
 179 assumes playback from file and modifies quality parameters as such.
 180 .PP
 181 The
 182 .B \-b
 183 flag specifies the baud rate of the serial line.  The standard baud rate for NMEA
 184 GPS is 4800 baud, but many device allow changing to higher speeds.
 185 .PP
 186 The
 187 .B \-s
 188 flag specifies the name under which the
 189 .I gpsfs
 190 service is posted in
 191 .BR /srv .
 192 .PP
 193 The
 194 .B \-m
 195 flag specifies a mount other than
 196 .BR /mnt .
 197 .SS Evermore
 198 .B Aux/gpsevermore
 199 is used to configure GPSs using an Evermore chipset.
 200 .PP
 201 The
 202 .B \-d
 203 flag specifies the serial device to the GPS.
 204 .PP
 205 The
 206 .B \-b
 207 flag specifies the baud rate of the serial line.  The standard baud rate for NMEA
 208 GPS is 4800 baud, but many device allow changing to higher speeds.
 209 .PP
 210 The
 211 .B \-n
 212 flag specifies the speed to set the GPS to.  When the command finishes, the
 213 GPS should be read (and configured) at the new speed.
 214 .PP
 215 The
 216 .B \-l
 217 flag is sued to specify the location to initialize the GPS to.  The format is
 218 .B dd:mm:ssX
 219 or
 220 .B dd:mm.mmmX
 221 or
 222 .BR dd.dddX ,
 223 where
 224 .B dd
 225 stands for degrees (one or more digits),
 226 .B mm
 227 for minutes and
 228 .B ss
 229 for seconds of arc.
 230 .B X
 231 is one of
 232 .BR W ,
 233 .BR E ,
 234 .B N
 235 or
 236 .BR S .
 237 Longitudes come with
 238 .B W
 239 or
 240 .BR E ,
 241 latitudes with
 242 .B N
 243 or
 244 .BR S .
 245 The
 246 .B \-l
 247 flag is followed by two such fields, one for longitude, one for latitude.  They may be
 248 given in a single argument (separated by white space), or in two arguments, in either order.
 249 Initialization time is taken from
 250 .IR time (2).
 251 .SH "SEE ALSO
 252 .IR timesync (8),
 253 .IR time (2)
 254 .SH FILES
 255 .TF /mnt/gps/satellites
 256 .TP
 257 .B /mnt/gps/position
 258 position, time, speed and heading
 259 .TP
 260 .B /mnt/gps/satellites
 261 satellites in view
 262 .TP
 263 .B /mnt/gps/time
 264 GPS time (millisecond accuracy)
 265 .TP
 266 .B /dev/eia0
 267 default GPS device
 268 .SH SOURCE
 269 .B /sys/src/cmd/aux/gps