Initial MBS Transport Function API examples

This tutorial describes the initial reference implementation of the MBS Transport Function (MBSTF) as specified in 3GPP TS 26.517 and 3GPP TS 29.581. You can check out the videos to see more details or follow the write-up tutorial.

Tutorial videos

Architecture 

---
title: "MBSTF and associated 5G NFs"
config:
  block:
    padding: 12
    useMaxWidth: true
---
block-beta
    columns 9
    block: g1:7
        columns 7
        space:3 text1["5MBS reference points"] space:3
        space:4 NEF["NEF"]:3
        space:7
        AMF["AMF"] space SMF["SMF"] space MBSMF["MB-SMF"] space MBSF["MBSF"]
        space:7
        RAN["NG-RAN"] space UPF["UPF"] space MBUPF["MB-UPF"] space MBSTF["MBSTF"]
        invis1((" ")) space:3 invis2((" ")) space:2
    end
    space AP["MBS Application Provider\n(AF/AS)"]
    NEF-- "N29mb" ---MBSMF
    NEF-- "Nmb5" ---MBSF
    MBSF-- "Nmb1" ---MBSMF
    MBSMF-- "N16mb" ---SMF
    MBSF-- "Nmb2" ---MBSTF
    MBSMF-- "N4mb" ---MBUPF
    MBSTF-- "Nmb9" ---MBUPF
    MBUPF-- "N19mb" ---UPF
    SMF-- "N4" ---UPF
    SMF-- "N11" ---AMF
    UPF-- "N3" ---RAN
    AMF-- "N2" ---RAN
    MBUPF---invis2
    invis2-- "N3mb" ---invis1
    invis1---RAN
    AP-- "N33" ---NEF
    AP-- "Nmb10" ---MBSF
    AP-- "Nmb8" ---MBSTF
    style invis1 fill: #0000, stroke: #0000, color: #0000
    style invis2 fill: #0000, stroke: #0000, color: #0000
    style text1 fill: #0000, stroke: #0000

Prerequisites

This tutorial assumes that you have cloned and built the rt-mbs-transport-function repository.

Description

In this tutorial we will configure the MBSTF with a variety of MBS Distribution Session types. This tutorial will also cover optional integration with the MB-SMF and MB-UPF.

You should follow the build instructions for the rt-mbs-transport-function repository found in the README.md on the repository main page.

For these examples you will also need Wireshark, to view the results, and either build the 5G-MAG version of Open5GS with UDP tunnelling or the install the netcat package to fake an MB-UPF UDP tunnel.

Step 1a: (Optional) Create an MBS Session on the MB-UPF with UDP tunnel

This is the first option for creating a UDP tunnel for multicast distribution. This implements the following highlighted steps from creating an MBS User Service.

---
title: "MBS User Service Creation: MBS Session creation on the MB-SMF"
config:
  sequence:
    showSequenceNumbers: true
---
sequenceDiagram
    participant MBUPF as MB-UPF
    participant MBSMF as MB-SMF
    participant MBSF
    participant AP as AF/AS
    activate MBSMF
    activate MBUPF
    activate MBSF
    AP ->> MBSF: Create MBS User Service
    MBSF -->> AP: MBS User Service created
    AP ->> MBSF: Add MBS User Data Ingest<br/>Session to MBS User Service
    rect rgb(160, 255, 160)
        MBSF ->> MBSMF: Add MBS Session,<br/>and request an Nmb9 ingress tunnel
        MBSMF ->> MBUPF: Set up Multicast/Broadcast service<br/>and create an Nmb9 ingress tunnel
        MBUPF -->> MBSMF: Success<br/>and Nmb9 ingress tunnel details
        MBSMF -->> MBSF: MBS Session created and Nmb9 tunnel details
    end

    deactivate MBSF
    deactivate MBSMF
    deactivate MBUPF

To use this you will need a 5G Core with an MB-UPF and an MB-SMF that are both capable of allocating an ingress tunnel at reference point Nmb9. An example of such a 5G Core can be found in the 5G-MAG/open5gs repository in the 5mbs branch.

Start the NRF, SCP, AMF, MB-SMF and MB-UPF.

git clone --depth 1 --recurse-submodules -b 5mbs https://github.com/5G-MAG/open5gs.git ~/open5gs
cd ~/open5gs
meson setup --prefix=$PWD/install build
ninja -C build install
LD_LIBRARY_PATH="$PWD/install/lib64:$PWD/install/lib" export LD_LIBRARY_PATH
install/bin/open5gs-nrfd > nrf.log 2>&1 &
install/bin/open5gs-scpd > scp.log 2>&1 &
install/bin/open5gs-amfd > amf.log 2>&1 &
install/bin/open5gs-smfd > smf.log 2>&1 &
sudo -E install/bin/open5gs-upfd > upf.log 2>&1 &

Copy this Nmbsmf_MBSSession CreateReqData JSON object into a file called create-mbs-session.json:

