from_scratch

This example walks through the entire process of setting up a Unity project to connect with a VectorNav sensor. Once you get to the end of the example, you will have the option of running the example on your computer or on an Android phone.

1. Startup Unity and create a new project from the menu File -> New Project.... The file location you choose to save the project will be referred to as the <TOP>.
   
   

2. Since we will be creating a 3D object and attaching it to yaw, pitch, roll data from a VectorNav sensor, we will need to get access to a serial port on the machine. The VectorNav .NET Library must make calls into the Win32 API (on Windows machine, see notes after the example for configuring for other environments) to access the serial port and this requires "unsafe" C# code compilation and must be enabled in Unity. Browse to the folder location <TOP>/Assets and create a new file called smcs.rsp. In this file, place the single line "-unsafe" without the quotes, save and close.

   NOTE: The above method for creating the file smcs.rsp only works if the project is configured to use just the .NET 2.0 Subset configuration, the default for a new project. However, if you have changed the Unity project to use the .NET 2.0 configuration, you will need to create the file called gmcs.rsp instead of smcs.rsp.

3. Create a simple cube and place it into the scene by going to the menu GameObject -> 3D Object -> Cube.
   
   
4. With the cube selected, add a new script by going to the Inspector on the right and click the Add Component button. From the drop-down, select the option "New Script" and name it Rotate. Make sure the language is CSharp.
   
   
5. Android Phone Step: If you will be deploying this application to an Android phone, you will need to include an additional library into the Unity project to allow access to a VectorNav sensor through the FTDI USB-to-Serial converter. We will make use of the d2xx.jar library provided by FTDI. First create the file path <top>/Assets/Plugins/Android/libs and place a copy of the d2xx.jar file located at <LIB_TOP>/libs/ftdi_d2xx. Placing this file in this folder location will allow Unity to properly package the d2xx.jar dependency when Android applications are created.
6. Under the Inspector, there should now be Rotate (Script) block. Open the script by double-clicking the "Rotate" icon in the field Script.
   
   
7. The MonoDevelop editor should now be started and displaying the new script code. We first want to add access to the VectorNav .NET Library so that we can connect to a sensor and get readings from it. And since Unity likes to keep all source code objects under the folder <TOP>/Assets, we will import the source files into the project folder. Right-click on the project file Assembly-CSharp and select the option Add -> Add Files From Folder.... Now browse to the VectorNav .NET Library folder located at <LIB_TOP>/net/core and click Open. You will now be asked to select which files to add. Select all of the top-level *.cs files and the sub-folders Communication, Data, Math, Protocol, and Sensor. You will then be asked to either copy, move or add a link to the files. Select the option Copy and click OK.
   
   
8. We should now have access to the code in the VectorNav .NET Library. Copy and paste the code below into the Rotate.cs file. The code comments explain what is going on with the code.
   
   

    using UnityEngine;
    using System;
    using System.Collections;
    using VectorNav.Communication;
    using VectorNav.Sensor;
    using VectorNav.Protocol.Uart;
    using VectorNav.Math;
    
    public class Rotate : MonoBehaviour
    {
        // Initialization of the script.
        void Start()
        {
            // This class will be used to scan for newly attached sensors and
            // will allow automatic connection to them.
            _acp = new AutoConnectPort();
            
            // Standard class for connecting and communicating with a VectorNav
            // sensor.
            _sensor = new VnSensor();
            
            // Use the overloaded Connect method to connect to an ISimplePort
            // object, which is implemented be our AutoConnectPort object.
            _sensor.Connect(_acp);
            
            // Register for event notification for whenever our sensor object
            // receives an asynchronous data packet, which will contain our
            // orientation information for rotating the 3D cube in Unity.
            _sensor.AsyncPacketReceived += HandleAsyncPacketReceived;
            
            // Start looking for any newly connected sensors.
            _acp.Start();
        }
        
        // Update any game objects once per frame.
        void Update()
        {
            // Give our sensor finder a chance to find any sensors or to
            // process any received data on the connected port.
            _acp.Update();
        }
        
        // This will be called whenever our sensor object has found a new
        // asynchronous data packet, hopefully containing our orientation data.
        void HandleAsyncPacketReceived(object sender, PacketFoundEventArgs e)
        {
            var p = e.FoundPacket;
            
            if (!p.IsAsciiAsync)
                // Might be a binary packet but we are not handling this
                // scenario in this example. Please refer to the net/examples/getting_started
                // for an example of how to parse binary data.
                return;
            
            // This is the factory default output data type for VN-100 sensors.
            if (p.AsciiAsyncType == AsciiAsync.VNYMR)
            {
                vec3f ypr, magnetic, acceleration, angularRate;
                
                // Now that we have identified the type of packet we have, we
                // can call the corresponding parse method.
                p.ParseVNYMR(
                    out ypr,
                    out magnetic,
                    out acceleration,
                    out angularRate);
                
                // Set the current orientation of the 3D cube. Note we must
                // convert the yaw, pitch, roll from the sensor reference
                // frame to the reference frame used by Unity.
                transform.localEulerAngles = Conv.VnYprInDegsToUnityEulerAngles(ypr);
            }
            
            // This is the factory default output data type for VN-200 and
            // VN-300 sensors.
            else if (p.AsciiAsyncType == AsciiAsync.VNINS)
            {
                double time;
                ushort week, status;
                vec3f ypr, nedVel;
                vec3d lla;
                float attUncertainty, posUncertainty, velUncertainty;
                
                // Now that we have identified the type of packet we have, we
                // can call the corresponding parse method.
                p.ParseVNINS(
                    out time,
                    out week,
                    out status,
                    out ypr,
                    out lla,
                    out nedVel,
                    out attUncertainty,
                    out posUncertainty,
                    out velUncertainty);
                
                // Set the current orientation of the 3D cube. Note we must
                // convert the yaw, pitch, roll from the sensor reference
                // frame to the reference frame used by Unity.
                transform.localEulerAngles = Conv.VnYprInDegsToUnityEulerAngles(ypr);
            }
            
            // If you have configured the sensor to output another message type,
            // you can add more parsers here.
       }
       
       private AutoConnectPort _acp;
       private VnSensor _sensor;
   }

   
   
