This man page is for SatPulse 0.3, which is currently in development. It may not accurately describe the versions of SatPulse available for download. If you have installed SatPulse, refer to the installed man pages for an accurate description.

NAME

satpulsetool-serial - examine serial ports

SYNOPSIS

DESCRIPTION

The satpulsetool serial command can perform the following operations related to serial ports:

detect the speed of a connected GPS receiver by trying to read data from the serial port at different speeds;
detect pulse-per-second (PPS) edges on a modem-control pin;
discover the available serial ports;
show information about a serial port without opening it (this is useful mainly with USB serial ports);
log packets received from a serial port.

With the -d option, it operates on a single specified serial port. With the -a option, it discovers serial ports and operates on all the discovered ports. When either the -d or -a option is specified, the default operation is speed detection. Otherwise, the default operation is to discover the available serial ports and show information about them.

OPTIONS

-h, --help: Show usage help for the serial command.
-a, --all: Discover the available serial ports and perform operations on all discovered ports.
-d, --serial-device path: Operate on the specified serial port.
-i, --info: Show information about serial ports without opening or reading from them.
-p, --pps-pin cts|dcd|dsr|ri: Detect PPS edges on the specified modem-control pin. This causes speed detection not to be performed.
-I, --invert-polarity: Invert the usual PPS pulse polarity. Use this if detected edges trail the start of the second by the pulse width (typically 0.1 s). Requires -p.
-m, --pps-method poll|wait|kernel: Controls how the operating system is used to detect modem status changes that mark pulse edges: kernel means the kernel timestamps the time of a status change; wait means the kernel notifies the application of a status change; poll means the application continually asks for the current status. When this option is omitted, the best available method is used. Requires -p.
--poll-pre-warm seconds: Busy-wait for seconds before each poll window opens. This makes the poll method more precise on hosts whose modem status reads slow down while the machine is idle, at the cost of that fraction of a CPU core. The default is 0, which disables it; a value between 0.02 and 0.05 is suggested. Requires -p.
--max-wakeup-latency seconds: Limit CPU wakeup latency to seconds while detecting PPS. This makes edge detection more precise, at the cost of power. 0 requests the lowest latency available; a value between 10e-6 and 50e-6 is suggested. Currently supported only on Linux. Requires -p.
--packet-log path: Write a log of packets received to path. The log is in JSON lines format. Requires -d.
-s, --device-speed bps: Set the speed of the serial port. This causes speed detection not to be performed. A speed of 0 uses the current speed of the serial port. Requires -d, and -p or --packet-log.
-t, --timeout seconds: Stop detecting PPS edges or capturing packets after seconds. A value of 0 means run until interrupted. The default is 10 with -p, and 0 otherwise. Requires -p, or -s and --packet-log.
-j, --jsonl: Write output in JSON Lines format. A port description object has device and display strings, for a USB port a usb object with numeric vid and pid fields, for a port with a USB serial number a serial string, for a USB port an interface string with the interface number, and, for a port with aliases, an aliases array of paths. A detected speed object has a device string and a numeric speed. With -p, an edge object has a device string, an RFC 3339 UTC timestamp t, and, when the poll method is used, uncertainty and pollWidths arrays and an optional reject string. uncertainty gives two durations in seconds: from the start of the status read before the edge to t, and from t to the end of the status read after the edge. pollWidths gives the durations in seconds of those two reads. A reject string gives the reason the edge is unsuitable for timing: acquiring means the poll window was still being narrowed onto the pulse; anomalous means the reads spanned far longer than for recent edges, as when host load stalls a read; clockStep means the system clock was stepped during the reads.

EXIT STATUS

0: Success
1: Error
2: No data found: no serial ports found, the -d path matched no discovered port, no output received from the device, no packets captured, or no PPS edges detected

EXAMPLES

List the serial ports:

satpulsetool serial

List the serial ports as JSON Lines:

satpulsetool serial --jsonl

Show information about one port:

satpulsetool serial -i -d /dev/ttyUSB0

Detect the speed of a receiver:

satpulsetool serial -d /dev/ttyUSB0

Detect the speed of every serial port:

satpulsetool serial -a

Detect the speed of a receiver, logging the packets received during detection:

satpulsetool serial -d /dev/ttyUSB0 --packet-log capture.jsonl

Capture packets for 30 seconds at 38400 bits per second:

satpulsetool serial -d /dev/ttyUSB0 -s 38400 -t 30 --packet-log capture.jsonl

Capture packets at the port’s current speed until interrupted:

satpulsetool serial -d /dev/ttyUSB0 -s 0 --packet-log capture.jsonl

Watch for PPS pulses on the CTS pin of every serial port:

satpulsetool serial -p cts -a

Monitor PPS edges on the CTS pin for 30 seconds at 38400 bits per second, logging received packets:

satpulsetool serial -p cts -s 38400 -t 30 -d /dev/ttyUSB0 --packet-log capture.jsonl

Show receiver information at the detected speed:

satpulsetool gps -d /dev/ttyUSB0 -s $(satpulsetool serial -d /dev/ttyUSB0) --show-receiver

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXIT STATUS

EXAMPLES

SEE ALSO