libenatsc3baseband

libentasc3baseband implements an ATSC 3.0 baseband packet processor accepting baseband packets and producing ALP packets.

The library is aware of both standard LMTs and “Korean” LMTs and will process baseband packet streams with either type of LMT.

Usage

    • Applications instantiate a baseband packet processor via ENATSC3BasebandOpen.
    • Applications use ENATSC3BasebandRegisterCallbacks to register a callback function to be called when  ALP packets are available.
    • The application sets the PLP(s) on which the processor operates by calling ENATSC3BasebandSetPLPs. The PLPs can be changed at any time by calling ENATSC3BasebandSetPLPs.
    • As baseband packets are received the application calls ENATSC3BasebandProcessBasebandPacket to provide them to the processor. The processor calls the ENATSC3BasebandALPCallbackFunction callback as ALP packets are extracted.
    • When the application is done with the processor it is closed by ENATSC3BasebandClose.

Callback Functions

typedef void(*ENATSC3BasebandALPCallbackFunction)(
    uint32_t plpId,
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber,
    const uint8_t *pPacket, 
    int32_t sPacket, 
    void *pUserData
);

ENATSC3BasebandALPCallbackFunction is called by the baseband packet processor to deliver an ALP packet to the application.

Parameters
    • plpId: The PLP on which the ALP packet was received.
    • pPacketTimeUTC: The timestamp of the baseband packet from which the ALP packet was received. If the ALP packet spans baseband packets then the timestamp is obtained from the first baseband packet containing a fragment of the ALP packet.
    • packetNumber: The packet number of the baseband packet from which the ALP packet was received. If the ALP packet spans baseband packets then the packet number is obtained from the first baseband packet containing a fragment of the ALP packet.
    • pPacket: The ALP packet. The data pointed to by pPacket is not valid once the callback function returns. Applications must copy any data if it is required for an extended period.
    • sPacket: The number of bytes referenced by pPacket.
    • pUserData: Application data provided when the callback was registered.

Function Reference

ENStatus ENATSC3BasebandOpen(
    ENATSC3BasebandHandle_t *phATSC3Baseband
);

ENATSC3BasebandOpen instantiates a baseband packet processor.

Parameters
    • phATSC3Baseband: On successful return contains a handle to the baseband processor.
Return Values
    • ENStatus_Success: A baseband packet processor was instantiated and a handle to the processor is returned in *phATSC3Baseband. The processor must be closed with ENATSC3BasebandClose when the application no longer requires the processor.
    • ENStatus_Failure: An error was encountered while instantiating the processor. The value of *phATSC3Baseband is undefined.
ENStatus ENATSC3BasebandClose(
    ENATSC3BasebandHandle_t hATSC3Baseband
);

ENATSC3BasebandClose closes a baseband packet processor opened with ENATSC3BasebandOpen.

Parameters
    • hATSC3Baseband: A handle to the baseband packet processor to close.
Return Values
    • ENStatus_Success: The processor was closed.
    • ENStatus_Failure: An error was encountered while closing the processor.
ENStatus ENATSC3BasebandRegisterCallbacks(
    ENATSC3BasebandHandle_t hATS3Baseband,
    ENATSC3BasebandALPCallbackFunction pALPCallback, 
    void *pUserData
);

ENATSC3BasebandRegisterCallbacks registers functions to be called when processor events occur.

Parameters
    • hATSC3Baseband: A handle to the baseband packet processor on which to register the callbacks.
    • pALPCallback: The function called when ALP packets are available.
    • pUserData: A pointer passed to the callback function.
Return Values
    • ENStatus_Success: The callbacks were registered.
    • ENStatus_Failure: An error was encountered while registering the callbacks.
ENStatus ENATSC3BasebandSetPLPs(
    ENATSC3BasebandHandle_t hBaseband, 
    uint64_t plpIdMask
);

ENATSC3BasebandSetPLPs specifies the PLPs on which the processor operates. Baseband packets corresponding to other PLPs are ignored.

Parameters
    • hATSC3Baseband: A handle to the baseband packet processor on which to specify the PLPs.
    • plpIdMask: A bitmask indicating the PLPs the processor operates on. A ‘1’ in the corresponding bit position enables processing. For example a plpIdMask of 0x8000000000000007 enables PLPs 0, 1 and 2, and 63.
Return Values
    • ENStatus_Success: The PLPs were set.
    • ENStatus_Failure: An error was encountered while setting the PLPs.
ENStatus ENATSC3BasebandProcessBasebandPacket(
    ENATSC3BasebandHandle_t hATSC3Baseband,
    uint32_t plpId, 
    struct timespec *pPacketTimeUTC, 
    uint64_t packetNumber,
    const uint8_t *pPayload, 
    int32_t payloadLength
);

ENATSC3BasebandProcessBasebandPacket provides a baseband packet to the processor. The baseband packet’s payload is not assumed to be available once ENATSC3BasebandProcessBasebandPacket returns.

Parameters
    • hATSC3Baseband: A handle to the baseband packet processor receiving the baseband packet.
    • plpId: The PLP on which the baseband packet originated.
    • pPacketTimeUTC: The time at which the baseband packet was received from the demodulator. This timestamp is not used by the Base Stack libraries but is passed throughout throughout the stack for use by the application.
    • packetNumber: The baseband packet number (counter) corresponding tot the baseband packet. The packet number is not used by the Base Stack libraries but is passed throughout the stack for use by the application.
    • pPayload: The baseband packet.
    • payloadLength: The number of bytes referenced by pPayload.
Return Values
    • ENStatus_Success: The baseband packet was accepted by the procesor.
    • ENStatus_Failure: The packet was rejected by the processor.
ENStatus ENATSC3BasebandSetVerbosity(
    ENATSC3BasebandHandle_t hATSC3Baseband,
    ENVerbosity verbosity
);

ENATSC3BasebandSetVerbosity specifies the logging verbosity for the baseband packet processor.

Parameters
    • hATSC3Baseband: A handle to the baseband packet processor on which to set the verbosity.
    • verbosity: The verbosity level to set.
Return Values
    • ENStatus_Success: The verbosity level was set.
    • ENStatus_Failure: An error was encountered while setting the verbosity level.
void ENATSC3BasebandSetBitrateStatisticsEnabled(
    ENATSC3BasebandHandle_t hATSC3Baseband, 
    int32_t fEnabled
);

ENATSC3BasebandSetBitrateStatisticsEnabled enables or disables bitrate statistics collection. When enabled statistics such as the baseband packet bitrate and amount of padding in baseband packets is registered with the bitrate statistics facility in libenatsc3utils.

Parameters
    • hATSC3Baseband: A handle to the baseband packet processor on which to enable or disable statistics collection.
    • fEnabled: Whether to enable (non-zero) or disable (zero) collection..