How to configure SPI (Service and Programme Information) for ODR-DabMux

From Opendigitalradio
(Difference between revisions)
Jump to: navigation, search
(Generating your SPI)
(Packet sizes and bitrates)

Revision as of 15:54, 24 July 2020

Howto by Ulrik Brinck on odr-radioepg-bridge installation on Debian Jessie. Nick Piggott has contributed with some additions.

Contents

Introduction

This tool (or rather series of tools) will pick up your SPI (Service and Programme Information) from the internet via RadioDNS and generate a DAB SPI from it. It was written by Ben Poor and Nick Piggott. In this HowTo, I will describe how it can be installed on Debian Jessie. Some details might be slightly different on other Debian generations.

  • Confused about EPG and SPI? In this context, EPG and SPI are basically the same thing. While EPG (Electronic Programme Guide) is an old, but commonly well-known term, SPI (Service and Programme Information) is now the official name of this feature.

Notes

This tool uses RadioDNS to locate and acquire Service Information (SI.xml), Programme Information (PI.xml) and Logos. Each station you want to add to the SPI must be registered in RadioDNS using the correct information (Ensemble ID, Service ID, Service Component ID), and have correctly formatted SI, PI and logo files in PNG format. Find out more at https://radiodns.org/technical/documentation/#howto

I have assumed that you are logged in to your Linux system as a standard user and have sudo installed on your system. If sudo is not installed, you can see here, how to install it on Debian Jessie: https://www.geek17.com/en/content/debian-8-jessie-install-and-configure-sudo-25

Installation

Step 0: Update your system

Begin with "sudo apt-get update" to make sure that you can install all that you need.

Step 1: Miscellaneous dependencies

First there are some dependencies to install with apt-get:

sudo apt-get install python-crcmod python-bitarray python-dateutil python-isodate

Next there are some dependencies and subcomponents which must be downloaded from github and installed:

Step 2: python-dabmot

Download from here https://github.com/Opendigitalradio/python-dabmot and unpack to a folder, e.g. /home/user/python-dabmot-master

Then navigate to the folder and run:

sudo python setup.py install

Step 3: python-mot-epg

Download from here https://github.com/Opendigitalradio/python-mot-epg and unpack to a folder, e.g. /home/user/python-mot-epg-master

Then navigate to the folder and run:

sudo python setup.py install

Step 4: python-msc

Download from here https://github.com/Opendigitalradio/python-dabmsc and unpack to a folder, e.g. /home/user/python-dabmsc-master

Then navigate to the folder and run:

sudo python setup.py install

Step 5: pyradiodns

Download from here https://github.com/radiodns/pyradiodns and unpack to a folder, e.g. /home/user/pyradiodns-master

Then navigate to the folder and run:

sudo python setup.py install

Step 6: odr-radiodns-bridge

Download from here https://github.com/Opendigitalradio/odr-radiodns-bridge and unpack to a folder, e.g. /home/user/odr-radiodns-bridge-master

Then navigate to the folder and run:

sudo python setup.py install

Step 7: python-hybridspi

Download from here https://github.com/Opendigitalradio/python-hybridspi and unpack to a folder, e.g. /home/user/python-hybridspi-master

Then navigate to the folder and run:

sudo python setup.py install

Step 8: odr-radioepg-bridge

And now for the RadioEPG-bridge itself.

Download from here https://github.com/Opendigitalradio/odr-radioepg-bridge and unpack to a folder, e.g. /home/user/odr-radioepg-bridge-master

Then run:

sudo ln -s /home/user/odr-radioepg-bridge-master/generate-epg /usr/local/bin/generate-epg

(If your folder is not /home/user/odr-radioepg-bridge-master, use your_path/generate-epg in the last command line above).

That's it. You should now be able to run this command and see a help text:

generate-epg -h

Generating and broadcasting your EPG

Generating your SPI

Odr-radioepg-bridge is a command-line tool, which will:

  • First read your mux.conf (from your ODR-DabMux configuration) to get information about your services.
  • Then try to fetch SPI data for your services from the internet using RadioDNS.
  • And lastly generate an output file containing a complete SPI.

If you type "generate-epg -h" you will get a list of available command-line arguments:

usage: generate-epg [-h] [-o OUTPUT] [-X] [-d DAYS] [-p PACKET_SIZE]
                    [-a PACKET_ADDRESS] [-D]
                    f

Encodes an SPI bitstream for services in a multiplex configuration file

positional arguments:
  f                  multiplex configuration file

optional arguments:
  -h, --help         show this help message and exit
  -o OUTPUT          output bitstream file
  -X                 turn debug on
  -d DAYS            number of days ahead to encode schedule files
  -p PACKET_SIZE     Packet size in bytes
  -a PACKET_ADDRESS  Packet address
  -D                 output Datagroups instead of Packets

The positional argument tells the tool where to find your mux.conf. The other arguments are optional, and some default values will be used if you don't set them:

  • -o can be used to set filename and path to your output file (your SPI). Default is output.dat, placed in the folder from where you run the tool.
  • -d is the number of days of programme schedule you want in you SPI. From 1 til 4 days, default is 2.
  • -p is packet size. Available values are 24, 48, 72 and 96. Default is 96. Which value you should use, depends on the bitrate in which you are broadcasting your SPI (see below).
  • -a is the packet address for your SPI. Default is 1, which will normally be fine. Important is, that you must set the same address in your mux.conf (see below).
  • -D will tell the script to output Datagroups instead of Packets. This is useful for some commercial multiplexers or in case you want to broadcast your SPI as X-PAD instead of packet data. Note: You do not need this if you plan to broadcast your SPI the way it's described on this wiki page.


