# Using the 3D Connexion SDK/Printable version

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

# 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.
* Next: A Quick Introduction to programming and Visual Basic
* Home

# 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:
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:
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:
Your complete code should look like this:

#### 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!
* Next: Using Variables
* Home

# 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.
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:
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:
Sets the value of A as 1.
Sets the value of A to the value of B.
Sets the value of A to 23 times the value of B.
We can also use A in assignation:
This increases the value of A by 1.
This doubles A
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:
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:
When Button1 is pressed, counter should increase by 1:
Counter = Counter + 1
Now, we need to add a line of code to update the text on the button:
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:
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 is greater than 1
A is less than 1
A is not equal to 1
A is less than 1, or A is equal to 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.
We have 2 conditions for our progress bar:
Both of these have to be true for the program to work, so let's use and to combine them:
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:
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
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.

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

The code used here was a decision making process:
* Next: Using Procedures
* Home

# 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:
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:
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:
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':
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:
We need to call DoubleMyNumber when the button is pressed. This is nice and simple; we just type its name:
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:
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:
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:
Here's the complete code:

### Functions

A function is like a procedure, but it is actually a variable. Let me explain:
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:
Like procedures, functions can have more than one parameter:
We have to declare functions in a different way:
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
## 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)
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:
Don't worry about this bit
Here, they add in the TDx Sensor objects. The TDx sensor is the data which the 3D Connexion mouse sends back.
This starts the feed of information
This is a "listener" for changes in the sensor's state:
This is an example procedure using inputs from the mouse:
This 'signs out' from the mouse when you finish with it
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.