Software/Zaber Console/Source Code

From ZaberWiki

Jump to: navigation, search

We provide the source code for Zaber Console, along with some simpler example projects as a learning tool for developers writing Microsoft.NET software to drive Zaber devices. This page links to design documentation, tips and tricks, and how-to pages. Before working with the source code, try installing Zaber Console and experimenting with it. Writing scripts in Zaber Console is an easy place to start before going to the effort of installing all the development tools.


Contents

[edit] Getting started with Zaber source code

Download the latest source code from the Zaber web site. The file includes the executable versions of all demos plus the help file for the Zaber library and the source code for all the projects. You can also download the source code for the test version. See the release notes to see what's in each version.

[edit] Development Tools

To view, edit and build the Zaber source files, you will require some additional development tools. Here are the basic development tools we use:

  • Visual Studio - for writing the code. To just compile the code, the free C# Express version is fine. We've used the 2008 version, but haven't tested the 2010 version yet. If you want to publish your own installer using our build script, you'll need to buy at least the Professional edition of Visual Studio.
  • NUnit - unit testing framework (needed if you want to run the unit tests)

[edit] Building and running the Zaber source files

These instructions describe how to build and run the projects from source code so that you can start making changes.

[edit] Downloading the source files

  1. Download the ZaberCSDemo.zip file and unzip it to a working folder on your computer. The following 5 folders should be located under the src folder:
    • Zaber - the Zaber library
    • ZaberConsole - general purpose project for controlling devices
    • ZaberCSDemo - simple C# Demo projects
    • ScriptRunner - lets the user run script files from the command line
    • lib - third-party libraries

[edit] Building the source files

  1. Install Visual Studio or C# Express on your system (see the development tools section above).
  2. Double-click on the solution file src/ZaberCSDemo/ZaberCSDemo.sln to open it.
  3. Make sure the Solution Explorer pane is visible. If not, click View/Solution Explorer.
  4. The Solution Explorer pane shows all the projects contained in the Solution. Make sure "ZaberConsole" is the startup project (it should be shown in bold). If not, right click on "ZaberConsole" and select "Set as Startup Project".
  5. Press F5 or click the "Start Debugging" icon (a green arrow in the title bar) to build and execute the Zaber Console project.
  6. Repeat the last 2 steps for any other project you wish to build and execute.

[edit] Running the executables

If you wish, you can create shortcuts to the executable files so you can run them without starting Visual Studio. Keep in mind that whenever you build a project, the corresponding executable gets overwritten. If the path shown below doesn't exist, you may need to build the project first by selecting Build Solution from the Build menu.

Project Executable location
Zaber Console src\ZaberConsole\ZaberConsole\bin\Release\ZaberConsole.exe
Script Runner (command line) src\ScriptRunner\ScriptRunner\bin\Release\ScriptRunner.exe

If you make changes to the Zaber library and re-build it, you can find the new Zaber.dll file in the folder src\Zaber\Zaber\bin\Release\Zaber.dll.

[edit] Strong name key

The Zaber library is signed with a strong name. If you're compiling from the public source code, it will use a dummy key file that doesn't require a password. This means that any code that uses the Zaber library will need to be recompiled with your version of the Zaber library. If you're working for Zaber, you will compile from the internal source code that includes the real key file, and you'll need to ask for the password.

If you are running without administrator rights, you may get an "Access denied" error when you try to import the strong name key. You just need to grant yourself access to C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys. One way is to run a command prompt under an administrator account and enter these commands: 

cd C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\
cacls RSA /e /t /g userid:f

Of course, replace userid with your user id.

[edit] Creating a new client project

Follow these steps to create an application that uses the Zaber library to drive a chain of Zaber devices. These steps assume you are using Visual C# 2008 Express, but the procedure should be similar for any version of the Visual Studio environment.

[edit] Zaber Console Plug In