9. We want to make sure the project builds correctly so we can catch and correct any errors before returning to Unity. However, we must first enable the "unsafe" code within the MonoDevelop environment. Enable this by right-clicking the project Assembly-CSharp and selecting Options. Now select the section Build -> General and make sure the option Allow 'unsafe' code is checked. Now check that the project builds correctly by right-clicking on the project Assembly-CSharp and selecting Build Assembly-CSharp. Make sure no errors were found. Close out of MonoDevelop to return to Unity.
   
   

10. We can now run the example on our preferred platform. Please refer to the appropriate section below for the specifics on running on each supported platform.

    Windows - Open the settings by going to File -> Build Settings.... Make sure the Platform option is set to PC, Mac & Linux Standalone and click the Build And Run button. If Unity prompts to save the *.exe file, choose a name and location to your likings and click Save. Unity should then compile and then run the program. If a configuration window pops up, make sure the option Windowed is checked and click the Play! button. The Rotate script will continuously search for a VectorNav sensor and when it finds it, it will connect and start using any yaw, pitch, roll data to rotate the 3D cube.

    Android - You will need to make sure you have an Android phone attached to the computer with debug mode enabled. You will also need an adapter to connect the USB cable of your VectorNav sensor into the Micro USB port of your phone. Please see the FAQ's How do I connect a VectorNav sensor to an Android phone? for information on getting a proper adapter. Open the settings by going to File -> Build Settings.... Make sure the Platform option is set to Android. Click on the button Player Settings... and in the Inspector pane on the right, update the Bundle Indentifier to a setting appropriate for your company and the project you are working on. The click the Build And Run button. If Unity prompts to save a *.apk file, choose a name and location to your likings and click Save. Unity should then compile, then push the program to your attached phone. The program should start automatically on the phone. Disconnect the phone from the computer and attach the VectorNav sensor to the phone with the USB adapter. The program should then detect and connect to the sensor and start rotating the displayed cube based on yaw, pitch, roll data from the sensor. If the message "Allow application from_scratch to access USB device?" pops up, click the OK button.