ubx

Documentation

Overview

Package ubx decodes the u-blox UBX binary protocol — the native binary message format that u-blox GNSS receivers speak as the compact alternative to NMEA 0183 text. It is the binary counterpart to internal/nmea (gps_nmea_decode): a GPS / GNSS capture from a u-blox module (the dominant GNSS chip family — NEO-6/7/8/9, the modules in countless wardriving / drone / tracker rigs) may be UBX rather than NMEA, and UBX is undecodable as text.

Wrap-vs-native judgement

Native. The UBX framing is a fixed, fully-public wire format
(two sync bytes 0xB5 0x62, a class + id, a little-endian
length, the payload, and an 8-bit Fletcher checksum) and the
NAV-PVT payload is a fixed 92-byte little-endian struct
documented in every u-blox receiver protocol spec. It is byte-
field extraction plus a two-byte checksum loop — a Go port is
a few hundred lines, so a runtime dependency on a UBX library
would not be justified. stdlib only, no new go.mod dep.

What this package covers

• UBX frame envelope: the 0xB5 0x62 sync, message class + id (named for the common NAV classes), little-endian length, and the 8-bit Fletcher checksum (CK_A / CK_B over class + id + length + payload), validated. A capture with several back-to-back frames decodes to a list; leading non-sync bytes are skipped so a mid-stream capture still parses.
• NAV-PVT (class 0x01 id 0x07) — the flagship "navigation position velocity time" message that bundles a complete fix into one record: iTOW, the UTC date/time with its validity flags and time accuracy, fix type (no-fix / dead- reckoning / 2D / 3D / GNSS+DR / time-only) and the gnssFixOK flag, satellites used, longitude / latitude (1e-7 deg), height above ellipsoid and above mean sea level, horizontal / vertical accuracy, the NED velocity vector, ground speed, heading of motion, and position DOP. Raw integer units (mm, mm/s, deg x 1e-7, deg x 1e-5, 0.01 DOP) are converted to metres / m·s⁻¹ / degrees.
• NAV-SAT (class 0x01 id 0x35) — per-satellite signal info: for each tracked SV the constellation (gnssId → GPS / SBAS / Galileo / BeiDou / QZSS / GLONASS / NavIC), the satellite id, carrier-to-noise C/N0, elevation / azimuth, pseudorange residual, the signal-quality indicator, whether the SV is used in the solution, and its health. Anomalous per-satellite C/N0 or geometry is a primary tell of GPS spoofing / jamming, so this is the UBX counterpart to the NMEA GSV decode.
• NAV-STATUS (class 0x01 id 0x03) — fix type + status flags (gpsFixOK, differential solution, week-number / time-of- week valid) + time-to-first-fix + receiver uptime.

What this package does NOT cover (deliberately out of scope)

• Other UBX messages (NAV-POSLLH, NAV-VELNED, NAV-TIMEUTC, RXM-*, CFG-*, MON-*, etc.) — the frame envelope is decoded and the class/id named, but the body is surfaced as a raw hex payload rather than guessed. The messages that carry a full fix / satellite picture (NAV-PVT, NAV-SAT, NAV-STATUS) are bodied out; the others can land in a future change against a reference vector.
• UBX message *encoding* / polling (sending CFG-* to a live receiver) — this is an offline read-only decoder.
• The RTCM / SPARTN correction streams a u-blox module can also emit — separate protocols.

Index

• type Message
  • func Decode(input string) ([]Message, error)
• type NavPVT
• type NavSAT
• type NavSatInfo
• type NavStatus

Types

type Message

type Message struct {
	ClassID    int        `json:"class"`
	ClassHex   string     `json:"class_hex"`
	MessageID  int        `json:"id"`
	IDHex      string     `json:"id_hex"`
	Name       string     `json:"name"`
	Length     int        `json:"payload_length"`
	ChecksumOK bool       `json:"checksum_ok"`
	NavPVT     *NavPVT    `json:"nav_pvt,omitempty"`
	NavSAT     *NavSAT    `json:"nav_sat,omitempty"`
	NavStatus  *NavStatus `json:"nav_status,omitempty"`
	PayloadHex string     `json:"payload_hex,omitempty"`
	Notes      []string   `json:"notes,omitempty"`
}

