Running the Virtual Wiring System

Once you have installed the Virtual Wiring System, it's time to run it.

• Open a command window and go into the top level directory of your Virtual Wiring installation (the "vw_application_xxxxxxxx" directory). Enter the ls command. You should see a few file names and one file called "run_vw_application.rb"

• Type:

  ./run_vw_application.rb

  A bunch of status messages will scroll by (depending on the speed of your host, this may take a second or two or a few tens of seconds). Wait until the messages stop. The last message should be something like:

  status: "Program is up and running"

• Open a browser on your host or on an internet connected host. Navigate to the host computer's IP address, port 4567. If you are running the browser on your host, the web address will be "http://localhost:4567". If you are on another computer connected by the internet, you will need to know the name or IP address of your host computer. If the host computer has the internet name "my_host", enter "http://my_host:4567" into your browser. If you only know the host's IP address (say 192.168.0.9), the web address will be "http://192.168.0.9:4567".

  You should see the Device Explorer page.

  Device Explorer Page

Your system is up and running. Try running a first Recipe.

Trouble Shooting

• Port conflicts. If you cannot start up your Virtual Wiring application because the 4567 port is already in use, you need to assign a different port to the application. The "run_vw_application.rb" command takes an optional port parameter. To run on a different port, say port 5678, type:

  ./run_vw_application.rb -p 5678

  Your Virtual Wiring application will now be running on host port 5678.

More about the run_vw_application Command

As we've seen, the run_vw_application starts the the Virtual Wiring program. The bare command has a bunch of default options, and these are fine for most users. You can, however, change the default options. To see all the options, type:

./run_vw_application.rb -h

You should see a screen like this:

Usage:
  run_vw_application.rb {-p <port>} {-s <Script>} {-S <Script dirs>}.
  Use -h for help

Options:
  -p, [--port=port number]                       # IP port number where the Virtual Wiring application will run
                                                 # Default: 4567
  -S, [--script-directories=Script directories]  # colon separated string of
                                                 # directories where additional Scripts are located
  -s, [--startup-script=startup script]          # Script file to run when starting up
                                                 # Default: Scripts/user/startup.script

Description:
  This command starts up the Virtual Wiring application. The command runs with
  default values when run without any parameters. Using parameters, one can
  change the default behavior. The parameters are as follows.

  Web server port or -p parameter. Sets the IP port number of the server.
  The default port number is 4567. To use port 5678 instead, add after your
  command:

  -p 5678

  Script directories parameter or -S. Adds additional directories of Scripts.
  The Script directories parameter is a colon separated list of directories. 
  Initially, there is just one Script directory, "Scripts". To include
  additional Script directories called "my_scripts" and "../new_scripts",
  add after your command:

  -S "my_scripts:../new_scripts"

  Start up Script parameter or -s. Identifies the Script the system should
  run when it is starting up. The default start up script is
  "Scripts/user/startup.script". To start from a Script called
  "Scripts/user/my_startup.script" add after your command:

  -s "Scripts/user/my_startup.script"

  All Script file and directory locations are relative to the
  "virtualizer" subdirectory.

  ***End***

Hopefully, the help message makes the options pretty clear. We'll go into more detail for the -S and -s options.

-S Option

The -S option allows adding more Script directories to your system. The default Scripts directory, "Scripts" is a directory in your VirtualWiring "virtualizer" directory. Notice that all Script directories are relative to your "virtualizer" directory.

You might want to add another Scripts directory, if you decide to create your own Scripts in your own directory outside of the "Scripts" directory. This would make sense if you were using different releases of the Virtual Wiring software or were updating your system frequently. Having a separate directory apart from your Virtual Wiring system would make sharing it between one release and another easier. You also might want to keep your Scripts separately for backup purposes.

Note: if you are familiar with the *nix command line, another way to keep a Script directory separate is by soft linking it (ln -s <source> <dest>) into a subdirectory underneath your "Scripts" directory.

-s Option

By default, the Virtual Wiring system runs a Script called "Scripts/user/startup.script" every time you start up or restart the system. You may wish to run a different Script. Perhaps you've got a new start up Script located with some Scripts you've written. Or maybe you are running the Virtual Wiring software multiple times on one system or are sharing Scripts between multiple systems. In either case, you will likely want to have a unique start up Script for each system.

The -s option allows you to use a unique start up Script each time you start your system. Notice that the Script names are the full names you would see in your Scripts page. If you have a start up Script you wish to run using the -s option and aren't sure what its full name is, find the name on the Scripts page (copy and pasting works well).