Scripts make things happen within the Virtual Wiring System. Typically, Scripts add Devices, but they can also configure Devices and wire them together. Scripts make doing things easy, because they let any single action or series of Virtual Wiring actions be performed with a single mouse click. If you are just starting to use the Virtual Wiring System, you'll probably get started by running Scripts.
The image below is a screen shot of the Scripts page. The Scripts page is accessible from any web page within the Virtual Wiring system. You can go to the Scripts page by clicking on the "Scripts" link at the top of the page.
The Scripts shown in the screen shot are for building Arduino based Devices. (Arduinos are a highly popular, low cost microcontroller). The Virtual Wiring System has many Scripts, typically one Script for every possible Virtual Wiring Device, and many kinds of Scripts. There are Recipe Scripts for building predefined small systems and for demonstrating how things work, and systems and Project Scripts for building larger systems. If you decide to build your own system, you will probably have some Scripts of your own.
Scripts are actually viewable, editable files containing Virtual Wiring commands. Scripts have names, and Scripts are located in user definable locations within the Scrips area. Generally Script names and Script locations make it easier to understand what Scripts do.
The View Filter Selector
There are many Scripts in the Virtual Wiring system. Though you could look at them all at once, there are probably too many for such a view to be useful. Instead, you may want to "filter" out all but a certain kind of Script. To do filtering, there is a View Filter. The View Filter is located at the top of the Scripts page.
If you click the "View Filter" selector, you will see all the filters available. Select the filter for the type of Script you wish to see. In the screen shot above, we have filtered out all the Arduino Scripts using the "Arduino" view filter. To see all the Scripts in the system, select the "ALL" filter.
Running, Showing, Editing Scripts
The Scripts page has a list of Scripts. To the right of every Script is a set of actions: Show, Edit, and Run (see screen shot above). For each Script, you can read it, using the Show action, Edit it, using the Edit action, or execute it, using the Run action.
You can see the contents of any Script in the system. Most Scripts have, in addition to their command lines, comments describing what the Script does. If you are unsure what a Script does, "Show" its contents to see what's inside. To show a Script, locate it in the list of Scripts on the Scripts page and click on its "Show" Action. Here we are showing the "startup.script" Script.
You can edit any Script in the system. If you see a problem with a Script or wish to add comments clarifying what the Script does, you'll need to edit the Script. To edit a Script, locate it in the list of Scripts on the Scripts page and click on its "Edit" Action. If you are already "showing" a Script, you can edit it by clicking on the "Edit" action at the bottom of the "Show" page. Here we are editing the "animal_game.script" Script.
If you make changes to a Script in the Editor, be sure to click the "Save" button at the bottom of the page. If you leave the editor page without saving, your changes won't be saved.
Scripts are only useful when you run them (if you aren't sure what a Script does, you can click on its "Show" action and read the Script before running it).
To learn more about running Scripts and adding devices to a system, see the following section.
The Restart Button - Removing All Devices, Restarting the System
At the bottom of the Scripts page, there is a "Restart" button. If you run the wrong Device Script or just want to start again, you can restart the system. If you click on this button, all your devices will be cleared out and your configuration will be as it was when your powered on your system.
If the Restart button doesn't work or if it's easier, you can kill and restart the Virtual Wiring application. Though it depends on how you are running things, it is usually easier to use the Restart button.
Session Script Button
At the bottom of the Scripts page, there is a "Session Script" button. Clicking the button shows a page with all the commands which have been run successfully, since the last restart.
Here we are showing the Session Script after running the "animal_game.script" Script.
Why is the Session Script of interest? If you execute the commands from the Session Script page on a fresh system, it will recreate the system that created the Session Script. So if you have built something you wish to save, create a new Script, click on the "Session Script" button, copy its contents to newly created Script, and save it - you've made a Script which builds your current system.
Note: in the Building Scripts from the Console Section, we describe how to copy the Console, save key commands and remove status lines, and create a Script which recreates you system. Using the Session Script button is an easier way of accomplishing the same thing.
Once one has created a running system, one may want it to recreate itself every time the system powers up. The following section describes how to do this.
Creating a New Script
The Virtual Wiring System comes with a set of Scripts which you can run or modify. In addition, you can create your own Scripts. At the bottom of the Scripts page, there is a "Create a Script" button. To create a new Script, click on the "Create a Script" button. You will be prompted for the Script's name and directory. The directory location will be pre-initialized to the Script directory you are viewing, so if you want to create a new Script, its easiest create it from the View you want your Script to be in.
Creating Scripts in Empty Subdirectories
There is a small limitation on Script creation, done for security purposes. You can only create Scripts in directories which already have Scripts in them; we don't want people creating Scripts just anywhere and overwriting sensitive host files.
To create a Script file in an empty directory, first be sure the directory is one of your Scripts subdirectories. Then go to a terminal session on your host and create the file in that subdirectory.
If you are wondering where your Scripts subdirectories are, you created them when you installed your Virtual Wiring System. When you first installed your Virtual Wiring System, you created a new top level directory. Inside the top level directory is your startup file (and a few others), and a directory called "virtualizer". Inside the "virtualizer" directory, there is a directory called "Scripts". All the Scripts visible from the Scripts page are inside of the "Scripts" directory.
To add a new Script from you terminal session, enter the "Scripts" directory:
Then "touch" the name of the Script you wish to create (here we create a my_new.script in the user subdirectory):
Restart your System and refresh the Scripts page. You should see "my_new.script" in the "user" view of your Scripts page.
You can put your new Scripts anywhere you want (though the "user" subdirectory isn't a bad place to start), or you can create a new subdirectory under the Scripts directory. If the directories already have Scripts in them, you can use the "Create a Script" button. If you plan on making lots of your own Scripts, creating a new subdirectory is a good idea, as it will make your Scripts easier to find and easier to migrate to another system in the future.