wire

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 28, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package wire defines the byte-level types used by the PX4 ULog file format.

ULog encodes all multi-byte values in little-endian order. A MessageHeader frames each message and MessageHeader.Size bounds its payload. Types ending in Header contain only a fixed payload prefix. Types ending in Message represent a complete payload; variable-width messages implement encoding.BinaryAppender and encoding.BinaryUnmarshaler.

The PX4 ULog specification defines the protocol semantics represented here.

Index

Constants

View Source
const FileMagic = "ULog\x01\x12\x35"

FileMagic is the seven-byte ULog file signature required at offset zero.

View Source
const FileVersion uint8 = 1

FileVersion is the format-version byte emitted by the writer.

View Source
const SyncMagic = "\x2f\x73\x13\x20\x25\x0c\xbb\x12"

SyncMagic is the byte sequence a recovery parser can search for after a corrupt message.

Variables

This section is empty.

Functions

This section is empty.

Types

type CompatibilityFlags

type CompatibilityFlags uint64

CompatibilityFlags advertises optional features that do not change how an older parser reads the rest of the log.

const (
	// CompatibilityFlagDefaultParameters indicates that [MessageTypeDefaultParameter] messages are present.
	CompatibilityFlagDefaultParameters CompatibilityFlags = 1 << 0
)

type DataHeader

type DataHeader struct {
	// MessageID identifies the [SubscriptionHeader.MessageID] that defines the following data bytes.
	MessageID uint16
}

DataHeader is the fixed prefix of a DataMessage. The bytes encoded according to the selected FormatMessage follow.

type DataMessage

type DataMessage struct {
	// MessageID identifies the [SubscriptionMessage.MessageID] that defines Data.
	MessageID uint16
	// Data contains bytes encoded according to the subscription's format.
	Data []byte
}

DataMessage carries one logged value for a previously declared SubscriptionMessage. The subscription selects the format used to interpret DataMessage.Data. Its message type is MessageTypeData.

func (DataMessage) AppendBinary

func (m DataMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*DataMessage) UnmarshalBinary

