Feature/5gbc (#79)

* WiP: 5G broadcast seamless switching tutorial * Add documentation for 5GBC-UC seamless switching
5G-MAG · Jul 3, 2024 · b8e1c05 · b8e1c05
1 parent 8189a08
commit b8e1c05
Show file tree

Hide file tree

Showing 15 changed files with 260 additions and 17 deletions.
diff --git a/assets/images/5gbc/5gbc-basic-setup.png b/assets/images/5gbc/5gbc-basic-setup.png
diff --git a/assets/images/5gbc/5gbc-playback.png b/assets/images/5gbc/5gbc-playback.png
diff --git a/assets/images/5gbc/5guc-playback.png b/assets/images/5gbc/5guc-playback.png
diff --git a/assets/images/5gbc/android-seamless-switching-architecture.png b/assets/images/5gbc/android-seamless-switching-architecture.png
diff --git a/assets/images/5gbc/safari-playback-ott.png b/assets/images/5gbc/safari-playback-ott.png
diff --git a/pages/lte-based-5g-broadcast/additional/additional.md 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/...sed-5g-broadcast/hardware-requirements.md → ...dcast/additional/hardware-requirements.md b/...sed-5g-broadcast/hardware-requirements.md → ...dcast/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/...shared/MBMS-service-announcement-files.md → ...shared/MBMS-service-announcement-files.md b/...shared/MBMS-service-announcement-files.md → ...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/...rt-mbms-modem/GPS-time-synchronization.md → ...rt-mbms-modem/GPS-time-synchronization.md b/...rt-mbms-modem/GPS-time-synchronization.md → ...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 → ...d-5g-broadcast/additional/sample-files.md b/pages/lte-based-5g-broadcast/sample-files.md → ...d-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
@@ -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/...sed-5g-broadcast/docker-implementation.md → ...adcast/tutorials/docker-implementation.md b/...sed-5g-broadcast/docker-implementation.md → ...adcast/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 → ...-broadcast/tutorials/hls-playback-5gbc.md b/pages/lte-based-5g-broadcast/Tutorial_1.md → ...-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:
 
-<img src="https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/wiki/rt-wui-mw-tab.jpg" width="800">
+<img src="https://github.com/5G-MAG/Getting-Started/blob/main/media/wiki/rt-wui-mw-tab.jpg?raw=true" width="800">
 
-<img src="https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/wiki/rt-wui-playback.jpg" width="800">
+<img src="https://github.com/5G-MAG/Getting-Started/blob/main/media/wiki/rt-wui-playback.jpg?raw=true" width="800">
 
 ### 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 → ...-broadcast/tutorials/rtp-playback-5gbc.md b/pages/lte-based-5g-broadcast/Tutorial_2.md → ...-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:
 
-<img src="https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/wiki/ffplay-rtp.png" width="800">
+<img src="https://github.com/5G-MAG/Getting-Started/blob/main/media/wiki/ffplay-rtp.png?raw=true" width="800">
 
 ### 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:
 
-<img src="https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/wiki/rtp-vlc.png" width="800">
+<img src="https://github.com/5G-MAG/Getting-Started/blob/main/media/wiki/rtp-vlc.png?raw=true" width="800">
 
 ## Troubleshooting
 

diff --git a/pages/lte-based-5g-broadcast/Tutorial_3.md → ...broadcast/tutorials/seamless-switching.md b/pages/lte-based-5g-broadcast/Tutorial_3.md → ...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:
 
-<img src="https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/wiki/rt-wui-mw-tab.jpg" width="800">
+<img src="https://github.com/5G-MAG/Getting-Started/blob/main/media/wiki/rt-wui-mw-tab.jpg?raw=true" width="800">
 
-<img src="https://github.com/5G-MAG/Documentation-and-Architecture/blob/main/media/wiki/rt-wui-playback.jpg" width="800">
+<img src="https://github.com/5G-MAG/Getting-Started/blob/main/media/wiki/rt-wui-playback.jpg?raw=true" width="800">
 
 ### 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.