{
  "mbsSession": {
    "mbsSessionId": {
      "ssm": {
        "sourceIpAddr": {
          "ipv4Addr": "127.0.0.1"
        },
        "destIpAddr": {
          "ipv4Addr": "232.0.0.1"
        }
      }
    },
    "tmgiAllocReq": true,
    "serviceType": "MULTICAST",
    "ingressTunAddrReq": true,
    "activityStatus": "ACTIVE",
    "anyUeInd": true
  }
}

Then we send this file to the MB-SMF to request that it creates a new multicast MBS Session (sequence steps 4 to 7):

curl --http2-prior-knowledge -H 'Content-Type: application/json' --data @create-mbs-session.json http://127.0.0.4:7777/nmbsmf-mbssession/v1/mbs-sessions

The response will look similar to this:

{
  "mbsSession": {
    "mbsSessionId": {
      "ssm": {
        "sourceIpAddr": {
          "ipv4Addr": "127.0.0.1"
        },
        "destIpAddr": {
          "ipv4Addr": "232.0.0.1"
        }
      }
    },
    "tmgi": {
      "mbsServiceId": "D8AA35",
      "plmnId": {
        "mcc": "000",
        "mnc": "000"
      }
    },
    "serviceType": "MULTICAST",
    "ingressTunAddr": [
      {
        "ipv4Addr": "127.0.0.7",
        "portNumber": 42497
      }
    ],
    "ssm": {
      "sourceIpAddr": {
        "ipv4Addr": "127.0.0.1"
      },
      "destIpAddr": {
        "ipv4Addr": "232.0.0.1"
      }
    }
  }
}

It contains the UDP tunnel details at JSON path .mbsSession.ingressTunAddr. These will need to be substituted in the .distSession.mbUpfTunAddr object in the Distribution Session JSON objects in the following steps in order to direct the output to the MB-UPF.

Step 1b: (Optional) Fake a UDP tunnel

This can be useful if you just want to inspect the output of the MBSTF in isolation. Instead of running an MBS-enabled 5G Core, you can simulate the receiving end of the UDP tunnel that would normally be provided by the MB-UPF.

For this we will need the netcat or nc command from the netcat package (nmap-ncat on RHEL based systems).

The command to create a tunnel at 127.0.0.7:5678 is:

nc -u -l 127.0.0.7 5678 > /dev/null &

Step 2: Start the mock media express server

When configured to operate in one of the pull-based object acquisition methods, the MBSTF requires an HTTP server from which to request the objects. For the purposes of these tutorials we will use a simple HTTP server based on the NodeJS Express module which has been configured to serve some simple media objects. This simulates a media server or CDN that would be provided by the MBS Application Provider (AF/AS).

To start the Express mock media server you will need to do the following things.

  1. Clone the rt-mbs-examples repository: 
    cd ~
git clone -b development https://github.com/5G-MAG/rt-mbs-examples.git
  2. Prepare the Express server for running: 
    cd ~/rt-mbs-examples/express-mock-media-server
npm install
  3. Run the Express server: 
    cd ~/rt-mbs-examples/express-mock-media-server
npm start

The mock media server is now running on TCP port 3004 and ready to serve objects for the following tutorial examples.

Step 3: Run the MBSTF

If the build and install instructions from rt-mbs-transport-function have been followed, then the MBSTF can be run using:

sudo /usr/local/bin/open5gs-mbstfd &

Step 4: Start and configure Wireshark to capture the encapsulated FLUTE

  1. Set up packet decoding:
    • In the Analyze menu, select Decode As… to open the “Decode As…” dialog.
    • Dissect the reference point Nmb9 unicast tunnel. If a rule does not exist for UDP with a port number matching the UDP tunnel (the portNumber given for the first tunnel (ingressTunAddr) in the response in Step 1a or 5678 for Step 1b), then create a new rule, set the field to UDP port, set the port number to the tunnel port and set the Current decoding as IPv4.
    • Dissect the multicast packets carried inside the reference point Nmb9 unicast tunnel. If a rule does not exist for the UDP port 5000 (the port we will use for the multicast) then create a new rule for a “UDP port”, set the port number to 5000 and the Current decoding to ALC.
    • Select the Save or OK button to close the dialog. Saving will store the rules for next time Wireshark is started. wireshark Decode As dialog example

  2. Select (but don’t start) the correct interface for capture. This will usually be the Ethernet interface if you used Step 1a or the local loopback (lo) interface if you are using Step 1b.

    Note: If Wireshark is not showing your Ethernet interface try starting it with sudo rights: sudo wireshark

  3. Enter the filter expression if…:
    • You followed Step 1a, enter a filter of ip.src == <tunnel-ip-address>, where <tunnel-ip-address> is the IP address of the tunnel given in the response for 1a (ingressTunAddr).
    • You followed Step 1b, enter a filter of ip.src == 127.0.0.7.
  4. Then start the capture.

Step 5: Create a single shot MBS Distribution Session for pull operation

