Difference between revisions of "Programmer's Guide"

From LinuxMCE
Jump to: navigation, search
(Imported document)
 
(→‎LinuxMCE software architecture)
 
(32 intermediate revisions by 17 users not shown)
Line 1: Line 1:
−
<table width="100%"> <tr><td bgcolor="#FFCFCF">This page was written by Pluto and imported with their permission when LinuxMCE branched off in February, 2007.  In general any information should apply to LinuxMCE.  However, this page should be edited to reflect changes to LinuxMCE and remove old references to Pluto.</td></tr> </table><p><h1>Introduction to the Pluto Architecure</h1></p>
+
[[Category: Programmer's Guide]]
  
−
Pluto's kick-start cd includes our own distribution based on Debian Linux.  This distribution includes hundreds of scripts and utilities that Pluto has written to fully automate everything so that a PC with Pluto becomes a 'turn it on and press play' appliance, rather than a traditional software application.  However if you strip away all this stuff, the guts of Pluto is software written in cross-platform c++.  In fact nearly all Pluto's code runs on Windows too.
+
This guide explains the architecture of the main C++ code of LinuxMCE.  
  
−
This guide explains the architecture of the main C++ code. Documentation for all the scripts and utilities that make up the distribution is ***here***.
+
A new tutorial for [[Developing a DCE Device]] has just been added to the wiki. While we're creating our own Doxygen documentation, the most recent information regarding architecture and getting started with development can be found on the "[[Developers Guide]]" page, and, the [http://plutohome.com/support/doxygen/ Pluto Doxygen] is still online.  
  
−
Pluto uses an extremely modular architecture.  The heart of Pluto, the 'main application' DCERouter is nothing but a general-purpose message router.  It has absolutely no code relating to any of Pluto's functionality--it just relays messages between devices.  The functionality of Pluto is, therefore, entirely in separate modules (ie Devices) which all run independently and communicate with each other by passing messages through DCERouter over sockets.  There can be hundreds of these devices in a smart home, that do all sorts of things.  As shown in the diagram below, many of Pluto's devices are actually 'wrappers' we have written for existing open source projects that allow them to work together seamlessly in a Pluto system.  For example, we wrote a wrapper for Asterisk that sends event messages to DCERouter whenever a phone call comes in, and receives command messages when it is time to place a call.  How the wrapper communicates with the open source project depends on that project.  Our Asterisk wrapper, for example, communicates with Asterisk over a socket.  It is really a translator converting messages from its socket connection with DCERouter into messages from its socket connection with Asterisk.  The wrapper for the Xine media player links in Xine's own library and calls Xine functions directly. 
 
  
 +
==== Why LinuxMCE? ====
  
−
<img src="include/images/quickstart/swmodules.jpg" border="0">
+
LinuxMCE has been designed as a Linux distribution that orchestrates all the numerous OSS applications that that run on the home PC of the 21st century home. To the end user, LinuxMCE aims to appear to be one single application with a single user interface, hiding the multitude of software it is comprised of. <br>
 +
Unlike its predecessor Pluto which is a platform for developing "smart home modules that all work together", LinuxMCE's primary mission is to benefit from the work at Pluto and others, by ensuring 100% compatibility with them. The LinuxMCE team is trying to do something bigger than just an Asterisk distro, or a MythTV distro, etc.: we're combining many applications into an integrated whole. We're doing this the UNIX way, using a messaging protocol over sockets, so that these applications can still be developed independently and added or removed from LinuxMCE as desired by the end user.
  
−
<p>Since there are literally thousands of home automation components and pieces of a/v equipment that require controlling with RS232, USB and Ethernet we developed a special system for these devices using GSD.  It's fast and often doesn't require any real programming skills.  It can be used to support lighting control systems, climate and pool systems, external devices like i/r emitters, cameras, etc.  If that's your interest skip this whole page and [[What if you don't have a driver for my home automation devic]]  Otherwise if you're a "real" programmer interested in adding new software modules or adding wrappers for existing software, then continue with this section.</p>
+
The functionality in LinuxMCE is provided by a variety of open source projects and it's our mission '''to make them work together'''.
  
−
<p><h1>Is Pluto a stand-alone software product, or a development platform?</h1></p>
+
<center><pre>
 +
LinuxMCE is the "glue" that binds the various
 +
hardware technologies and Open Source Software
 +
into a full featured and coordinated system
 +
that uses a simple unified interface
 +
to control the modern home's entertainment, security, and automation.
 +
</pre></center>
  
−
<p>Pluto is sold commercially as a complete turnkey appliance.  To the end user it appears to be 1 single application with 1 common user interface.  From a developer's standpoint, however, Pluto is actually a platform for developing smart home modules that all work together.  Much of the top-level functionality is provided by a variety of open source projects.  Pluto adds it's own home automation engine, UI front-end, configuration web site, and the heart of it all, [[Pluto Libraries DCE]], which allows this collection of devices and software projects to work together as a seamless whole.</p>
+
{{p}}
  
−
<p>In many cases, a Pluto DCE device is just a thin wrapper for another open source project.  The wrapper's job is to launch the open source project with the right parameters, forward incoming commands to it, and fire DCE events in response to triggers within it.  We added DCE wrappers for the projects index.php?section=home&package=270"><b>Asterisk</b></a> (pbx telephone switch), <a href="index.php?section=home&package=118, Linphone (SIP software telephone) and Motion (surveillance video capture).  In most cases, no modifications to the open source project were needed since the project already contained a mechanism for feeding it commands.</p>
 
  
−
<p>The software is completely modular and we offer a wealth of development tools, like code generators, design tools, a rapid development module for adding new devices (GSD), our own messenging platform and a ton of general-purpose libraries.  Our GSD+sqlCVS is an entirely [[A new concept in collaborative development]] for quickly adding support for communicating with external equipment.  If you're a developer, you can add to Pluto, or even remove our modules and use Pluto as a platform to do something else entirely.</p>
+
==== Origins of LinuxMCE ====
 +
In 2006, LinuxMCE was forked from Pluto's linux distribution because Pluto was designed as a 'turn it on and press play' appliance, rather than a traditional software application. While LinuxMCE includes hundreds of scripts and utilities from Pluto, it is designed with as a modular system to which many other OSS projects can be integrated.
  
−
<p><h1>Pluto allows projects to work together</h1></p>
+
To learn more about Pluto's code, please consult the [http://plutohome.com/support/doxygen/ Doxygen documentation] which details all the scripts and utilities that make up the Pluto distribution.
  
−
<p>By allowing these various projects to work together seamlessly, many new features and benefits are now possible.  For example, if there's a security breach in your house, the lights and TV's in the house come on automatically using our home automation DCE device interfaces, and the security pn pad appears on all the Windows webpads and PDA's.  After 30 seconds a menacing video plays for the burglar using Xine, while the surveillance cameras monitored by Motion feed a live video to your mobile phone over GPRS.  Hit 'Talk' on the phone and Xine suspends, passing control to Linphone which makes a call using Asterisk to your mobile phone with the audio piped through the stereo so you can shout at the intruder and let him know you're watching him from a remote location and calling.  To the end-user, it works seamlessly, like 1 cohesive whole, but in reality, what Pluto did is enable a bunch of existing applications to work together.</p>
+
{{p}}
  
−
<p>[[Why should I use the Pluto platform for my project?]]</p>
+
====LinuxMCE  software architecture====
−
<p>[[Overview of the software modules]]</p>
+
LinuxMCE uses a '''modular''' architecture made of "devices" that are integrated to the system by interfacing them to the DCERouter.
 +
<!-- [Need diagram of software modules here]. -->
 +
{{P}}
  
−
<p>[[I want my software to run on Pluto but it isn't open source]]</p>
+
===== DCERouter =====
 +
The heart of LinuxMCE, the 'main application' '''DCERouter''' is nothing but a general-purpose message router. It has absolutely no code relating to any of LinuxMCE's functionality--it just relays messages between "Devices".  <br>
  
−
<p>[[Will you host, compile and support the Pluto plug-ins for my]]</p>
+
[[Image:LMCE_Architecture_mini.jpg|LinuxMCE architecture – the devices]]
 +
{{p}}
  
 +
===== Devices =====
 +
The functionality of LinuxMCE is entirely in separate programs (aka "'''Devices'''") which all run independently and communicate with each other by passing messages through DCERouter over sockets. There can be hundreds of these "Devices" in a smart home, that do all sorts of things. As shown in the diagram below, many of LinuxMCE's devices are actually "'''wrappers'''" we have written for existing open source programs to allow them to work together seamlessly in a LinuxMCE system. An example of this is the wrapper written for Asterisk: it sends event messages to the DCERouter whenever a phone call comes in, and, receives command messages when it is time to place a call. <br>
 +
How the wrapper communicates with the open source program depends on that project. In the case of Asterisk, the wrapper communicates with Asterisk over a socket. It acts as a translator, converting messages from its socket connection with the DCERouter into messages from its socket connection with Asterisk. The wrapper for the Xine media player links in Xine's own library, and calls Xine functions directly, while for MythTV, the wrapper communicates via a special telnet interface. Each project's wrapper is written to meet its needs.
 +
 +
LinuxMCE uses the GPL home automation engine and UI front-end developed by Pluto, the GPL PVR developed by the MythTV folks, the GPL phone system Asterisk originally developed by Mark Spencer at Digium, the GPL Xine program, etc, and combines them into a whole using the DCERouter. Since these OSS projects all have disparate histories and development roadmaps, the wrappers need to be kept up to date as these applications develop, and we're hoping to get some of these applications to talk directly to the DCERouter in the future
 +
 +
;Note: Some devices are not implemented as separate binaries, but as plug-ins that run as dynamic libraries in DCERouter’s memory space.
 +
{{p}}
 +
 +
===== The GSD protocol =====
 +
Since there are literally thousands of home automation components and pieces of A/V equipment that require controlling with serial port, USB, or Ethernet, LinuxMCE has been designed with GSD support to enable communication with these various technologies. GSD is a fast protocol which is simple to use, yet flexible enough to be used to support lighting control systems, climate and pool systems, cameras, or external devices such as IR blasters, and much more.
 +
{{p}}
 +
 +
==== Software builds ====
 +
The DCE message router and the controllers for the various applications are modular by nature, which means you can just modify a small module at a time, then quickly compile, and test it in the system.
 +
Initially, the build system was a little cumbersome because we inherited it from a commercial company that paid their developers and could expect them to learn a custom build system. One of the immediate development goals was to switch to a more traditional OSS build system so any developer could just jump in and start making changes using a simple "make; sudo make install" for the whole distribution, or just one program, or library within the whole. In time, this was abandoned mostly because nobody was interested in working on it, and it wasn't critical for the developers who were working on it. However, changes have been made that removed the need for a dedicated build server. The source tree can be copied and the individual pieces can be compiled using make. Currently, LinuxMCE is being developed on such a server as it is the most efficient way to produce all the packages in one go. Although this is not necessary for someone developing a C++ DCE device, you can use it if you wish to build packages for a Linux distribution. There is a set of tables in our database that are package definitions which are used in two places:
 +
::* ''MakeRelease'', which builds packages for a given operating system.
 +
::* ''ConfirmDependencies'', which installs packages for a given operating system.
 +
They both pull their software and dependencies from the same database. You can go to <code>advanced > software > packages</code> to find the list of packages, including those for the Pluto manufacturer which is the data we use to figure out what to install when and where.
 +
 +
{{p}}
 +
 +
==== So the DCE Router lets applications communicate, so what? ====
 +
 +
Imagine you set up a LinuxMCE system in your living room and want the lights to dim when you start watching a movie. If you were using a regular Linux distribution without the DCERouter, you would need to write a launch script for Xine that tells MisterHouse to dim the lights on entry and restore them on exit. If you wanted this to be delayed so that when you exit one movie and enter another shortly thereafter the lights don't dim, the script would become rather complicated. You would need to adapt the script for watching TV in MythTV and any other media application you wanted to use. <br>
 +
With Linux MCE, you just listen for the the start and stop DCE events in a small module, and send out DCE events for the light control. For this one task, you can still just write a script. But you might also want to notify yourself of a call and pause the media player based on who is calling. You can do this with Asterisk and MythTV without a DCERouter, but you need to learn about how Asterisk handles events and MythTV handled OSD notifications; and, you need to write a notifier for Xine because it doesn't have built in notifications. With LinuxMCE you only have to learn a single interface, DCE, and you simply intercept the DCE message sent from Asterisk, then send a DCE message out to the Orbiter UI, and send out a pause DCE message to all media players. This means that these '''tasks can all be handled with just some knowledge of the DCE rather than learning a bunch of protocols and APIs'''. The "Devices" handle the translation of DCE messages for all the applications involved, for the various APIs, and the remote control protocols. <br>
 +
Ordinary users that have no programming knowledge can just hook up events using a tool provided by Pluto, but the good news for programmers is that they don't need domain knowledge of all the different applications they wish to integrate. All that is needed is a basic knowledge of DCE messages, and optionally, the Orbiter overlay UI.
 +
 +
DCE does what DBUS and many other protocols were supposed to do, but in contrast, it works. With the wrappers that we inherited from Pluto for various applications, applications don't need to commit to DCE or DBUS or any other protocol for LinuxMCE to communicate with them. DCE messages work today.
 +
 +
{{p}}
 +
 +
==Programmer's Guide Sections==
 +
*[[Why should I use the LinuxMCE platform for my project?]]
 +
**[[Overview of the software modules]]
 +
**[[A new concept in collaborative development]]
 +
**[[Adding support for home automation devices]]
 +
*[[Developing a DCE Device]]
 +
*[[Building_From_Source]]
 +
*[[STEngine]]
 +
**[[OpenGL implementation]]
 +
**[[Photo Screen Saver]]
 +
*[[Z-Wave | ZWave implementation]]
 +
*[[AVWizard specifications]]
 +
*[[Orbiter]]
 +
*[[wxWidgets]]
 +
*[[Window manager]]
 +
*[[Window controller]]
 +
*[[X11 locking]]
 +
*[[X11 pointer shapes]]
 +
*[[LinuxMCE Plugins]]
 +
*[[I want my software to run on LinuxMCE but it isn't open source]]
 +
*[[GSD - Ruby codes]]
 +
** [[Apex Destiny 6100]] (alarm panel)
 +
*[[Automated_Builder]]
 +
 +
{{p}}

Latest revision as of 17:17, 25 October 2012


This guide explains the architecture of the main C++ code of LinuxMCE.

A new tutorial for Developing a DCE Device has just been added to the wiki. While we're creating our own Doxygen documentation, the most recent information regarding architecture and getting started with development can be found on the "Developers Guide" page, and, the Pluto Doxygen is still online.


Why LinuxMCE?

LinuxMCE has been designed as a Linux distribution that orchestrates all the numerous OSS applications that that run on the home PC of the 21st century home. To the end user, LinuxMCE aims to appear to be one single application with a single user interface, hiding the multitude of software it is comprised of.
Unlike its predecessor Pluto which is a platform for developing "smart home modules that all work together", LinuxMCE's primary mission is to benefit from the work at Pluto and others, by ensuring 100% compatibility with them. The LinuxMCE team is trying to do something bigger than just an Asterisk distro, or a MythTV distro, etc.: we're combining many applications into an integrated whole. We're doing this the UNIX way, using a messaging protocol over sockets, so that these applications can still be developed independently and added or removed from LinuxMCE as desired by the end user.

The functionality in LinuxMCE is provided by a variety of open source projects and it's our mission to make them work together. 

LinuxMCE is the "glue" that binds the various 
hardware technologies and Open Source Software 
into a full featured and coordinated system 
that uses a simple unified interface
to control the modern home's entertainment, security, and automation.




Origins of LinuxMCE

In 2006, LinuxMCE was forked from Pluto's linux distribution because Pluto was designed as a 'turn it on and press play' appliance, rather than a traditional software application. While LinuxMCE includes hundreds of scripts and utilities from Pluto, it is designed with as a modular system to which many other OSS projects can be integrated.

To learn more about Pluto's code, please consult the Doxygen documentation which details all the scripts and utilities that make up the Pluto distribution.



LinuxMCE software architecture

LinuxMCE uses a modular architecture made of "devices" that are integrated to the system by interfacing them to the DCERouter.

DCERouter

The heart of LinuxMCE, the 'main application' DCERouter is nothing but a general-purpose message router. It has absolutely no code relating to any of LinuxMCE's functionality--it just relays messages between "Devices".

LinuxMCE architecture – the devices

Devices

The functionality of LinuxMCE is entirely in separate programs (aka "Devices") which all run independently and communicate with each other by passing messages through DCERouter over sockets. There can be hundreds of these "Devices" in a smart home, that do all sorts of things. As shown in the diagram below, many of LinuxMCE's devices are actually "wrappers" we have written for existing open source programs to allow them to work together seamlessly in a LinuxMCE system. An example of this is the wrapper written for Asterisk: it sends event messages to the DCERouter whenever a phone call comes in, and, receives command messages when it is time to place a call.
How the wrapper communicates with the open source program depends on that project. In the case of Asterisk, the wrapper communicates with Asterisk over a socket. It acts as a translator, converting messages from its socket connection with the DCERouter into messages from its socket connection with Asterisk. The wrapper for the Xine media player links in Xine's own library, and calls Xine functions directly, while for MythTV, the wrapper communicates via a special telnet interface. Each project's wrapper is written to meet its needs.

LinuxMCE uses the GPL home automation engine and UI front-end developed by Pluto, the GPL PVR developed by the MythTV folks, the GPL phone system Asterisk originally developed by Mark Spencer at Digium, the GPL Xine program, etc, and combines them into a whole using the DCERouter. Since these OSS projects all have disparate histories and development roadmaps, the wrappers need to be kept up to date as these applications develop, and we're hoping to get some of these applications to talk directly to the DCERouter in the future

Note
Some devices are not implemented as separate binaries, but as plug-ins that run as dynamic libraries in DCERouter’s memory space.



The GSD protocol

Since there are literally thousands of home automation components and pieces of A/V equipment that require controlling with serial port, USB, or Ethernet, LinuxMCE has been designed with GSD support to enable communication with these various technologies. GSD is a fast protocol which is simple to use, yet flexible enough to be used to support lighting control systems, climate and pool systems, cameras, or external devices such as IR blasters, and much more.

Software builds

The DCE message router and the controllers for the various applications are modular by nature, which means you can just modify a small module at a time, then quickly compile, and test it in the system. Initially, the build system was a little cumbersome because we inherited it from a commercial company that paid their developers and could expect them to learn a custom build system. One of the immediate development goals was to switch to a more traditional OSS build system so any developer could just jump in and start making changes using a simple "make; sudo make install" for the whole distribution, or just one program, or library within the whole. In time, this was abandoned mostly because nobody was interested in working on it, and it wasn't critical for the developers who were working on it. However, changes have been made that removed the need for a dedicated build server. The source tree can be copied and the individual pieces can be compiled using make. Currently, LinuxMCE is being developed on such a server as it is the most efficient way to produce all the packages in one go. Although this is not necessary for someone developing a C++ DCE device, you can use it if you wish to build packages for a Linux distribution. There is a set of tables in our database that are package definitions which are used in two places:

  • MakeRelease, which builds packages for a given operating system.
  • ConfirmDependencies, which installs packages for a given operating system.

They both pull their software and dependencies from the same database. You can go to advanced > software > packages to find the list of packages, including those for the Pluto manufacturer which is the data we use to figure out what to install when and where.



So the DCE Router lets applications communicate, so what?

Imagine you set up a LinuxMCE system in your living room and want the lights to dim when you start watching a movie. If you were using a regular Linux distribution without the DCERouter, you would need to write a launch script for Xine that tells MisterHouse to dim the lights on entry and restore them on exit. If you wanted this to be delayed so that when you exit one movie and enter another shortly thereafter the lights don't dim, the script would become rather complicated. You would need to adapt the script for watching TV in MythTV and any other media application you wanted to use.
With Linux MCE, you just listen for the the start and stop DCE events in a small module, and send out DCE events for the light control. For this one task, you can still just write a script. But you might also want to notify yourself of a call and pause the media player based on who is calling. You can do this with Asterisk and MythTV without a DCERouter, but you need to learn about how Asterisk handles events and MythTV handled OSD notifications; and, you need to write a notifier for Xine because it doesn't have built in notifications. With LinuxMCE you only have to learn a single interface, DCE, and you simply intercept the DCE message sent from Asterisk, then send a DCE message out to the Orbiter UI, and send out a pause DCE message to all media players. This means that these tasks can all be handled with just some knowledge of the DCE rather than learning a bunch of protocols and APIs. The "Devices" handle the translation of DCE messages for all the applications involved, for the various APIs, and the remote control protocols.
Ordinary users that have no programming knowledge can just hook up events using a tool provided by Pluto, but the good news for programmers is that they don't need domain knowledge of all the different applications they wish to integrate. All that is needed is a basic knowledge of DCE messages, and optionally, the Orbiter overlay UI.

DCE does what DBUS and many other protocols were supposed to do, but in contrast, it works. With the wrappers that we inherited from Pluto for various applications, applications don't need to commit to DCE or DBUS or any other protocol for LinuxMCE to communicate with them. DCE messages work today.



Programmer's Guide Sections



Retrieved from "http://wiki.linuxmce.org/index.php?title=Programmer%27s_Guide&oldid=33272"