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
- type CompatibilityFlags
- type DataHeader
- type DataMessage
- type DefaultParameterHeader
- type DefaultParameterMessage
- type DefaultParameterTypes
- type Dropout
- type DropoutMessage
- type FileHeader
- type FlagBits
- type FlagBitsMessage
- type FormatMessage
- type IncompatibilityFlags
- type InformationHeader
- type InformationMessage
- type LogLevel
- type LoggingHeader
- type LoggingMessage
- type MessageHeader
- type MessageType
- type MultiInformationHeader
- type MultiInformationMessage
- type ParameterHeader
- type ParameterMessage
- type PrimitiveType
- type SubscriptionHeader
- type SubscriptionMessage
- type Synchronization
- type SynchronizationMessage
- type TaggedLoggingHeader
- type TaggedLoggingMessage
- type Unsubscription
- type UnsubscriptionMessage
Constants ¶
const FileMagic = "ULog\x01\x12\x35"
FileMagic is the seven-byte ULog file signature required at offset zero.
const FileVersion uint8 = 1
FileVersion is the format-version byte emitted by the writer.
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.