This tests the single-shot object operating mode (SINGLE) for the pull-based object acquisition method. This executes the following highlighted steps from MBS User Service provisioning using the command line to perform the actions that the MBSF would otherwise perform.

---
title: "MBS User Service Creation: PULL Single Shot Distribution Session creation on the MBSTF"
config:
  themeCSS: |
    .loopLine { stroke-width: 4px; stroke-dasharray: 5,5; }
  sequence:
    showSequenceNumbers: true
---
sequenceDiagram
    participant RAN as NG-RAN
    participant MBUPF as MB-UPF
    participant MBSMF as MB-SMF
    participant MBSTF
    participant MBSF
    participant AP as MBS Application Provider (AF/AS)
    activate RAN
    activate MBSMF
    activate MBUPF
    activate MBSF
    activate MBSTF
    AP ->> MBSF: Add MBS User Data Ingest Session<br/>to MBS User Service
    MBSF ->> MBSMF: Create MBS Session<br/>and request an Nmb9 ingress tunnel
    MBSMF ->> MBUPF: Set up Multicast/Broadcast service and<br/>create an Nmb9 ingress tunnel
    MBUPF -->> MBSMF: Success and Nmb9 tunnel details
    MBSMF -->> MBSF: MBS Session created and Nmb9 tunnel details
    rect rgb(160,255,160)
        MBSF ->> MBSTF: Create Distribution Session<br/>using tunnel from MB-SMF
        MBSTF -->> MBSF: Distribution Session created
    end
    MBSF -->> AP: MBS User Data Session created
    rect rgb(160,255,160)
        MBSTF ->> AP: Fetch object(s) described<br/>in Distribution Session
        AP -->> MBSTF: Response with object(s)
        MBSTF ->> MBUPF: Package object(s) into multicast FLUTE session packets<br/>and send to Nmb9 tunnel at configured bit rate
        MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
    end

    deactivate MBSTF
    deactivate MBSF
    deactivate MBSMF
    deactivate MBUPF
    deactivate RAN

With the following processes running:

  • Express server from Step 2
  • the MBSTF from Step 3
  • Wireshark from step 4

…perform the following actions to test a single shot distribution from PULL requested media objects.

Copy the following into a file called DistSession-PULL-request.json:

