applications.h

Go to the documentation of this file.

/**
 * @file    applications.h
 * @brief   Documentation: Overview of official WOSH Applications
 ****************************************************************************
 * @author  Alessandro Polo
 * @version 0.8.527 $Id: applications.h 3774 2011-01-01 16:37:15Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2011, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/
 
/*! \page page_applications Applications
 *
 * This page describes (official) Applications that ships with WOSH.
 *
 * \par Official WOSH Applications:
 *
 *  - \ref page_applications_woshsrv
 *  - \ref page_applications_woshcesrv
 *  - \ref page_applications_woshshop
 *  - \ref page_applications_wosh3d
 *  - \ref page_applications_woshshell
 *  - \ref page_applications_woshremote
 *  - \ref page_applications_woshkiosk
 *
 * \section page_applications_toc Table of Contents:
 *
 *  - \ref page_applications_overview
 *  - \ref page_applications_philosophy
 *  - \ref page_applications_flow
 *
 *  - \ref page_applications_sample
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_applications_overview Overview
 *
 * A WOSH Application is defined as a generic software based on WOSH Framework.
 * 
 * Such applications are designed for end-users (inhabitants) and system/home administrators.
 *
 * Main goal of WOSH applications is to load, setup and boot the WOSH Kernel.
 * Usually they also expose some access/viewport to the user (graphical or console).
 * Because of that, these application are not expected to be complex and grow as the 
 * framework and its services.
 *
 * Beginners and Windows' users should give a look to \ref page_applications_woshshop "WOSH WorkShop":
 * a graphical application designed (mostly) for the administration of the whole system.
 * WoshShop is a good example of standalone vs. distributed/remote management, it can
 * control transparently the local kernel (integrated) and any reachable remote kernel both.
 * 
 * Another graphical application, started recently, is \ref page_applications_woshkiosk "WOSH KiosK".
 * KiosK is designed specifically for the inhabitant user, preferably running on a
 * touch-screen device. KiosK is the most user-friendly WOSH application.
 * \note The development of WOSH KiosK has been delayed.
 *
 * \ref page_applications_woshcesrv "WOSH CE Server" is a minimal server designed for
 * on smartphones and embedded devices, it hosts a specific bundle which exports messaging
 * and communication services to the WOSH Network (assuming device is always connected to the network).
 *
 * Last but not least, \ref page_applications_woshsrv "WOSH Server" is a console (CLI) application
 * running WoshKernel and a standard I/O console to WOSH Shell. It is designed to be
 * (one of) the main server and run 24/7.
 *
 * Latest introduced WOSH Application is \ref page_applications_wosh3d "WOSH 3D", it's a
 * graphical application based on QT and GLC library, able to render the abstract representation
 * of the house (see wosh::building).
 * \note The development of WOSH 3D is in early stage.
 *
 * Expert users and developers just love shell and ssh, \ref page_applications_woshshell "WOSH Shell"
 * is a mimimal (console) client application designed to control WOSH System (remotely).
 *
 *
 * Applications' source code is located in <a href="../../src/apps">/src/apps</a>
 * folder [<a href="../../src/apps/README">README</a>].
 *
 * Binaries are always built in <a href="../../bin">/bin</a> directory (eventually sub-folders).
 *
 * \note
 *  Because of WOSH framework itself is under development, application are not linked
 *  against the WOSH Library, but the whole WOSH Framework and bundles are directly
 *  included in final executable (static linking).
 *
 * Once a stable release of WOSH is available, applications will statically or dynamically link
 * against the WOSH Framework library and bundles will be loaded from shared or dynamic libraries.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_applications_philosophy Design (philosophy)
 *
 * Consider a WOSH server (such as \ref page_applications_woshsrv "woshsrv"),
 * it makes sense to have the WOSH Kernel on it because it hosts services (bundles).
 *
 * Generally speaking, frameworks and middleware are useful because of abstraction, 
 * rapid development and well-defined interfaces/features.
 * So, why a graphical application like a remote controller or an embedded system
 * should implement custom accessing layers? In fact, having them based on the
 * same micro-kernel will speed up and simplify development and maintenance both.
 *
 * In other words: a WOSH application ships with a WOSH Kernel and acts as one
 * host of the WOSH network. The 'main' WOSH server running on the Residential gateway
 * (home server) and the \ref page_applications_woshremote "WOSH Remote" software
 * (running on the laptop) are two idempotent hosts of the WOSH network by many (most)
 * points of view.
 *
 * All WOSH applications are clients and servers at same time.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_applications_flow Flow
 *
 * As said in previous sections, WOSH Applications share the underlying layer
 * (micro-kernel) and the (optional) configuration profile, because of that
 * the application flow follows the same structure.
 *
 * \msc
Application,Settings,WoshKernel, QT;

Application=>QT [label="Initialize QT Framework"];
Application=>Settings [label="Initialize defaults and load settings"];
|||;
Application=>WoshKernel [label="Initialize Kernel", URL="\ref wosh::WoshKernel::init()"];
Application=>WoshKernel [label="Start Kernel", URL="\ref wosh::WoshKernel::start()"];
|||;
--- [ label=" More threads are launched "];
Application=>WoshKernel [label="Initialize explicit Bundles"];
|||;
Application=>Application [label="Setup optional user Session"];
|||;
Application=>WoshKernel [label="Acquire main thread"];
|||;
Application=>WoshKernel [label="Shutdown Kernel", URL="\ref wosh::WoshKernel::shutdown()"];
 * \endmsc
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_applications_sample Sample Log files
 *
 * A sample log file of \ref page_applications_woshsrv "woshsrv"
 * (<a href="../../var/log/sample.woshsrv.log">/var/log/sample.woshsrv.log</a>)
 *
 * A sample log file of \ref page_applications_woshshop "woshshop"
 * (<a href="../../var/log/sample.woshshop.log">/var/log/sample.woshshop.log</a>)
 *
 *
 ****************************************************************************
 *
 */