This is the simplest type of client project. It's just a control library that has at least one Windows Forms control marked with the PlugIn attribute. There are three small sample plug ins included with the source code: ZaberPortDemo, ZaberDeviceDemo, and ZaberConversationDemo. They are all under the src/ZaberCSDemo folder. The simplest way to set up your own plug in is to add a new project to the ZaberCSDemo solution.

  1. Open the ZaberCSDemo.sln file.
  2. Scroll to the top of the Solution Explorer window, right click on the solution, and choose Add: New Project....
  3. Type a name for your plug-in project, and create a folder to save it in.
  4. If the list of templates includes a Windows Forms Control Library, choose that. Otherwise, choose Class Library. Click OK.
  5. If you chose the Windows Forms Control Library, delete the UserControl1.cs file. Otherwise, do the following steps:
    1. Delete the Class1.cs file.
    2. Add a reference from your project to the Windows Forms library. To add a reference, right-click on your project in the Solution Explorer pane and select "Add Reference...". Then click the .NET tab and choose System.Windows.Forms. Click OK.
  6. Add a reference from your project to the Zaber library project. To add a reference, right-click on your project in the Solution Explorer pane and select "Add Reference...". Then click the Projects tab and choose Zaber. Click OK.
  7. Right click your project and choose Add: User Control.... Type a name for your control.
  8. Open the control by double clicking on it.
  9. Mark the control as a plug in.
    1. From the View menu, choose Code.
    2. At the top of the file, add two using declarations: using Zaber; and using Zaber.PlugIns;
    3. Just before the class declaration, add this attribute: [PlugIn]
  10. Now you can add some plug-in properties that will be set by Zaber Console. The simplest is to add a Conversation property:
    [PlugInProperty]
    public Conversation Conversation { get; set; }
  11. Build the user interface for your control. A simple way to start is to drag a button from the tool box onto the control. For more information, see Developing Custom Windows Forms Controls.
  12. Write the code for your control. For example, double click on a button to add an event handler. Then include some code like you would use in a Zaber script. For example:
    Conversation.Request(Command.Home);
  13. Decide whether you need initialization code in your plug in. The simplest technique is to handle the Load event, but that doesn't run until the user clicks on your plug in's tab. If you need to register for events like opening the port, then you should add a ZaberPortFacade property, mark it with the [PlugInProperty] attribute, and register for any events in the property setter.
  14. The easiest way to test your plug in is to go to Zaber Console's advanced tab, and point the plug-in folder at your plug in's bin/Release folder. Keep in mind, you won't be able to compile your plug in while Zaber Console is running. If you're using several plug ins, you may prefer to add a post-build step that copies your plug in to Zaber Console's plug-in folder.

You have several options for sharing your plug in with other users.

  1. You can get all users to download it to their own plug-in folders. When you release a new version, they have to exit Zaber Console and copy the new version to their folder.
  2. If your users are on the same local network, they can use a network share as a plug-in folder. If you put a version number at the end of your plug-in's file name, then you can copy new versions into the folder while users have the old version running. When Zaber Console starts, it loads the highest version number. For example: ZaberPortDemo-1.1.dll is higher than ZaberPortDemo-1.0.dll.

When you are deciding what to name your project and control, the names appear in two places. The plug in will show up in the list on the Advanced tab as "ProjectName.ControlName". The plug in's name in the main list of tabs defaults to "ControlName". However, you can override the default with a parameter in the [PlugIn] attribute. Here's an example that overrides the name: 

   [PlugIn(Name="Device Demo")]
   public partial class DevicePlugIn : UserControl
   {
       ...
   }

[edit] Stand-alone client project

If you don't want to run as part of Zaber Console, you have to take care of configuration and opening the serial port yourself. There are two example projects that show ways of doing that: SpringDemo and SpringFreeDemo. The source code for both of them is in the src/ZaberCSDemo folder. The help tab on each form describes some benefits of each technique.

[edit] Packaging and distributing the software

This section will probably only be of interest to Zaber staff. It contains instructions on how to build an installer, package the source code, and publish a new version of the software.

[edit] Tools