func (m *DataMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a data payload without its MessageHeader. A failed decode leaves m unchanged.

type DefaultParameterHeader

type DefaultParameterHeader struct {
	// Types contains [DefaultParameterTypes] scopes; at least one bit must be set.
	Types DefaultParameterTypes
	// KeyLength is the key length in bytes.
	KeyLength uint8
}

DefaultParameterHeader is the fixed prefix of a DefaultParameterMessage. Its key and encoded value follow.

type DefaultParameterMessage

type DefaultParameterMessage struct {
	// Types contains [DefaultParameterTypes] scopes; at least one bit must be set.
	Types DefaultParameterTypes
	// Key declares the parameter type and name. ULog permits int32_t and float.
	Key string
	// Value contains the parameter's encoded default value bytes.
	Value []byte
}

DefaultParameterMessage records a parameter's default value for one or more vehicle configurations. DefaultParameterMessage.Key and DefaultParameterMessage.Value use the same encoding as ParameterMessage. A log need not provide every default: for each scope without an entry, the parameter value is also its default. These messages may appear in either the definitions or data section; in the definitions section, they precede the first SubscriptionMessage or logging message. Its message type is MessageTypeDefaultParameter.

func (DefaultParameterMessage) AppendBinary

func (m DefaultParameterMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*DefaultParameterMessage) UnmarshalBinary

func (m *DefaultParameterMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a default-parameter payload without its MessageHeader. A failed decode leaves m unchanged. The codec does not enforce ULog's parameter type restriction.

type DefaultParameterTypes

type DefaultParameterTypes uint8

DefaultParameterTypes identifies the independent configuration scopes to which a DefaultParameterMessage applies. At least one scope must be set.

const (
	// DefaultParameterSystemWide marks a system-wide default value.
	DefaultParameterSystemWide DefaultParameterTypes = 1 << 0
	// DefaultParameterCurrentConfiguration marks a default for the current configuration.
	DefaultParameterCurrentConfiguration DefaultParameterTypes = 1 << 1
)

type Dropout

type Dropout = DropoutMessage

Dropout is the former name of DropoutMessage and remains for source compatibility.

type DropoutMessage

type DropoutMessage struct {
	// Duration is the period of lost logging messages in milliseconds.
	Duration uint16
}

DropoutMessage marks a period in which logging messages were lost, often because the logging device could not keep up. It can be encoded and decoded directly with encoding/binary. Its message type is MessageTypeDropout.

type FileHeader

type FileHeader struct {
	// Magic identifies the file as ULog and must equal [FileMagic].
	Magic [7]byte
	// Version is the file format version. [FileVersion] is the current value.
	Version uint8
	// Timestamp is when logging started, in microseconds.
	Timestamp uint64
}

FileHeader is the fixed 16-byte little-endian header at the start of a ULog file.

type FlagBits

type FlagBits = FlagBitsMessage

FlagBits is the former name of FlagBitsMessage and remains for source compatibility.

type FlagBitsMessage

type FlagBitsMessage struct {
	// CompatibilityFlags identifies features compatible with existing parsers.
	CompatibilityFlags CompatibilityFlags
	// IncompatibilityFlags identifies features that require explicit parser support.
	IncompatibilityFlags IncompatibilityFlags
	// AppendedOffsets contains zero-based file offsets for appended data; unused entries are zero.
	AppendedOffsets [3]uint64
}

FlagBitsMessage tells a parser which optional and incompatible ULog features are present. It represents the first 40 payload bytes and must be the first message after FileHeader. Those bytes can be encoded and decoded directly with encoding/binary; parsers must tolerate future trailing bytes. Its message type is MessageTypeFlagBits.

type FormatMessage

type FormatMessage struct {
	// Format uses the ULog grammar "message_name:type field;type field;".
	Format string
}

FormatMessage defines the name and fields of one logged message format. A format may refer to another FormatMessage, including one that appears later in the definitions section. Its message type is MessageTypeFormat.

func (FormatMessage) AppendBinary

func (m FormatMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*FormatMessage) UnmarshalBinary

func (m *FormatMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a format payload without its MessageHeader. A failed decode leaves m unchanged.

type IncompatibilityFlags

type IncompatibilityFlags uint64

IncompatibilityFlags advertises features that change how the log must be read. A parser must reject any set bit it does not support.

const (
	// IncompatibilityFlagDataAppended indicates that [FlagBitsMessage.AppendedOffsets] contains appended data offsets.
	IncompatibilityFlagDataAppended IncompatibilityFlags = 1 << 0
)

type InformationHeader

type InformationHeader struct {
	// KeyLength is the key length in bytes.
	KeyLength uint8
}

InformationHeader is the fixed prefix of an InformationMessage. InformationHeader.KeyLength bytes of key follow it; all remaining payload bytes are the value.

type InformationMessage

type InformationMessage struct {
	// Key declares the value type and key name, for example "char[3] sys_name".
	Key string
	// Value contains the key's encoded value bytes.
	Value []byte
}

InformationMessage stores one typed metadata entry, such as a hardware or software version. Information keys must be unique within a log. Its message type is MessageTypeInformation.

func (InformationMessage) AppendBinary

func (m InformationMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*InformationMessage) UnmarshalBinary

func (m *InformationMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes an information payload without its MessageHeader. A failed decode leaves m unchanged.

type LogLevel

type LogLevel uint8

LogLevel is an ASCII-encoded Linux kernel log level.

const (
	// LogLevelEmergency indicates that the system is unusable.
	LogLevelEmergency LogLevel = '0'
	// LogLevelAlert indicates that action must be taken immediately.
	LogLevelAlert LogLevel = '1'
	// LogLevelCritical indicates a critical condition.
	LogLevelCritical LogLevel = '2'
	// LogLevelError indicates an error condition.
	LogLevelError LogLevel = '3'
	// LogLevelWarning indicates a warning condition.
	LogLevelWarning LogLevel = '4'
	// LogLevelNotice indicates a normal but significant condition.
	LogLevelNotice LogLevel = '5'
	// LogLevelInfo indicates an informational message.
	LogLevelInfo LogLevel = '6'
	// LogLevelDebug indicates a debug message.
	LogLevelDebug LogLevel = '7'
)

type LoggingHeader

type LoggingHeader struct {
	// Level is the [LogLevel] for the message.
	Level LogLevel
	// Timestamp is the message timestamp in microseconds.
	Timestamp uint64
}

LoggingHeader is the fixed prefix of a LoggingMessage. The untagged log text follows without a terminating null byte.

type LoggingMessage

type LoggingMessage struct {
	// Level is the [LogLevel] for the message.
	Level LogLevel
	// Timestamp is the message timestamp in microseconds.
	Timestamp uint64
	// Message contains the log text without a terminating null byte.
	Message string
}

LoggingMessage carries untagged printf-style log output from the vehicle. Its message type is MessageTypeLogging.

func (LoggingMessage) AppendBinary

func (m LoggingMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*LoggingMessage) UnmarshalBinary

func (m *LoggingMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a logging payload without its MessageHeader. A failed decode leaves m unchanged.

type MessageHeader

type MessageHeader struct {
	// Size is the payload size in bytes, excluding this header.
	Size uint16
	// Type identifies the payload content.
	Type MessageType
}

MessageHeader is the three-byte little-endian frame before every message in the definitions and data sections.

type MessageType

type MessageType uint8

MessageType is the one-byte tag identifying the payload after a MessageHeader.

const (
	// MessageTypeFlagBits identifies a [FlagBitsMessage] payload.
	MessageTypeFlagBits MessageType = 'B'
	// MessageTypeFormat identifies a [FormatMessage] payload.
	MessageTypeFormat MessageType = 'F'
	// MessageTypeInformation identifies an [InformationMessage] payload.
	MessageTypeInformation MessageType = 'I'
	// MessageTypeMultiInformation identifies a [MultiInformationMessage] payload.
	MessageTypeMultiInformation MessageType = 'M'
	// MessageTypeParameter identifies a [ParameterMessage] payload.
	MessageTypeParameter MessageType = 'P'
	// MessageTypeDefaultParameter identifies a [DefaultParameterMessage] payload.
	MessageTypeDefaultParameter MessageType = 'Q'
	// MessageTypeSubscription identifies a [SubscriptionMessage] payload.
	MessageTypeSubscription MessageType = 'A'
	// MessageTypeUnsubscription identifies an [UnsubscriptionMessage] payload.
	MessageTypeUnsubscription MessageType = 'R'
	// MessageTypeData identifies a [DataMessage] payload.
	MessageTypeData MessageType = 'D'
	// MessageTypeLogging identifies a [LoggingMessage] payload.
	MessageTypeLogging MessageType = 'L'
	// MessageTypeTaggedLogging identifies a [TaggedLoggingMessage] payload.
	MessageTypeTaggedLogging MessageType = 'C'
	// MessageTypeSynchronization identifies a [SynchronizationMessage] payload.
	MessageTypeSynchronization MessageType = 'S'
	// MessageTypeDropout identifies a [DropoutMessage] payload.
	MessageTypeDropout MessageType = 'O'
)

type MultiInformationHeader

type MultiInformationHeader struct {
	// IsContinued is 1 when this value continues the previous message with the same key.
	IsContinued uint8
	// KeyLength is the key length in bytes.
	KeyLength uint8
}

MultiInformationHeader is the fixed prefix of a MultiInformationMessage. MultiInformationHeader.IsContinued is 1 when the value continues the previous message with this key.

type MultiInformationMessage

type MultiInformationMessage struct {
	// IsContinued is 1 when Value belongs to the previous group with the same key
	// name, and 0 when it starts a new group.
	IsContinued uint8
	// Key declares this value's type and key name.
	Key string
	// Value contains this message's complete encoded value bytes.
	Value []byte
}

MultiInformationMessage carries one independently typed metadata value that belongs to an ordered group for its key name. Consumers retain these messages in file order. Its message type is MessageTypeMultiInformation.

func (MultiInformationMessage) AppendBinary

func (m MultiInformationMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*MultiInformationMessage) UnmarshalBinary

func (m *MultiInformationMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a multi-information payload without its MessageHeader. A failed decode leaves m unchanged.

type ParameterHeader

type ParameterHeader struct {
	// KeyLength is the key length in bytes.
	KeyLength uint8
}

ParameterHeader is the fixed prefix of a ParameterMessage. Its key and encoded value follow.

type ParameterMessage

type ParameterMessage struct {
	// Key declares the parameter type and name, for example "float MPC_XY_CRUISE".
	Key string
	// Value contains the parameter's encoded value bytes.
	Value []byte
}

ParameterMessage records a vehicle parameter value. In the definitions section it is the value at the start of logging; in the data section it is a later change. ULog parameters are limited to int32_t and float values. Its message type is MessageTypeParameter.

func (ParameterMessage) AppendBinary

func (m ParameterMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*ParameterMessage) UnmarshalBinary

func (m *ParameterMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a parameter payload without its MessageHeader. A failed decode leaves m unchanged. The codec does not enforce ULog's parameter type restriction.

type PrimitiveType

type PrimitiveType string

PrimitiveType is the case-sensitive type spelling used in a format definition.

const (
	// PrimitiveTypeInt8 identifies a signed 8-bit integer.
	PrimitiveTypeInt8 PrimitiveType = "int8_t"
	// PrimitiveTypeUint8 identifies an unsigned 8-bit integer.
	PrimitiveTypeUint8 PrimitiveType = "uint8_t"
	// PrimitiveTypeInt16 identifies a signed 16-bit integer.
	PrimitiveTypeInt16 PrimitiveType = "int16_t"
	// PrimitiveTypeUint16 identifies an unsigned 16-bit integer.
	PrimitiveTypeUint16 PrimitiveType = "uint16_t"
	// PrimitiveTypeInt32 identifies a signed 32-bit integer.
	PrimitiveTypeInt32 PrimitiveType = "int32_t"
	// PrimitiveTypeUint32 identifies an unsigned 32-bit integer.
	PrimitiveTypeUint32 PrimitiveType = "uint32_t"
	// PrimitiveTypeInt64 identifies a signed 64-bit integer.
	PrimitiveTypeInt64 PrimitiveType = "int64_t"
	// PrimitiveTypeUint64 identifies an unsigned 64-bit integer.
	PrimitiveTypeUint64 PrimitiveType = "uint64_t"
	// PrimitiveTypeFloat identifies a 32-bit IEEE-754 floating-point value.
	PrimitiveTypeFloat PrimitiveType = "float"
	// PrimitiveTypeDouble identifies a 64-bit IEEE-754 floating-point value.
	PrimitiveTypeDouble PrimitiveType = "double"
	// PrimitiveTypeBool identifies a one-byte boolean value.
	PrimitiveTypeBool PrimitiveType = "bool"
	// PrimitiveTypeChar identifies a one-byte character.
	PrimitiveTypeChar PrimitiveType = "char"
)

type SubscriptionHeader

type SubscriptionHeader struct {
	// MultiID identifies an instance of a message format; the first and default instance is zero.
	MultiID uint8
	// MessageID uniquely identifies this subscription in [DataHeader.MessageID].
	MessageID uint16
}

SubscriptionHeader is the fixed prefix of a SubscriptionMessage. The name of a previously defined FormatMessage follows.

type SubscriptionMessage

type SubscriptionMessage struct {
	// MultiID identifies an instance of a message format; the first and default instance is zero.
	MultiID uint8
	// MessageID uniquely identifies this subscription in [DataMessage.MessageID].
	MessageID uint16
	// MessageName identifies a previously defined [FormatMessage].
	MessageName string
}

SubscriptionMessage assigns a runtime message ID to one instance of a named format. It must precede every DataMessage that uses that ID. Its message type is MessageTypeSubscription.

func (SubscriptionMessage) AppendBinary

func (m SubscriptionMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*SubscriptionMessage) UnmarshalBinary

func (m *SubscriptionMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a subscription payload without its MessageHeader. A failed decode leaves m unchanged.

type Synchronization

type Synchronization = SynchronizationMessage

Synchronization is the former name of SynchronizationMessage and remains for source compatibility.

type SynchronizationMessage

type SynchronizationMessage struct {
	// Magic is the fixed synchronization sequence in [SyncMagic].
	Magic [8]byte
}

SynchronizationMessage gives a parser a known byte sequence from which it can resume after a corrupt message. It can be encoded and decoded directly with encoding/binary. Its message type is MessageTypeSynchronization.

type TaggedLoggingHeader

type TaggedLoggingHeader struct {
	// Level is the [LogLevel] for the message.
	Level LogLevel
	// Tag identifies the source of the message, such as a process, thread, or class.
	Tag uint16
	// Timestamp is the message timestamp in microseconds.
	Timestamp uint64
}

TaggedLoggingHeader is the fixed prefix of a TaggedLoggingMessage. The log text follows without a terminating null byte.

type TaggedLoggingMessage

type TaggedLoggingMessage struct {
	// Level is the [LogLevel] for the message.
	Level LogLevel
	// Tag identifies the source of the message, such as a process, thread, or class.
	Tag uint16
	// Timestamp is the message timestamp in microseconds.
	Timestamp uint64
	// Message contains the log text without a terminating null byte.
	Message string
}

TaggedLoggingMessage carries printf-style log output with an application- defined source tag, such as a process, thread, or class identifier. Its message type is MessageTypeTaggedLogging.

func (TaggedLoggingMessage) AppendBinary

func (m TaggedLoggingMessage) AppendBinary(dst []byte) ([]byte, error)

AppendBinary appends m without a MessageHeader to dst. A validation error returns dst unchanged.

func (*TaggedLoggingMessage) UnmarshalBinary

func (m *TaggedLoggingMessage) UnmarshalBinary(data []byte) error

UnmarshalBinary validates and decodes a tagged-logging payload without its MessageHeader. A failed decode leaves m unchanged.

type Unsubscription

type Unsubscription = UnsubscriptionMessage

Unsubscription is the former name of UnsubscriptionMessage and remains for source compatibility.

type UnsubscriptionMessage

type UnsubscriptionMessage struct {
	// MessageID identifies the [SubscriptionHeader.MessageID] that will no longer be logged.
	MessageID uint16
}

UnsubscriptionMessage ends the subscription identified by UnsubscriptionMessage.MessageID. Later DataMessage values therefore have no active format for that ID. The payload can be encoded and decoded directly with encoding/binary. Its message type is MessageTypeUnsubscription.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL