Mini SSC DLL for 32-bit Windows

Thousands of users have successfully interfaced the Mini SSC to everything from BASIC Stamps to high-end workstations. For most, the hardest part is determining how to configure and use the serial port with their programming language. This app note presents an ultra-simple dynamic link library (DLL) for Windows (95/98/NT/2000) computers that should allow any programming language that can use DLLs to talk to the Mini SSC.

Fine Print: This software is presented free to our customers for their own private, non-commercial use. Scott Edwards Electronics, Inc. accepts no liability for any consequences of its use, performance, or non-performance. Use this software at your own risk.

While we encourage you to report any problems you encounter with this software, we cannot provide tech assistance with the DLL-calling mechanism for the various Windows programming languages. Some provide no, partial, or buggy DLL support.

Installing the Mini SSC DLL

A DLL is a library of software functions that can be loaded and used by a program running on your Windows computer. Much of what we think of as the "Windows operating system" is made up of many DLLs.

The Mini SSC DLL is a single, small (less than 12kB) file. To install it, just drop it into the folder "C:\Windows\System".

Using the DLL

Just three functions make up the Mini SSC DLL:

• SSC_OPEN(port,baudrate) --Set up the comm port for the specified baud rate, initialize memory for the DLL, and start a background thread (task) that will update the Mini SSC via the serial port.
• SSC_MOVE(servo,position) --Move servo to position Note: the DLL supports servo numbers 0-31 only.
• SSC_CLOSE() --Shut down the background thread and close the serial port.

Using the DLL just consists of calling SSC_OPEN at the beginning of your program; using SSC_MOVE as needed to move servos around; then calling SSC_CLOSE when your program is done. You cannot use SSC_MOVE if you have not called SSC_OPEN, or if you have previously used SSC_CLOSE. You should never allow your program to end without calling SSC_CLOSE, as this will leave the port open and the background task running.

All of the values (arguments) that you pass to these functions are of the long integer type. Each function returns TRUE (-1) if it was successful, or FALSE (0) if it failed. If, as in our example, you don't want to use the return values, most languages allow you to Call the functions, which discards the result. A really robust program should always at least check for success of the SSC_OPEN since users often select nonexistent comm ports when configuring software.

Visual BASIC and Delphi Program Examples

It's fair to say that Visual BASIC is a popular Windows language, so that's what we used to create a demo for the DLL. The details of declaring and calling DLLs from other languages are in their respective user manuals--we cannot provide tech support on this subject.

If you've never called a DLL from your programming language before, read the manual thoroughly, and try the idea out with some other DLL.

UPDATE: Although this page discusses the VB6 example, we have added a similar example program written in Delphi 5 to the ZIP file. This file may not be compatible with earlier versions of Delphi due to changes in the .FRM file. The example information in the .PAS should be sufficient to get you going. The only tricky aspect of the form is that each of the scroll bars was assigned a Tag value to identify which servo # (0-7) it controls.

Here's a screenshot of the demo program:

Here is the entire code-window listing of the example program, which was written in VB6:

Private Declare Function SSC_OPEN& Lib "Ssc05.dll" (ByVal commPort&, ByVal baudRate&)
Private Declare Function SSC_CLOSE& Lib "Ssc05.dll" ()
Private Declare Function SSC_MOVE& Lib "Ssc05.dll" (ByVal servo&, ByVal pos&)

Private Sub Form_Load()     ' When form loads,
  Call SSC_OPEN(5, 9600)    ' open comm 5 for SSC at 9600 baud.
End Sub

Private Sub Form_Unload(Cancel As Integer)
  Call SSC_CLOSE            ' When form unloads, close the SSC/comm port
End Sub

Private Sub VScroll1_Change(Index As Integer)
' When one of the array of scroll bars changes, instruct the corresponding
' servo (Index) to move to the new position (scroll bar Value).
  Call SSC_MOVE(Index, VScroll1(Index).Value)
End Sub

Download and Run the VB Example

Click here to download a small ZIP file containing the DLL and VB example programs. This is version 0.1, August 26, 1999.

• UnZIP the file and place the DLL (SSC05.DLL) into C:\Windows\System
• Place the VB files into a folder that's convenient to access from VB
• Open the project with Visual BASIC, and pull up the Code window (Menu item View - Code)
• Edit the instruction Call SSC_OPEN(5, 9600) subsitituting your comm port number for "5"
• Connect a Mini SSC to the comm port, configure for 9600 baud, apply power
• Run the program

Under the Hood

The whole point of wrapping up the Mini SSC driver as a ready-to-use DLL is to spare you the effort of coding your own serial-port routine. But you may be wondering just how the DLL works. Here's a brief description:

When you call SSC_OPEN, the DLL opens and configures the selected comm port. It also establishes two arrays; one in which it will store new-position requests, and another in which it keeps a record of positions previously sent to the Mini SSC. It then activates a background thread (described below) that actually sends instructions to the Mini SSC. Upon activation, all servos get commanded to their centered position (the default position when the Mini SSC is powered up).

SSC_MOVE takes the servo number and position value you specify and updates the new-position array. It returns control to your program almost immediately. The background thread then sees that the new position is different from the old position, and sends an instruction to the Mini SSC to eliminate the difference. It records the update in the old-position array and continues scanning for changes.

SSC_CLOSE just shuts down the background task and closes the serial port.

The DLL works a little differently from a typical serial-port driver in that it does not put bytes in a buffer waiting for an opportunity to send them out the port. It is designed to overcome a couple of problems with buffers:

• A poorly planned program could clog up a buffer with unnecessary instructions telling servos to go to their current positions. The DLL sends a position instruction only if it finds that a newly commanded position is different from the current position. This can cut down the amount of serial traffic to the Mini SSC tremendously.
• Buffering could allow a timing discrepancy to arise between the program and the Mini SSC. If a hyperactive program rapidly jammed 300 servo positions into the buffer, it would take about a second (at 9600 baud) for that data to drain off. The program's reckoning of time would be about 1 second different from the instructions reaching the Mini SSC. With the DLL's method, this kind of timing discrepancy can't occur. Redundant or overridden position instructions just harmlessly replace each other in the new-position array.

Going Further

The demo is fun to play with, but is admittedly not very useful. Feel free to expand on it to suit your purposes. If you like the idea of a Windows-based front end for the Mini SSC, but writing your own program sounds too much like work, consider one of the excellent commercial packages available:

• Mister Computer offers a complete animatronics package with an assembled Mini SSC II, servos, and software.
• Roscoe Robotics' ServoMotion software supports joysticks, .WAV (audio) files, and more.
• Reynolds Electronics' Robo-Ware software offers sophisticated control, scripting, .WAV (audio) files, etc.
• Brookshire Software's Visual Servo Automation offers .WAV sync--even 'lip sync' for animatronics--via graphical timeline.

For a more comprehensive tutorial on controlling the Mini SSC with the VB comm control (provided with Pro versions of Visual BASIC), see Reynolds Electronics' web article.