|
|
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 | |