Main Content

read

Read next VITA 49 packet from file

    Description

    example

    [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.

    example

    [___] = 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

    collapse all

    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: [1472x1 uint8]
                       IQSamples: [361x1 double]
                         Trailer: [1x1 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
    
    

    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: [1472x1 uint8]
                       IQSamples: [361x1 double]
                         Trailer: [1x1 struct]
    
    
    signalDataPacket = struct with fields:
                      PacketType: 1
                        StreamID: 0
                         ClassID: "7C386C0000"
                     PadBitCount: 0
            IntegerTimestampType: "GPS"
           IntegerTimestampValue: 1625215654
         FractionalTimestampType: "real time"
        FractionalTimestampValue: 900042328000
                        RawBytes: [1472x1 uint8]
                       IQSamples: [361x1 double]
                         Trailer: [1x1 struct]
    
    
    signalDataPacket = struct with fields:
                      PacketType: 1
                        StreamID: 0
                         ClassID: "7C386C0000"
                     PadBitCount: 0
            IntegerTimestampType: "GPS"
           IntegerTimestampValue: 1625215654
         FractionalTimestampType: "real time"
        FractionalTimestampValue: 900084248000
                        RawBytes: [1472x1 uint8]
                       IQSamples: [361x1 double]
                         Trailer: [1x1 struct]
    
    

    Input Arguments

    collapse all

    VITA 49 file reader, specified as a vita49Reader object.

    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.

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

    Data Types: char | string

    Number of packets to be read, specified as a positive integer.

    Data Types: double

    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

    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

    collapse all

    Decoded signal data packet, returned as a structure containing these fields.

    Field DescriptionValue
    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

    Integer in the range [0, 5]
    StreamID

    Stream ID, as specified by the name-value argument StreamID.

    32-bit unsigned integer
    ClassID

    Class ID, as specified by the name-value argument ClassID.

    Character vector or string scalar
    PadBitCountPad bit count is 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 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 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
    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.

    FieldDescription
    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

    Decoded context packet, returned as a structure containing these fields.

    Field DescriptionValue
    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

    Integer in the range [0, 5]
    StreamID

    Stream ID, as specified by the name-value argument StreamID.

    32-bit unsigned integer
    ClassID

    Class ID, as specified by the name-value argument ClassID.

    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 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

    Intermediate frequency (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 radio frequency (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.

    FieldDescription
    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.

    FieldDescription
    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.

    FieldDescription
    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

    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

    Extended Capabilities

    Version History

    Introduced in R2022b

    See Also

    Objects

    Functions