Sample of an integration of a UPnP AV MediaServer and digitalSTROM. Presentation by Sergey "Jin" Bostandzhyan, MediaTomb.

1. 
UPnP AV MediaServer
and
digitalStrom Developer Day, January 15, 2010 Sergey 'Jin' Bostandzhyan
jin@mediatomb.cc

2. 

Overview
● very brief introduction on UPnP
● introduction on MediaTomb and feature overview
● closer look at the “active items” feature
● interaction with digitalSTROM

3. 

Universal Plug and Play
The UPnP forum, an industry initiative of more than 800
companies.
“The Forum's goals are to allow devices to connect seamlessly
and to simplify network implementation in the home and corporate
environments. Toward this end, UPnP Forum members work
together to define and publish UPnP device control protocols built
upon open, Internet-based communication standards.”
http://www.upnp.org/about/default.asp

4. 

Universal Plug and Play
● allows peer-to-peer networking of CE devices, PC's, etc.
● protocol based on IP, TCP, UDP, HTTP, XML among others
● supports zero-configuration networking
● devices announce their presence
● devices can query and learn capability of other devices
● defines various standardized specifications

5. 

Universal Plug and Play
MediaServer
● provides information about media format
● reads meta data from media files
● offers means to organize media collections
● presents a browseable hierarchy to the MediaRenderer via
the Content Directory Service
● allows to stream/download media

6. 

Universal Plug and Play
MediaRenderer
● allows the user to browse content of media servers
● shows information about the media
● allows the user to play/watch media

7. 

WAN
Universal Plug and Play
LAN Iomega StorCenter
running
MediaTomb
Philips SPF508 Digital Picture Frame
Notebook running MediaTomb D-Link DSM-510

8. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
● open source, GPLv2
● meta data extraction from media files (ID3, EXIF, etc.)
● user configurable media layout / browse hierarchy via JS
● provides means for custom playlist parsing via JS
● highly flexible media format transcoding via plugins / scripts
● web UI with a tree view of the database and the file system
● runs on x86, Alpha, ARM, MIPS, Sparc, ...
● available in major Linux distributions like Debian, Fedora, etc.

9. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc

10. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
Active Item Feature
● allows to run a script on the server when media was
requested for download
● allows the script to modify properties of the virtual UPnP
object that corresponds to the requested media

11. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
“Browse”
User navigates into a container:
S browse request (SOAP, XML)
P
E Server lists container contents:
browse response (SOAP, XML)
L
R <DIDL­Lite>
<item id="1888" parentID="1752" restricted="1">
<dc:title>УАЗик, реставрация</dc:title> A
V <upnp:class>object.item.imageItem</upnp:class>
<dc:date>2009­10­29</dc:date>
<res protocolInfo="http­get:*:image/jpeg:*" size="1526998"
Y
E resolution="2848x2136">http://192.168.5.5:50500/content/media/object_id
/1888/res_id/0/ext/file.jpg</res>
<res protocolInfo="http­get:*:image/jpeg:*"
E
R resolution="160x120">http://192.168.5.5:50500/content/media/object_id/
1888/res_id/1/rct/EX_TH/ext/file.jpg</res>
</item>
R
</DIDL­Lite>

12. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
“Play”
S User presses “Play”: HTTP GET
http://192.168.5.5:50500/content/media/object_id/1888/res_id/0/ext/file.jpg
P
E ● server looks up object id 1888 in the database
● looks up the location of the media on disk L
R ● sends data
A
V
HTTP/1.1 200 OK
CONTENT­LENGTH: 1526998
CONTENT­TYPE: image/jpeg
Y
E DATE: Fri, 01 Jan 2010 21:39:18 GMT
LAST­MODIFIED: Thu, 19 Nov 2009 09:22:57 GMT
SERVER: Linux/2.6.31.9­174.fc12.x86_64, UPnP/1.0, MediaTomb/0.12.0
E
R CONNECTION: close
Content­Disposition: attachment; filename="DSCF7914.JPG"
Accept­Ranges: bytes
R

13. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
“Play”: Active Item
S User presses “Play”: HTTP GET
http://192.168.5.5:50500/content/media/object_id/1889/res_id/0/ext/file.jpg
P
E L
server looks up object id 1889 in the database
R
●
A
● recognizes, that the requested object is an “Active Item”
● ...
V Y
E E
R R

14. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
“Play”: Active Item
S ●
●
...
recognizes, that the requested object is an “Active Item”
E ● renders the requested UPnP object as XML
R ● launches a user defined script, feeding it a the rendered XML on stdin
V ●
●
expects the script to spit out same or modified XML to stdout
updates the object in the database using the XML received from the script
E ● looks up the location of the updated object on disk
R ● sends the data to the player

15. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
Active Item: script input
<item id="2292" parentID="1752" restricted="1"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:upnp="urn:schemas­upnp­org:metadata­1­/upnp/">
<dc:title>DSCF7919.JPG</dc:title>
<upnp:class>object.item.imageItem</upnp:class>
<dc:date>2009­10­29</dc:date>
<action>/usr/local/bin/myscript.py</action>
<state>0</state>
<location>/opt/Photos/УАЗ/25­11­09/DSCF7919.JPG</location>
<mime­type>image/jpeg</mime­type>
</item>

16. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
Active Item: script logic
● read XML from standard input
● parse XML and if needed evaluate the <status> tag
● perform any desired operation on the server machine
● update the XML if you want to pass along information to the user
● print updated XML to standard output

17. 

MediaTomb – UPnP AV MediaServer
http://mediatomb.cc
Active Item: script output
<item id="2292" parentID="1752" restricted="1"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:upnp="urn:schemas­upnp­org:metadata­1­/upnp/">
<dc:title>I ran a script!</dc:title>
<upnp:class>object.item.imageItem</upnp:class>
<dc:date>2009­10­29</dc:date>
<action>/usr/local/bin/myscript.py</action>
<state>1</state>
<location>/opt/Photos/УАЗ/25­11­09/DSCF7919.JPG</location>
<mime­type>image/jpeg</mime­type>
</item>

18. 

How to control digitalSTROM via MediaTomb?
We need to...
● think of an easy way to generate a browseable hierarchy of
active items which would represent the dS controls
● create a script that will be triggered by the active items, that
will identify them as particular dS controls and perform
appropriate calls to the digitalSTROM server

19. 

How to control digitalSTROM via MediaTomb?
Generating the hierarchy can be done using MediaTomb's
playlist import feature which allows to write custom playlist
parsers using JavaScript.
We have to...
● come up with a meaningful playlist format that we could use
● tell MediaTomb to treat our file as a playlist
● customize the default playlist parser so that it handles our
playlist

20. 