Message is one decoded UBX frame.

func Decode

func Decode(input string) ([]Message, error)

Decode parses every UBX frame found in the input. The input may be a hex string (whitespace / ':' / '-' separators and a '0x' prefix tolerated) carrying one or more back-to-back UBX frames.

type NavPVT

type NavPVT struct {
	ITOWms         uint32  `json:"itow_ms"`
	UTC            string  `json:"utc,omitempty"`
	Year           int     `json:"year"`
	Month          int     `json:"month"`
	Day            int     `json:"day"`
	Hour           int     `json:"hour"`
	Minute         int     `json:"minute"`
	Second         int     `json:"second"`
	ValidDate      bool    `json:"valid_date"`
	ValidTime      bool    `json:"valid_time"`
	FullyResolved  bool    `json:"fully_resolved"`
	TimeAccuracyNs uint32  `json:"time_accuracy_ns"`
	FixType        int     `json:"fix_type"`
	FixTypeName    string  `json:"fix_type_name"`
	GNSSFixOK      bool    `json:"gnss_fix_ok"`
	NumSV          int     `json:"num_sv"`
	LongitudeDeg   float64 `json:"longitude_deg"`
	LatitudeDeg    float64 `json:"latitude_deg"`
	HeightM        float64 `json:"height_ellipsoid_m"`
	HeightMSLM     float64 `json:"height_msl_m"`
	HorizAccuracyM float64 `json:"horizontal_accuracy_m"`
	VertAccuracyM  float64 `json:"vertical_accuracy_m"`
	VelNorthMS     float64 `json:"velocity_north_ms"`
	VelEastMS      float64 `json:"velocity_east_ms"`
	VelDownMS      float64 `json:"velocity_down_ms"`
	GroundSpeedMS  float64 `json:"ground_speed_ms"`
	HeadingDeg     float64 `json:"heading_of_motion_deg"`
	PositionDOP    float64 `json:"position_dop"`
}

NavPVT is the decoded NAV-PVT (Navigation Position Velocity Time) payload — a complete GNSS fix in a single message.

type NavSAT

type NavSAT struct {
	ITOWms     uint32       `json:"itow_ms"`
	Version    int          `json:"version"`
	NumSVs     int          `json:"num_svs"`
	Satellites []NavSatInfo `json:"satellites"`
}

NavSAT is the decoded NAV-SAT (satellite information) payload — per-satellite signal strength, elevation/azimuth, pseudorange residual and the quality / used / health flags. Anomalous per-satellite C/N0 or geometry is a primary tell of GPS spoofing / jamming, so this is the UBX counterpart to the NMEA GSV decode.

type NavSatInfo

type NavSatInfo struct {
	GNSSID         int     `json:"gnss_id"`
	GNSSName       string  `json:"gnss_name"`
	SVID           int     `json:"sv_id"`
	CNoDBHz        int     `json:"cno_dbhz"`
	ElevationDeg   int     `json:"elevation_deg"`
	AzimuthDeg     int     `json:"azimuth_deg"`
	PseudoRangeRes float64 `json:"pseudorange_residual_m"`
	QualityInd     int     `json:"quality_indicator"`
	QualityName    string  `json:"quality_name"`
	Used           bool    `json:"used_in_solution"`
	Health         int     `json:"health"`
	HealthName     string  `json:"health_name"`
	EphemerisAvail bool    `json:"ephemeris_available"`
	AlmanacAvail   bool    `json:"almanac_available"`
}

NavSatInfo is one satellite row of a NAV-SAT message.

type NavStatus

type NavStatus struct {
	ITOWms       uint32 `json:"itow_ms"`
	GPSFix       int    `json:"gps_fix"`
	GPSFixName   string `json:"gps_fix_name"`
	GPSFixOK     bool   `json:"gps_fix_ok"`
	DiffSoln     bool   `json:"differential_solution"`
	WeekNumSet   bool   `json:"week_number_set"`
	TimeOfWeekOK bool   `json:"time_of_week_set"`
	TTFFms       uint32 `json:"time_to_first_fix_ms"`
	UptimeMs     uint32 `json:"uptime_ms"`
}

NavStatus is the decoded NAV-STATUS (receiver navigation status) payload — fix type + status flags + time-to-first-fix.