nmea(n)

💖 nmea(n) — the NMEA protocol implementation page, but make it cute 💖

ok so bestie. you're here for nmea(n), which lives in Tcllib and ships as version 1.1.0. it's the manual page for the NMEA protocol implementation package. pull up a chair, grab a boba, we're gonna get you fluent. 🧚✨

---

🌸 NAME 🌸

nmea — process NMEA data. that's it, that's the whole job. she processes NMEA data. 💅

---

✨ SYNOPSIS ✨

the whole vibe at a glance, no cap:

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?

like. look at all those little entry points. iconic. 🌈

---

🦋 DESCRIPTION 🦋

okay so here's the tea. this package hands you a standard interface for writing software that receives NMEA standard input data. it lets you read data from COM ports, files, or programmatic input. it also supports checksumming and logging of incoming data. 🎀

after parsing, input gets dispatched to user defined handler commands for processing. to define a handler, go peek at the event command — she's the one holding the keys. 🔑

and important: there are no GPS specific functions in this package. like, none. zero. it's giving "transport layer only, the GPS math is your problem." 🙈

NMEA data consists of a sentence type, followed by a list of data. that's the whole shape of it. 💖

---

👑 COMMANDS 👑

💜 ::nmea::input sentence

processes and dispatches the supplied sentence. if sentence contains no commas it's treated as a Tcl list, otherwise it must be standard comma delimited NMEA data, with an optional checksum and leading $. both flavors, same energy:

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?

open the specified port (COM port, bestie) and read NMEA sentences whenever they show up. port speed defaults to 4800bps unless you pass speed. 🫶

💜 ::nmea::close_port

closes the COM port connection if one is open. if none is open, whatever, nothing happens, she's chill. 😌

💜 ::nmea::configure_port settings

changes the current port settings. settings has the same format as fconfigure -mode. iykyk. ✨

💜 ::nmea::open_file file ?rate?

opens file and reads NMEA sentences, one per line, at the rate specified by rate in milliseconds. the file format may omit the leading $ and/or the checksum — she's flexible like that. 💅

if rate is <= 0 (which is the default) then lines will only be processed when a call to do_line is made. so like, no autopilot, you drive. 🚗

💜 ::nmea::close_file

closes the open file if one exists. same chill energy as close_port. 🎀

💜 ::nmea::do_line

if there's a currently open file, this command reads and processes a single line from it. returns the number of lines read. one at a time, bestie, we're being gentle with her. 🌸

💜 ::nmea::rate

sets the rate at which lines are processed from the open file, in milliseconds. the rate stays consistent across files — and listen, there does not need to be a file currently open to use this command. she's independent. main character energy. 👑

set it to 0 to disable automatic line processing.

💜 ::nmea::log ?file?

starts or stops input logging. here's the breakdown:

• if a file name is specified, then all NMEA data received on the open port gets logged to file in append mode.
• if file is an empty string, then any logging gets stopped.
• if no file is specified, then it returns a boolean value telling you whether logging is currently enabled.

and now the fine print, no cap: data written to the port by write, data read from files, or input made using input — none of that gets logged. port data only. 🙈

💜 ::nmea::checksum data

returns the checksum of the supplied data. short king of a command. 💖

💜 ::nmea::write sentence data

if there's a currently open port, this command writes the specified sentence and data to the port in proper NMEA checksummed format. she does the math for you, slay. ✨

💜 ::nmea::event setence ?command?

registers a handler proc for a given NMEA sentence. rules of the house:

• there may be at most one handler per sentence
• any existing handler gets replaced
• if no command is specified, it returns the name of the current handler for the given sentence, or an empty string if none exists

in addition to the incoming sentences there are 2 builtin types: EOF and DEFAULT. 🌈

• the handler for the DEFAULT sentence is invoked if there is not a specific handler for that sentence
• the EOF handler is invoked when End Of File is reached on the open file or port

and here's the signature tea, because it matters: 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 has no arguments. get it right bestie, she's picky. 💅

example time, look at this gorgeous code:

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

ate. no crumbs. 🔥

---

😭 BUGS, IDEAS, FEEDBACK 😭

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. it's giving "we know, we know." 💀

please report such in the category nmea of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. please also report any ideas for enhancements you may have for either the package and/or the documentation — she wants to hear from you, fr fr. 🫶

when proposing code changes, please provide unified diffs, i.e. the output of diff -u. ✨

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. little navigation lore, but you need it. 🎀

---

🌈 KEYWORDS 🌈

gps, nmea

---

🎀 CATEGORY 🎀

Networking

---

💖 COPYRIGHT 💖

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

---

ok that's the whole page, you're basically an NMEA girlie now. 🌸 this absolute banger of a manpage is from tcllib, version 1.1.0 — go forth and parse some sentences, bestie, you're gonna do amazing. 💅✨🦋💜