read

Read next VITA 49 packet

Since R2022b

Syntax

[signalDataPacket,contextPacket,contextPacketChangeIndex] = read(vita49ReaderObj)

[signalDataPacket,contextPacket,contextPacketChangeIndex,commandPacket,processedLength] = read(vita49ReaderObj,data)

[___] = read(vita49ReaderObj,Name=Value)

Description

[signalDataPacket,contextPacket,contextPacketChangeIndex] = read(vita49ReaderObj) reads the next packet from the VMEbus International Trade Association (VITA) 49 file specified by the input VITA 49 file reader object, vita49ReaderObj, and returns the signal data packet, signalDataPacket, and context packet, contextPacket. The function also returns the starting indices of the signal data packets after any new context packet arrival, in contextPacketChangeIndex. Note that the read function will terminate if it finds any ill-formatted packet while reading the file.

[signalDataPacket,contextPacket,contextPacketChangeIndex,commandPacket,processedLength] = read(vita49ReaderObj,data) reads the next packet form the VITA 49 data specified by data variable in the VITA 49 file reader object, vita49ReaderObj. The function also returns the number of decoded bytes processedLength from the given VITA 49 data.

[___] = read(vita49ReaderObj,Name=Value) specifies one or more optional name-value arguments, in addition to the output arguments from the previous syntax. For example, StreamID=2 sets the stream identifier to 2.

Examples

Read Specified Number of Packets from File

Create a VITA 49 file reader object, specifying the name of a VITA 49 file and an output format for the packet timestamp.

vita49ReaderObj = vita49Reader("VITA49SampleData.bin");
vita49ReaderObj.OutputTimestampFormat = "seconds";

Specify the number of packets to be read from the file.

numpkt = 11;

Read the specified number of packets from the VITA 49 file to the MATLAB® workspace.

[signalDataPacket,contextPacket,contextPacketChangeIndex] = read(vita49ReaderObj,NumPackets=numpkt)

signalDataPacket = struct with fields:
                  PacketType: 1
                    StreamID: 0
                     ClassID: "7C386C0000"
                 PadBitCount: 0
        IntegerTimestampType: "GPS"
       IntegerTimestampValue: 1625215654
     FractionalTimestampType: "real time"
    FractionalTimestampValue: 900000344000
                    RawBytes: [1472×1 uint8]
                   IQSamples: [722×1 double]
                     Trailer: [1×1 struct]

contextPacket=1×10 struct array with fields:
    PacketType
    StreamID
    ClassID
    IntegerTimestampType
    IntegerTimestampValue
    FractionalTimestampType
    FractionalTimestampValue
    RawBytes
    ContextFieldChangeIndicator
    ReferencePointIdentifier
    Bandwidth
    IFReferenceFrequency
    RFFrequency
    RFFrequencyOffset
    IFBandOffset
    ReferenceLevel
    Gain
    OverRangeCount
    SampleRate
    TimestampAdjustment
    TimestampCalibrationTime
    StateAndEventIndicator
    SignalDataPayloadFormat
      ⋮

contextPacketChangeIndex = 1×10

     0     0     0     0     0     0     0     0     0     1

Clear the vita49Reader System object.

clear vita49ReaderObj

Read Packets in Streaming Mode from File

Create a VITA 49 file reader object, specifying the name of a VITA 49 file.

vita49ReaderObj = vita49Reader("VITA49SampleData.bin");

Set the stream identifier as 1, class identifier as "736C860000", and packet type as signal data packet.

pktType = "signal data";
streamID = 0;
classID = "7C386C0000";

In streaming mode, read the VITA 49 packets that match the specified filters to the MATLAB workspace.

for idx = 1:3
    signalDataPacket = read(vita49ReaderObj, ...
      PacketType=pktType,StreamID=streamID,ClassID=classID)
end

signalDataPacket = struct with fields:
                  PacketType: 1
                    StreamID: 0
                     ClassID: "7C386C0000"
                 PadBitCount: 0
        IntegerTimestampType: "GPS"
       IntegerTimestampValue: 1625215654
     FractionalTimestampType: "real time"
    FractionalTimestampValue: 900000344000
                    RawBytes: [1472×1 uint8]
                   IQSamples: [722×1 double]
                     Trailer: [1×1 struct]

