Project Entangle ATSC 3.0 Base Stack
The Project Entangle ATSC 3.0 Base Stack provides a foundation for developing receiver solutions around the ATSC 3.0 (aka NextGen TV) broadcast standard. It supports reception of broadcast data from tuner / demodulators in the baseband or ALP formats and provides library layers for handling low-level and service-level signaling, ROUTE/DASH and MMT object reception, NRT object reception, ESG reception, and other functions required of an ATSC 3.0 receiving device. It is hoped that by making the Base Stack available developers can focus on developing innovative solutions around media and data delivered via ATSC 3.0 emissions.
If you find the Base Stack helpful and and/or incorporate it into a project, drop us a note. We’d love to hear what uses its put to!
What Is The Base Stack?
The Base Stack is a small but vital component of the Project Entangle ecosystem. It provides the foundation for the Entangle ATSC 3.0 front-end which allows the Entangle DVR to receive ATSC 3.0 services.
In a typical application the Base Stack is paired with components for acquisition and presentation of ATSC 3.0 services. The following diagram illustrates how it might be used in a receiver.
Among the Base Stack’s features are:
- Low Level Signaling and Service Level Signaling acquisition.
- Non-realtime object receipt.
- Support for ROUTE/DASH and MMTP services.
- Multiple services contained within a single emission can be received using a single tuner.
- Support for multi-PLP emissions.
The Base Stack is implemented as a collection of libraries, with each library implementing a layer of the ATSC 3.0 network stack. The implementation focuses on robust execution (including in the presence of impaired reception) with constrained memory usage as is common in embedded environments.
Each layer of the stack operates in roughly the same manner, with packet data provided by the application and the layer calling back into the application when upper layer data is available. For example, the baseband packet layer accepts baseband packets and calls back into the application as ALP packets are obtained from the baseband packets.
The Base Stack is designed for single-threaded execution. A multi-threaded application utilizing the stack from multiple threads must implement its own locks to prevent concurrent access. However multiple instances of the stack (e.g. in a multi-tuner client) can be run with each instance in its own thread.
The design goals for the Base Stack reflect that it is intended to run in an embedded environment but also that ATSC 3.0 is still taking it first steps and aspects of the standard being fine-tuned and clarified, and best-practices are being developed.
- Robustness. Televisions don’t crash. Even more complex devices such as DVRs and other receivers shouldn’t (though we know they do from time to time). The Base Stack is stable even in the presence of impaired emissions.
- Memory Footprint. One of the challenges of running in an embedded environment is that there’s typically a limited amount of RAM/storage (and no swap). The Base Stack attempts to minimize memory usage. For example, buffering is minimized and XML documents are reformatted into a compact but easily accessible format (EnXML) when they need to be retained.
- CPU load. In the context of a receiver the Base Stack is one small component of the system. Ideally it should take no CPU. In practice of course it does require CPU, and as with most network-like stacks processing the various protocol layers can be non-trivial. The Base Stack was developed with mobile and embedded processors, such as the Raspberry Pi in mind. However it should be noted that the present implementation prioritizes robustness, memory footprint, and maintainability / debuggability over CPU loading. We are happy to assist users in optimizing the Base Stack for specific platforms or use cases.
The Base Stack is currently used as the foundation for the Project Entangle ATSC 3.0 Front-End, which accepts a ATSC 3.0 emission, receives the ROUTE/DASH and MMTP services it contains, and re-containers/re-muxes those services into an MPTS. The resulting MPTS is compatible with solutions accepting transport streams, such as the Project Entangle DVR.
While handling of audiovisual programming is a staple of broadcast TV, there is increasing interest in data delivery via broadcast emissions. These include carouseled delivery of objects (e.g. for digital signage), software/firmware update delivery, and distance learning. Applications receiving data via ATSC 3.0’s NRT, IP, or other mechanisms can be built on the Base Stack.
Supported Source Devices
The Base Stack operates with the both physical ATSC 3.0 tuner/demodulator devices as well as capture files for development and debugging.
The Airwavz RedZone Receiver 1200 and 1400 USB tuner/demodulators are supported by the Base Stack. SDK v2 is required. The SDK is not distributed with the Base Stack but can be obtained from Airwavz.tv.
Limited support for the HDHomerun Flex 4K Development Edition is also provided. The J288 output format is used.
In addition to physical devices the Base Stack supports a file format containing ATSC 3.0 baseband packets and PLP-related L1 data which can be replayed into the stack for development and debugging. Tools are provided for capturing files from Airwavz RedZone Receiver and HDHomerun devices.
The Base Stack is intended to be easily ported to 64-bit Linux platforms.
Additional tuner/demodulators can be supported by replacing the lowest-level “driver” software which serves as an abstraction layer. The requirements for such a driver are fairly trivial:
- Supply certain aspects of tuning status such as signal lock.
- Provide elements of L1 such as the enumeration of PLPs in the emission and the PLPs carrying LLS.
- Provide baseband or ALP packets which can be fed into the baseband or ALP layers of the Base Stack.
Documentation and Sample Code
Documentation for using the layer libraries can be found under the Documentation links to the left.
Various tools utilizing the layer libraries to convert baseband or alp to higher level representations can be found in the enatsc3-base/enatsc3-tools folder. Note that tools starting with “alp2XXX” generally accept either ALP or baseband.
The atsc3BasebandToFMP4 sample app is provided in enatsc3-base/enatsc3-examples. This is a comprehensive example which receives an emission via an Airwavz USB tuner or a capture file, tunes to a service given it’s major/minor number, and receives the fMP4 media and signaling associated with the service. The example writes these objects to files.