If you wish to generate a distribution package for installation on other computers, you will need to install the basic tools plus these additional tools:

  • NAnt - automated build tool for generating distribution package. After installation, add the NAnt bin folder to your path as follows so you can run it from the command line:
  1. From the Windows Start menu, right click on My Computer.
  2. Click on the Advanced tab.
  3. Click on the Environment variables button
  4. Find the Path variable, select it, and click the Edit button.
  5. Add ;C:\Program Files\nant-0.85\bin to the end, but make sure you use the path where you installed NAnt.
  6. Click OK. Click OK. Click OK.
  7. Open a new command line, and type nant -help to check that it runs.
  • NAntContrib - add-on features for NAnt like the msbuild task to compile solution files. Read the readme.txt carefully! You can't just dump all the files in the same folder. You have to create some new folders to put the files in.
  • Subversion client - command-line client used by NAnt
  • Sandcastle - used by NAnt to build the help file - see the Sandcastle wiki for more details
  • Sandcastle Help File Builder - front end to Sandcastle used by NAnt to build the help file
  • HTML Help builder - used by Sandcastle to generate the HTML help file
  • FxCop - code scanner used by NAnt (checks .NET managed code assemblies for conformance to the Microsoft .NET Framework Design Guidelines)

[edit] Third party libraries

The Zaber library and other projects make use of some third party libraries (dll files). These are included with the Zaber source files. However, you may wish to download newer versions if you are modifying the Zaber source code for your own purposes.

File Download Site Description
Spring.Core.dll Website Spring.net core library
log4net.dll Website used by Spring.Core.dll for logging
Common.Logging.dll Website used by Spring.Core.dll for logging
antlr.runtime.dll Website used by Spring.Core.dll for code parsing and generating
nunit.framework.dll Website used by NUnit for unit testing (comes with NUnit application software)
Rhino.Mocks.dll Website

Wiki

Used to create mock objects and simulate hardware for unit tests
TickingTest.dll Website helps unit test multithreaded scenarios

[edit] Creating a distribution package

The scripts necessary to create a distribution package are contained in the build file "src\ZaberCSDemo\ZaberPortDemo\ZaberCSDemo.build". If you open this file in notepad or Visual Studio you will see that it contains several "targets". Each target contains a sequence of instructions. NAnt is the program used to read the build file and implement the instructions. All targets can be executed in sequence by typing "nant" at the command line (in the folder containing the build file). Individual targets can be executed by typing "nant xxxxx" where xxxxx is the name of the particular target in the build file. View the build file in notepad or in Visual Studio you will see what instructions are contained in each target.

To create a distribution package from the Zaber source files, you will first need to install all the tools listed in the "develpment tools for packaging and deployment section" above. Once you have done this, follow these steps:

  1. Open a command prompt in the folder src\ZaberCSDemo\ZaberPortDemo
  2. Enter the command line nant dist
  3. If you have installed all the development tools correctly, when NAnt completes, you should see these new folders:
    src\ZaberCSDemo\dist - contains the new distribution files ZaberConsole.zip and ZaberCSDemo.zip
    src\ZaberCSDemo\package - contains the unzipped versions of the above two files
    src\ZaberCSDemo\package\ZaberCSDemo\doc - contains the help file, Zaber.chm
  4. To install the distribution files, simply unzip them into the folder of your choice and create shortcuts to the executable files as needed.
  5. In order to run the executables, the Microsoft .NET Framework Version 3.5 must be installed. Therefore you may wish to include it with your distribution.

The NAnt build script assumes that all the development tools are installed to default locations. If you installed them to non-default locations, or installed newer versions, you may need not get any error messages, but the build script will not do everything it's supposed to (for example, you may be missing the help file). In this case you should edit the NAnt build script src\ZaberCSDemo\ZaberPortDemo\ZaberCSDemo.build in a text editor and correct the path names for your machine.

Retrieved from "http://zaber.com/wiki/Software/Zaber_Console/Source_Code"
Personal tools
Zaber Website