signalDataPacket = struct with fields:
                  PacketType: 1
                    StreamID: 0
                     ClassID: "7C386C0000"
                 PadBitCount: 0
        IntegerTimestampType: "GPS"
       IntegerTimestampValue: 1625215654
     FractionalTimestampType: "real time"
    FractionalTimestampValue: 900042328000
                    RawBytes: [1472×1 uint8]
                   IQSamples: [722×1 double]
                     Trailer: [1×1 struct]

signalDataPacket = struct with fields:
                  PacketType: 1
                    StreamID: 0
                     ClassID: "7C386C0000"
                 PadBitCount: 0
        IntegerTimestampType: "GPS"
       IntegerTimestampValue: 1625215654
     FractionalTimestampType: "real time"
    FractionalTimestampValue: 900084248000
                    RawBytes: [1472×1 uint8]
                   IQSamples: [722×1 double]
                     Trailer: [1×1 struct]

Clear the vita49Reader System object.

clear vita49ReaderObj

Read Specified Number of Packets from Workspace

Create a VITA 49 file reader object without any input arguments.

vita49ReaderObj = vita49Reader;

Load vita49Data.mat into the workspace.

load('vita49Data.mat')

The vita49Data.mat consists of a variable data with 37 VITA 49 packets. Read the VITA 49 packets from the variable data.

[sigDataPackets,contextPackets,contextChangeIdx,commandPackets, ...
      processedlen] = read(vita49ReaderObj, data, "NumPackets",37);

Clear the vita49Reader System object.

clear vita49ReaderObj

Input Arguments

vita49ReaderObj — VITA 49 file reader

vita49Reader object

VITA 49 file reader, specified as a vita49Reader object.

data — VITA 49 formatted data

array

VITA 49 formatted data, specified as a unit8 array in the workspace.

Data Types: uint8

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: StreamID=2 sets the stream identifier to 2.

PacketType — Type of packet to be read

"signal data" | "context" | "command"

Type of packet to be read, specified as "signal data", "context", or "command". If you do not specify this argument, the function reads the next packet from the file.

Data Types: char | string

NumPackets — Number of packets to be read

1 (default) | positive integer

Number of packets to be read, specified as a positive integer. To read all packets up to the end of the file, set NumPackets to intmax ("uint32") or intmax ("uint64").

Data Types: double | uint32 | uint64

StreamID — Stream identifier

nonnegative integer

Stream identifier, specified as a nonnegative integer.

If you specify StreamID, the function identifies the packets belonging to only the specified ID from the packet stream.

Data Types: uint32

ClassID — Class identifier

character vector | string scalar

Class identifier, specified as a character vector or string scalar.

A class identifier is a 5-byte-long, hex-formatted string that includes three bytes of Organizational Unique Identifier (OUI) information and two bytes of information class code.

Data Types: char | string

Output Arguments

signalDataPacket — Decoded signal data packet

structure

Decoded signal data packet, returned as a structure.

Signal data packets convey digitized intermediate frequency (IF) and radio frequency (RF) signals. The output structure of the decoded signal data packet contains these fields:

Field	Description	Value
PacketType	Type of VITA 49 packet, returned as one of these values. 0, 1, 2, or 3 — Indicates signal time data packet 4 or 5 — Indicates context packet 6 or 7 — Indicates command packet	Integer in the range [0, 7]
StreamID	Stream ID, as specified by the name-value argument StreamID, of the read object function.	32-bit unsigned integer
ClassID	Class ID, as specified by the name-value argument ClassID, of the read object function.	Character vector or string scalar
PadBitCount	Pad bit count represents the difference between the nearest multiple of 32 and the actual number of payload bits to pack, returned as a nonnegative integer. Pad bits are required when the size and the number of data items do not completely fill the last 32-bit word of a data packet.	8-bit unsigned integer
IntegerTimestampType	Integer timestamp type, returned as "UTC", "GPS", or a user-specified time-code.	Character vector or string scalar
IntegerTimestampValue	Integer timestamp value, in seconds. This value represents the reference point time of the data samples or metadata in the packet, returned to 1-second resolution accuracy.	32-bit unsigned integer
FractionalTimestampType	Fractional timestamp, returned as "sample count", "real time", or "free running count". When this value is "sample count" or "real time", the FractionalTimestampValue value adds resolution to the IntegerTimestampValue value, so that together they provide a range of years, and a precision down to sample period or picoseconds, respectively. When returned as "free running count", the value provides an incrementing sample count from any chosen starting time.	Character vector or string scalar
FractionalTimestampValue	Fractional timestamp value in picoseconds, represents the reference point time of the data samples or metadata in the packet, returned as a timestamp of higher resolution than the integer timestamp value.	64-bit unsigned integer
RawBytes	Raw payload in bytes, which is not decoded, returned as a column vector.	Column vector with 8-bit unsigned integer elements
IQSamples	Decoded real or complex in-phase quadrature (IQ) Cartesian samples of the signal data, returned as a column vector. This function does not support decoding of complex polar samples.	Column vector with elements of data type double
Trailer	Validity of the decoded data and the status of the processes producing that data, returned as a structure with these fields. Field Description CalibratedTimeIndicator Calibrated time indicator, returned as one of these logical values. 1 — Indicates the timestamp in the signal data packet is calibrated to some external reference 0 — Indicates the timestamp is free running and may be inaccurate ValidDataIndicator Valid data indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates the data packet as valid. ReferenceLockIndicator Reference lock indicator, returned as one of these logical values. 1 — Indicates any phase-locked loops (PLL) affecting the data are locked and stable 0 — Indicates at least one PLL is not locked and stable AGCIndicator AGC indicator, returned as one of these logical values. 1 — Indicates AGC is active 0 — Indicates MGC is active MGCIndicator MGC indicator, returned as one of these logical values. 1 — Indicates MGC is active 0 — Indicates AGC is active DetectedSignalIndicator Detected signal indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that the data contained in the packet has some detected signal. SpectrumInversionIndicator Spectrum inversion indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that the signal conveyed in the data payload has an inverted spectrum with respect to the spectrum of the signal at the system reference point. OverRangeIndicator Over range indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that at least one data sample in the payload is invalid due to the signal exceeding the range of the data item. SampleLossIndicator Sample loss indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that the packet contains at least one sample discontinuity due to processing errors or buffer overflow. AssociatedContextPacketCount Associated context packet count, returned as a 7-bit unsigned integer. This count includes the associated context packets transmitted by a process other than the one that transmits the signal data packet containing the count.	Structure

Data Types: struct

contextPacket — Decoded context packet

structure

Decoded context packet, returned as a structure.

Context packets convey information such as the sample rate of the data, the frequency range being transmitted, and the type of modulation used. It also conveys transmit control information that allows the receiver to dynamically adjust various parameters of the transmitted data, such as the gain or frequency offset, to optimize the reception quality to interpret and process the data accurately.

The output structure of the decoded context packet contains these fields:

Field	Description	Value
PacketType	Type of VITA 49 packet, returned as one of these values. 0, 1, 2, or 3 — Indicates signal time data packet 4 or 5 — Indicates context packet 6 or 7 — Indicates command packet	Integer in the range [0, 7]
StreamID	Stream ID, as specified by the name-value argument StreamID, of the read object function.	32-bit unsigned integer
ClassID	Class ID, as specified by the name-value argument ClassID, of the read object function.	Character vector or string scalar
IntegerTimestampType	Integer timestamp type, returned as "UTC", "GPS", or a user-specified time-code.	Character vector or string scalar
IntegerTimestampValue	Integer timestamp value, in seconds. This value represents the reference point time of the data samples or metadata in the packet, returned to 1-second resolution accuracy.	32-bit unsigned integer
FractionalTimestampType	Fractional timestamp, returned as "sample count", "real time", or "free running count". When this value is "sample count" or "real time", the FractionalTimestampValue value adds resolution to the IntegerTimestampValue value, so that together they provide a range of years, and a precision down to sample period or picoseconds, respectively. When returned as "free running count", the value provides an incrementing sample count from any chosen starting time.	Character vector or string scalar
FractionalTimestampValue	Fractional timestamp value in picoseconds, represents the reference point time of data samples or metadata in the packet, returned as a timestamp of higher resolution than the integer timestamp value.	64-bit unsigned integer
RawBytes	Raw payload in bytes, which is not decoded, returned as a column vector.	Column vector with 8-bit unsigned integer elements
ContextFieldChangeIndicator	Bit indicator returned as 0 (false) or 1 (true). A value of 1 indicates that at least one context field contains a new value.	0 (false) or 1 (true)
ReferencePointIdentifier	Reference point ID consists of the StreamID of the reference point, returned as a nonnegative integer.	32-bit unsigned integer
Bandwidth	Usable spectrum at the output of a communication channel, returned as a nonnegative scalar in hertz.	Nonnegative scalar
IFReferenceFrequency	IF at which a carrier wave shifts as an intermediate step in transmission or reception of the signal, returned as a real scalar in hertz.	Real scalar
RFFrequency	Location in the signal path that corresponds to the original frequency, returned as a real scalar in hertz.	Real scalar
RFFrequencyOffset	Intentional slight deviation of the broadcast RF to reduce the interference with other transmitters, returned as a real scalar in hertz.	Real scalar
IFBandOffset	IF offset from the IFReferenceFrequency to the center of the band, returned as a real scalar in hertz.	Real scalar
ReferenceLevel	Physical signal amplitude at a reference point relative to the corresponding data sample value, returned as a real scalar in dB.	Real scalar
Gain	Amount of signal gain or signal attenuation from the reference point, returned as a real scalar in dB.	Real scalar
OverRangeCount	Number of data samples in the paired data packet whose amplitudes are beyond the range of the data item format, returned as a nonnegative integer in dB.	32-bit unsigned integer
SampleRate	Sampling rate of the data samples in the payload of a paired data packet stream, returned as a positive integer in hertz.	Positive integer
TimeStampAdjustment	Delay used to adjust the timestamp information of the first packet of the file, returned as a structure with these fields. Field Description GlobalTimestamp Global timestamp indicator, returned as one of these logical values. 1 — Indicates the timestamp details apply globally to all packets in the information stream 0 — Indicates the timestamp details apply only to the context stream and the paired data stream TSECode Indicates the type of TimestampEpoch provided, returned as "Unspecified", "UTC", "GPS", or "POSIX". TimestampEpoch Conveys the time in one of these formats, depending on the value of the TSECode field. If the TSECode field is returned as "UTC", then timestamp epoch conveys time in the UTC epoch. The value returned provides the time of the start of the epoch in international system of units (SI) seconds, including leap seconds, since 1970-01-01T00:00:00Z (UTC). If the TSECode field is returned as "GPS", then timestamp epoch conveys time in the GPS epoch. The value returned provides the time of the start of the epoch used in SI seconds, since 1980-01-06T00:00:00Z (UTC). Leap seconds are not applicable within the GPS epoch. If the TSECode field is returned as "POSIX", then timestamp epoch conveys time in the POSIX epoch. The value returned provides the time of the start of the epoch used in nominal seconds, since 1970-01-01T00:00:00Z (UTC). Leap seconds are not applicable within the POSIX epoch. LeapSecondHandle Indicates how the leap seconds are handled in the packet timestamps, returned as "Not applicable", "normal", "duplication", or "overflow". SecScheduledPerDay Indicates the number of seconds in the current day denoted by the packet timestamps, returned as 0, 86399, 86400, or 86401 seconds. TimeSource Indicates the time reference source used, returned as "Unspecified", "Atomic Clock", "Satellite System", "Terrestrial Radio", "PTP", "NTP or SNTP", or "Not Defined". PosixTimebufferOffset Conveys the difference in seconds between UTC time and POSIX time, returned as a 8-bit unsigned integer. This value represents the current total leap seconds count.	Structure
TimestampCalibrationTime	Conveys the date and time at which the timestamp in the data signal packet and context packet was confirmed accurate, returned as a nonnegative integer.	32-bit unsigned integer
StateAndEventIndicator	Conveys a set of binary indications and a limited number of non-binary state indications, returned as a structure with these fields. This structure field is equivalent to be the Trailer field of the signalDataPacket output argument structure. Field Description CalibratedTimeIndicator Calibrated time indicator, returned as one of these logical values. 1 — Indicates the timestamp in the signal data packet is calibrated to some external reference 0 — Indicates the timestamp is free running and may be inaccurate ValidDataIndicator Valid data indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates the data packet as valid. ReferenceLockIndicator Reference lock indicator, returned as one of these logical values. 1 — Indicates any phase-locked loops (PLL) affecting the data are locked and stable 0 — Indicates at least one PLL is not locked and stable AGCIndicator AGC indicator, returned as one of these logical values. 1 — Indicates AGC is active 0 — Indicates MGC is active MGCIndicator MGC indicator, returned as one of these logical values. 1 — Indicates MGC is active 0 — Indicates AGC is active DetectedSignalIndicator Detected signal indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that the data contained in the packet has some detected signal. SpectrumInversionIndicator Spectrum inversion indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that the signal conveyed in the data payload has an inverted spectrum with respect to the spectrum of the signal at the system Reference Point. OverRangeIndicator Over range indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that at least one data sample in the payload is invalid due to the signal exceeding the range of the data item. SampleLossIndicator Sample loss indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates that the packet contains at least one sample discontinuity due to processing errors or buffer overflow. AssociatedContextPacketCount Associated context packet count, returned as a 7-bit unsigned integer. This count includes the associated context packets transmitted by a process other than the one that transmits the signal data packet containing the count.	Structure
SignalDataPayloadFormat	Consists of the format of the real or complex signal data (of either 8, 16, or 32 bits) and the data item size, returned as a structure with these fields. Field Description LinkEfficientPacking Link-efficient packing indicator, returned as one of these logical values. 1 — Indicates link-efficient packing is used in the paired data packet stream 0 — Indicates processing-efficient packing is used DataSampleType Indicates whether the data samples are real or complex Cartesian samples. DataItemFormat Five-bit code that indicates the type of data items used in the paired data packet stream. This function supports the decimal values of 0 (signed fixed-point) and 16 (unsigned fixed-point). RepeatCountIndicator Repeat count indicator, returned as a logical value of 1 or 0. When returned as 1, it indicates sample component repeating in the paired data packet stream. EventTagSize Event tag size field value used in the paired data packet stream, returned as a 3-bit unsigned integer. ChannelTagSize Channel tag size field value used in the paired data packet stream, returned as a 4-bit unsigned integer. DataItemFractionSize Number of bits in the fraction of a non-normalized number of the format integer.fraction, where the total size of the number is given by the data item size field. The value is returned as a 4-bit unsigned integer. ItemPackingFieldSize Item packing field size, returned as a 6-bit unsigned integer. The value is one less than the actual item packing size used in the paired data packet stream. DataItemSize Data item size, returned as a 6-bit unsigned integer. This value is one less than the actual data item size used in the paired data packet stream. RepeatCount Repeat count, returned as a 16-bit unsigned integer. This value is one less than the actual repeat count used in the paired data packet stream. VectorSize Vector size, returned as a 16-bit unsigned integer. This value is one less than the actual vector size used in the paired data packet stream.	Structure

