[ViewVC] Annotation of: cvs/cvsroot/AnyEvent-GPSD/README

NAME
    AnyEvent::GPSD - event based interface to GPSD

SYNOPSIS
       use AnyEvent::GPSD;

DESCRIPTION
    This module is an AnyEvent user, you need to make sure that you use and
    run a supported event loop.

    This module implements an interface to GPSD (http://gpsd.berlios.de/).

    You need to consult the GPSD protocol desription in the manpage to make
    better sense of this module.

  METHODS
    $gps = new AnyEvent::GPSD [key => value...]
        Creates a (virtual) connection to the GPSD. If the "hostname:port"
        argument is missing then "localhost:2947" will be used.

        If the connection cannot be established, then it will retry every
        second. Otherwise, the connection is put into watcher mode.

        You can specify various configuration parameters, most of them
        callbacks:

        host => $hostname
            The host to connect to, default is "locahost".

        port => $port
            The port to connect to, default is 2947.

        min_speed => $speed_in_m_per_s
            Sets the mininum speed (default: 0) that is considered real for
            the purposes of replay compression or estimate. Speeds below
            this value will be considered 0.

        on_error => $cb->($gps)
            Called on every connection or protocol failure, reason is in $!
            (protocl errors are signalled via EBADMSG). Can be used to bail
            out if you are not interested in retries.

        on_connect => $cb->($gps)
            Nornormally used: Called on every successful connection
            establish.

        on_response => $cb->($gps, $type, $data, $time)
            Not normally used: Called on every response received from GPSD.
            $type is the single letter type and $data is the data portion,
            if any. $time is the timestamp that this message was received
            at.

        on_satellite_info => $cb->($gps, {satellite-info}...)
            Called each time the satellite info changes, also on first
            connect. Each "satellite-info" hash contains at least the
            following members (mnemonic: all keys have three letters):

            "prn" holds the satellite PRN (1..32 GPS, anything higher is
            wASS/EGNOS/MCAS etc, see GPS::PRN).

            "ele", "azi" contain the elevation (0..90) and azimuth (0..359)
            of the satellite.

            "snr" contains the signal strength in decibals (28+ is usually
            the minimum value for a good fix).

            "fix" contains either 1 to indicate that this satellite was used
            for the last position fix, 0 otherwise. EGNOS/WAAS etc.
            satellites will always show as 0, even if their correction info
            was used.

            The passed hash references are read-only.

        on_fix => $cb->({point})
            Called regularly (usually about once/second), even when there is
            no connection to the GPSD (so is useful to update your idea of
            the current position). The passed hash reference must *not* be
            modified in any way.

            If "mode" is 2 or 3, then the "{point}" hash contains at least
            the following members, otherwise it is undefined which members
            exist. Members whose values are not known are "undef" (usually
            the error values, speed and so on).

               time         when this fix was received (s)

               lat          latitude (S -90..90 N)
               lon          longitude (W -180..180 E)
               alt          altitude

               herr         estimated horizontal error (m)
               verr         estimated vertical error (m)

               bearing      bearing over ground (0..360)
               berr         estimated error in bearing (degrees)
               speed        speed over ground (m/s)
               serr         estimated error in speed over ground (m/s)
               vspeed       vertical velocity, positive = upwards (m/s)
               vserr        estimated error in vspeed (m/s)

               mode         1 = no fix, 2 = 2d fix, 3 = 3d fix

    ($lat, $lon) = $gps->estimate ([$max_seconds])
        This returns an estimate of the current position based on the last
        fix and the time passed since then.

        Useful for interactive applications where you want more frequent
        updates, but not very useful to store, as the next fix might well be
        totally off. For example, when displaying a real-time map, you could
        simply call "estimate" ten times a second and update the cursor or
        map position, but you should use "on_fix" to actually gather data to
        plot the course itself.

        If the fix is older then $max_seconds (default: 1.9 times the update
        interval, i.e. usually 1.9 seconds) or if no fix is available,
        returns the empty list.

    $gps->record_log ($path)
        If $path is defined, then that file will be created or truncated and
        a log of all (raw) packets received will be written to it. This log
        file can later be replayed by calling "$gps->replay_log ($path)".

        If $path is undefined then the log will be closed.

    $gps->replay_log ($path, %options)
        Replays a log file written using "record_log" (or stops replaying
        when $path is undefined). While the log file replays, real GPS
        events will be ignored. This comes in handy when testing.

        Please note that replaying a log will change configuration options
        that will not be restored, so it's best not to reuse a gpsd object
        after a replay.

        The "AnyEvent::GPSD" distribution comes with an example log
        (eg/example.aegps) that you can replay for testing or enjoyment
        purposes.

        The options include:

        compress => 1
            If set to a true value (default: false), then passages without
            fix will be replayed much faster than passages with fix. The
            same happens for passages without much movement.

        stretch => $factor
            Multiplies all times by the given factor. Values < 1 make the
            log replay faster, values > 1 slower. Note that the frequency of
            fixes will not be increased, o stretch factors > 1 do not work
            well.

            A stretch factor of zero is not allowed, but if you want to
            replay a log instantly you may speicfy a very low value (e.g.
            1e-10).

SEE ALSO
    AnyEvent.

AUTHOR
       Marc Lehmann <schmorp@schmorp.de>
       http://home.schmorp.de/

Revision:	1.2
Committed:	Sat Jul 26 05:35:16 2008 UTC (18 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-1_0, HEAD
Changes since 1.1:	+161 -0 lines
Log Message:	1.0
#	User	Rev	Content
1	root	1.2	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