diff --git a/assets/images/5gbc/5gbc-basic-setup.png b/assets/images/5gbc/5gbc-basic-setup.png new file mode 100644 index 00000000..9e43486e Binary files /dev/null and b/assets/images/5gbc/5gbc-basic-setup.png differ diff --git a/assets/images/5gbc/5gbc-playback.png b/assets/images/5gbc/5gbc-playback.png new file mode 100644 index 00000000..f767ab1b Binary files /dev/null and b/assets/images/5gbc/5gbc-playback.png differ diff --git a/assets/images/5gbc/5guc-playback.png b/assets/images/5gbc/5guc-playback.png new file mode 100644 index 00000000..e2e1299e Binary files /dev/null and b/assets/images/5gbc/5guc-playback.png differ diff --git a/assets/images/5gbc/android-seamless-switching-architecture.png b/assets/images/5gbc/android-seamless-switching-architecture.png new file mode 100644 index 00000000..8da397d1 Binary files /dev/null and b/assets/images/5gbc/android-seamless-switching-architecture.png differ diff --git a/assets/images/5gbc/safari-playback-ott.png b/assets/images/5gbc/safari-playback-ott.png new file mode 100644 index 00000000..fd23c1b1 Binary files /dev/null and b/assets/images/5gbc/safari-playback-ott.png differ diff --git a/pages/lte-based-5g-broadcast/additional/additional.md b/pages/lte-based-5g-broadcast/additional/additional.md new file mode 100644 index 00000000..45dea811 --- /dev/null +++ b/pages/lte-based-5g-broadcast/additional/additional.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Additional Resources +parent: MBMS and LTE-based 5G Broadcast +has_children: true +nav_order: 5 +--- + + diff --git a/pages/lte-based-5g-broadcast/hardware-requirements.md b/pages/lte-based-5g-broadcast/additional/hardware-requirements.md similarity index 99% rename from pages/lte-based-5g-broadcast/hardware-requirements.md rename to pages/lte-based-5g-broadcast/additional/hardware-requirements.md index aba88f8c..99fe9730 100644 --- a/pages/lte-based-5g-broadcast/hardware-requirements.md +++ b/pages/lte-based-5g-broadcast/additional/hardware-requirements.md @@ -1,7 +1,7 @@ --- layout: default title: Hardware requirements -parent: Tutorials +parent: Additional Resources grand_parent: MBMS and LTE-based 5G Broadcast has_children: false nav_order: 1 diff --git a/pages/lte-based-5g-broadcast/rt-common-shared/MBMS-service-announcement-files.md b/pages/lte-based-5g-broadcast/additional/rt-common-shared/MBMS-service-announcement-files.md similarity index 99% rename from pages/lte-based-5g-broadcast/rt-common-shared/MBMS-service-announcement-files.md rename to pages/lte-based-5g-broadcast/additional/rt-common-shared/MBMS-service-announcement-files.md index c9f6adab..f868aa23 100644 --- a/pages/lte-based-5g-broadcast/rt-common-shared/MBMS-service-announcement-files.md +++ b/pages/lte-based-5g-broadcast/additional/rt-common-shared/MBMS-service-announcement-files.md @@ -1,7 +1,7 @@ --- layout: default title: MBMS Service Announcement Files -parent: Tutorials +parent: Additional Resources grand_parent: MBMS and LTE-based 5G Broadcast has_children: false nav_order: 0 diff --git a/pages/lte-based-5g-broadcast/rt-mbms-modem/GPS-time-synchronization.md b/pages/lte-based-5g-broadcast/additional/rt-mbms-modem/GPS-time-synchronization.md similarity index 98% rename from pages/lte-based-5g-broadcast/rt-mbms-modem/GPS-time-synchronization.md rename to pages/lte-based-5g-broadcast/additional/rt-mbms-modem/GPS-time-synchronization.md index e6c34243..17d1546f 100644 --- a/pages/lte-based-5g-broadcast/rt-mbms-modem/GPS-time-synchronization.md +++ b/pages/lte-based-5g-broadcast/additional/rt-mbms-modem/GPS-time-synchronization.md @@ -1,7 +1,7 @@ --- layout: default title: GPS Time Synchonization for rt-mbms-modem -parent: Tutorials +parent: Additional Resources grand_parent: MBMS and LTE-based 5G Broadcast has_children: false nav_order: 0 diff --git a/pages/lte-based-5g-broadcast/sample-files.md b/pages/lte-based-5g-broadcast/additional/sample-files.md similarity index 99% rename from pages/lte-based-5g-broadcast/sample-files.md rename to pages/lte-based-5g-broadcast/additional/sample-files.md index b147bc71..00209caa 100644 --- a/pages/lte-based-5g-broadcast/sample-files.md +++ b/pages/lte-based-5g-broadcast/additional/sample-files.md @@ -1,7 +1,7 @@ --- layout: default title: Sample files -parent: Tutorials +parent: Additional Resources grand_parent: MBMS and LTE-based 5G Broadcast has_children: false nav_order: 2 diff --git a/pages/lte-based-5g-broadcast/tutorials/android-mw-seamless-switching.md b/pages/lte-based-5g-broadcast/tutorials/android-mw-seamless-switching.md new file mode 100644 index 00000000..175dbf57 --- /dev/null +++ b/pages/lte-based-5g-broadcast/tutorials/android-mw-seamless-switching.md @@ -0,0 +1,238 @@ +--- +layout: default +title: Android Middleware - Seamless Switching +parent: Tutorials +grand_parent: MBMS and LTE-based 5G Broadcast +has_children: false +--- + +# Tutorial - Android Middleware - Seamless Switching + +## Introduction + +This tutorial describes the end-to-end setup for seamless switching between 5G Broadcast and unicast delivery on an +Android device. The basic architecture of the setup is depicted in the Figure below: + +![Android Seamless Switching](../../../assets/images/5gbc/android-seamless-switching-architecture.png) + +We use `ffmpeg` to create an HLS livestream from a plain .mp4 file. The resulting manifest files and media segments are +stored on a `watchfolder` located on a simple `express.js webserver`. From this webserver the files are accessible to +media +players located in the same network. This setup corresponds to a classic OTT and CDN based workflow. As an example, the +HLS +stream can be played natively in a Safari Web-browser by simply pasting the URL to the primary or the media playlist +into the URL address bar: + +![Safari playback](../../../assets/images/5gbc/safari-playback-ott.png) + +Whenever a new file is added to the `watchfolder` located on the webserver, a background process called `flute-ffmpeg` +is notified. `flute-ffmpeg` uses the `rt-libflute` library to FLUTE encode the files and sends them via a dedicated +network tunnel as a multicast to the `srsmbms` process. For that reason the `srsmbms` process acts as an MBMS gateway +and +exposes the `sgi_mb` interface. +The `rt-mbms-tx-for-qrd-and-crd` repository acts as a 5G Broadcast transmitter hosting the `srsmbms`, `srsepc` +and `srsenb` processes. It is based on srsRAN with additional changes from 5G-MAG to support LTE-based 5G Broadcast +transmission. + +Finally on the receiver side the `rt-mbms-mw-android` is running on a QRD or CRD device. It is responsible for receiving +the media files delivered via 5G Broadcast. The files are exposed to a media player such as the Exoplayer via a local +webserver. In cases in which no 5G Broadcast is available the Android Middleware fetches the required manifest and media +files directly from the CDN via unicast and exposes them again via the local webserver. From a media player's +perspective it does not matter if the files hosted on the local webserver have been received via unicast or via 5G +broadcast. It is simply consuming the files via standard HTTP GET requests to `localhost`. That way the Android MW can +dynamically switch between broadcast and unicast delivery based on the availability of the respective delivery +mechanism. + +## Requirements + +To replicate the setup described in this tutorial the following components are required: + +* An Ubuntu 22 system to install and host ffmpeg, an express.js webserver, the flute-ffmpeg repository as well as our + 5G-MAG QRD and CRD transmitter. +* A Software Defined Radio (SDR) such as the BladeRF with an antenna for transmission of the 5G Broadcast signal +* A QRD or CRD device operating in Receive-only mode (ROM) to receive the 5G Broadcast transmission and run the 5G-MAG + MBMS Android Middleware. + +A photo of the basic setup is depicted below: + +![Basic Setup](../../../assets/images/5gbc/5gbc-basic-setup.png) + +## Installation + +First, we need to install and configure a few components: + +### 1. Install the express.js webserver + +The `express.js` webserver acts as our CDN for unicast delivery. To install the webserver follow the +instructions [here](https://github.com/5G-MAG/rt-mbms-examples/tree/development/simple-express-server). + +## 2. Install flute-ffmpeg + +We use `flute-ffmpeg` to create an HLS livestream and monitor changes to our watchfolder. Once new files have been added +to the watchfolder `flute-ffmpeg` will FLUTE encode them and multicast them to the MBMS Gateway. + +To install `flute-ffmpeg` follow the installation and build +instructions [here](https://github.com/5G-MAG/rt-mbms-examples/tree/development/flute-ffmpeg). Do not apply the +configuration and running steps yet. We will do this later as part of this tutorial. + +### 3. Install rt-mbms-tx-for-qrd-and-crd + +Next we install our 5G Broadcast transmitter. For that reason follow the steps +described [here](https://github.com/5G-MAG/rt-mbms-tx-for-qrd-and-crd). Do not run the transmitter yet. + +### 4. Clone the Android MW + +The Android MW is responsible for receiving the media files delivered via 5G Broadcast. In addition, it fetches files +from the webserver if they are not available via 5G Broadcast. + +## Configuration + +Before putting the pieces together and running all components we to run some configuration steps: + +### 1. Configure ffmpeg + +First we configure the `ffmpeg` output. Navigate to `flute-ffmpeg/files` and open `ffmpeg-hls.sh`. Change the following +two lines and point them to the path of the local webserver installed previously. If there is no `watchfolder/hls` +folder on your webserver yet create that as well. + +```` +-hls_segment_filename /home/dsi/5gmag/simple-express-server/public/watchfolder/hls/stream_%v_data%02d.ts \ +-var_stream_map "v:0,a:0" /home/dsi/5gmag/simple-express-server/public/watchfolder/hls/stream_%v.m3u8 +```` + +### 2. Configure flute-ffmpeg + +Next we configure `flute-ffmpeg` to monitor the watchfolder on our webserver and also to multicast the resulting packets +to the right address. Open `flute-ffmpeg/config/default.cfg` and edit the following lines: + +```` +general : { + multicast_ip = "239.11.4.50"; + multicast_port = 9988; + watchfolder_path = "/home/dsi/5gmag/simple-express-server/public/watchfolder/hls"; + path_to_transmit = "watchfolder/hls/" +} +```` + +Set the `multicast_ip` and the `multicast_port` to the multicast IP that you will be using for the `sgi_mb` interface of +the MBMS Gateway later. The configuration above matches the default configuration of the 5G Broadcast Transmitter. If +you are unsure what to do use the default `multicast_ip` and `multicast_port` as defined in the example above. + +Set the `watchfolder_path` to the path of your watchdfolder located on the local webserver. `path_to_transmit` should be +set to `"watchfolder/hls/"`. + +### Configure rt-mbms-tx-for-qrd-and-crd + +Now we need to configure our 5G Broadcast transmitter. For that reason follow the +instructions [here](https://github.com/5G-MAG/rt-mbms-tx-for-qrd-and-crd?tab=readme-ov-file#configuration-after-installation). +Make sure to set the right downlink frequency based on the frequency that your CRD/QRD device are operating on. For +instance, for a frequency of 626MHz using a BladeRF SDR these are the required settings +in `/root/.config/srsran/enb.conf`: + +```` +[rf] +dl_freq = 626000000 +ul_freq = 688000000 +dl_earfcn = 68676 +tx_gain = 130 +rx_gain = 0 + +device_name = soapy +device_args = id=2 +```` + +`device_name` and `device_args`might be different in your setup. Make sure that the `enb` process later uses the right +SDR. + +### Configure rt-mbms-mw-android + +In the current implementation the Android Middleware uses a static MBMS Service Announcement file. We need to add the +right unicast endpoint to this static service announcement. For that reason open the `bootstrap.multipart.hls` file +located in the `assets` folder. Search for all occurrences of `watchfolder/hls` that contain an IP. For +instance: `http://192.168.2.2:3333/watchfolder/hls/manifest.m3u8`. Now replace the IP with the IP of your machine that +is running the local webserver. The MW will use this address later to fetch manifest and media files via unicast from +our webserver. + +## Running + +After the configuration we are now ready to run all components and put all the pieces together: + +### Start ffmpeg + +Navigate to `flute-ffmpeg/files` and run `sh ffmpeg-hls.sh`. You should now see files being added to your watchfolder, +e.g.: + +```` +~/5gmag/simple-express-server/public/watchfolder/hls$ ls +manifest.m3u8 stream_0_data12773.ts stream_0_data28.ts +stream_0_data12530.ts stream_0_data12774.ts stream_0_data29.ts +stream_0_data12531.ts stream_0_data12775.ts stream_0_data7389.ts +stream_0_data12532.ts stream_0_data12776.ts stream_0_data7390.ts +stream_0_data12533.ts stream_0_data12777.ts stream_0_data7391.ts +stream_0_data12534.ts stream_0_data12778.ts stream_0_data7392.ts +stream_0_data12535.ts stream_0_data12779.ts stream_0_data7393.ts +stream_0_data12536.ts stream_0_data19.ts stream_0_data7394.ts +stream_0_data12537.ts stream_0_data20.ts stream_0_data7395.ts +stream_0_data12538.ts stream_0_data21.ts stream_0_data7396.ts +stream_0_data12539.ts stream_0_data22.ts stream_0_data7397.ts +stream_0_data12540.ts stream_0_data23.ts stream_0_data7398.ts +stream_0_data12769.ts stream_0_data24.ts stream_0_data7399.ts +stream_0_data12770.ts stream_0_data25.ts stream_0.m3u8 +stream_0_data12771.ts stream_0_data26.ts +stream_0_data12772.ts stream_0_data27.ts +```` + +### Start the express.js webserver + +Run `npm start` in `simple-express-server`. Our files created by `ffmpeg` are now hosted and available via unicast. Try +to query the master manifest to check for the availability of the files: + +```` +curl http://192.168.178.33:3333/watchfolder/hls/manifest.m3u8 +#EXTM3U +#EXT-X-VERSION:6 +#EXT-X-STREAM-INF:BANDWIDTH=2305600,RESOLUTION=1280x720,CODECS="avc1.64001f,mp4a.40.2" +stream_0.m3u8 +```` + +### Start the rt-mbms-tx-for-qrd-and-crd + +Next we start our 5G Broadcast transmitter. For that reason, we need to start three different processes. In addition, we +need to create the `sgi_mb` interface. Follow the steps +described [here](https://github.com/5G-MAG/rt-mbms-tx-for-qrd-and-crd?tab=readme-ov-file#running) to start everything. + +### Start flute-ffmpeg + +Now that we are ready to transmit files via 5G Broadcast we can start our `flute-ffmpeg` process to multicast all data +that is written to the `watchfolder` to `srsmbms`(MBMS Gateway). + +Navigate to `flute-ffmpeg/build` and run `./flute-ffmpeg`. The logs should show messages similar to this indicating that +files written to the watchfolder are processed: + +```` +[2024-07-03 13:52:08.343] [info] Queued /home/dsi/5gmag/simple-express-server/public/watchfolder/hls/stream_0_data159.ts for transmission, TOI is 38 +[2024-07-03 13:52:08.347] [info] Queued /home/dsi/5gmag/simple-express-server/public/watchfolder/hls/stream_0.m3u8 for transmission, TOI is 39 +[2024-07-03 13:52:10.811] [info] Queued /home/dsi/5gmag/simple-express-server/public/watchfolder/hls/stream_0_data160.ts for transmission, TOI is 40 +[2024-07-03 13:52:10.812] [info] Queued /home/dsi/5gmag/simple-express-server/public/watchfolder/hls/stream_0.m3u8 for transmission, TOI is 41 +```` + +### Start the rt-mbms-mw-android + +The final step is to start our Android Middleware to receive the files we are broadcasting now with our transmitter. +Follow the instructions [here](https://github.com/5G-MAG/rt-mbms-mw-android) to deploy the Android Middleware to your +QRC/CRD device. As an alternative, the Android +Middleware can also be deployed to the device using Android Studio. + +After the Android Middleware has started click on "Start Middleware". Then click on the play icon in the middle of the +screen. Since the 5G broadcast is active the HLS media playlist and the HLS media segments are now received via 5G +broadcast and placed on the local webserver of the Android Middleware. From there they are consumed by the underlying +media player: + +![5GBC Playback](../../../assets/images/5gbc/5gbc-playback.png) + +When terminating the `enb` process the media files are no longer transmitted via 5G Broadcast. Now the Android +Middleware falls back to fetching the media files via unicast: + + +![5GUC Playback](../../../assets/images/5gbc/5guc-playback.png) + diff --git a/pages/lte-based-5g-broadcast/docker-implementation.md b/pages/lte-based-5g-broadcast/tutorials/docker-implementation.md similarity index 99% rename from pages/lte-based-5g-broadcast/docker-implementation.md rename to pages/lte-based-5g-broadcast/tutorials/docker-implementation.md index 6a5a2da9..95fd4a9d 100644 --- a/pages/lte-based-5g-broadcast/docker-implementation.md +++ b/pages/lte-based-5g-broadcast/tutorials/docker-implementation.md @@ -4,7 +4,6 @@ title: Docker implementation parent: Tutorials grand_parent: MBMS and LTE-based 5G Broadcast has_children: false -nav_order: 3 --- # Docker Implementation for rt-mbms client side diff --git a/pages/lte-based-5g-broadcast/Tutorial_1.md b/pages/lte-based-5g-broadcast/tutorials/hls-playback-5gbc.md similarity index 97% rename from pages/lte-based-5g-broadcast/Tutorial_1.md rename to pages/lte-based-5g-broadcast/tutorials/hls-playback-5gbc.md index 2405e428..60b5e00c 100644 --- a/pages/lte-based-5g-broadcast/Tutorial_1.md +++ b/pages/lte-based-5g-broadcast/tutorials/hls-playback-5gbc.md @@ -4,7 +4,6 @@ title: HLS playback over 5G Broadcast parent: Tutorials grand_parent: MBMS and LTE-based 5G Broadcast has_children: false -nav_order: 4 --- # Tutorial - HLS playback over 5G Broadcast @@ -70,7 +69,7 @@ As described in [Requirements](#Requirements) we need the MBMS Modem, the MBMS M enable playback of HLS content in broadcast mode using the 5G-MAG Reference Tools. The basic interaction and output of these components is illustrated in the Figure below: -![Architecture](https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/architecture/5G-MAG%20RT%20Architecture%20simplified.drawio.png) +![Architecture](https://github.com/5G-MAG/Getting-Started/blob/main/media/architecture/5G-MAG%20RT%20Architecture%20simplified.drawio.png?raw=true)) The output of the SDR or the sample file serves as the input for the MBMS Modem. The MBMS Modem converts the input data to a UDP multicast. The UDP multicast serves as the input for the MBMS Middleware. The FLUTE encoded content is decoded @@ -174,9 +173,9 @@ In order to use the webinterface for playback perform the following steps: The output for step 3 and step 4 should look similar to this: - + - + ### VLC It is also possible to use other players like VLC. Simply paste the url to the `index.m3u8` into the VLC player. As an example the URL can look the following: `http://localhost/f/00001009f165/index.m3u8`. Replace the `localhost` part with the IP of the machine that is running the MBMS Middleware in order to access the stream from other machines in the same network. diff --git a/pages/lte-based-5g-broadcast/Tutorial_2.md b/pages/lte-based-5g-broadcast/tutorials/rtp-playback-5gbc.md similarity index 96% rename from pages/lte-based-5g-broadcast/Tutorial_2.md rename to pages/lte-based-5g-broadcast/tutorials/rtp-playback-5gbc.md index 56d23c50..7ace127a 100644 --- a/pages/lte-based-5g-broadcast/Tutorial_2.md +++ b/pages/lte-based-5g-broadcast/tutorials/rtp-playback-5gbc.md @@ -4,7 +4,6 @@ title: RTP Playback over 5G Broadcast parent: Tutorials grand_parent: MBMS and LTE-based 5G Broadcast has_children: false -nav_order: 5 --- # Tutorial - RTP Playback over 5G Broadcast @@ -63,7 +62,7 @@ As described in [Requirements](#Requirements) we need the MBMS Modem, the MBMS M enable playback of HLS content in broadcast mode using the 5G-MAG Reference Tools. The basic interaction and output of these components are illustrated in the Figure below: -![Architecture](https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/architecture/5G-MAG%20RT%20Architecture%20RTP%20example.drawio.png) +![Architecture](https://github.com/5G-MAG/Getting-Started/blob/main/media/architecture/5G-MAG%20RT%20Architecture%20RTP%20example.drawio.png?raw=true) The output of the SDR or the sample file serves as the input for the MBMS Modem. The MBMS Modem converts the input data to a UDP multicast. The UDP multicast can be played directly in ffplay or VLC. @@ -145,7 +144,7 @@ To play the stream in ffplay run the following steps The output should look like this: - + ### VLC It is also possible to use VLC for playback: @@ -157,7 +156,7 @@ It is also possible to use VLC for playback: The output should look like this: - + ## Troubleshooting diff --git a/pages/lte-based-5g-broadcast/Tutorial_3.md b/pages/lte-based-5g-broadcast/tutorials/seamless-switching.md similarity index 96% rename from pages/lte-based-5g-broadcast/Tutorial_3.md rename to pages/lte-based-5g-broadcast/tutorials/seamless-switching.md index a07ec2ab..a967e143 100644 --- a/pages/lte-based-5g-broadcast/Tutorial_3.md +++ b/pages/lte-based-5g-broadcast/tutorials/seamless-switching.md @@ -4,7 +4,6 @@ title: Seamless switching parent: Tutorials grand_parent: MBMS and LTE-based 5G Broadcast has_children: false -nav_order: 6 --- # Tutorial - Seamless switching @@ -84,7 +83,7 @@ As described in [Requirements](#Requirements) we need the MBMS Modem, the MBMS M enable playback of HLS content in unicast and broadcast mode using the 5G-MAG Reference Tools. The basic interaction and output of these components is illustrated in the Figure below: -![Architecture](https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/architecture/5G-MAG%20RT%20Architecture%20Seamless%20Switching%20v8.drawio.png) +![Architecture](https://github.com/5G-MAG/Getting-Started/blob/main/media/architecture/5G-MAG%20RT%20Architecture%20Seamless%20Switching%20v8.drawio.png?raw=true) The output of the SDR or the sample file serves as the input for the MBMS Modem. The MBMS Modem converts the input data to a UDP multicast. The UDP multicast serves as the input for the MBMS Middleware. The FLUTE encoded content is decoded @@ -189,9 +188,9 @@ In order to use the webinterface for playback perform the following steps: The output for step 3 and step 4 should look similar to this: - + - + ### VLC It is also possible to use other players like VLC. Simply paste the url to the `index.m3u8` into the VLC player. As an example the URL can look the following: `http://localhost/f/00001009f165/index.m3u8`. Replace the `localhost` part with the IP of the machine that is running the MBMS Middleware in order to access the stream from other machines in the same network.