Using WOSH

This page explains how to use WOSH in the real world.

Table of Contents:

See also Configuration and Running

Todo:
[..]
Warning:
This page is out-of-date and still transitional from WOSH 0.6.030 [ byron ] to WOSH 0.8.499 [ icarus ].

Overview

WOSH is actually used 24/7 by its creator, Alessandro Polo, in order to automate his home. Usually following services and devices are running on the home gateway (server):

Moreover WOSH WorkShop and/or WOSH Remote runs on my lap/workstation.

One more WOSH Server runs on my other Linux box and a WOSH CE Server lives on my Samsung smartphone which is USB connected with the Linux box.

Soon, WOSH KiosK will run on a new ATX board mouted in-wall.


(My) Equipment

The Residential gateway is an x86 (server) PC, running Debian Lenny, online 24/7.

There are also some devices in the rack:

Server and almost all devices are on two different safe power line (during blackout, I'm still able to walk around home watching online-streaming-movie on my netbook).

Server acts also as Firewall (using Shorewall) having the three network (lan, wlan, internet) on different hardware interfaces, with custom policies.

Server hosts some software related to home-automation and required by some WOSH components:

I installed a lot of Marmitek X10 devices, most rooms are equipped with motion and light sensors and their lights/appliance may be controlled locally and remotely:

Garden and irrigation is automated as well, [..]


WOSH Shell and Sessions

There are many ways to interact with WOSH system directly, even if the user will often act through a specific high-level interface (such as KiosK or other applications).

Sessions

wosh::communication::SessionProtocolDefault

When running WOSH Server a stdin/stdout shell is activated by default, it is very similar to POSIX shell and it allows the user to browse the system, execute commands and read results. Since logs are prompted on stderr by default, it may be flodded even while you typing (but they won't interfere each other). This specific wosh::Session is implemented by wosh::communication::SessionShell.

GUI software as WOSH WorkShop supports multiple independent consoles (just like GUI desktops of common operative systems). -----------IMAGE

Finally, user may interact with WOSH remotely, through any CommunicationService. My favorite communicator is wosh::bundles::JabberGlooxBundle, it act as a bot for jabber network (such as GTalk) and once configured it will appear just an human friend in the contact list. I may send messages to any WOSH users (see Communication), but even interact just as the Shell described before. wosh::bundles::CommunicationManagerBundle is required in order to initialize and route messages to wosh::communication::SessionIM handler. -----------IMAGE

. is a low-level service which lets users access to the system (run Methods, get and set Properties).

It really looks like a POSIX terminal and basic commands are very similar too.

Since WOSH is still in development state, I usually run it in a remote shell and start a local shell from/to standard input/output (just like a Linux terminal or Windows' prompt).

Input is parsed by wosh::session::SessionProtocolShell, which will also render the response and interacts with a wosh::session::Session implementation.

Session Server is a very important component because it manages also IM (Instant Messaging) sessions. When users want to interact 'directly' with WOSH, then Session Server is the proxy. (such a direct shell command from an SMS or a GMail/GTalk message).

A sample flow is:

Here is prompted I/O of some basic commands (/var/log/sample.Shell.log):

root@wosh28# help

WOSH Shell Protocol - Commands:
     help :      print this screen
     session :   print session info
     whoami :    print username
     su :    switch user
     echo :      reply input
     proto :     change session protocol
     notify :    notify a message to user(s)
     pwd :   print current path
     ck :    change kernel
     cd :    change destination (location)
     cb :    change bus (target)
     home :      change to home URI
     scd :   (smart) change destination (name)
     which :     find method
     exit :      close session


root@wosh28# pwd
  wosh28

root@wosh28# whoami
  root

root@wosh28# home
root@wosh28:Users/root# pwd
  wosh28:Users/root

root@wosh28:Users/root# echo This is replied by Shell :)
This is replied by Shell :)

root@wosh28:Users/root# session

Session Information:
    ID :        1816683231
    User :      root
    Path :      wosh28:Users/root


root@wosh28:Users/root# su alex
alex@wosh28:Users/root# whoami
  alex [root]

alex@wosh28:Users/root# home
alex@wosh28:Users/root# pwd
  wosh28:Users/alex

alex@wosh28:Users/alex# cd ..
alex@wosh28:Users# list
  Users:
   ID      Name           Groups Location
-----------------------------------------
    1      root     root;virtual         
   10      wosh     root;virtual         
   50    nobody   nobody;virtual         
   52 anonymous   nobody;virtual         
 1020      alex root;inhabitants         
   66    Butler     root;virtual         


alex@wosh28:Users# cd ..
alex@wosh28# props
  Properties:
          Name                            Value          Permission
-------------------------------------------------------------------
     BuiltDate           Dec 19 2009 : 05:32:32 r--r--r-- root root
 BuiltPlatform                          WINDOWS r--r--r-- root root
      BuiltRev                           $Rev $ r--r--r-- root root
    DebugLevel                          VERBOSE rw-rw-r-- root root
       LogFile          ../var/log/woshshop.log r--r--r-- root root
         State                          RUNNING         r--r--r--  
        entity 082395869bfd4ab55c19789de434c0e7 r--r--r-- root root
         group                             root r--r--r-- root root
    interfaces                 wosh::WoshKernel r--r--r-- root root
          name                           wosh28 r--r--r-- root root
         owner                             root r--r--r-- root root
        parent                                  r--r--r-- root root
        rights                              755 r--r--r-- root root
          type                 wosh::WoshKernel r--r--r-- root root
       version                            0.501 r--r--r-- root root


alex@wosh28# cd Bundles
alex@wosh28:Bundles# list
  Bundles:
            Name Interfaces   State                            URI
------------------------------------------------------------------
       Discovery          X STARTED       wosh28:Bundles/Discovery
   PlayerStation          X STARTED   wosh28:Bundles/PlayerStation
  SystemServices          X STARTED  wosh28:Bundles/SystemServices
   MediaDirector          X STARTED   wosh28:Bundles/MediaDirector
       Organizer          X STARTED       wosh28:Bundles/Organizer
          Butler          X STARTED          wosh28:Bundles/Butler
    light_office          X STARTED    wosh28:Bundles/light_office
   SessionServer          X STARTED                wosh28:Sessions
 DesktopNotifier          X STARTED wosh28:Bundles/DesktopNotifier


alex@wosh28:Bundles# cd Discovery
alex@wosh28:Bundles/Discovery# props
  Properties:
                 Name                                                 Value          Permission
-----------------------------------------------------------------------------------------------
      BindAddressPort                                          0.0.0.0:8787 rw-rw-r-- root root
 BroadcastAddressPort                 192.168.0.255:8787;169.254.2.255:8787 rw-rw-r-- root root
     BundleInterfaces wosh::Bundle;wosh::Service;wosh::services::Discovery; r--r--r-- root root
          BundleState                                               STARTED r--r--r-- root root
           DebugLevel                                                  INFO rw-r--r-- root root
      NotifyFrequency                                                    60 rw-rw-r-- root root
               entity                      da8eb078234b828ab541d5ea6c997913 r--r--r-- root root
                group                                                  root rw-r--r-- root root
           interfaces wosh::Bundle;wosh::Service;wosh::services::Discovery; r--r--r-- root root
                 name                                             Discovery r--r--r-- root root
                owner                                                  root rw-r--r-- root root
               rights                                                   755 rw-r--r-- root root
                 type                             wosh::services::Discovery r--r--r-- root root
              version                                                  1.01 r--r--r-- root root

There are also some advanced features (like regex Destination with expressions) which are inherited by the WOSH Framework functionalities, you may give a look to /var/log/sample.Shell.advanced.log


Multimedia

Note:
Video is under planning, WOSH actually supports Audio Multimedia.

Thanks to the MPD server and some ALSA hacking, you may turn a linux box equipped with a built-in surround audio card into a multi-zone music player

Thanks to the great feature of MPD server and some ALSA hacking, you may turn any linux box (with at least one built-in surround audio card) into a multi-zone music player. See Multimedia for more information. wosh::bundles::PlayerMPDBundle supports audio-output selection, while other players (such as wosh::bundles::PlayerGStreamerBundle) don't. In short, we have one global audio player (one for all outputs), but we can enable/disable each outputs at runtime.

This is a limitation when we want multiple different streams around, but usually we will play the same stream and we are more interested about how to switch zones (belive me). Fortunatly WOSH players can run at same time, so it is possible to multiplex/share outputs against more different players.

Almost all rooms have been equipped with an audio box, because of architecture and rack position it was simpler to place (in-wall) wires and have amplifiers in the rack. Each channel (box) is hardware-independent: from the input (audio) line (by the audio-box point of view) through the amplifier and finally the audio box.

My server-hardware comes with a built-in Intel Audio card (Dolby surround), I'm using ALSA and hacking its configuration I was able to have SIX (good) independent channel as (virtual) devices.

So, I can play a different song in each room, or same song with different volumes and so on.

WOSH server runs an instance of wosh::bundles::PlayerGStreamerBundle for each channel (virtual device) and some more mixed channels (both bathrooms, kitchen and living room together, the whole house).

Moreover the workstation (and laptop) runs WOSH Remote or WOSH WorkShop and they support a custom (Qt-phonon based) wosh::interfaces::entertainment::PlayerAudio implementation: wosh::bundles::PlayerPhononBundle

Here is prompted I/O of some basic commands of PlayerAudio devices (using PlayerGStreamer) (/var/log/sample.Multimedia.Audio.log):

root@wosh1# cd Bundles
root@wosh1:Bundles# cd PlayerCucina
root@wosh1:Bundles/PlayerCucina# props
  Properties:
             Name                                                                                Value          Permission
--------------------------------------------------------------------------------------------------------------------------
 BundleInterfaces wosh::Bundle;wosh::Device;wosh::devices::PlayerAudio;wosh::devices::PlayerGStreamer; r--r--r-- root root
      BundleState                                                                              STARTED r--r--r-- root root
      CurrentFile                                                                                      r--r--r-- root root
       DebugLevel                                                                                 INFO rw-r--r-- root root
     DeviceOutput                                                                             d_rear_l rw-rw-rw- root root
     DeviceStatus                                                                               LINKED r--r--r-- root root
         GS_Built                                                                            [unknown] r--r--r-- root root
       GS_Version                                                                              0.10.19 r--r--r-- root root
           Length                                                                                      r--r--r-- root root
             Mute                                                                                    0 r--r--r-- root root
      PlayerState                                                                                 Idle r--r--r-- root root
         Position                                                                                      r--r--r-- root root
       RepeatItem                                                                                    0 rw-rw-rw- root root
   RepeatPlayList                                                                                    0 rw-rw-rw- root root
           Volume                                                                                    1 rw-rw-rw- root root
           entity                                                     ad6302f4b6263b464a5609f1176e98e0 r--r--r-- root root
            group                                                                                 root rw-r--r-- root root
       interfaces                                                                         wosh::Bundle r--r--r-- root root
             name                                                                         PlayerCucina r--r--r-- root root
            owner                                                                                 root rw-r--r-- root root
           rights                                                                                  755 rw-r--r-- root root
             type                                                       wosh::devices::PlayerGStreamer r--r--r-- root root
          version                                                                              0.10.19 r--r--r-- root root


root@wosh1:Bundles/PlayerCucina# enqueue $MUSIC/IT/Zucchero/Zucchero(Nco)
  Response of 'enqueue' : OK, {Data::INT}
 18

root@wosh1:Bundles/PlayerCucina# list
  PlayList:
 Index                                                                                                                     Info
--------------------------------------------------------------------------------------------------------------------------------
     0                                      file:///archive/music/IT/Zucchero/Zucchero(Nco)/01 - dune mosse ( Miles Davis ).mp3 
     1                                          file:///archive/music/IT/Zucchero/Zucchero(Nco)/02 - muoio per te ( Sting ).mp3 
     2 file:///archive/music/IT/Zucchero/Zucchero(Nco)/03 - indaco dagli occhi del cielo ( Vanessa Carlton & Haylie Ecker ).mp3 
     3                                file:///archive/music/IT/Zucchero/Zucchero(Nco)/04 - il grande baboomba ( Mousse T. ).mp3 
     4                          file:///archive/music/IT/Zucchero/Zucchero(Nco)/05 - like the sun ( Mary Grey & Jeff Beck ).mp3 
     5                                          file:///archive/music/IT/Zucchero/Zucchero(Nco)/06 - baila morena ( Maná ).mp3 
     6                                   file:///archive/music/IT/Zucchero/Zucchero(Nco)/07 - ali d'oro ( John Lee Hooker ).mp3 
     7                                            file:///archive/music/IT/Zucchero/Zucchero(Nco)/08 - blue ( Sheryl Crow ).mp3 
     8                                 file:///archive/music/IT/Zucchero/Zucchero(Nco)/09 - pure love ( Dolores O'Riordan ).mp3 
     9                              file:///archive/music/IT/Zucchero/Zucchero(Nco)/10 - a wonderful world ( Eric Clapton ).mp3 
    10                                             file:///archive/music/IT/Zucchero/Zucchero(Nco)/11 - pippo ( Tom Jones ).mp3 
    11                                          file:///archive/music/IT/Zucchero/Zucchero(Nco)/12 - Hey man ( B. B. King ).mp3 
    12                                         file:///archive/music/IT/Zucchero/Zucchero(Nco)/13 - il volo (Ronan Keating).mp3 
    13                                    file:///archive/music/IT/Zucchero/Zucchero(Nco)/14 - così celeste (  Cheb Mami ).mp3 
    14                                 file:///archive/music/IT/Zucchero/Zucchero(Nco)/15 - diavolo in me ( Solomon Burke ).mp3 
    15                                  file:///archive/music/IT/Zucchero/Zucchero(Nco)/16 - senza una donna ( Paul Young ).mp3 
    16                                       file:///archive/music/IT/Zucchero/Zucchero(Nco)/17 -  il mare... ( Brian May ).mp3 
    17                 file:///archive/music/IT/Zucchero/Zucchero(Nco)/18 - miserere ( Luciano Pavarotti & Andrea Bocelli ).mp3 


root@wosh1:Bundles/PlayerCucina# volume 2
  Method: volume returned OK [No data]

root@wosh1:Bundles/PlayerCucina# play#8
  Method: play#8 returned ERROR#1
  Data: STR(Method not found!)

root@wosh1:Bundles/PlayerCucina# play# 8
  Response of 'play#' : OK, {Data::INT}
 8

root@wosh1:Bundles/PlayerCucina# props
  Properties:
             Name                                                                                    Value          Permission
------------------------------------------------------------------------------------------------------------------------------
 BundleInterfaces     wosh::Bundle;wosh::Device;wosh::devices::PlayerAudio;wosh::devices::PlayerGStreamer; r--r--r-- root root
      BundleState                                                                                  STARTED r--r--r-- root root
      CurrentFile file:///archive/music/IT/Zucchero/Zucchero(Nco)/09 - pure love ( Dolores O'Riordan ).mp3 r--r--r-- root root
       DebugLevel                                                                                     INFO rw-r--r-- root root
     DeviceOutput                                                                                 d_rear_l rw-rw-rw- root root
     DeviceStatus                                                                                   LINKED r--r--r-- root root
         GS_Built                                                                                [unknown] r--r--r-- root root
       GS_Version                                                                                  0.10.19 r--r--r-- root root
           Length                                                                        0:03:28.039156250 r--r--r-- root root
             Mute                                                                                        0 r--r--r-- root root
      PlayerState                                                                                  Playing r--r--r-- root root
         Position                                                                        0:00:03.560062500 r--r--r-- root root
       RepeatItem                                                                                        0 rw-rw-rw- root root
   RepeatPlayList                                                                                        0 rw-rw-rw- root root
           Volume                                                                                        2 rw-rw-rw- root root
           entity                                                         ad6302f4b6263b464a5609f1176e98e0 r--r--r-- root root
            group                                                                                     root rw-r--r-- root root
       interfaces                                                                             wosh::Bundle r--r--r-- root root
             name                                                                             PlayerCucina r--r--r-- root root
            owner                                                                                     root rw-r--r-- root root
           rights                                                                                      755 rw-r--r-- root root
             type                                                           wosh::devices::PlayerGStreamer r--r--r-- root root
          version                                                                                  0.10.19 r--r--r-- root root


root@wosh1:Bundles/PlayerCucina# next
  Method: next returned OK [No data]

root@wosh1:Bundles/PlayerCucina# props
  Properties:
             Name                                                                                       Value          Permission
---------------------------------------------------------------------------------------------------------------------------------
 BundleInterfaces        wosh::Bundle;wosh::Device;wosh::devices::PlayerAudio;wosh::devices::PlayerGStreamer; r--r--r-- root root
      BundleState                                                                                     STARTED r--r--r-- root root
      CurrentFile file:///archive/music/IT/Zucchero/Zucchero(Nco)/10 - a wonderful world ( Eric Clapton ).mp3 r--r--r-- root root
       DebugLevel                                                                                        INFO rw-r--r-- root root
     DeviceOutput                                                                                    d_rear_l rw-rw-rw- root root
     DeviceStatus                                                                                      LINKED r--r--r-- root root
         GS_Built                                                                                   [unknown] r--r--r-- root root
       GS_Version                                                                                     0.10.19 r--r--r-- root root
           Length                                                                           0:04:35.408968750 r--r--r-- root root
             Mute                                                                                           0 r--r--r-- root root
      PlayerState                                                                                     Playing r--r--r-- root root
         Position                                                                           0:00:02.274562500 r--r--r-- root root
       RepeatItem                                                                                           0 rw-rw-rw- root root
   RepeatPlayList                                                                                           0 rw-rw-rw- root root
           Volume                                                                                           2 rw-rw-rw- root root
           entity                                                            ad6302f4b6263b464a5609f1176e98e0 r--r--r-- root root
            group                                                                                        root rw-r--r-- root root
       interfaces                                                                                wosh::Bundle r--r--r-- root root
             name                                                                                PlayerCucina r--r--r-- root root
            owner                                                                                        root rw-r--r-- root root
           rights                                                                                         755 rw-r--r-- root root
             type                                                              wosh::devices::PlayerGStreamer r--r--r-- root root
          version                                                                                     0.10.19 r--r--r-- root root


root@wosh1:Bundles/PlayerCucina# stop
  Method: stop returned OK [No data]

A management service in the Multimedia context is wosh::bundles::MediaDirectorBundle, which takes care of the whole house-multimedia and is aware of the distributed status, relations within multimedia renderers.

One (or more) multimedia device (such as audio box) is linked to a MediaZone which is mapped to its location (such as home/ground_floor/living_room), it also holds many other settings. Media Director manages MediaZone(s), their setup, update and invocation.

The other (optional) key feature of Media Director is to keep track of playing media for each MediaZone (and user), SQL support and MySQL server are required. The database will be updated on each playback, so Media Director is able to restore last scenario or guess one.

Media Director simplifies the 'multimedia mobility' and supports smart shortcuts about entertainment.

Warning:
Specifications and Implementation of Media Director is under planning/development.

Communication

Communication and remote control is a must within Smart home (automation).

Warning:
The current architecture and specification are not finalized yet. (but nearly to be)

As you may have read in Specifications, WOSH is a message-based system, so the request => response pattern is deeply integrated into implementation. By humans' point of view we still act as another actor in the scene: making requests and parsing responses, as usual the process is (full) asynchronous.

There are usually many communication channels, each one has different (technologic) features and each (target) user may prefer a custom communicator anytime.

Let's consider following use-cases:

So, there are some fundamental points:

The centralized service is wosh::bundles::CommunicationManagerBundle and it is a smart router of messages, this type of messages is based on wosh::Notification.

There are many services which works as adapters/bridges, implementing the interface wosh::interfaces::communication::CommunicatorService:

By user's point of view it's still a configuration task. You just need to configure the services.

Shell protocol provides an useful command for sending a notification: "notify <USER> <MESSAGE>"


Devices

An home automation system without Devices is quite useless, WOSH framework defines an abstraction layer (using interfaces) to standardize the features of each (real) device.

wosh::bundles::ModemDslBundle is a device-bundle which provides real-time stats, online status of the xDSL connection and notifies disconnection. It is supported on POSIX system only and it is based on pppstatus program (part of PPPoE driver)

wosh::bundles::PlayerGStreamer is another device-bundle, implementing the PlayerAudio interface.

My house is (mostly) X10 embedded, I installed many sensors and switches. As you may know X10 is an old protocol which communicate over the power-line without any extra (custom) cable. The X10 controller is connected (RS232/USB) to the Residential gateway which runs Heyu and WOSH Server. Heyu is an open source software which manages the X10 protocol and has been chosen as lower layer of WOSH adapter (wosh::bundles::HeyuBundle)

Here is prompted I/O of some basic commands of X10 devices (using HeyuBundle) (/var/log/sample.Devices.X10.log):

root@wosh1# cd Devices
root@wosh1:Devices# cd light_office_desktop
root@wosh1:Devices/light_office_desktop# on
root@wosh1:Devices/light_office_desktop# off
root@wosh1:Devices/light_office_desktop# bright 4

Devices usually raise events (wosh::Fact) to inform the whole (distributed) system, these messages are broadcasted on bus wosh.Bus.Device (they don't want to flood the core bus)


Building and Appliances

But devices are still 'low-level', very hardware and software dependent and they are a lot.

An higher level approach is often required for automations and cooperation of services. The whole house is represented with wosh::BuildingObject implementations' as Floor(s), Room(s), Appliance(s), ..

Here is prompted I/O of some basic commands of building objects (using BuildingManagerBundle) (/var/log/sample.Building.log):

root@wosh1# cd Building
root@wosh1:Building# list

  Building Objects:
                   Name                      Type        Parent                     Perms
-----------------------------------------------------------------------------------------
                   home     wosh::building::House               rwxr-xr-- alex inhabitans
           garage_floor     wosh::building::Floor          home rwxr-xr-- alex inhabitans
            under_floor     wosh::building::Floor          home rwxr-xr-- alex inhabitans
           ground_floor     wosh::building::Floor          home rwxr-xr-- alex inhabitans
           second_floor     wosh::building::Floor          home rwxr-xr-- alex inhabitans
                 garden    wosh::building::Garden          home rwxr-xr-- alex inhabitans
            luci_garden wosh::building::Appliance        garden rwxr-xr-- alex inhabitans
               cancello      wosh::building::Door        garden rwxr-xr-- alex inhabitans
                 garage      wosh::building::Room  garage_floor rwxr-xr-- alex inhabitans

 [.. RIPPED ..]
 
 audiobox_bathroom_nord  wosh::building::AudioBox bathroom_nord rwxr-xr-- alex inhabitans
       door_bell_living  wosh::building::DoorBell   living_room rwxr-xr-- alex inhabitans
                 office      wosh::building::Room  second_floor rwxr-xr-- alex inhabitans
               soffitta      wosh::building::Room  second_floor rwxr-xr-- alex inhabitans
              stairs_up      wosh::building::Room  second_floor rwxr-xr-- alex inhabitans
            luce_office wosh::building::Appliance        office rwxr-xr-- alex inhabitans
         luce_scrivania wosh::building::Appliance        office rwxr-xr-- alex inhabitans
         luce_stairs_up wosh::building::Appliance     stairs_up rwxr-xr-- alex inhabitans

root@wosh1:Building# cd office
root@wosh1:Building/office# props

Properties:
           Name                           Value                Permission
-------------------------------------------------------------------------
     DebugLevel                            INFO rw-r--r-- alex inhabitans
       Geometry (0,0);(325,0);(325,430);(0,430) rwxr-xr-- alex inhabitans
         Height                             260 rwxr-xr-- alex inhabitans
       Position                         (710,0) rwxr-xr-- alex inhabitans
   PresenceSeen                         UNKNOWN rw-r--r-- alex inhabitans
 PresenceSeenTs                      1257596519 rw-r--r-- alex inhabitans
          State                                 r--r--r-- alex inhabitans
        StateTs                               0 r--r--r-- alex inhabitans
          group                      inhabitans rw-rw-r-- alex inhabitans
           name                          office r--r--r-- alex inhabitans
          owner                            alex rw-rw-r-- alex inhabitans
         parent                    second_floor rwxr-xr-- alex inhabitans
         rights                             755 rw-rw-r-- alex inhabitans
           type            wosh::building::Room r--r--r-- alex inhabitans

root@wosh1:Building/office# cd ..
root@wosh1:Building/*[parent=second_floor]# 
root@wosh1:Building/*[parent=second_floor]# lights_off
  wosh1:Building/office :: Method: lights_off returned OK [No data]
  wosh1:Building/soffitta :: Method: lights_off returned OK [No data]
  wosh1:Building/stairs_up :: Method: lights_off returned OK [No data]

Automations

Looks like 'automations' are a must in a smart home environment, with this term we refer to generic wosh::automations::Automation which monitors busses (messages) and wait for valid triggers, there are also some integrated extensions, such as wosh::automations::CronJob (a generic task/action executed at certain time/period).

wosh::bundles::TaskManagerBundle takes care of loading and scheduling them.

Check out Use cases:


Networking

Note:
Networking is not required or necessary, you may test or use on a single host.

Networking is an huge task, especially for network distributed systems.

WOSH Framework tries to be as transparent (but scalable) as possible, for technical information or issues you should read Network and page_framework_network pages.

This section is a little how-to for users and developers which don't care about WOSH networking.

You will be happy to hear that when everything goes right, WOSH Networking is incredibly easy. Basically you will need to configure the system once and nothing more.

But there are at least some requirements such as:

After that, let's see how to run/configure WOSH networking, first step is Discovery.

WOSH hosts must be able to see each other in other to communicate. This job is performed by wosh::bundles::DiscoveryBundle service using UDP protocol.

You just need to configure the broadcast address for your network and sometimes the binding address (Discovery service is able to listed on all network interfaces). A sample configuration file of Discovery service is available 001_Discovery.conf

In the sample, host listens on all available network interfaces and send the Discovery packet to 192.168.0.255 at port 8787 and to 169.254.2.255 at port 8787.

Just few points about that for newbie:

Once two hosts are aware of each other presence, a connection may be established. This document doesn't really care about how this is done, but how get it working. The most important configuration keys are defined in the NetworkManager group of /etc/wosh/wosh.conf file:

AutoLoadProtocols=wosh::network::NetworkProtocolTcp
ListenChannels=TCP://192.168.0.28:9595

You will need to configure the ListenChannels key for your network. This is the binding address-port of the TCP socket. Just set it to the IP of current host.

If the network and the configuration are correct, (and keeping default settings) WOSH will auto-connect to new hosts and channel will be automatically managed by the Network Manager module.

Note:
You may see some warning messages in the Log files, but the system is actually working nice.

As you may have seen in the sample log file, there are some very important properties stored in wosh::WoshHost object (response of props command):

  wosh28:Network/Hosts/wosh28 :: Properties:
                 Name                                                Value
--------------------------------------------------------------------------
                 name                                                wosh1
                 type                                       wosh::WoshHost
                 Seen                                  2009-12-19 06:19:55
       DiscoverSource                                     192.168.0.1:8787
 DiscoveryBindAddress                                         0.0.0.0:8787
      NotifyFrequency                                                   60
      ProtocolVersion                                                    0
          KernelState                                                    1
           KernelType                                                    0
        ProtocolCount                                                    1
      ConnectionCount                                                    2
            Protocols                              TCP://192.168.0.1:9595;
          Connections TCP://192.168.0.1{1042291111};TCP://192.168.0.28{0};

Here is prompted I/O of some basic commands of wosh::NetworkManager core-service (/var/log/sample.Network.shell.log):

root@wosh28# cd Network
root@wosh28:Network# props
  Properties:
              Name                            Value          Permission
-----------------------------------------------------------------------
       AutoConnect                              Yes r-xr-xr-- root root
 AutoLoadProtocols               NetworkProtocolTCP rw-r--r-- root root
  ConnectionsCount                                2 r--r--r-- root root
         HostCount                                2         r--r--r--  
    ListenChannels          TCP://192.168.0.28:9595 rw-r--r-- root root
     ProtocolCount                                1 r--r--r-- root root
        SaveOnExit                             true rw-r--r-- root root
             State                                1 r--r--r-- root root
            entity 7859e6ccf8bdd893e1819cd54f0cce2a r--r--r-- root root
              name                   NetworkManager r--r--r-- root root
              type             wosh::NetworkManager r--r--r-- root root
           version                                0 r--r--r-- root root


root@wosh28:Network# cd Hosts
root@wosh28:Network/Hosts# list
  wosh28:Network :: Hosts:
   Name           Source  BindAddress Connected            LastSeen
-------------------------------------------------------------------
  wosh1 192.168.0.1:8787 0.0.0.0:8787       Yes 2009-12-19 06:00:55
 wosh28     0.0.0.0:8787 0.0.0.0:8787       Yes 2009-12-19 05:36:54


root@wosh28:Network/Hosts# cd ..
root@wosh28:Network# cd Protocols
root@wosh28:Network/Protocols# list
  wosh28:Network :: Protocols:
               Name                              Type ProtocolPrefix
--------------------------------------------------------------------
 NetworkProtocolTCP wosh::network::NetworkProtocolTcp         TCP://


root@wosh28:Network/Protocols# cd ..
root@wosh28:Network# cd Connections
root@wosh28:Network/Connections# list
  wosh28:Network :: Connections:
                   Name Type RemoteWoshName Connected          Protocol
-----------------------------------------------------------------------
 wosh::ChannelTcpSocket          wosh1       Yes TCP://192.168.0.1
 wosh::ChannelTcpSocket          wosh1       Yes TCP://192.168.0.1


root@wosh28:Network/Connections# cd ..
root@wosh28:Network# cd Hosts
root@wosh28:Network/Hosts# cd wosh1
root@wosh28:Network/Hosts/wosh1# props
  wosh28:Network/Hosts/wosh28 :: Properties:
                 Name                                                Value
--------------------------------------------------------------------------
                 name                                                wosh1
                 type                                       wosh::WoshHost
                 Seen                                  2009-12-19 06:19:55
       DiscoverSource                                     192.168.0.1:8787
 DiscoveryBindAddress                                         0.0.0.0:8787
      NotifyFrequency                                                   60
      ProtocolVersion                                                    0
          KernelState                                                    1
           KernelType                                                    0
        ProtocolCount                                                    1
      ConnectionCount                                                    2
            Protocols                              TCP://192.168.0.1:9595;
          Connections TCP://192.168.0.1{1042291111};TCP://192.168.0.28{0};

Generated on Sat Feb 26 2011 11:28:30 for WOSH system 0.8.888 [phoenix] by Alessandro Polo, using DoxyGen 1.7.2 hosted by WOSH Framework