Data Types: struct

contextPacketChangeIndex — Starting indices of signal data packets after any new context packet arrival

array of nonnegative integers

Starting indices of the signal data packets after any new context packet arrival, returned as an array of nonnegative integers.

When two context packets arrive one after another, the corresponding value returned is two zeros.

Data Types: double

commandPacket — Undecoded command packet

structure

Undecoded command packet, returned as a structure. Command packets convey information to control receivers, exciters, platforms, and related components

The output structure of the undecoded command contains these fields:

Field	Description	Value
PacketType	Type of VITA 49 packet, returned as one of these values. 0, 1, 2, or 3 — Indicates signal time data packet 4 or 5 — Indicates context packet 6 or 7 — Indicates command packet	Integer in the range [0, 7]
StreamID	Stream ID, as specified by the name-value argument StreamID, of the read object function.	32-bit unsigned integer
ClassID	Class ID, as specified by the name-value argument ClassID, of the read object function.	Character vector or string scalar
PadBitCount	Pad bit count represents the difference between the nearest multiple of 32 and the actual number of payload bits to pack, returned as a nonnegative integer. Pad bits are required when the size and the number of data items do not completely fill the last 32-bit word of a data packet.	8-bit unsigned integer
IntegerTimestampType	Integer timestamp type, returned as "UTC", "GPS", or a user-specified time-code.	Character vector or string scalar
IntegerTimestampValue	Integer timestamp value, in seconds. This value represents the reference point time of the data samples or metadata in the packet, returned to 1-second resolution accuracy.	32-bit unsigned integer
FractionalTimestampType	Fractional timestamp, returned as "sample count", "real time", or "free running count". When this value is "sample count" or "real time", the FractionalTimestampValue value adds resolution to the IntegerTimestampValue value, so that together they provide a range of years, and a precision down to sample period or picoseconds, respectively. When returned as "free running count", the value provides an incrementing sample count from any chosen starting time.	Character vector or string scalar
FractionalTimestampValue	Fractional timestamp value in picoseconds, represents the reference point time of data samples or metadata in the packet, returned as a timestamp of higher resolution than the integer timestamp value.	64-bit unsigned integer
RawBytes	Raw payload in bytes, which is not decoded, returned as a column vector.	Column vector with 8-bit unsigned integer elements

Data Types: struct

processedLength — Number of bytes processed

nonnegative integer

Number of bytes processed in a read call, returned as a nonnegative integer.

Data Types: double

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Code generation is available only when the OutputTimestampFormat property of the vita49Reader object is set to the default value of "seconds".

Version History

Introduced in R2022b