Using the 3D Connexion SDK

The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at
https://en.wikibooks.org/wiki/Using_the_3D_Connexion_SDK

Permission is granted to copy, distribute, and/or modify this document under the terms of the Creative Commons Attribution-ShareAlike 3.0 License.

Getting Started

About 3D Connexion

3D connexion is a Logitech company which produces 3D input devices for personal and professional use. WikiBooks is not a place to advertise products, so for those who wish to find out more about 3D connexion products, please visit the 3D connexion Website

Pre-Requisites

Before getting started, you will need to download Microsoft Visual Basic. I would recommend the free express edition, available from Microsoft. Mac users will need to improvise at this stage (edit- any suggestions?).

You will also need to register with 3D connexion to gain access to the SDK files for free. VB.zip will form the template for the visual basic programs on this tutorial.

A Quick introduction to Visual Basic

A Quick introduction to programming and Visual Basic

There are many excellent references for learning to program in Visual Basic. Sites such as the Microsoft Developer Network provide a good overview, and the WikiBook [Visual Basic] provides an excellent guide for those with some experience in programming.

It may be useful for those new to programming to read the following section, however, those with experience in Visual Basic Programming should skip to the next section.

Getting Ready

Let's get started and open up Visual Basic Express (In the Prerequisites section). The program should look like this (arrangements of toolbars may vary): (IMAGE1) Hit CTRL+N to start a new project. This window allows you to choose a project to start.

(IMAGE2)

Most courses start on Consoles (text only), but we're going to start with a Windows Forms Application. We want to create something which looks good (rather than a console window). Double Click the 'Windows Forms Application' to open a new application. You should see this:

(IMAGE3)

Look at the 'Solution Explorer' Panel. This shows all the parts of the program. We have "Windows Application 1", a default name for the program. This contains "My Project" and "Form1.vb". My Project is a set of instructions which tell the computer to run your 'form' (programmer jargon for a window). Form1.vb is a form which you can edit. This has 2 parts: Design and Code. You can switch between these by using these buttons in the Solution Explorer:

(IMAGE4)

Let's look at the code by pressing the View Code Button. (IMAGE5) You can see a text document. This contains some instructions already built in. It should say:

 Public Class Form1
 

 End Class

This is simply a way to start and stop the code. Form 1 is a "Class", basically this means that it can contain other bits of code. Making it Public means that other bits of code can refer to it (e.g. If you made another form it could get information from form1). You'll come across Private code later; this is code which can only be accessed by things in the same form.

Hello World

Hello World: Your first application

Let's switch back to design view with the button in the solutions explorer (IMAGE6). It is easy to create a new button for the program. Click the Toolbox button (IMAGE7). This opens up the toolbox:

(IMAGE8)

Click and drag a button onto your window. It should appear in the window with the name 'Button1':

(Image9)

Properties

Every object you place on your window has a set of properties. You can view these by single clicking on an object and clicking the Properties pane (Image10). You may have to hunt around for this. Here are the properties of my button:

(Image11)

You will never use some of these properties, but some you will use all the time. The three most important ones are 'Text', 'Position' and 'Size'. Try changing these and see what happens. Note that Position and Size only accept numbers.

Events

An event is something which happens which causes the computer to run a section of code. This could include clicking on a button, changing the text of a text box, moving the mouse across an image or any number of other things. Each event has a listener process which keeps waiting for the event to happen. As soon as it does, it tells the computer to run the appropriate bit of code. We'll make some of our own listeners later, but for now, let's use the ones built into Visual basic.

Press the lightning bolt icon to open the events window: (Image12). Here are the events for Button 1:

(Image13)

Click is the most common (default) event. To add the Click event to your program, double click in the text box next to 'Click'. The windows will change to enter Code view. Notice that it has added the words:

 Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
 

 End Sub

The exact meaning of this is not important; essentially it the first line means "This is a bit of code called 'Button1_Click'. It starts here" and the last line means "Stop here if you're trying to run the Button1_Click code".