How to control digitalSTROM via MediaTomb?
Simply use JSON apartment structure dump from the
digitalSTROM server!
http://<dsshost>:8080/json/apartment/getStructure
{"ok":true,
"result":{"apartment":{
"zones":[{"id":313,"name":"Wohnzimmer","isPresent":true,"firstZoneOnDSMeter":0,
"devices":[{"id":"3504175fe000000000001b78","isSwitch":false,
"name":"Taster Eingang","fid":4098, "circuitID":0,"busID":897,
"isPresent":true,"lastDiscovered":"2010­01­12 14:49:19",
"firstSeen":"2009­11­09 10:44:16","on":false},
{"id":"3504175fe000000000001b9f","isSwitch":false,
"name":"Gehen Taster","fid":28770,"circuitID":0,"busID":898,
"isPresent":true,"lastDiscovered":"2010­01­12 14:49:19",
"firstSeen":"2009­11­09 10:44:16","on":false},
........

21. 

How to control digitalSTROM via MediaTomb?
In the playlist parser script of MediaTomb, convert the JSON
data to a JS object and loop through the data:
do
{
json_content = json_content + line;
line = readln(); // readln function is provided by MediaTomb
}
while (line);
// evaluate content of json file
apartment = eval('(' + json_content + ')').result.apartment;
while(apartment.zones.length > 0)
{
zone = apartment.zones.shift();
addScenes(zone.id, zone.name); // helper function
};

22. 

How to control digitalSTROM via MediaTomb?
Define desired scenes depending on the zone id:
function Scene(id, name) {
this.id = id;
this.name = name;
}
function addScenes(zoneid, zonename) {
var item = new Object();
// scene id ­> scene name mapping
if(zoneid == 313) // Wohnen
{
scenes = new Array(new Scene(5, "Essen"), new Scene(17, "Fernsehen"),
new Scene(18, "Lesen"), new Scene(19, "Putzen"),
new Scene(13, "Alles aus"));
} ...

23. 

How to control digitalSTROM via MediaTomb?
Create new active item objects and add them to MediaTomb:
function addScenes(zoneid, zonename) {
.....
while(scenes.length > 0) {
scene = scenes.shift();
item.objectType = OBJECT_TYPE_ACTIVE_ITEM;
item.action = "/home/demo/Desktop/call_item_by_state.py";
item.state = "class=scene;zone=" + zoneid + ";scene=" + scene.id;
item.title = scene.name;
item.location = "/home/demo/Desktop/selected.mp3";
item.mimetype = 'audio/mpeg';
item.upnpclass = UPNP_CLASS_ITEM_MUSIC_TRACK;
chain = new Array("Wohnung – Musik", zonename, scene.name);
addCdsObject(item, createContainerChain(chain),
UPNP_CLASS_PLAYLIST_CONTAINER);
}
}

24. 

How to control digitalSTROM via MediaTomb?

25. 

How to control digitalSTROM via MediaTomb?
When the “Essen” item gets played, the action
/home/demo/Desktop/call_item_by_state.py is executed,
receving this XML on stdin:
<item id="49921" parentID="49920" restricted="1"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:upnp="urn:schemas­upnp­org:metadata­1­0/upnp/">
<dc:title>Essen</dc:title>
<upnp:class>object.item.audioItem.musicTrack</upnp:class>
<action>/home/demo/Desktop/call_item_by_state.py</action>
<state>class=scene;zone=313;scene=5</state>
<location>/home/demo/Desktop/send.mp3</location>
<mime­type>audio/mpeg</mime­type>
</item>

26. 

How to control digitalSTROM via MediaTomb?
call_item_by_state.py:
● parses the item XML and get the <state> value
● parses the state and gets zone and scene id's
● runs a helper script which calls the scene on the dSS
● returns unmodified XML back to MediaTomb (no item update)

27. 

How to control digitalSTROM via MediaTomb?
call_scene.sh helper script:
#!/bin/bash
DSS_SERVER=localhost:8080
BASE_URL="http://$DSS_SERVER/json/zone/callScene"
if [ ­z "$2" ]; then
echo "Usage: $(basename $0) <zone id> <scene id>"
exit 1
fi
wget ­O ­ "${BASE_URL}?id=$1&sceneNr=$2&groupID=1" &> /dev/null

28. 

Summary
In order to perform calls on the dSS from any UPnP player
● download the JSON dump from dSS and use it as a playlist
in MediaTomb
● use the playlist parser from this presentation or customize
your own
● install the active item action script and the dSS helper script
● setup MediaTomb to use your parser and import the playlist
● on the player, navigate to the desired item and press play to
trigger a call to the dSS
Scripts used in this presentation are available here:
http://developer.digitalstrom.org/files/contrib/

29. 

Questions?
http://www.digitalstrom.org/
http://mediatomb.cc/
jin@mediatomb.cc
Scripts used in this presentation:
http://developer.digitalstrom.org/files/contrib/