Example: If your mux.conf is placed in /home/user/odr/config/mux.conf, and you want 4 days in your SPI (today and the next 3 days) and you want to broadcast it in 16 kbit/s, your command line could look like this:

generate-epg -d 4 -p 48 /home/user/odr/config/mux.conf

This will generate a file named output.dat containing your SPI. In this example, I have set the packet size to 48, which is suitable for 16 kbit/s. I have not set the packet address, which means that the default value of 1 will be used.

Packet sizes and bitrates

The packet size, which you set when you generate your SPI, should match the bitrate in which you intend to broadcast it. If the packet size is too large, your SPI will not be transmitted. If the packet size is too small, your SPI will (probably) be transmitted, but it will be slower than necessary, because more space will be used for packet headers and maybe partly empty data packets. I will recommend these values:

Bitrate Packet size
8 24
16 48
24 72
32 96
48 72
64 96

Broadcasting your EPG

To broadcast your EPG using ODR-DabMux, create a packet data service in your mux.conf like in this example:

In the services section:

srv-epg {
label "EPG"
shortlabel "EPG"
; the service-ID consists of 8 hex digits for packet data services. Usually the first two digits will
; be the same as your ECC, and the third digit will be the same as the first digit in your Ensemble Id.
id 0xe1912345
}

In the subchannels section:

sub-epg {
; type packet or enhancedpacket can be used for EPG.
type enhancedpacket
; if you change the bitrate, remember to also change the packet size accordingly (see above) and generate your EPG again.
bitrate 16
protection-profile EEP_A
protection 3
; inputuri is the path and filename for your output file from generate-epg
inputuri "/home/user/odr-radioepg-bridge-master/output.dat"
inputproto file
} 

And in the components section:

comp-epg {
type 60
service srv-epg
subchannel sub-epg
figtype 0x7
; The address must be the same as your packet address set when you generate the EPG (default value is 1).
address 0x1
datagroup true
}

That's it. Now (re)start your ODR-DabMux, and your EPG should be broadcasted.

Updating your EPG automatically every day

Feeding the EPG from a fifo to be able to update it without restarting the MUX

While the setup shown above will allow you to broadcast your EPG, it will not allow you to update your EPG without having to restart your MUX. To get around this, you can feed your EPG to ODR-DabMux from a named fifo instead of a file.

Navigate to the folder where you have your EPG and create a fifo like this:

mkfifo epgfifo

In the subchannel section of your mux.conf, you should replace your EPG file (output.dat) with your fifo, and also add a new line, "nonblock true", so that your EPG subchannel looks like this:

sub-epg {
; type packet or enhancedpacket can be used for EPG.
type enhancedpacket
; if you change the bitrate, remember to also change the packet size accordingly (see above) and generate your EPG again.
bitrate 16
protection-profile EEP_A
protection 3
; inputuri is the path and filename for your output from generate-epg
inputuri "/home/user/odr-radioepg-bridge-master/epgfifo"
inputproto file
nonblock true
} 

Your EPG must be continously sent to the fifo. You can make a shell script for that. Create a file, sendepg.sh, with this content:

#!/bin/bash
 
while :
do
 
cat /home/user/odr-radioepg-bridge-master/output.dat >> /home/user/odr-radioepg-bridge-master/epgfifo
 
done

And make it executable (chmod +x sendepg.sh).

This script must be running all the time. If you're already using Supervisor to keep your MUX running (as described here: https://github.com/Opendigitalradio/dab-scripts), it's easy to also use supervisor for this script. Create a new file, sendepg.conf, in your /home/user/odr/config/supervisor folder with this content:

[program:sendepg]
command=bash -c "/home/user/odr-radioepg-bridge-master/sendepg.sh"
autostart=true
autorestart=true
startretries=99999
priority=10
stderr_logfile=/dev/stdout
stdout_logfile=/dev/stdout

Then run these commands:

sudo ln -s /home/user/odr/config/supervisor/sendepg.conf /etc/supervisor/conf.d/sendepg.conf
sudo supervisorctl reread
sudo supervisorctl update

Now your EPG is sent to ODR-DabMux from the fifo, and you will now be able to update your EPG without having to restart ODR-DabMux.

Updating your EPG automatically every day

You can update your EPG every 24 hours by adding a new daily task to cron.

Create a new file

/etc/cron.daily/epg

with the single line (with the same parameters as when you generate your EPG yourself)

/usr/local/bin/generate-epg -d 4 -p 48 /home/user/odr/config/mux.conf -o /home/user/odr-radioepg-bridge-master/output.dat

By default, the cron job will run every day at around 06:00. If you want your EPG to update more frequently (every 4 hours), you could add it to the user cron job with

crontab -e

and add the line

0 */4 * * * /usr/local/bin/generate-epg -d 4 -p 48 /home/user/odr/config/mux.conf -o /home/user/odr-radioepg-bridge-master/output.dat

NOTE: The EPG creates new MOT TransportIDs for every object each time it is run. A receiver will not recognise that objects have been previously received and cached. If there is an interruption in reception, the EPG will be incomplete. The more frequently you update the EPG, more likely it is that a receiver will not be able to utilise the cached objects.

Some observations

  • According to specs, logo slides in DAB EPG must be PNG. Although JPG is allowed in hybrid radio SPI, JPG logos will not be added to your DAB EPG. Be sure that your logos (at least those up to 320x240) are PNG.
  • Programme descriptions (shortDescription) seem to be processed but not shown. Perhaps we will have to look a little further into this.
Personal tools