Let's add some code. The way you use a property in code view is by typing the name of the object (in our case, Button1), followed by a dot, followed by a property. You can change it by typing = and then the new value in "double quotes" So, let's type:

 button1.text = "Hello World"

Your complete code should look like this:

 Public Class Form1
   Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
       Button1.Text = "Hello World"
   End Sub
 End Class

Compiling your Code

Compiling is a process where Visual Basic converts your design and your code into an application which your computer can run. There are two stages to this; debugging and compiling.

Before it makes your program, it has to understand what you've typed. The compiler checks through what you've typed to make sure it makes sense. This is called debugging. If you make a mistake, it will underline it in the code in blue:

(Image14)

Here, I've left out the = symbol. The debugger has looked through the code and underlined it. It has also added a line to the errors list.

Once the code is all valid, it is compiled into a program. A program cannot be compiled if it contains errors.

To compile your code, hit F5, or press the Play (Image15) button. This opens up the program. Press the button and watch it change!

Using Variables

Variables: your second program

Most programs rely on a set of variables. These are ways to get the computer to store and recall bits of information. It is like a box to store information in. You give each variable a name when you declare it. Declaring a variable tells the computer 3 things:

1: The name

2: What sort of information it is supposed to store

3: The initial value

The name has to be a word which is not already used. Visual basic checks to make sure the name is alright and will tell you if there is a problem. Use something which is memorable (Time_taken rather than t), but quick to type (MyChNum rather than My_Chosen_Number).

The type of data is important. The most common types are Integer- a whole number such as 15, Single- a number with a decimal part such as 14.560385, Double- a number with a decimal part which needs to be very accurate such as 14.359649064923490 and String, a bit of text such as "A bit of text".

The way we declare a variable in Visual basic is by using the word 'Dim'. Here's how we declare a variable called MyVar as a String of text.

 Dim MyVar As String = "This is the initial value"

Let's go into our hello world application and add the variable. You can add a variable at any point in the program, but where it is determines what it can be used for. If we add it in the description of Form1 it can be used anywhere in the program:

 Public Class Form1
   Dim MyVar As String = "This is the initial value"
 

       Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
         Button1.Text = "Hello World"
       End Sub
 

 End Class

You may have spotted by now that the properties of an object are all variables.

Assignation

Assignation is simply setting the value of a variable. You set the value like so:

 A = 1

Sets the value of A as 1.

 A = B

Sets the value of A to the value of B.

 A = 23 * B

Sets the value of A to 23 times the value of B.

We can also use A in assignation:

 A = A + 1

This increases the value of A by 1.

 A = A * 2

This doubles A

 A = A / 2

This halves A

Let's make an application which counts the number of times a button is pressed.

Just like in the Hello World application, create a new program and add a button. Go to the Events list and add a Click event to the button. Your code should now look like this:

 Public Class Form1
     Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
     End Sub
 End Class

Let's create a variable named 'counter'. We don't need it to have a decimal part, so we'll set the type to Integer. It should start at 0. The code for this is:

Dim counter As Integer = 0

Because this variable has to be stored even when button1 is not being clicked, it needs to go in the main part of the program:

 Public Class Form1
   Dim counter As Integer = 0
     Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
     End Sub
 End Class

When Button1 is pressed, counter should increase by 1:

Counter = Counter + 1

 Public Class Form1
   Dim counter As Integer = 0
     Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
       Counter = Counter + 1
     End Sub
 End Class

Now, we need to add a line of code to update the text on the button:

 Public Class Form1
   Dim counter As Integer = 0
     Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
            Counter = Counter + 1
       button1.text = Counter
     End Sub
 End Class

Notice that Button1.Text is actually a string. If you use other languages, you will need to convert between variable types before you can assign to a different type.

Run your code to see the program.

Limits and Relativity

Often, you will need to add limits to a variable. Let's add a Progress Bar to our form:

(Image)

