Net::GPSD3(3pm)

💖 Net::GPSD3 💖

okay so bestie, this is the manual page for Net::GPSD3 — that's the Perl module, in section 3pm of the User Contributed Perl Documentation. pull up a chair, grab a boba, and let's get into it 🧋✨

---

✨ NAME ✨

Net::GPSD3 — Interface to the gpsd server daemon protocol versions 3 (JSON).

like, it's the little Perl buddy that talks to gpsd and speaks JSON protocol v3. that's the whole vibe 💅

---

🛰️ SYNOPSIS 🛰️

👀 Watch Interface 👀

use Net::GPSD3;
my $gpsd=Net::GPSD3->new;
$gpsd->watch;

One Liner — yes she can do it in one line, she's an icon:

perl -MNet::GPSD3 -e 'Net::GPSD3->new->watch'

📡 Poll Interface 📡

use Net::GPSD3;
use Data::Dumper qw{Dumper};
my $gpsd=Net::GPSD3->new;
my $poll=$gpsd->poll;
print Dumper($poll);

One Liner — look at her go:

perl -MNet::GPSD3 -e 'printf "Protocol: %s\n", Net::GPSD3->new->poll->parent->cache->VERSION->protocol;'

and she prints, no cap:

Protocol: 3.4

🌸 POE Interface 🌸

go look at Net::GPSD3::POE, she lives over there 🫶

---

💫 DESCRIPTION 💫

so Net::GPSD3 gives you an object client interface to the gpsd server daemon, and it's using the version 3 protocol. gpsd is an open source GPS daemon from http://www.catb.org/gpsd/ 🌈

Version 3 of the protocol (that's the JSON one) got added to the daemon back in version 2.90. so if your daemon is from before 2.90 (aka protocol 2.X territory, ancient history, grandma era 😭), you need to use the Net::GPSD package instead. wrong module for your daemon = no data, and we don't do that here 💀

---

🎀 CONSTRUCTOR 🎀

✨ new ✨

Returns a new Net::GPSD3 object. fresh out the box, ready to slay 👑

my $gpsd=Net::GPSD3->new;
my $gpsd=Net::GPSD3->new(host=>"127.0.0.1", port=>2947); #defaults

those are literally the defaults btw, host of "127.0.0.1" and port of 2947, so you're getting them whether you ask or not 💖

---

🛠️ METHODS 🛠️

🌐 host 🌐

Sets or returns the current gpsd host. get it, set it, whatever you need bestie.

my $host=$obj->host;

🚪 port 🚪

Sets or returns the current gpsd TCP port.

my $port=$obj->port;

📬 poll 📬

Sends a Poll request to the gpsd server and returns a Net::GPSD3::Return::POLL object. and not only that, this method also populates the cache object with the Net::GPSD3::Return::VERISON and Net::GPSD3::Return::DEVICES objects. multi-tasking queen 👑

my $poll=$gpsd->poll; #isa Net::GPSD3::Return::POLL object

Note: In order to use the poll method consistently you should run the GPSD daemon as a service. You may also need to run the daemon with the -n option. fr fr, do this or poll will be flaky and you'll be sad 😭

👁️ watch 👁️

Calls all handlers that are registered in the handler method.

$gpsd->watch;  #will not return unless something goes wrong.

like she will NOT come back. she stays out there. only if something goes wrong does she return, and at that point, we're not okay 💀

➕ addHandler ➕

Adds handlers to the handler list. stack 'em up.

$gpsd->addHandler(\&myHandler);
$gpsd->addHandler(\&myHandler1, \&myHandler2);

A handler is a sub reference where the first argument is a Net::GPSD3::Return::* object. so your sub gets fed the good stuff 🍓

📋 handlers 📋

List of handlers that are called in order to process objects from the gpsd wathcer stream.

my @handler=$gpsd->handlers; #()
my $handler=$gpsd->handlers; #[]

list context → list, scalar context → arrayref. she's flexible like that 💅

🗄️ cache 🗄️

Returns the Net::GPSD3::Cache caching object. that's where the good stuff gets stashed ✨

---

🔒 METHODS Internal 🔒

🧩 default_handler 🧩

(no description here, she's just chillin' in the internal section, keeping it mysterious 🙈)

🔌 socket 🔌

Returns the cached IO::Socket::INET6 object.

my $socket=$gpsd->socket;  #try to reconnect on failure

she'll try to reconnect on failure. resilient icon 🫶

🧾 json 🧾

Returns the cached JSON::XS object.

🔓 decode 🔓

Returns a perl data structure given a JSON formated string.

my %data=$gpsd->decode($string); #()
my $data=$gpsd->decode($string); #{}

hash in list context, hashref in scalar context, she read the room 💜

🔐 encode 🔐

Returns a JSON string from a perl data structure. the reverse girly 🔁

🏗️ constructor 🏗️

Constructs a class object by lazy loading the classes. lazy but make it efficient, we love her for it 😌

my $obj=$gpsd->constructor(%$data);
my $obj=$gpsd->constructor(class=>"DEVICE",
                           string=>'{...}',
                           ...);

Returns and object in the Net::GPSD3::Return::* namespace. (that's "an object", the original said "and object", we're just quoting the vibe here bestie, no notes 💖)

---

🐛 BUGS 🐛

Log on RT and Send to gpsd-dev email list. that's the protocol, literally 📮

There are no two GPS devices that are alike. Each GPS device has a different GPSD signature as well. If your GPS device does not work out of the box with this package, please send me a log of your devices JSON sentences. every device is a unique little main character and sometimes they need a vibe check 🌈

echo '?POLL;' | nc 127.0.0.1 2947

echo '?WATCH={"enable":true,"json":true};' | socat -t10 stdin stdout | nc 127.0.0.1 2947

run those, capture the tea, send it over ☕

---

🫶 SUPPORT 🫶

DavisNetworks.com supports all Perl applications including this package. shoutout 💖

Try gpsd-dev email list.

---

👑 AUTHOR 👑

Michael R. Davis
CPAN ID: MRDVT
STOP, LLC
domain=>michaelrdavis,tld=>com,account=>perl
http://www.stopllc.com/

---

📜 COPYRIGHT 📜

This program is free software licensed under the...

The BSD License

The full text of the license can be found in the LICENSE file included with this module. read it, it's giving legal but make it slay ⚖️✨

---

🔭 SEE ALSO 🔭

• Net::GPSD
• Net::GPSD3::POE
• GPS::Point
• JSON::XS
• IO::Socket::INET6
• DateTime

go read those too, they're all part of the friend group 🦋

---

okay that's the whole page bestie, you're officially a Net::GPSD3 girlie now 🎀

this masterpiece was brought to you by perl v5.34.0 on 2022-06-16 — and yes, the manual name really is Net::GPSD3(3pm), remember it for the exam 💅💖🌸