Crate tag_dwnld 

tag-dwnld: download a stopped tag’s log into a SQLite database.

Port of host/commandline/dwnld.cc. The tag side uses tagcore-rs; the database is written by the C++ writer (SqliteTagLogWriter) through the taglogwriter crate and the tagcore_c library (static on macOS, shared on Linux and Windows), so the file is the one the C++ tag-dwnld writes from the same tag: byte for byte, on the IMUTag and UIUCTag downloads it was checked with.

The sequence, as in the C++:

1. Check --format before attaching, since attaching resets the tag.
2. Attach, then poll status until the tag reports a definite state.
3. With --rescue-exception, turn an old BitTag’s EXCEPTION into ABORTED; with --stop, stop a RUNNING tag and poll until it stops.
4. Refuse unless the tag is FINISHED, ABORTED or EXCEPTION.
5. Read the config, open the database, and write the header from the same requests, in the same order, as readTagLogHeader().
6. Request pages from index 0. The writer decodes each one and says how many records it consumed; the next request is at the index advanced by that, and a page that consumes nothing ends the log. A NODATA page below the tag’s record count is skipped over.

Exits 0 when the log is written (or there was nothing to download), 1 on any failure, 2 on an option error (clap).

Built only with the sqlitelog feature, which needs libtagcore_c; see host/libraries/taglogwriter-rs/README.md.

Hardware side effects

The attach resets the tag; --stop ends a run; --rescue-exception rewrites one backup-state word. Downloading itself changes nothing on the tag, so a download can be repeated.

Differences from the C++

• An unsupported tag type is reported by the writer when the database is created (“Could not open output: SQLite log output does not support tag type …”), not by a separate check first. The writer refuses before touching the file, so the effect is the same, and the list of supported types stays in one place.
• Durations are printed at full precision (0.022837829) rather than C++ stream precision (0.0233391).
• Option errors exit 2 (clap) rather than 1, as for every Rust tool.

Maintaining

Keep this in step with dwnld.cc: same options, messages, exit status and request sequence, since scripts and the bench procedures use either tool. Two parts must match the C++ exactly, because they decide what is read from the tag:

• read_header mirrors readTagLogHeader(): the same requests, in the same order, and the same ways of stopping (a refused calibration read; a refused or empty state-log chunk).
• The page loop: the index advances by what the writer consumed, a NODATA page below the record count advances it by one, and the loop ends when the writer consumes nothing.

To check a change, download the same finished tag with both tools and cmp the databases; downloading does not change the tag.

Structs

Cli 🔒

Downloads data from a tag

Functions

check_format 🔒

Checks --format without touching the tag: Ok for SQLite (the only format), Err with the message otherwise.

duration_line 🔒

Prints one timing line, with the per-request figure when count > 0.

fail 🔒

Prints message to stderr and returns exit status 1.

is_downloadable 🔒

Whether a download may run in state. EXCEPTION counts: collection is no longer changing the log, and field recovery may depend on reading it.

main 🔒

Attaches, brings the tag to a downloadable state, and writes the log.

print_profile 🔒

Prints --profile: the download’s own timing, then the monitor RPC and link transport counters.

print_progress 🔒

Draws the 40-column progress bar on stdout, as the C++ does.

read_header 🔒

Reads the log header with the requests, in the order, that the C++ readTagLogHeader() makes: Config, TagInfo, calibration constants from index 0 until one is refused, then the state log in chunks until one is refused or empty.

settle 🔒

Polls status a second apart, at least once, until the tag reports a state other than STATE_UNSPECIFIED, and returns that status.

stop 🔒

Stops a running tag and polls every 2 s, at least once, until it reaches FINISHED or ABORTED; returns the final status.

transfer_line 🔒

Prints one transfer line: calls, bytes, time and rate.