Have a look at the properties. The Value Property sets how far the progress bar has gone- notice how it does a nice animation when changed.

This value has limits; it cannot be more than 100 or less than 0. Sort of makes sense; I've never copied 110% of a file. If you try setting Value to 200, your program will fail. To stop this, we need to compare the value we are about to use with the maximum. We need to use Relativity expressions:

Relativity

Relativity essentially compares 2 values. A Relativity expression is phrased like this:

 A = 1

This expression is actually another form of Variable; a Boolean variable. This variable is either TRUE or FALSE. If A=1, (A = 1)=TRUE.

It's identical to assignment, but has to be used in a different place. I'll come on to that later. Here are a few more Relativity expressions:

 A > 1

A is greater than 1

 A < 1

A is less than 1

 A <> 1

A is not equal to 1

 A <= 1

A is less than 1, or A is equal to 1

 A >= 1

A is greater than 1, or A is equal to 1

We can combine expressions using AND, OR, NOT or XOR conditions. And means that both expressions must be TRUE, OR means neither of the expressions are FALSE, XOR means only one of them is TRUE. Not is used to change TRUE to FALSE and FALSE to TRUE.

      not(TRUE) = false
  TRUE or FALSE = true
 FALSE xor TRUE = true
  TRUE xor TRUE = false

We have 2 conditions for our progress bar:

 counter >= 0
 counter <= 100

Both of these have to be true for the program to work, so let's use and to combine them:

 (counter >= 0) and (counter <= 100)

We then use standard English to get the program to correct it. We type If, followed by our condition, followed by Then. Next comes the code to run, ended by an End If:

 If (counter >= 0) and (counter <= 100) then
       Counter = Counter + 1
       button1.text = Counter
       progressbar1.value = counter
 End If

There's a problem here. If we test the program and get Counter up to 100, we can then press the button again and try and get the progress bar up to 101. This crashes the program. The problem is with the order in which we give instructions:

1. Check if value of Counter is OK

2. Add 1 to Counter

3. Update form

Visual Basic works on a line-by-line basis; it does each line in order. We need to re arrange the program.

2. Add 1 to Counter

1. Check if value of Counter is OK

3. Update form

 Counter = Counter + 1
 If (counter >= 0) and (counter <= 100) then
       button1.text = Counter
       progressbar1.value = counter
 End If

We can add more things to this code; how about setting the value to 0 once it gets to the top? For this we need an Else part.

       counter = counter + 5
       If (counter >= 0) And (counter <= 100) Then
           Button1.Text = counter
           ProgressBar1.Value = counter
       Else
           counter = 0
       End If

What Just Happened (If...Then...Else Logic)

The code used here was a decision making process:

 If Condition Then
   Things to do if Condition = TRUE
 Else
   Things to do if Condition = FALSE
 End If

Procedures

So, What are Procedures?

A procedure is a bit of code which you can move out of your main program and use again and again for different purposes. Let's say you had a program which tool in variable A, and divided it by 2, squared the result and added 4, and did this 10 times. In standard Visual Basic, it would look like this:

 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4
 A = ((A / 2) * (A / 2))  + 4

If you do this a lot, it makes sense to get Visual Basic to do all the tedious coding. Once you've read this chapter, you'll be able to make a procedure which does it for you. If you called it 'Calculate', your code could look like this:

 Calculate
 Calculate
 Calculate
 Calculate
 Calculate
 Calculate
 Calculate
 Calculate
 Calculate
 Calculate

This causes the program to jump to 'Calculate' and then jump back when Calculate is finished.

Making a simple procedure

To make a procedure, let's make a new Visual Basic program and add a button. Add a Click event to it (Look at the Hello World Tutorial for more). Declare an Integer variable called MyNumber:

   Public Class Form1
     Dim MyNumber As Integer = 1
     Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
     

     End Sub
   End Class