{
  "distSession": {
    "distSessionId": "cab87e4b-01b1-4138-9018-7d30bcb1606b",
    "distSessionState": "ACTIVE",
    "mbUpfTunAddr": {
      "ipv4Addr": "127.0.0.7",
      "portNumber": 5678
    },
    "upTrafficFlowInfo": {
      "destIpAddr": {
        "ipv4Addr": "232.0.0.1"
      },
      "portNumber": 5000
    },
    "mbr": "10 Mbps",
    "objDistributionData": {
      "objDistributionOperatingMode": "SINGLE",
      "objAcquisitionMethod": "PULL",
      "objAcquisitionIdsPull": [
        "object1",
        "object2",
        "object3",
        "object4"
      ],
      "objIngestBaseUrl": "http://127.0.0.1:3004/",
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

If you are using the option to use a running MB-SMF/MB-UPF (Step 1a) then make the following changes to the JSON above:

  • Change the MB-UPF tunnel IP address distSession.mbUpfTunAddr.ipv4Addr from 127.0.0.7 to the destination IP address of the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).
  • Change the MB-UPF tunnel port number distSession.mbUpfTunAddr.portNumber from 5678 to the destination port number for the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).

Then send the DistSession JSON object in DistSession-PULL-request.json to the MBSTF to configure it (sequence step 6):

curl --http2-prior-knowledge -H 'Content-Type: application/json' --data-binary @DistSession-PULL-request.json http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions

The response from the MBSTF (step 7) should look like:

{
  "distSession": {
    "distSessionId": "cab87e4b-01b1-4138-9018-7d30bcb1606b",
    "distSessionState": "ACTIVE",
    "objDistributionData": {
      "objDistributionOperatingMode": "SINGLE",
      "objAcquisitionMethod": "PULL",
      "objAcquisitionIdsPull": [
        "object1",
        "object2",
        "object3",
        "object4"
      ],
      "objIngestBaseUrl": "http://127.0.0.1:3004/",
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

The Wireshark packet capture (sequence step 11) will look like:

Wireshark capture showing the FDT (TOI 0) packet for the first object from the PULL SINGLE Distribution Session

This shows the FLUTE FDT Instance File entry for the first object pulled from the Express server. Examining the packet it can be noticed that:

  1. There are outer IP and UDP protocol headers showing the packet is sent from 127.0.0.1:58158 to 127.0.0.7:49484 ➀ because an MB-UPF was used for this example which presented its tunnel at 127.0.0.7:49484.
  2. The next (inner) pair of IP and UDP headers show that this encapsulated packet is from 127.0.0.1:5000 to multicast address 232.0.0.1:5000 ➁, as requested in the DistributionSession creation request to the MBSTF.
  3. The packet contents are a FLUTE packet for Transport Session Identifier 0 and Transport Object Identifier0 (“ TSI: 0 TOI: 0”, from the packet summary ➂) which indicates that the transport object is the FDT Instance document. The contents of the FDT Instance document show that the FLUTE Session is currently sending a 39-byte transmission object ➅ referenced as TOI="1" ➃ with a content location of “http://127.0.0.2/object1” ➄. The “http://127.0.0.2” prefix is the one requested by the objDistributionBaseUrl field in the DistributionSession configured in the MBSTF, and has replaced the origin prefix of “http://127.0.0.1:3004” ( objIngestBaseUrl field).
  4. The next packet contains the same multicast packet ➆ sent from the MB-UPF to the gNodeB using GTP-U tunnel encapsulation.

This next screenshot shows the FLUTE packet for TOI 1, the ingested media object object1 itself.

Wireshark capture showing the FDT (TOI 0) packet for the first object from the PULL SINGLE Distribution Session

Step 6: Create a single shot MBS Distribution Session for push operation

This tests the SINGLE distribution mode for PUSHed content. This executes the following highlighted steps from MBS User Service provisioning using the command line to perform the actions that the MBSF and AP would otherwise perform.

---
title: "MBS User Service Creation: PUSH Single Shot Distribution Session creation on the MBSTF"
config:
  themeCSS: |
    .loopLine { stroke-width: 4px; stroke-dasharray: 5,5; }
  sequence:
    showSequenceNumbers: true
---
sequenceDiagram
    participant RAN as NG-RAN
    participant MBUPF as MB-UPF
    participant MBSMF as MB-SMF
    participant MBSTF
    participant MBSF
    participant AP as MBS Application Provider (AF/AS)
    activate RAN
    activate MBSMF
    activate MBUPF
    activate MBSF
    activate MBSTF
    AP ->> MBSF: Add MBS User Data Ingest<br/>Session to MBS User Service
    MBSF ->> MBSMF: Create MBS Session and<br/>request an Nmb9 ingress tunnel
    MBSMF ->> MBUPF: Set up Multicast/Broadcast service and<br/>create an Nmb9 ingress tunnel
    MBUPF -->> MBSMF: Success and tunnel details
    MBSMF -->> MBSF: MBS Session created and tunnel details
    rect rgb(160, 255, 160)
        MBSF ->> MBSTF: Create Distribution Session<br/>using tunnel from MB-SMF
        MBSTF -->> MBSF: Distribution Session created<br/>include push service URL if requested
    end
    MBSF -->> AP: MBS User Data Session created,<br/>including push Service Entry Point URL, if requested
    rect rgb(160, 255, 160)
        AP ->> MBSTF: Push object for Distribution Session
        MBSTF -->> AP: Object received OK
        MBSTF ->> MBUPF: Package object(s) into multicast FLUTE session packets<br/>and send to Nmb9 tunnel at configured bit rate
        MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
    end

    deactivate MBSTF
    deactivate MBSF
    deactivate MBSMF
    deactivate MBUPF
    deactivate RAN

With the following processes running:

  • the MBSTF from Step 3
  • Wireshark from step 4

…perform the following actions to test a single shot distribution for PUSH delivered media objects.

Copy the following into a file called DistSession-PUSH-request.json:

{
  "distSession": {
    "distSessionId": "3e3dc3fb-0677-42a3-86c6-bc44e3544b0f",
    "distSessionState": "ACTIVE",
    "mbUpfTunAddr": {
      "ipv4Addr": "127.0.0.7",
      "portNumber": 5678
    },
    "upTrafficFlowInfo": {
      "destIpAddr": {
        "ipv4Addr": "232.0.0.1"
      },
      "portNumber": 5000
    },
    "mbr": "10 Mbps",
    "objDistributionData": {
      "objDistributionOperatingMode": "SINGLE",
      "objAcquisitionMethod": "PUSH",
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

If you are using the option to use a running MB-SMF/MB-UPF (Step 1a) then make the following changes to the JSON above:

  • Change the MB-UPF tunnel IP address distSession.mbUpfTunAddr.ipv4Addr from 127.0.0.7 to the destination IP address of the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).
  • Change the MB-UPF tunnel port number distSession.mbUpfTunAddr.portNumber from 5678 to the destination port number for the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).

Then send the DistSession object to the MBSTF to configure it (sequence step 6):

curl --http2-prior-knowledge -H 'Content-Type: application/json' --data-binary @DistSession-PUSH-request.json http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions

The result (sequence step 7) should look like:

{
  "distSession": {
    "distSessionId": "3e3dc3fb-0677-42a3-86c6-bc44e3544b0f",
    "distSessionState": "ACTIVE",
    "objDistributionData": {
      "objDistributionOperatingMode": "SINGLE",
      "objAcquisitionMethod": "PUSH",
      "objIngestBaseUrl": "http://127.0.0.1:33945/",
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

Take note of the objIngestBaseUrl prefix URL for pushing the media objects to, e.g.:

push_prefix_url="http://127.0.0.1:33945/"

Then we can send objects to be packaged and sent via the multicast MBS Session (sequence steps 9 and 10). For example to send the meson.build file from the rt-mbs-transport-function repository that was cloned earlier we perform an HTTP PUT of the file to a URL with the prefix we remembered earlier:

curl -H 'Content-Type: text/plain' -X PUT --data-binary @"${HOME}/rt-mbs-transport-function/meson.build" "${push_prefix_url}example/path/to/object.txt"

Once pushed, the object is packaged as FLUTE and sent to the UDP tunnel.

The wireshark capture will look something like (sequence step 11):

Wireshark showing FDT packet for SINGLE PUSH distribution

This shows the FDT for the pushed file. This is encapsulated in the same way as in step 5 of the pull-based object acquisition example. The Content-Location field in the FDT File entry shows it using the objDistributionBaseUrl followed by the path that the object was PUT to following the objIngestBaseUrl.

The FLUTE packet conveying the pushed file in TOI 1 will look something like:

Wireshark showing first file object packet for SINGLE PUSH distribution

This packet (packet number 9 in the above image), containing the first bytes of the meson.build file, is followed by the rest of the file in packet number 11.

Step 7: Create a streaming MBS Distribution Session for pull operation on the DASH manifest

This tests the STREAMING distribution mode for PULLed DASH manifest file (MPD). This executes the following highlighted steps from MBS User Service provisioning using the command line to perform the actions that the MBSF would otherwise perform.

---
title: "MBS User Service Creation: PULL STREAMING Distribution Session creation on the MBSTF"
config:
  themeCSS: |
    .loopLine { stroke-width: 4px; stroke-dasharray: 5,5; }
  sequence:
    showSequenceNumbers: true
---
sequenceDiagram
    participant RAN as NG-RAN
    participant MBUPF as MB-UPF
    participant MBSMF as MB-SMF
    participant MBSTF
    participant MBSF
    participant AP as MBS Application Provider (AF/AS)
    activate RAN
    activate MBSMF
    activate MBUPF
    activate MBSF
    activate MBSTF
    AP ->> MBSF: Add MBS User Data Ingest<br/>Session to MBS User Service
    MBSF ->> MBSMF: Create MBS Session and request Nmb9 ingress tunnel
    MBSMF ->> MBUPF: Set up Multicast/Broadcast service and<br/>create an Nmb9 ingress tunnel
    MBUPF -->> MBSMF: Success and Nmb9 ingress tunnel details
    MBSMF -->> MBSF: MBS Session created<br/>and Nmb9 ingress tunnel details
    rect rgb(160, 255, 160)
        MBSF ->> MBSTF: Create Distribution Session<br/>using Nmb9 tunnel details from MB-SMF
        MBSTF -->> MBSF: Distribution Session created
    end
    MBSF -->> AP: MBS User Data Session created
    rect rgb(160, 255, 160)
        MBSTF ->> AP: Pull DASH manifest
        AP -->> MBSTF: DASH manifest
        MBSTF ->> MBUPF: DASH manifest packaged in multicast FLUTE session packets and send to tunnel at given rate
        MBUPF ->> RAN: Multicast FLUTE packets<br/>forwarded to gNodeB(s) via multicast GTP-U tunnel
        loop For each initialization segment in the DASH manifest
            MBSTF ->> AP: Pull Initialization Segment
            AP -->> MBSTF: Initialization Segment
            MBSTF ->> MBUPF: Initialization Segment packaged in multicast FLUTE session packets and send to tunnel at given rate
            MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
        end
        par If the DASH manifest has a refresh period
            loop If the DASH manifest has a refresh period
                MBSTF ->> MBSTF: Wait for the next MPD refresh time
                MBSTF ->> AP: Pull DASH manifest
                AP -->> MBSTF: DASH manifest
                MBSTF ->> MBUPF: Package DASH manifest into multicast FLUTE session packets<br/>and send to Nmb9 tunnel at configured bit rate
                MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB via multicast GTP-U tunnel
                loop For each initialization segment in the DASH manifest
                    MBSTF ->> AP: Pull Initialization Segment
                    AP -->> MBSTF: Initialization Segment
                    MBSTF ->> MBUPF: Package Initialization Segment into multicast FLUTE session packets<br/>and send to Nmb9 tunnel at configured bit rate
                    MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
                end
            end
        and For each Representation in the current period
            loop For each Media Segment in the Representation
                MBSTF ->> MBSTF: Wait for the Media Segment to become available
                MBSTF ->> AP: Pull Media Segment
                AP -->> MBSTF: Media Segment
                MBSTF ->> MBUPF: Package Media Segment into multicast FLUTE session packets<br/>and send to Nmb9 tunnel at configured bit rate
                MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
            end
        end
    end

    deactivate MBSTF
    deactivate MBSF
    deactivate MBSMF
    deactivate MBUPF
    deactivate RAN

With the following processes running:

  • the MBSTF from Step 3
  • Wireshark from step 4

…perform the following actions to test a streaming distribution from PULL of a DASH MPD.

Copy the following into a file called DistSession-DASH-PULL-request.json:

{
  "distSession": {
    "distSessionId": "541ebbd2-ebf9-496b-a3b8-dcd1c17fbc9d",
    "distSessionState": "ACTIVE",
    "mbUpfTunAddr": {
      "ipv4Addr": "127.0.0.7",
      "portNumber": 5678
    },
    "upTrafficFlowInfo": {
      "destIpAddr": {
        "ipv4Addr": "232.0.0.1"
      },
      "portNumber": 5000
    },
    "mbr": "10 Mbps",
    "objDistributionData": {
      "objDistributionOperatingMode": "STREAMING",
      "objAcquisitionMethod": "PULL",
      "objIngestBaseUrl": "https://livesim2.dashif.org/livesim2/WAVE/vectors/cfhd_sets/12.5_25_50/t1/2022-10-17/",
      "objAcquisitionIdsPull": [
        "stream.mpd"
      ],
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

If you are using the option to use a running MB-SMF/MB-UPF (Step 1a) then make the following changes to the JSON above:

  • Change the MB-UPF tunnel IP address distSession.mbUpfTunAddr.ipv4Addr from 127.0.0.7 to the destination IP address of the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).
  • Change the MB-UPF tunnel port number distSession.mbUpfTunAddr.portNumber from 5678 to the destination port number for the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).

When pushed as a configuration for the MBSTF, this will configure a Distribution Session based on a single Service Entry Point (DASH manifest document).

When an MBSTF Distribution Session is configured for STREAMING operating mode using a DASH MPD, the MBSTF queues for inclusion in the FLUTE stream the MPD, the initialization segments and then, as they become available, each media segment for each Representation declared for the DASH presentation in its MPD.

  • Note that the present implementation of the MBSTF only supports live-profile DASH manifests.

To push the DistSession to the MBSTF to configure it (sequence step 6), use the following command:

curl --http2-prior-knowledge -H 'Content-Type: application/json' --data-binary @DistSession-DASH-PULL-request.json http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions

The MBSTF response (sequence step 7) should look like:

{
  "distSession": {
    "distSessionId": "541ebbd2-ebf9-496b-a3b8-dcd1c17fbc9d",
    "distSessionState": "ACTIVE",
    "objDistributionData": {
      "objDistributionOperatingMode": "STREAMING",
      "objAcquisitionMethod": "PULL",
      "objAcquisitionIdsPull": [
        "stream.mpd"
      ],
      "objIngestBaseUrl": "https://livesim2.dashif.org/livesim2/WAVE/vectors/cfhd_sets/12.5_25_50/t1/2022-10-17/",
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

The MBSTF will now send the MPD in the FLUTE Session, followed by the initialization segments (if present in the MPD). Then it will download each media segment at its availability time and send it in the FLUTE Session. If the MPD indicates a refresh time, then the MBSTF will issue a conditional HTTP GET to reacquire it at that time, and if the MPD has changed, then the new MPD and any initialization segments will be transmitted again in the FLUTE Session.

The wireshark capture will look like (sequence step 11 onwards):

Wireshark screenshot showing the FDT with File entry for the MPD sent as part of a PULL STREAMING Distribution Session

This payload of this packet is a FLUTE transmission object (TOI 0) that conveys the FDT Instance. This document includes a File entry for the MPD transmission object (TOI 1). The objIngestBaseUrl from the Distribution Session configuration has been substituted for the objDistributionBaseUrl in the FDT File entry, resulting in “http://127.0.0.2/stream.mpd” being the advertised path of the MPD file.

The file contents for this example are contained in packets 7 and 9. The screenshot below shows the first packet of the MPD being carried as TOI 1 in the FLUTE stream. Packets 8 and 10 are the MB-UPF forwarding packets 7 and 9 to the gNodeB, encapsulated in a GTP-U tunnel.

Wireshark screenshot showing the MPD file contents sent as part of a PULL STREAMING Distribution Session

This packet shown in the screenshot below is the File entry in the FDT Instance transmission object (TOI 0) for a DASH initialization segment (with TOI 2). Because this is fetched from the same source as the MPD, the objDistributionBaseUrl substitution happens to this URL too, resulting in the avertised path being “http://127.0.0.2/1/init.mp4”.

Wireshark screenshot showing the FDT with File entry for the initialization segment sent as part of a PULL STREAMING Distribution Session

The screenshot below shows the same initialization segment being sent in the FLUTE Session as TOI 2.

Wireshark screenshot showing the initialization segment file contents sent as part of a PULL STREAMING Distribution Session

The FDT File entry for the first media segment (TOI=3 in this example FLUTE Session) describes the media segment to be presented as the next live segment in the DASH presentation according to the MPD. This is advertised in the FDT File entry as having a Content-Location value of “http://127.0.0.2/1/876641739.m4s”, as shown in the screenshot below.

Wireshark screenshot showing the FDT with File entry for the first live media segment sent as part of a PULL STREAMING Distribution Session

The FDT File entry for the second media segment (TOI=4 in this example FLUTE Session) describes the media segment to be presented as the next live segment one segment duration after the first (just after it became available). This is advertised in the FDT File entry as having a Content-Location value of “http://127.0.0.2/1/876641740.m4s” location, as shown in the screenshot below.

Wireshark screenshot showing the FDT with File entry for the second live media segment sent as part of a PULL STREAMING Distribution Session

Step 7a: (Optional) Destroying the MBS Distribution Session

As the MPD is constantly updated the MBSTF will keep sending MPD, initialization segments and media segments until the process is killed or the MBS distribution session is destroyed.

To destroy the MBS distribution session run the following command replacing distSessionId in the URL below with the distSessionId you used when pushing the DistSession to the MBSTF.

curl --http2-prior-knowledge -X DELETE http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions/{distSessionId}

Based on our example above the REST call looks like this:

curl --http2-prior-knowledge -X DELETE http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions/541ebbd2-ebf9-496b-a3b8-dcd1c17fbc9d

Step 8: Create a streaming MBS Distribution Session for push operation on the DASH manifest

This tests the STREAMING distribution mode for PUSHed DASH manifest file (MPD). This executes the following highlighted steps from MBS User Service provisioning using the command line to perform the actions that the MBSF would otherwise perform.

---
title: "MBS User Service Creation: PUSH STREAMING Distribution Session creation on the MBSTF"
config:
  themeCSS: |
    .loopLine { stroke-width: 4px; stroke-dasharray: 10,5; }
  sequence:
    showSequenceNumbers: true
---
sequenceDiagram
    participant RAN as NG-RAN
    participant MBUPF as MB-UPF
    participant MBSMF as MB-SMF
    participant MBSTF
    participant MBSF
    participant AP as MBS Application Provider (AF/AS)
    activate RAN
    activate MBSMF
    activate MBUPF
    activate MBSF
    activate MBSTF
    AP ->> MBSF: Add MBS User Data Ingest Session<br/>to MBS User Service
    MBSF ->> MBSMF: Create MBS Session<br/>and request an Nmb9 ingress tunnel
    MBSMF ->> MBUPF: Set up Multicast/Broadcast service and<br/>create an Nmb9 ingress tunnel
    MBUPF -->> MBSMF: Success and Nmb9 ingress tunnel details
    MBSMF -->> MBSF: MBS Session created<br/>and Nmb9 ingress tunnel details
    rect rgb(160, 255, 160)
        MBSF ->> MBSTF: Create Distribution Session<br/>using Nmb9 tunnel details from MB-SMF
        MBSTF -->> MBSF: Distribution Session created,<br/>including push Service Entry Point URL,<br/>if requested
    end
    MBSF -->> AP: MBS User Data Ingest Session created<br/>including push Service Entry Point URL,<br/>if requested
    rect rgb(160, 255, 160)
        AP ->> MBSTF: DASH manifest
        MBSTF -->> AP: DASH manifest received OK
        MBSTF ->> MBUPF: DASH manifest packaged in multicast FLUTE session packets<br/>and sent to Nmb9 tunnel at given rate
        MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
        loop For each initialization segment in the DASH manifest
            MBSTF ->> AP: *GET* Initialization Segment
            AP -->> MBSTF: Initialization Segment
            MBSTF ->> MBUPF: Initialization Segment packaged in multicast FLUTE session packets<br/>and sent to Nmb9 tunnel at given rate
            MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
        end
        par For each Representation in the current period
            loop For each Media Segment in the Representation
                MBSTF ->> MBSTF: Wait for the Media Segment to become available
                MBSTF ->> AP: Pull Media Segment
                AP -->> MBSTF: Media Segment delivered
                MBSTF ->> MBUPF: Media Segment packaged in multicast FLUTE session packets<br/>and sent to Nmb9 tunnel at given rate
                MBUPF ->> RAN: Multicast FLUTE packets forwarded<br/>to gNodeB(s) via multicast GTP-U tunnel
            end
        end
    end

    deactivate MBSTF
    deactivate MBSF
    deactivate MBSMF
    deactivate MBUPF
    deactivate RAN

This configuration behaves in a similar manner as the PULL STREAMING configuration in Step 7 except that:

  1. The MPD is the only file whose distribution URL, as given in the Content-Location attribute in the distributed FDT Instance File entry, is subject to substitution with the objDistributionBaseUrl value from the configuration (it is the only file pushed to the objIngestBaseUrl URL prefix). All initialization segments and media segments will be distributed with the Content-Location attribute set to the original media server URL.
  2. The MPD is not automatically refreshed. To refresh, push another MPD to the ingest URL.

With the following processes running:

  • the MBSTF from Step 3
  • Wireshark from step 4

…perform the following actions to test a streaming distribution from the PUSH of a DASH MPD.

Copy the following into a file called DistSession-DASH-PUSH-request.json:

{
  "distSession": {
    "distSessionId": "33acd99a-8564-42a1-a96c-9f293d90c41e",
    "distSessionState": "ACTIVE",
    "mbUpfTunAddr": {
      "ipv4Addr": "127.0.0.7",
      "portNumber": 5678
    },
    "upTrafficFlowInfo": {
      "destIpAddr": {
        "ipv4Addr": "232.0.0.1"
      },
      "portNumber": 5000
    },
    "mbr": "10 Mbps",
    "objDistributionData": {
      "objDistributionOperatingMode": "STREAMING",
      "objAcquisitionMethod": "PUSH",
      "objAcquisitionIdPush": "manifest.mpd",
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

If you are using the option to use a running MB-SMF/MB-UPF (Step 1a) then make the following changes to the JSON above:

  • Change the MB-UPF tunnel IP address distSession.mbUpfTunAddr.ipv4Addr from 127.0.0.7 to the destination IP address for the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).
  • Change the MB-UPF tunnel port number distSession.mbUpfTunAddr.portNumber from 5678 to the destination port number for the Nmb9 tunnel returned in the MB-SMF response (sequence step 5).

When pushed as a configuration for the MBSTF, this will configure a Distribution Session that will provide an ingest URL and will wait for a Service Entry Point (DASH manifest) document to be PUT to the ingest URL. The ingest URL is the concatenation of objIngestBaseUrl and objAcquisitionIdPush from the response.

Note that the present implementation of the MBSTF only supports live-profile DASH manifests as the Service Entry Point document.

To push the DistSession to the MBSTF to configure it (sequence step 6), use the following command:

curl --http2-prior-knowledge -H 'Content-Type: application/json' --data-binary @DistSession-DASH-PUSH-request.json http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions

The MBSTF response (sequence step 7) should look like (the objIngestBaseUrl field will be different):

{
  "distSession": {
    "distSessionId": "33acd99a-8564-42a1-a96c-9f293d90c41e",
    "distSessionState": "ACTIVE",
    "objDistributionData": {
      "objDistributionOperatingMode": "STREAMING",
      "objAcquisitionMethod": "PUSH",
      "objAcquisitionIdPush": "manifest.mpd",
      "objIngestBaseUrl": "http://127.0.0.1:12345/",
      "objDistributionBaseUrl": "http://127.0.0.2/"
    }
  }
}

In this example response, the ingest URL, formed from objIngestBaseUrl and objAcquisitionIdPush, would be http://127.0.0.1:12345/manifest.mpd. This can be stored in a shell variable for ease of use later:

ingest_url="http://127.0.0.1:12345/manifest.mpd"

The MBSTF will now wait for a live profile DASH MPD to be PUT to the ingest URL (http://127.0.0.1:12345/manifest.mpd from the example) with Content-Type application/dash+xml. We will simulate this push from the AP (sequence step 9).

To push a live-profile MPD we can use the command:

curl -H 'Content-Type: application/dash+xml' -X PUT --data-binary @"${HOME}/rt-mbs-transport-function/tests/tutorial/push-croatia-live.mpd" "${ingest_url}"

Once pushed the MBSTF will add the MPD to the distribution FLUTE stream and proceed to pull the initialization segments and media segments as happened in Step 7 above for the PULL STREAMING Distribution Session.

The Wireshark capture will show that the MPD has a Content-Location in its FDT File entry which is the concatenation of the objDistrubutionBaseUrl and objAcquisitionIdPush. All other objects sent on the FLUTE stream will have Content-Location entries showing a URL from the origin media server. For this example they will all begin with https://livesim2.dashif.org/livesim2/WAVE/vectors/cfhd_sets/12.5_25_50/t1/2022-10-17/.

The following Wireshark screenshot shows the FDT File entry for the MPD with a Content-Location URL of “http://127.0.0.2/manifest.mpd”. This comes from the objDistributionBaseURL concatenated with the objAcquisitionIdPush value.

Wireshark screenshot showing the FDT File entry for the pushed MPD

The next Wireshark screenshot above shows the FDT File entry for the first initialization segment after an MPD has been pushed. Because the MPD included a BaseURL element, directing the rest of the fetches to the original media server, the Content-Location URL is the URL the initialization segment was pulled from.

Wireshark screenshot showing the FDT File entry for the initialization segment after pushing an MPD

Step 8a: (Optional) Destroying the MBS Distribution Session

Based on the structure of the MPD (for instance when SegmentTemplate without SegmentTimeline addressing is used) the MBSTF will keep sending initialization segments and media segments until the process is killed or the MBS distribution session is destroyed.

To destroy the MBS distribution session run the following command replacing distSessionId in the URL below with the distSessionId you used when pushing the DistSession to the MBSTF.

curl --http2-prior-knowledge -X DELETE http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions/{distSessionId}

Based on our example above the REST call looks like this:

curl --http2-prior-knowledge -X DELETE http://127.0.0.62:7777/nmbstf-distsession/v1/dist-sessions/33acd99a-8564-42a1-a96c-9f293d90c41e