documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.html - felix-site-pub - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <!--

     Licensed to the Apache Software Foundation (ASF) under one or more
     contributor license agreements.  See the NOTICE file distributed with
     this work for additional information regarding copyright ownership.
     The ASF licenses this file to You under the Apache License, Version 2.0
     (the "License"); you may not use this file except in compliance with
     the License.  You may obtain a copy of the License at

        https://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.
 -->
   <head>
     <title>Apache Felix - UPnP Driver architecture</title>
     <link rel="icon" href="/res/favicon.ico">
     <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
     <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
   </head>
   <body>
     <div class="title">
       <div class="logo">
         <a href="https://felix.apache.org/">
           <img border="0" alt="Apache Felix" src="/res/logo.png">
         </a>
       </div>
       <div class="header">
         <a href="https://www.apache.org/">
           <img border="0" alt="Apache" src="/res/apache.png">
         </a>
       </div>
     </div>

     <div class="menu">
       <style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
 /*
  * Hide class="elementid-permalink", except when an enclosing heading
  * has the :hover property.
  */
 .headerlink, .elementid-permalink {
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <p><a href="/news.html">News</a>  <br />
 <a href="/license.html">License</a>  <br />
 <a href="/downloads.cgi">Downloads</a>  <br />
 <a href="/documentation.html">Documentation</a>  <br />
 <a href="/documentation/community/project-info.html">Project Info</a>  <br />
 <a href="/documentation/community/contributing.html">Contributing</a>  <br />
 <a href="/sitemap.html">Site Map</a>  <br />
 <a href="https://www.apache.org/">ASF</a>  <br />
 <a href="https://www.apache.org/security/">Security</a>  <br />
 <a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>  <br />
 <a href="https://www.apache.org/foundation/thanks.html">Sponsors</a>    </p>
 <iframe
     src="https://www.apache.org/ads/button.html"
     style="border-width:0; float: left"
     frameborder="0"
     scrolling="no"
     width="135"
     height="135">
 </iframe>
     </div>

     <div class="main">
       <div class="breadcrump" style="font-size: 80%;">
         <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects/apache-felix-upnp.html">Apache Felix UPnP</a>
       </div>

       <h1>UPnP Driver architecture</h1>
       <style type="text/css">
 /* The following code is added by mdx_elementid.py
    It was originally lifted from http://subversion.apache.org/style/site.css */
 /*
  * Hide class="elementid-permalink", except when an enclosing heading
  * has the :hover property.
  */
 .headerlink, .elementid-permalink {
   visibility: hidden;
 }
 h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
 <h1 id="overview-of-the-base-driver-architecture">Overview of the Base Driver Architecture&nbsp;<a class="headerlink" href="#overview-of-the-base-driver-architecture" title="Permanent link">&para;</a></h1>
 <p>The Figure 4 shows a simplified component view of the base driver. The driver is composed of two components, the <em>exporter</em> and <em>importer</em>; both using the <em>CyberDomo</em> library, which is a modified version of the library released by the <a href="http://www.cybergarage.org/net/upnp/java/index.html">"CyberLink for Java" project</a>, maintained by the [Domoware project|http://domoware.isti.cnr.it/ ]. The library implements a full UPnP stack. The base driver acts as a bridge between OSGi and the UPnP networks .
 !BaseDriverArchitecture.jpg!
 <em>Figure 4</em> The UPnP Base Driver architecture</p>
 <p>In order to instantiate UPnP devices, developers must register services implementing the interfaces represented in Figure 5 and provided by the <em>org.osgi.compendium bundle</em>. The <em>exporter</em> is registered as <a href="http://www.osgi.org/javadoc/r4/org/osgi/framework/ServiceListener.html">ServiceListener </a>with the framework and it automatically exposes on the networks each [UPnPDevice |http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html]service registered with the registration property [UPNP<em>EXPORT|http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html#UPNP</em>EXPORT]. The <em>importer</em> listens to the advertisements sent on the networks by external devices and registers with the framework one or more UPnPDevice services. Even if it is not required by the specification, the devices imported by the Felix base driver are labeled with the registration property [UPNP_IMPORT|http://svn.apache.org/viewvc/felix/trunk/upnp/basedriver/src/main/java/org/apache/felix/upnp/basedriver/util/Constants.java?view=markup].
 !UPnPDeviceInterfaces.jpg!
 <em>Figure 5</em> The UPnP Device interfaces</p>
 <p>Working with UPnP Device from the OSGi point of view means to operate with services; the discovery, controlling and eventing phases of the UPnP protocol are naturally mapped to the OSGi service layer, which allows to publish, find, bind and notify events. There are some aspects that make it different to work with UPnP in OSGi with respect to other UPnP libraries, due basically to the centralized nature of the OSGi registry opposed to the distributed approach used in UPnP networks; some hints are provided in the section "Writing UPnP Devices and Control Points"</p>
 <p>The Felix base driver comes with some system properties you can use to configure it at startup.</p>
 <p>The system properties:
 • <em>cyberdomo.ssdp.mx</em> (default 5)
 • <em>cyberdomo.ssdp.buffersize</em> (default 2048)
 • <em>cyberdomo.ssdp.port</em> (default 1900)</p>
 <p>are used by the UPnP stack library during the UPnP discovery process. The paper "<a href="http://w3.antd.nist.gov/~mills/papers/Paper521.pdf">Adaptive Jitter Control for UPnP M-Search</a>" [1] provides a good analysis of the tuning of such parameters related to scalability issues. The MX parameter default has been set to 5 sec. Higher values improve the discovery effectiveness but increase the latency for new device discovery. The Intel "[Device Spy|http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/index.htm]" tool uses a delay of 10 sec, the "CyberLink for Java" library 3 sec. The SSDP port in UPnP specification is by default 1900 we allow the modification of such parameter.</p>
 <p>The following system properties:
 • <em>felix.upnpbase.exporter.enabled</em> (default true)
 • <em>felix.upnpbase.importer.enabled</em> (default true)</p>
 <p>can be used to enable or disable the two main components of the base driver. For example with small devices (ARM-based processor), disabling the exporting or importing of devices might reduce the resource consumption.</p>
 <p>• <em>felix.upnpbase.log</em> (default 2)
 • <em>felix.upnpbase.cyberdomo.log</em> (default false)</p>
 <p>are properties used to enable the different logging facilities offered by the base driver. You can also modify them at run time by using the GUI provided by the UPnP Tester bundle</p>
 <p>Finally the following properties are used to set the networking parameters. The loopback interface is usually disabled :</p>
 <p>• <em>felix.upnpbase.cyberdomo.net.loopback</em> (default false)
 • <em>felix.upnpbase.cyberdomo.net.onlyIPV4</em> (default true)
 • <em>felix.upnpbase.cyberdomo.net.onlyIPV6</em> (default false)</p>
 <h5 id="getting-started-testing-upnp-devices-upnp-testing-devices"><a href="/documentation/subprojects/apache-felix-upnp/upnp-getting-started.html">Getting Started</a> &lt;&lt; \| &gt;&gt; [Testing UPnP Devices| UPnP Testing Devices]<a class="headerlink" href="#getting-started-testing-upnp-devices-upnp-testing-devices" title="Permanent link">&para;</a></h5>
 <hr />
 <p>[1]() K. Mills, C. Dabrowski "Adaptive Jitter Control for UPnP M-Search" IEEE International Conference on Communications, 2003. ICC '03. page(s): 1008- 1013 vol.2 </p>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
         Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
       </div>
       <div class="trademarkFooter">
         Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
         logo are trademarks of The Apache Software Foundation. All other marks mentioned
         may be trademarks or registered trademarks of their respective owners.
       </div>
     </div>
   </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<!--

	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<head>
	<title>Apache Felix - UPnP Driver architecture</title>
	<link rel="icon" href="/res/favicon.ico">
	<link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
	<link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
	<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
	</head>
	<body>
	<div class="title">
	<div class="logo">
	<a href="https://felix.apache.org/">
	<img border="0" alt="Apache Felix" src="/res/logo.png">
	</a>
	</div>
	<div class="header">
	<a href="https://www.apache.org/">
	<img border="0" alt="Apache" src="/res/apache.png">
	</a>
	</div>
	</div>

	<div class="menu">
	<style type="text/css">
	/* The following code is added by mdx_elementid.py
	It was originally lifted from http://subversion.apache.org/style/site.css */
	/*
	* Hide class="elementid-permalink", except when an enclosing heading
	* has the :hover property.
	*/
	.headerlink, .elementid-permalink {
	visibility: hidden;
	}
	h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
	<p><a href="/news.html">News</a> <br />
	<a href="/license.html">License</a> <br />
	<a href="/downloads.cgi">Downloads</a> <br />
	<a href="/documentation.html">Documentation</a> <br />
	<a href="/documentation/community/project-info.html">Project Info</a> <br />
	<a href="/documentation/community/contributing.html">Contributing</a> <br />
	<a href="/sitemap.html">Site Map</a> <br />
	<a href="https://www.apache.org/">ASF</a> <br />
	<a href="https://www.apache.org/security/">Security</a> <br />
	<a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> <br />
	<a href="https://www.apache.org/foundation/thanks.html">Sponsors</a> </p>
	<iframe
	src="https://www.apache.org/ads/button.html"
	style="border-width:0; float: left"
	frameborder="0"
	scrolling="no"
	width="135"
	height="135">
	</iframe>
	</div>

	<div class="main">
	<div class="breadcrump" style="font-size: 80%;">
	<a href="/">Home</a> &raquo <a href="/documentation.html">Documentation</a> &raquo <a href="/documentation/subprojects/apache-felix-upnp.html">Apache Felix UPnP</a>
	</div>

	<h1>UPnP Driver architecture</h1>
	<style type="text/css">
	/* The following code is added by mdx_elementid.py
	It was originally lifted from http://subversion.apache.org/style/site.css */
	/*
	* Hide class="elementid-permalink", except when an enclosing heading
	* has the :hover property.
	*/
	.headerlink, .elementid-permalink {
	visibility: hidden;
	}
	h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
	<h1 id="overview-of-the-base-driver-architecture">Overview of the Base Driver Architecture <a class="headerlink" href="#overview-of-the-base-driver-architecture" title="Permanent link">¶</a></h1>
	<p>The Figure 4 shows a simplified component view of the base driver. The driver is composed of two components, the <em>exporter</em> and <em>importer</em>; both using the <em>CyberDomo</em> library, which is a modified version of the library released by the <a href="http://www.cybergarage.org/net/upnp/java/index.html">"CyberLink for Java" project</a>, maintained by the [Domoware project\|http://domoware.isti.cnr.it/ ]. The library implements a full UPnP stack. The base driver acts as a bridge between OSGi and the UPnP networks .
	!BaseDriverArchitecture.jpg!
	<em>Figure 4</em> The UPnP Base Driver architecture</p>
	<p>In order to instantiate UPnP devices, developers must register services implementing the interfaces represented in Figure 5 and provided by the <em>org.osgi.compendium bundle</em>. The <em>exporter</em> is registered as <a href="http://www.osgi.org/javadoc/r4/org/osgi/framework/ServiceListener.html">ServiceListener </a>with the framework and it automatically exposes on the networks each [UPnPDevice \|http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html]service registered with the registration property [UPNP<em>EXPORT\|http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html#UPNP</em>EXPORT]. The <em>importer</em> listens to the advertisements sent on the networks by external devices and registers with the framework one or more UPnPDevice services. Even if it is not required by the specification, the devices imported by the Felix base driver are labeled with the registration property [UPNP_IMPORT\|http://svn.apache.org/viewvc/felix/trunk/upnp/basedriver/src/main/java/org/apache/felix/upnp/basedriver/util/Constants.java?view=markup].
	!UPnPDeviceInterfaces.jpg!
	<em>Figure 5</em> The UPnP Device interfaces</p>
	<p>Working with UPnP Device from the OSGi point of view means to operate with services; the discovery, controlling and eventing phases of the UPnP protocol are naturally mapped to the OSGi service layer, which allows to publish, find, bind and notify events. There are some aspects that make it different to work with UPnP in OSGi with respect to other UPnP libraries, due basically to the centralized nature of the OSGi registry opposed to the distributed approach used in UPnP networks; some hints are provided in the section "Writing UPnP Devices and Control Points"</p>
	<p>The Felix base driver comes with some system properties you can use to configure it at startup.</p>
	<p>The system properties:
	• <em>cyberdomo.ssdp.mx</em> (default 5)
	• <em>cyberdomo.ssdp.buffersize</em> (default 2048)
	• <em>cyberdomo.ssdp.port</em> (default 1900)</p>
	<p>are used by the UPnP stack library during the UPnP discovery process. The paper "<a href="http://w3.antd.nist.gov/~mills/papers/Paper521.pdf">Adaptive Jitter Control for UPnP M-Search</a>" [1] provides a good analysis of the tuning of such parameters related to scalability issues. The MX parameter default has been set to 5 sec. Higher values improve the discovery effectiveness but increase the latency for new device discovery. The Intel "[Device Spy\|http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/index.htm]" tool uses a delay of 10 sec, the "CyberLink for Java" library 3 sec. The SSDP port in UPnP specification is by default 1900 we allow the modification of such parameter.</p>
	<p>The following system properties:
	• <em>felix.upnpbase.exporter.enabled</em> (default true)
	• <em>felix.upnpbase.importer.enabled</em> (default true)</p>
	<p>can be used to enable or disable the two main components of the base driver. For example with small devices (ARM-based processor), disabling the exporting or importing of devices might reduce the resource consumption.</p>
	<p>• <em>felix.upnpbase.log</em> (default 2)
	• <em>felix.upnpbase.cyberdomo.log</em> (default false)</p>
	<p>are properties used to enable the different logging facilities offered by the base driver. You can also modify them at run time by using the GUI provided by the UPnP Tester bundle</p>
	<p>Finally the following properties are used to set the networking parameters. The loopback interface is usually disabled :</p>
	<p>• <em>felix.upnpbase.cyberdomo.net.loopback</em> (default false)
	• <em>felix.upnpbase.cyberdomo.net.onlyIPV4</em> (default true)
	• <em>felix.upnpbase.cyberdomo.net.onlyIPV6</em> (default false)</p>
	<h5 id="getting-started-testing-upnp-devices-upnp-testing-devices"><a href="/documentation/subprojects/apache-felix-upnp/upnp-getting-started.html">Getting Started</a> << \\| >> [Testing UPnP Devices\| UPnP Testing Devices]<a class="headerlink" href="#getting-started-testing-upnp-devices-upnp-testing-devices" title="Permanent link">¶</a></h5>
	<hr />
	<p>[1]() K. Mills, C. Dabrowski "Adaptive Jitter Control for UPnP M-Search" IEEE International Conference on Communications, 2003. ICC '03. page(s): 1008- 1013 vol.2 </p>
	<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
	Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
	</div>
	<div class="trademarkFooter">
	Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
	logo are trademarks of The Apache Software Foundation. All other marks mentioned
	may be trademarks or registered trademarks of their respective owners.
	</div>
	</div>
	</body>
	</html>