In visual basic, our entire program is just one massive procedure for Windows (or other OS) to run, so procedures inside the program are called Sub-Procedures, or Subs for short. Visual basic lets us say whether it is Public (other programs can start it running) or Private (it is invisible to other processes). We'll make ours public. You can see in the code that Visual Basic has already made a Private Sub for our button click event. Let's add another sub, this time Public, and call it 'DoubleMyNumber':

 Public Class Form1
   Dim MyNumber As Integer = 1
   

   Public Sub DoubleMyNumber()
     This is where the procedure code goes
   End Sub
   

   Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
   

   End Sub
 End Class

The reason for putting the '()' after the name of the procedure will become clear in a moment. (Visual Basic actually adds it in automatically)

So, let's add the code to DoubleMyNumber:

 Public Class Form1
   Dim MyNumber As Integer = 1
   

   Public Sub DoubleMyNumber()
     MyNumber = MyNumber * 2
   End Sub
   

   Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
   

   End Sub
 End Class

We need to call DoubleMyNumber when the button is pressed. This is nice and simple; we just type its name:

 Public Class Form1
   Dim MyNumber As Integer = 1
   

   Public Sub DoubleMyNumber()
     MyNumber = MyNumber * 2
   End Sub
   

   Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
   DoubleMyNumber
   Button1.Text = MyNumber
   End Sub
 End Class

Congratulations; you've just made a new procedure.

Adding Parameters

To make the procedure more useful, we can add parameters. A parameter is a variable which you can send to a procedure. Let's say we need to multiply the number by something other than 2. How about being able to do:

 Multiply_My_Number_By(312)

We can tell the procedure to expect a variable. In fact, we can tell it to expect as many variables as we like, and separate them with commas. We could have a procedure to add 5 numbers:

 AddUp(2,54,23,12,9)

All we need to do is declare it when we write the procedure description. Let's edit the program we just made. The brackets after the name are actually the place where a parameter can be declared. First we have to tell the procedure what to do with the variable after running:

ByRef: Call by Reference. This means you can change the variable

ByVal: Call by Value. The procedure cannot change the variable

Let's use ByRef. At this level, the choice of ByRef and ByVal is rarely important.

The code to get the parameter ByHowMuch is like so:

 ByRef ByHowMuch As Integer

Here's the complete code:

 Public Class Form1
   Dim MyNumber As Integer = 1
 

   Public Sub DoubleMyNumber(ByRef ByHowMuch As Integer)
       MyNumber = MyNumber * ByHowMuch
   End Sub
 

   Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
       DoubleMyNumber(312)
       Button1.Text = MyNumber
   End Sub
 End Class

Functions

A function is like a procedure, but it is actually a variable. Let me explain:

 A = Half(14)

Half(14) can be used just like a number. In fact, it is a number. Functions are much more flexible than procedures because they can be used to assign to different variables:

 A = Half(A)
 B = Half(B)
 C = Half(C)

Like procedures, functions can have more than one parameter:

 A = Multiply(A, 0.5)

We have to declare functions in a different way:

   Public Function DoubleMyNumber(ByRef MyNumber As Integer) As Integer
       DoubleMyNumber = MyNumber * 2
   End Function

Look at the last 2 words of line 1; As Integer. We have actually declared DoubleMyNumber as a new Integer, which we can assign to. We say DoubleMyNumber(Mynumber) = MyNumber * 2, and visual basic can work out that DoubleMyNumber(7) = 7 * 2

Visual Basic has a huge number of built in libraries of functions, try typing 'Math.' to open the Mathematical Operators library.

Welcome to the VB World!

If you read and understood all that, you're now ready for the big bad world of Visual Basic. You're also ready to get going on the 3D connexion SDK. If you didn't understand it, you need to hunt around for a Visual Basic course which suits you. There are loads out there, mainly much better than this, so happy hunting!

Go to the contents and start on the 3D Connexion tutorials.

Home

Introducing the 3D Connexion SDK

An SDK is a Software Development Kit, a load of code to allow you to make programs which do things with companies' products.

