This is a very brief “getting started” tutorial for SoapBox Snap:

Installing SoapBox Snap

SoapBox Snap is a Windows desktop application. You can download the install program from the SoapBox Snap Project Page.

Once you’ve downloaded it, double click on the install program that you downloaded, and it will install it on your computer. Follow the prompts of the installer wizard. You also have to install the Phidgets Drivers (pick the appropriate 32 or 64 Bit Installer Download, but make sure you have Phidgets 21, not 22.

Quick Start

When you first run SoapBox Snap, it will open the SoapBox Snap Start Page. There is a “getting started” section, and a link called Load Example Application. Click this link and it will open a small example application, connect to the runtime, download it, start the runtime, and display the executing logic for you.

Creating a New Solution

Begin by running SoapBox Snap: go to Start -> Program Files -> SoapBox Automation -> SoapBox Snap

Note: if you’re interested in using SoapBox Snap to program an Arduino with ladder logic then go to the SoapBox Snap Arduino Tutorial.

Click File->New… on the main menu. This will open an empty solution. Look for the “Solution Explorer”. It’s a small window that contains one item: Solution[].

You will see a Runtime item if you expand the Solution[] item in your Solution Explorer. The icon next to the Runtime item is a broken link, indicating that you’re not connected to the runtime (you will learn how to connect below).

If you expand the arrow (or plus sign) next to the Runtime item, you will see two items under it: Logic and Device Configuration. Logic is a folder structure where you can add “pages” of logic. You can also add sub-folders to the Logic folder to organize your application any way you like. To add a folder or a page, right click on the Logic item and select Add->Folder or Add->Page respectively. The order of the logic in the tree is important. The logic pages will be executed in the Runtime in the same order that they appear in the tree.

You can edit the names of folders and pages in the Logic folder by selecting the folder or page in the tree, waiting a second, and then clicking it again. When you finish entering the new name, press Enter.

Double-click on a page to edit it.

Editing a Page of Logic

When you first open a page, it’s empty. Add your first rung of logic by right clicking anywhere in the page and choosing Insert at Bottom->Ladder Logic. You can insert any number of rungs. (Note: rungs are sometimes called Instruction Groups). You can insert new rungs anywhere in the page, and you can re-order rungs by selecting one, right clicking, and choosing Move Selected Group Up/Move Selected Group Down, or by selecting a rung and using drag & drop to move it up or down. The order of rungs are important because they are executed in this order in the runtime.

To add logic to your rung, you need to drop instructions on the rung from the Instruction Pad. You should see a list of instructions on the right side of your window (go to View->Instructions if you don’t see them). Use drag and drop to insert instructions into your rung(s).

When you drop an instruction into a rung, SoapBox Snap gives the instruction a name. Make sure you change this name to something meaningful. It will let you give two instructions the same name, but if you want to reference them elsewhere, this can get confusing. The blue rectangle above the instruction is a place where you can enter a multi-line description. This is generally a good idea. Try to keep it brief.

Once you’ve written some logic, make sure to save it. Choose File->Save As… from the main menu.

The next step is to download your application to the runtime where it will be executed…

Going “Online” with the Runtime

Assuming you have a solution loaded (see above), going “online” with the runtime is relatively simple. Find the Runtime item in the Solution Explorer. Right click on it and choose Connect from the context menu.

If this is the first time you’ve downloaded something to the Runtime, SoapBox Snap will detect that the Runtime is empty. It will ask you if you want to download the application. Say yes. If the Runtime already has a loaded application, it will ask you if you want to “upload” or “download”. In this case choose “download”.

After downloading, take a look at the Runtime item in the Solution Explorer. The “broken link” icon should now have turned into a “non-broken link”, and there will be a new icon next to it that displays the Running status of the Runtime. If you see two green arrows, the Runtime is executing, but if you see a white ‘X’ in a red octagon, it means the runtime is stopped. To start it, right click on the Runtime item and choose Start from the context menu.

Once you’re connected to the Runtime and it’s Running, if you open a logic page, you will now see the logic being executed in real-time. You can make some changes, such as the name and descriptions of instructions, but most edits will require you to disconnect. Once disconnected, make your edit, and then reconnect, and select the Download option to download your changes to the runtime.

Scanning for I/O Devices

Currently, SoapBox Snap supports the following Phidgets I/O devices:

• Interface Kit 0/16/16
• Interface Kit 0/0/4
• Interface Kit 0/0/8
• Interface Kit 0/8/8
• Interface Kit 4/8/8
• Interface Kit 8/8/8
• Servo 1-Motor
• Servo 4-Motor
• Servo 8-Motor
• Text LCD 2×20

These devices can be detected automatically if they are plugged into a USB port on your computer. Use this procedure:

1. Open a solution (see above)
2. Go online with the runtime (see above)
3. Expand the solution tree so you see the Device Configuration item
4. Right click on the Device Configuration item
5. Select Read Device Configuration from the context menu
6. Detected Phidgets will show up under the Device Configuration tree
7. You will be disconnected from the Runtime after this operation

To test if your devices are working:

1. Go online with the runtime (see above) and choose the “download” option
2. Drill down in the device tree to an individual output
3. Right click on the output and choose one of the Force options from the context menu to write an explicit value to the output
4. You can right click again and choose Remove Force to restore the output to program control

The inputs on any Phidgets devices can be referenced directly in your SoapBox Snap application’s logic pages. In order to drive outputs from your logic, find the output you want to hook up in your Device Configuration tree, expand the output, and double click on the item underneath the output. This is a signal chooser that lets you tie control of the output to any signal in your program. You can even tie an output directly to an input.

Running the Runtime Engine as a Service

When you exit SoapBox Snap, the runtime engine will stop, and your logic won’t be executed anymore. That’s because the engine is actually part of SoapBox Snap. This works well for getting started and troubleshooting, but you probably want your program to keep executing even if SoapBox Snap isn’t.

First, double click on the Runtime item in the Solution Explorer, and check the box that says Execute on Startup. This will force the engine to execute the runtime application as soon as it has loaded it. If you didn’t do this, you would still have to connect to the runtime engine and start it manually.

Next, go to Tools->Options… in the main menu. In the Options Window that pops up, select the SoapBox Snap Soft Runtime item in the tree on the left. Check the box that says Run as a Service. Click the OK button to save. If you’re using Vista or Windows 7, you’ll have to acknowledge some security prompts to allow it to install the Runtime as a service. While being installed, the Runtime engine will stop. In order to start again, SoapBox Snap will have to close in order to release some resources to the service. The runtime will start executing as a service right away.

You can still start SoapBox Snap and connect to the Runtime just as you had before. You will notice that the communication between SoapBox Snap and the Runtime is slower, but this is simply because they are completely separate programs now.