nmea(3tcl)

🛰️ NAME 🛰️

nmea — bestie, this is the manual for the nmea package (section 3tcl, she's a Tcl girlie 💅) and her one job is processing NMEA data. That's the whole name. Short, sweet, iconic. ✨

---

🎀 SYNOPSIS 🎀

Okay so before literally anything else you gotta have Tcl on deck, and then you pull in the package. The version is optional, hence the lil ?1.1.0? situation:

package require Tcl 8.5 9

package require nmea ?1.1.0?

::nmea::input sentence

::nmea::open_port port ?speed?

::nmea::close_port

::nmea::configure_port settings

::nmea::open_file file ?rate?

::nmea::close_file

::nmea::do_line

::nmea::rate

::nmea::log ?file?

::nmea::checksum data

::nmea::write sentence data

::nmea::event setence ?command?

and yes it literally says setence in there. not me being the one to fix it 💀 we report, we don't rewrite. no cap.

---

🌸 DESCRIPTION 🌸

So here's the vibe: this package gives you a standard interface for writing software that receives NMEA standard input data. Which means you can read data from COM ports, from files, or just feed it in programmatically like the main character you are. 👑

It also handles checksumming and logging of incoming data, because nobody wants to do that by hand, fr fr.

Once parsing happens, the input gets dispatched to user defined handler commands for processing. Wanna define one of those handlers? Go look at the event command, bestie, she's the one in charge. 🫶

Important note: there are no GPS specific functions in this package. She's just the plumbing, not the satellite. 🛰️

And an NMEA sentence is literally just: a sentence type, followed by a list of data. That's the whole structure. Periodt.

---

✨ COMMANDS ✨

🦋 The lineup

• ::nmea::input sentence — takes that sentence and processes + dispatches it. Here's the tea: if the sentence has no commas in it, it's treated as a plain Tcl list. Otherwise it has to be standard comma delimited NMEA data, with an optional checksum and an optional leading $. Both of these work:

nmea::input {$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39}
nmea::input [list GPGSA A 3 04 05  09 12 "" "" 24 "" "" ""  2.5 1.3 2.1]

• ::nmea::open_port port ?speed? — opens the COM port you named and reads NMEA sentences whenever they show up. Port speed defaults to 4800bps, or you can pass speed and do your own thing. ✨
• ::nmea::close_port — closes the COM port connection, but only if one is actually open. No drama.
• ::nmea::configure_port settings — changes the current port settings. settings takes the exact same format as fconfigure -mode, so go read that if you need the details.
• ::nmea::open_file file ?rate? — opens file and reads NMEA sentences, one per line, at the rate you give in ?rate? measured in milliseconds. The file format is chill — it may omit the leading $ and/or the checksum. And if rate is <= 0 (which is the default, btw) then lines only get processed when something calls do_line. 💤
• ::nmea::close_file — closes the open file if one exists. bye bestie 👋
• ::nmea::do_line — if there's a file currently open, this reads and processes a single line from it. Returns the number of lines read. 📖
• ::nmea::rate — sets the rate at which lines get processed from the open file, in milliseconds. The rate stays consistent across files, so there doesn't need to be a file currently open for you to use this command. Set it to 0 to disable automatic line processing entirely. 🛑
• ::nmea::log ?file? — starts or stops input logging. If you give it a file name, then all NMEA data received on the open port gets logged to ?file? in append mode. If file is an empty string, any logging gets stopped. And if you pass no file at all, it returns a boolean telling you whether logging is currently enabled. 🫧

big caveat, don't skip this one: data written to the port by write, data read from files, or input made using input is NOT logged. only the port data. okay? okay. 💅

• ::nmea::checksum data — returns the checksum of the data you handed it. math girl summer 🧮
• ::nmea::write sentence data — if there's a port currently open, this writes the given sentence and data out to the port in proper NMEA checksummed format. ✍️
• ::nmea::event setence ?command? — registers a handler proc for a given NMEA sentence. Rules: there can be at most one handler per sentence, and any existing handler gets replaced. If you don't pass a command, it returns the name of the current handler for that sentence, or an empty string if none exists. 🔍

So besides the actual incoming sentences, there are 2 builtin types: EOF and DEFAULT.

• The DEFAULT handler fires when there's no specific handler for that sentence.
• The EOF handler fires when End Of File is reached on the open file or port.

Now the signature tea: the handler procedures — with the exception of the builtin types — must take exactly one argument, which is a list of the data values. The DEFAULT handler should have two arguments: the sentence type and the data values. The EOF handler takes no arguments. 📝

Here's the whole squad in action:

nmea::event gpgsa parse_sat_detail
nmea::event default handle_unknown

proc parse_sat_detail {data} {
    puts [lindex $data 1]
}

proc handle_unknown {name data} {
    puts "unknown data type $name"
}

---

🙈 BUGS, IDEAS, FEEDBACK 🙈

Real talk, bestie: this document, and the package it describes, will undoubtedly contain bugs and other problems. Not being shady, that's just how it is. 😭

Please report them in the category nmea of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist

Got ideas for enhancements? For the package and/or the documentation? Also bring those there. We want them. 🫶

If you're proposing code changes, please provide unified diffs — i.e. the output of diff -u. That's the format, no substitutions.

And one more: attachments are strongly preferred over inlined patches. To attach something, go to the Edit form of the ticket right after you create it, then use the left-most button in the secondary navigation bar. boom. done. ✨

---

🔑 KEYWORDS 🔑

gps, nmea

---

🌈 CATEGORY 🌈

Networking

---

👑 COPYRIGHT 👑

Copyright (c) 2006-2009, Aaron Faupell <afaupell@users.sourceforge.net>

---

okay that's the whole page, you made it, so proud of you 🥹💖 this beauty ships out of tcllib, version 1.1.0, and she answers to the name nmea(3tcl). go read your GPS data. slay. 💅✨