Let's unzip the VB.ZIP file which 3D connexion provides as part of the SDK, and drag the monitor.sln file into Visual Basic Express. You will need to run it through the converter to upgrade to your version of Visual Basic, so just keep pressing Ignore, Yes or Next until it finishes. Hit F5 to try it out. You should see a live readout of the data that the device is feeding back; which button is being pressed, what its rotation is, all sorts of nice, useful stuff.

Double click Form1.vb to look at the code. What this is a mixture of massively complex code which the 3D connexion team has written to connect your mouse to your computer, and stuff which we don't actually need. What we're going to do is make a template file from this project. First, go into design view and select all. Delete and go into code view. Delete all code and paste the following in:

(Reproduced by kind permission of Logitech)

 Public Class Form1
   Delegate Sub SetMotionTextCallback()
   Delegate Sub SetKeyTextCallback(ByVal keyCode As Integer)
 

   Private WithEvents Sensor As TDxInput.Sensor
   Private WithEvents Keyboard As TDxInput.Keyboard
   Private WithEvents Device As TDxInput.Device
 

   Public Sub New()
       Device = New TDxInput.Device
       Sensor = Device.Sensor
       Keyboard = Device.Keyboard
 

       SetMotionTexts()
 

       Device.Connect()
 

   End Sub
 

   Private Sub Sensor_SensorInput() Handles Sensor.SensorInput
 

       Me.SetMotionTexts()
 

   End Sub
 

   Private Sub SetMotionTexts()
 

       Dim Style1 As String = "f"
       Dim translation As TDxInput.Vector3D
       translation = Sensor.Translation
 

       Dim rotation As TDxInput.AngleAxis
       rotation = Sensor.Rotation
 

   End Sub
 

 

   Protected Overrides Sub Finalize()
       Device.Disconnect()
       MyBase.Finalize()
   End Sub
 

 End Class

You need to save all of this, by pressing Save All. Now close Visual Basic. To create a new program, create a copy of the template folder and open the Monitor.sln file in Visual Basic. There are ways to create your own from scratch, however, it gets complicated.

So, let's have a look at the code:

First they start Form1:

 Public Class Form1

Don't worry about this bit

   Delegate Sub SetMotionTextCallback()
   Delegate Sub SetKeyTextCallback(ByVal keyCode As Integer)

Here, they add in the TDx Sensor objects. The TDx sensor is the data which the 3D Connexion mouse sends back.

   Private WithEvents Sensor As TDxInput.Sensor
   Private WithEvents Keyboard As TDxInput.Keyboard
   Private WithEvents Device As TDxInput.Device

This starts the feed of information

   Public Sub New()
       Device = New TDxInput.Device
       Sensor = Device.Sensor
       Keyboard = Device.Keyboard
 

       SetMotionTexts()
 

       Device.Connect()
 

   End Sub

This is a "listener" for changes in the sensor's state:

   Private Sub Sensor_SensorInput() Handles Sensor.SensorInput
 

       Me.SetMotionTexts()
 

   End Sub

This is an example procedure using inputs from the mouse:

   Private Sub SetMotionTexts()
 

       Dim Style1 As String = "f"
       Dim translation As TDxInput.Vector3D
       translation = Sensor.Translation
 

       Dim rotation As TDxInput.AngleAxis
       rotation = Sensor.Rotation
 

   End Sub

This 'signs out' from the mouse when you finish with it

   Protected Overrides Sub Finalize()
       Device.Disconnect()
       MyBase.Finalize()
   End Sub
 

 End Class

Don't worry about the exact details of this. All you need to know is that it created 7 variables:

Rotation.x: The rotation in the x axis as an accurate decimal

Rotation.y: Rotation in the y axis given as 0, -1 or 1. Rotation.y * rotation.Angle must be used for this.

Rotation.z: rotation in the z axis

rotation.angle: The total angle that the device has moved from its rest position

translation.x: The total translation in the x axis

translation.y: guess

translation.z: guess

translation.length: The distance the node of the device has moved from rest.