ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-GPSD/README
Revision: 1.2
Committed: Sat Jul 26 05:35:16 2008 UTC (16 years ago) by root
Branch: MAIN
CVS Tags: rel-1_0, HEAD
Changes since 1.1: +161 -0 lines
Log Message:
1.0

File Contents

# Content
1 NAME
2 AnyEvent::GPSD - event based interface to GPSD
3
4 SYNOPSIS
5 use AnyEvent::GPSD;
6
7 DESCRIPTION
8 This module is an AnyEvent user, you need to make sure that you use and
9 run a supported event loop.
10
11 This module implements an interface to GPSD (http://gpsd.berlios.de/).
12
13 You need to consult the GPSD protocol desription in the manpage to make
14 better sense of this module.
15
16 METHODS
17 $gps = new AnyEvent::GPSD [key => value...]
18 Creates a (virtual) connection to the GPSD. If the "hostname:port"
19 argument is missing then "localhost:2947" will be used.
20
21 If the connection cannot be established, then it will retry every
22 second. Otherwise, the connection is put into watcher mode.
23
24 You can specify various configuration parameters, most of them
25 callbacks:
26
27 host => $hostname
28 The host to connect to, default is "locahost".
29
30 port => $port
31 The port to connect to, default is 2947.
32
33 min_speed => $speed_in_m_per_s
34 Sets the mininum speed (default: 0) that is considered real for
35 the purposes of replay compression or estimate. Speeds below
36 this value will be considered 0.
37
38 on_error => $cb->($gps)
39 Called on every connection or protocol failure, reason is in $!
40 (protocl errors are signalled via EBADMSG). Can be used to bail
41 out if you are not interested in retries.
42
43 on_connect => $cb->($gps)
44 Nornormally used: Called on every successful connection
45 establish.
46
47 on_response => $cb->($gps, $type, $data, $time)
48 Not normally used: Called on every response received from GPSD.
49 $type is the single letter type and $data is the data portion,
50 if any. $time is the timestamp that this message was received
51 at.
52
53 on_satellite_info => $cb->($gps, {satellite-info}...)
54 Called each time the satellite info changes, also on first
55 connect. Each "satellite-info" hash contains at least the
56 following members (mnemonic: all keys have three letters):
57
58 "prn" holds the satellite PRN (1..32 GPS, anything higher is
59 wASS/EGNOS/MCAS etc, see GPS::PRN).
60
61 "ele", "azi" contain the elevation (0..90) and azimuth (0..359)
62 of the satellite.
63
64 "snr" contains the signal strength in decibals (28+ is usually
65 the minimum value for a good fix).
66
67 "fix" contains either 1 to indicate that this satellite was used
68 for the last position fix, 0 otherwise. EGNOS/WAAS etc.
69 satellites will always show as 0, even if their correction info
70 was used.
71
72 The passed hash references are read-only.
73
74 on_fix => $cb->({point})
75 Called regularly (usually about once/second), even when there is
76 no connection to the GPSD (so is useful to update your idea of
77 the current position). The passed hash reference must *not* be
78 modified in any way.
79
80 If "mode" is 2 or 3, then the "{point}" hash contains at least
81 the following members, otherwise it is undefined which members
82 exist. Members whose values are not known are "undef" (usually
83 the error values, speed and so on).
84
85 time when this fix was received (s)
86
87 lat latitude (S -90..90 N)
88 lon longitude (W -180..180 E)
89 alt altitude
90
91 herr estimated horizontal error (m)
92 verr estimated vertical error (m)
93
94 bearing bearing over ground (0..360)
95 berr estimated error in bearing (degrees)
96 speed speed over ground (m/s)
97 serr estimated error in speed over ground (m/s)
98 vspeed vertical velocity, positive = upwards (m/s)
99 vserr estimated error in vspeed (m/s)
100
101 mode 1 = no fix, 2 = 2d fix, 3 = 3d fix
102
103 ($lat, $lon) = $gps->estimate ([$max_seconds])
104 This returns an estimate of the current position based on the last
105 fix and the time passed since then.
106
107 Useful for interactive applications where you want more frequent
108 updates, but not very useful to store, as the next fix might well be
109 totally off. For example, when displaying a real-time map, you could
110 simply call "estimate" ten times a second and update the cursor or
111 map position, but you should use "on_fix" to actually gather data to
112 plot the course itself.
113
114 If the fix is older then $max_seconds (default: 1.9 times the update
115 interval, i.e. usually 1.9 seconds) or if no fix is available,
116 returns the empty list.
117
118 $gps->record_log ($path)
119 If $path is defined, then that file will be created or truncated and
120 a log of all (raw) packets received will be written to it. This log
121 file can later be replayed by calling "$gps->replay_log ($path)".
122
123 If $path is undefined then the log will be closed.
124
125 $gps->replay_log ($path, %options)
126 Replays a log file written using "record_log" (or stops replaying
127 when $path is undefined). While the log file replays, real GPS
128 events will be ignored. This comes in handy when testing.
129
130 Please note that replaying a log will change configuration options
131 that will not be restored, so it's best not to reuse a gpsd object
132 after a replay.
133
134 The "AnyEvent::GPSD" distribution comes with an example log
135 (eg/example.aegps) that you can replay for testing or enjoyment
136 purposes.
137
138 The options include:
139
140 compress => 1
141 If set to a true value (default: false), then passages without
142 fix will be replayed much faster than passages with fix. The
143 same happens for passages without much movement.
144
145 stretch => $factor
146 Multiplies all times by the given factor. Values < 1 make the
147 log replay faster, values > 1 slower. Note that the frequency of
148 fixes will not be increased, o stretch factors > 1 do not work
149 well.
150
151 A stretch factor of zero is not allowed, but if you want to
152 replay a log instantly you may speicfy a very low value (e.g.
153 1e-10).
154
155 SEE ALSO
156 AnyEvent.
157
158 AUTHOR
159 Marc Lehmann <schmorp@schmorp.de>
160 http://home.schmorp.de/
161