<div style="text-align:center;display:block;"> <img src ="http://remoriavr.com/development/lignum/images/LIGNUM Controller SDK.png"/> </div> <div style="text-align:center;display:block;"> <img id="platforms" usemap="#platforms" src ="http://remoriavr.com/development/lignum/images/platforms_2_1_v2.png" /> <map name="platforms" id="platforms"> <area alt="Android" title="Android" href="#android" shape="poly" coords="61,0,61,65,2,64,4,0" /> <area alt="iOS" title="iOS" href="#ios" shape="poly" coords="66,2,66,63,149,65,146,0" /> <area alt="Cordova" title="Cordova" href="#cordova" shape="poly" coords="155,3,157,62,226,61,230,0" /> <area alt="Windows" title="Windows" href="#windows" shape="poly" coords="240,62,239,3,304,3,309,62" /> <area alt="Mac OSX" title="Mac OSX" href="#macosx" shape="poly" coords="315,0,324,65,393,62,393,1" /> <area alt="Linux" title="Linux" href="#linux" shape="poly" coords="405,1,403,66,469,66,468,0" /> <area alt="Unity3D" title="Unity3D" href="#unity3d" shape="poly" coords="478,3,482,66,560,65,557,0" /> <area alt="Oculus Rift" title="Oculus Rift" href="#oculusrift" shape="poly" coords="564,0,569,63,631,64,629,0" /> </map> <!--<img id="platforms" usemap="#platforms" src ="http://remoriavr.com/development/lignum/images/platforms_2_1.png"/> <map id="platforms" name="platforms"> <area shape="rect" alt="Android" title="Android" coords="17,27,114,109" href="#android" /> <area shape="rect" alt="iOS" title="iOS" coords="121,27,222,108" href="#ios" /> <area shape="rect" alt="Cordova" title="Cordova" coords="230,27,314,110" href="#cordova" /> <area shape="rect" alt="Windows" title="Windows" coords="329,31,419,108" href="#windows" /> <area shape="rect" alt="Mac OSX" title="Mac OSX" coords="16,121,113,210" href="#macosx" /> <area shape="rect" alt="Linux" title="Linux" coords="122,123,222,209" href="#linux" /> <area shape="rect" alt="Unity3D" title="Unity3D" coords="230,124,314,210" href="#unity3d" /> <area shape="rect" alt="Oculus Rift" title="Oculus Rift" coords="328,126,416,210" href="#oculusrift" /> </map>--> </div> <br> # LIGNUM Controller SDK <table> <tbody> <tr> <td>Document status</td> <td>Development</td> </tr> <tr> <td>SDK Version</td> <td>2.2</td> </tr> <tr> <td>Latest Update</td> <td>21 September 2016</td> </tr> <tr> <td>Author</td> <td>Matteo Pisani</td> </tr> </tbody> </table> #### Links Website: <a href="#" onclick="window.open('http://remoriavr.com')">remoriavr.com</a> Blog: <a href="#" onclick="window.open('http://blog.remoriavr.com')">blog.remoriavr.com</a> #### Contacts General inquiries: <a href="#" onclick="window.open('mailto:hello@remoriavr.com')">hello[at]remoriavr.com</a> Technical support: <a href="#" onclick="window.open('mailto:support@remoriavr.com')">support[at]remoriavr.com</a> Team: <a href="#" onclick="window.open('mailto:team@remoriavr.com')">team[at]remoriavr.com</a> #### Copyright &copy; 2016 Remoria VR S.r.l., Via Marsala 29/H, 00185, Roma, P.IVA 13940971008 All rights reserved. <hr> #### Update History * 21 September 2016: SDK v2.2 released. * Changelog: * Addedd Samsung Gear VR (Powered by Oculus) compatibility. * 25 August 2016: SDK v2.1 released. * Changelog: * Added Oculus Rift compatibility * 11 August 2016: SDK v2.0 released. * Changelog: * Added Android compatibility * Added iOS compatibility * Added Cordova compatibility * Added Windows compatibility * Added Mac OSX compatibility * Added Linux/Raspberry Pi compatibility * Extended LIGNUM Controller SDK for Unity3D (iOS/Android/PC) * Added LIGNUM Firmware Uploader tools (Windows/Mac OSX/Linux) * 29 May 2016: SDK v1.0 released. * Changelog: * Added LIGNUM Controller SDK for Unity3D (iOS/Android) <hr> <a name="top"></a> # Index #### Supported platforms * <a href="#android">Android</a> * <a href="#ios">iOS</a> * <a href="#cordova">Cordova</a> * <a href="#windows">Windows</a> * <a href="#macosx">Mac OSX</a> * <a href="#linux">Linux</a> * <a href="#unity3d">Unity3D</a> * <a href="#oculusrift">Oculus Rift</a> * <a href="#gearvr">Gear VR</a> #### Tools * <a href="#fupwin">LIGNUM Firmware Uploader for Windows</a> * <a href="#fupmac">LIGNUM Firmware Uploader for Mac OSX</a> * <a href="#fuplin">LIGNUM Firmware Uploader for Linux</a> <hr> <a name="android"></a> #Android * Requirements * LIGNUM Controller Driver for Android * Google Android Studio 1. Creating a new Android Studio project 2. Installing LIGNUM Controller's Driver for Android 3. Accessing the LIGNUM Controller data 4. LIGNUM Controller packets 5. Additional requirements ### Requirements #### LIGNUM Controller Driver for Android Download our `LIGNUM Controller's Driver for Android` <a href="#" onclick="DownloadCounter('Android');window.open('https://github.com/remoriavr/lignum-android-driver/archive/master.zip')"><u>here</u></a> and unzip the `master.zip` archive. * Inside the folder you will find the `Android Studio Project` source code of `LIGNUM Android Driver`. Inside the directory `lignum-android-driver/app/libs/` you can find the `LIGNUM.jar` library that you can use separately in your own project. #### Google Android Studio We will assume that you have already installed the <a href="https://developer.android.com/studio/index.html"><u>Google Android Studio</u></a> on your machine, if not, follow the instructions on the official reference. ### 1. Creating a new Android Studio project Follow the steps on the official reference at this <a href="https://developer.android.com/studio/projects/create-project.html"><u>page</u></a> to setup a blank project. ### 2. Installing LIGNUM Controller's Driver for Android You can add the `LIGNUM.jar` file in the Android Studio as follows: * Unless you have it already, add a folder in your projectand named it `Libs`. * Keep the `*.jar` files inside this folder, that you want to use in your project. * In the `Project->Project` view, you will be able to see the jar file from Android Studio. * You may not see it in the `Project->Android` view. Right click on the `.jar` file and select the option `Add as Library` click `Ok`. Open your `Android Studio` <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_1.png) <br> Load the `lignum-android-driver` project <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_2.png) <br> Wait unitle `Gradle` has completed all the tasks <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_3.png) <br> On the left vertical bar, click on `Project` <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_4.png) <br> Click on `Android` on the top bar then on `Project` <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_5.png) <br> Inside the `app\libs` folder you can find `LIGNUM.jar` library <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_6.png) <br> Once you expand it, you will see the `com.lignum.driver` package that contains `BluetoothLeDriver.java` and the `BluetoothLeUart.java` classes <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_7.png) <br> To get your hands on the code, move inside `src\main\java\driver.lignum.com\` <br> Look inside `lignum_android_driver` folder and then open the `MainActivity.java` file in the editor <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_9.png) <br> Defining `private BluetoothLeUart uart;` you are able to prepare the `Bluetooth LE` on your device <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_8.png) <br> `LIGNUM Driver` will start the discovery process automatically: when a packet is received, the callback `onReceive(...)` is triggered. Here each packet will be processed. <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_10.png) <br> Once processed, each packet is forwarded to the viewport through the `Output(...)` method <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_11.png) <br> Plug your `Android` device in `Debug Mode` and run the app. In this way you can see the entire code flow inside the log console From the `Android` device side, the output flow will be this: * App launch * LIGNUM Controller Discovery * Connection * Communication <br> ![](http://remoriavr.com/development/lignum/screens/android/android.png) <br> ### 3. Accessing the LIGNUM Controller data `LIGNUM Controller` sends encoded data received by your `Android` device via `Bluetooth LE`. To access `LIGNUM Controller` data inside your application, you have to define the following: * Variables ``` private BluetoothLeUart uart; private String blepacket; ``` * Methods ``` // Initialize UART. @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); uart = new BluetoothLeUart(getApplicationContext()); Output("STATUS: onCreate Called"); } ``` ``` // OnResume, called right before UI is displayed. Connect to the bluetooth device. @Override protected void onResume() { super.onResume(); uart.registerCallback(this); uart.connectFirstAvailable(); Output("STATUS: onResume Called"); } ``` ``` // OnStop, called right before the activity loses foreground focus. Close the BTLE connection. @Override protected void onStop() { super.onStop(); uart.unregisterCallback(this); uart.disconnect(); Output("STATUS: onStop Called"); } ``` ``` // UART Callback event handlers. @Override public void onConnected(BluetoothLeUart uart) { Output("STATUS: Connected"); } ``` ``` // Connection failed advertisement @Override public void onConnectFailed(BluetoothLeUart uart) { Output("STATUS: Connection failed"); } ``` ``` // Advise when the UART device disconnected @Override public void onDisconnected(BluetoothLeUart uart) { Output("STATUS: Disconnected"); uart.unregisterCallback(this); uart.registerCallback(this); uart.connectFirstAvailable(); Output("STATUS: Reconnecting"); } ``` ``` // Send messages to label @Override public void onReceive(BluetoothLeUart uart, BluetoothGattCharacteristic rx) { blepacket += rx.getStringValue(0); String[] buffer = blepacket.split("\\|"); if(buffer.length>2) { Output(buffer[1] + "|"); blepacket = ""; } } ``` ``` @Override public void onDeviceFound(BluetoothDevice device) { Output("STATUS: Device found - "+device.getName()+"["+device.getAddress()+"]"); } ``` ``` @Override public void onDeviceInfoAvailable() { Output("STATUS: Device info available - " + uart.getDeviceInfo()); } ``` ``` public void Output(final String message) { try { runOnUiThread(new Runnable() { @Override public void run() { Log.d("state", message); setContentView(R.layout.activity_main); TextView t = (TextView) findViewById(R.id.LIGNUM_STATUS); t.setText(message); } }); Thread.sleep(1); } catch (InterruptedException e) { e.printStackTrace(); } } } ``` To test that everything is working properly, perform this steps: 1. Connect an `Android` device to your `Mac` or `PC`. 2. Turn on `Bluetooth` on your device. 3. Plug your device to your machine via `USB` cable. 3. From `Anroid Studio`, run your appliaction. 4. The `log console` should pop out and you should see the `LIGNUM Controller packets` arriving to destination. <br> ![](http://remoriavr.com/development/lignum/screens/android/android_studio_12.png) <br> * By using `blepacket` variable defined above, your able to access over each incoming `LIGNUM Controller` RAW packet You can split and organize the received data. Moreover you will be able to manipulate and move 3D objects around. You can interact with them or perform any other kind of activity which could unleash all your creativity. ### 4. LIGNUM Controller packets Depending on the user input, `LIGNUM Controller` can send two kinds of `packets`: 1. Orientation tracking packet in the form: `-6.61,-97.24,198.43,1,4,0|` <br> ![](http://remoriavr.com/development/lignum/screens/packets/orientation.png) <br> 2. Motion gesture packet in the form: `gesture:forward-up-right|` <br> ![](http://remoriavr.com/development/lignum/screens/packets/motion.png) <br> Be aware that `EOP` means `End Of Packet`, represented by the `|` symbol. ### 5. Additional requirements (only for Android) If the `OS` version of your `Android` device is `>= 5.0` everything should works out fine. Otherwise, if your `Android` device is running an `OS` version `>= 6.0` you have to be aware of this: Google strengthened the `Android API` security level introducing the need to declare extra permissions in your `AndroidManifest.xml` to allow your applications to interoperate via `Bluetooth Low Energy` with external devices. ``` <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> ``` The above permission obliges the user to accept to turn on the `GPS` while running the app the first time: if user declines the permission, the app will not be able to access the entire `Bluetooth API` layer. ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="ios"></a> #iOS * Requirements * LIGNUM Controller Driver for iOS * Apple XCode 1. Creating a new XCode project 2. Installing LIGNUM Controller's Driver for iOS 3. Accessing the LIGNUM Controller data 4. LIGNUM Controller packets 5. Performance profiling ### Requirements #### LIGNUM Controller Driver Download our `LIGNUM Controller Driver for iOS` <a href="#" onclick="DownloadCounter('iOS');window.open('https://github.com/remoriavr/lignum-ios-driver/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. Inside the folder you will find: * `LIGNUM.h` Header file * `LIGNUM.m` Objective-C file. #### Apple XCode We will assume that you have already installed the <a href="https://developer.apple.com/download/"><u>Apple XCode</u></a> on your machine, if not, follow the instruction on the official reference. ### 1. Creating a new XCode project To start developing an iOS app you have to follow this steps: 1. Open XCode 2. Choose `File` -> `New` -> `New Project` <br> ![](http://remoriavr.com/development/lignum/screens/ios/1.png) <br> 3. Select the project template `Single View Application` for `iOS` and click `Next` 4. Enter the product name and the other project details and click `Next` <br> ![](http://remoriavr.com/development/lignum/screens/ios/2.png) <br> 5. Specify the project's container and its location in your file system, and click `Save` All software products require a project. The project organizes the files and resources needed to build one or more products, such as apps, plug-ins, and command-line tools. The New Project dialog displays platforms, template families, project templates, and a description for the selected project template. In the project options pane you enter information required by the template to generate the project, such as the product name. In the Save dialog you specify the container (one of your open projects or workspaces, and a group within it) and file-system location for the new project before completing the operation. For example, you can indicate that the container of the project be a project within your workspace instead of the workspace itself. After saving the project, XCode places a folder containing the new project’s files at the location you specified. Once you’ve created a project, you can add new source files and begin writing code. ### 2. Installing LIGNUM Controller's Driver for iOS What you need is to add a LIGNUM Driver files to your new project. This process places the new file at a specific location in your file system and creates a reference to it. To add a new file in the project navigator, select the project or group to which you want to add the file. 1. Right click on your project folder > `Add Files to ...` <br> ![](http://remoriavr.com/development/lignum/screens/ios/3.png) <br> 2. Import the `LIGNUM.m` and the `LIGNUM.h` files. <br> ![](http://remoriavr.com/development/lignum/screens/ios/4.png) <br> 3. You can add a file also by dragging it from its path to to the project navigator. <br> ![](http://remoriavr.com/development/lignum/screens/ios/7.png) <br> ### 3. Accessing the LIGNUM Controller data LIGNUM Controller sends encoded data received to your `iOS` device via `Bluetooth`. To access LIGNUM Controller data inside your application, you have to 1. Instantiate a `LIGNUM` object 2. Call the `setup` method to initiate the `Bluetooth LE` connection 3. Call the `list` method to initiate the `LIGNUM Controller` discovery ``` BLE_UART *LIGNUM_OBJECT = [BLE_UART new]; [LIGNUM_OBJECT setup]; [LIGNUM_OBJECT list]; ``` Place the above snippet according to your code as shown below: <br> ![](http://remoriavr.com/development/lignum/screens/ios/9.png) <br> To test that everything is working properly, perform this steps: 1. Connect an `iOS` device to your Mac 2. Turn on `Bluetooth` 3. From `XCode`, run your appliaction 4. The `log console` should pop out and you should see the `LIGNUM Controller packets` arriving to destination: <br> ![](http://remoriavr.com/development/lignum/screens/ios/5.png) <br> 5. By navigating in `LIGNUM.m` you are able to access to RAW packets inside the `bleDidReceiveData` method: <br> ![](http://remoriavr.com/development/lignum/screens/ios/8.png) <br> Here, you can get access over the `LIGNUM_PACKET` variable, split and organize the received data. You can split and organize the received data. Moreover you will be able to manipulate and move 3D objects around. You can interact with them or perform any other kind of activity which could unleash all your creativity. ### 4. LIGNUM Controller packets According to user input, `LIGNUM Controller` can perform send of two kind of `packets`: 1. Orientation tracking packet in the form: `-6.61,-97.24,198.43,1,4,0|` <br> ![](http://remoriavr.com/development/lignum/screens/packets/orientation.png) <br> 2. Motion gesture packet in the form: `gesture:forward-up-right|` <br> ![](http://remoriavr.com/development/lignum/screens/packets/motion.png) <br> Be aware that `EOP` means `End Of Packet`, represented by the `|` symbol. ### 5. Performance profiling In the `GitHub` package that includes the drivers, you can find the `LIGNUM iOS Driver` Demo Application written in native `Objective-C`. You can run the `LIGNUM iOS Driver.xcodeproj` to deploy source code to your `iOS` device. This is a sample screenshot in which you can easily check the `Bluetooth LE` packet flow: <br> ![](http://remoriavr.com/development/lignum/screens/ios/10.png) <br> `LIGNUM Controller Driver` for `iOS` is designed to be lightweight. As you can see in the performance monitor, CPU, Memory and Energy impacts are low. <br> ![](http://remoriavr.com/development/lignum/screens/ios/6.png) <br> ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="cordova"></a> #Cordova * Requirements * Node.js NPM * Cordova * Deploy tools (only for iOS) 1. Creating a new Cordova project 2. Installing LIGNUM Controller Plugin for Cordova 3. Accessing the LIGNUM Controller data 4. Deploying 5. Additional requirements (only for Android) ### Requirements We will assume that you have already installed the <a href="https://developer.android.com/studio/index.html"><u>Google Android Studio</u></a> or <a href="https://developer.apple.com/xcode/"><u>Apple XCode</u></a> on your system. ##### Node.js NPM If Node.js isn't installed yet on your system, take a look <a href="https://nodejs.org/en/download/package-manager/"><u>here</u></a> and follow the instructions according to your OS The `NPM` (Node Package Manager) will be installed and will be available in your OS command line. ##### Cordova Cordova command-line runs on `Node.js` and is available on `NPM`. You can find official installation guide <a href="https://cordova.apache.org/#getstarted"><u>here</u></a> You will use all the stuff inside in the later installation steps. #### Deploy tools (only for iOS) Execute from command-line: * `npm install -g ios-sim` * `npm install -g ios-deploy` or `sudo npm install --global --unsafe-perm ios-deploy` if error occurs. ### 1. Creating a new Cordova project Open the command-line and execute the following commands: * `cordova create lignum com.lignum.example "lignum"` * `cd lignum` * `cordova platform add ios` or `cordova platform add android` * `cordova prepare` or `cordova build` ### 2. Installing LIGNUM Controller Plugin for Cordova #### Installing the plugin Clone the plugin: `git clone https://github.com/remoriavr/cordova-plugin-lignum.git` Install the plugin: `cd lignum` `cordova -d plugin add ../cordova-plugin-lignum` ### 3. Accessing the LIGNUM Controller data After you have added `LIGNUM.js` to your `~/www/` path from any side of your JavaScript code you can easily access to `LIGNUM_CONTROLLER_DATA` JSON object: ``` var LIGNUM_CONTROLLER_DATA = { x : '0.0', y : '0.0', z : '0.0', joystick : '0', buttons : '0', battery : '0', gesture : '' } ``` Edit `~/www/index.js` and add the following code inside `<script>...</script>` tags: ``` document.addEventListener('deviceready', function () { // when Cordova starts, asks plugin to instantiate LIGNUM object LIGNUM(); // you can choose denoised x,y,z coordinates instead of unfiltered ones (default -> denoise = true) denoise = false; // set the interval to call the method 60 times per second setInterval(GET_LIGNUM_DATA(),15); // 15? => 1000ms/15 = ~60fps; }, false); // get control over LIGNUM Controller data by accessing to its entire status function GET_LIGNUM_DATA() { if(LIGNUM_CONTROLLER_DATA.gesture != '') { document.getElementById('gesture').innerText = 'gesture: ' + LIGNUM_CONTROLLER_DATA.gesture; // wait 750 ms before clean gesture variable setTimeout(function() { LIGNUM_CONTROLLER_DATA.gesture = ''; document.getElementById('gesture').innerText = 'gesture: '; },750); } else { document.getElementById('x').innerText = 'x: ' + LIGNUM_CONTROLLER_DATA.x; document.getElementById('y').innerText = 'y: ' + LIGNUM_CONTROLLER_DATA.y; document.getElementById('z').innerText = 'z: ' + LIGNUM_CONTROLLER_DATA.z; document.getElementById('joystick').innerText = 'joystick: ' + LIGNUM_CONTROLLER_DATA.joystick; document.getElementById('buttons').innerText = 'buttons: ' + LIGNUM_CONTROLLER_DATA.buttons; document.getElementById('battery').innerText = 'battery: ' + LIGNUM_CONTROLLER_DATA.battery; if(LIGNUM_CONTROLLER_DATA.x != '0.0' && LIGNUM_CONTROLLER_DATA.y != '0.0' && LIGNUM_CONTROLLER_DATA.z != '0.0') { if(denoise) document.querySelector('a-entity[id=lignum]').setAttribute('rotation', -y_denoised+ ' '+ -z_denoised + ' ' + -x_denoised); else document.querySelector('a-entity[id=lignum]').setAttribute('rotation', -LIGNUM_CONTROLLER_DATA.y+ ' '+ -LIGNUM_CONTROLLER_DATA.z + ' ' + -LIGNUM_CONTROLLER_DATA.x); } } } ``` As you can see, there is a `denoise` parameter (true|false) that allows you to choose filtered coordinates instead of raw ones. Faster output results comes with `denoise = false;`. Inside the `LIGNUM.js` script you can find the `processData` prototype method in which `LIGNUM Controller Data` is parsed and processed: ``` proto.processData = function(data) { pps++; if (data.indexOf(':') > 0) { LIGNUM_CONTROLLER_DATA.gesture = data.split(':')[1].replace('|',''); } else { data = data.replace('|','').split(','); if(data.length == 6) { LIGNUM_CONTROLLER_DATA.x = data[0]; LIGNUM_CONTROLLER_DATA.y = data[1]; LIGNUM_CONTROLLER_DATA.z = data[2]; LIGNUM_CONTROLLER_DATA.joystick = data[3]; LIGNUM_CONTROLLER_DATA.buttons = data[4]; LIGNUM_CONTROLLER_DATA.battery = data[5]; if(denoise) { this.populate(x_buffer,parseInt(data[0])); this.populate(y_buffer,parseInt(data[1])); this.populate(z_buffer,parseInt(data[2])); x_denoised = this.denoise(x_buffer); y_denoised = this.denoise(y_buffer); z_denoised = this.denoise(z_buffer); } } } }; ``` Under the `denoise` condition each coordinate buffer is populated and properly denoised: ``` // x,y,z buffer arrays var x_buffer = []; var y_buffer = []; var z_buffer = []; // x,y,z smoothed coordinates var x_denoised = 0.0; var y_denoised = 0.0; var z_denoised = 0.0; ``` ``` proto.populate = function(vector,number) { if(vector.length > 9) vector.shift(); vector.push(number); }; ``` ``` proto.denoise = function(vector) { var denoised_sum = vector.reduce(function(a, b) { return a + b; }); return parseInt(denoised_sum / vector.length); }; ``` As shown above, it's extremely simple to get control of your `LIGNUM Controller` through few lines of `JavaScript` code. ### 4. Deploying Once you are ready, you can deploy the application to your device in easy steps. Run the code on the emulator `cordova run ios` # or `cordova run android` Or on device `cordova run ios --device` # or `cordova run android --device` <br> ![](http://remoriavr.com/development/lignum/screens/cordova/cordova_ios_demo.png) <br> This is the `LIGNUM Cordova Demo` sandbox for `iOS`: same as the `Android` one, you can use it to test your `LIGNUM Controller` functionalities an trim the data according to your needs. Listed in the top-left corner the output values to be interpreted: * **status**: shows information about connection between `LIGNUM Controller` and the device * **compass**: the degrees of device internal compass * **battery**: shows battery level (0:charged|1:discharged) * **pps**: `Bluetooth LE` packets per second counter * **gesture**: recognized gesture in the form `gesture:up-forward-left|` * **x**: x axis coordinate degrees * **y**: y axis coordinate degrees * **z**: z axis coordinate degrees * **joystick**: shows joystick direction (from 1 to 8) * **buttons**: shows buttons combinations (from 1 to 7) ### 5. Additional requirements (only for Android) If the `OS` version of your `Android` device is `>= 5.0` everything should work out fine. Otherwise, if your `Android` device is running an `OS` version `>= 6.0` you have to be aware of this: Google strengthened the `Android API` security level introducing the need to declare extra permissions in your `AndroidManifest.xml` to allow your applications to interoperate via `Bluetooth Low Energy` with external devices. ``` <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> ``` The above permission obliges the user to accept to turn on the `GPS` while running the app the first time: if user declines the permission, the app will not be able to access the entire `Bluetooth API` layer. ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="windows"></a> #Windows * Requirements * LIGNUM Controller Universal Driver for Windows 1. Configuring an external Bluetooth LE 4.0/4.1 USB dongle 2. Running LIGNUM Controller Universal Driver application 3. Accessing LIGNUM Data 4. Accessing LIGNUM SandBox (directly from the browser) ### Requirements ##### LIGNUM Controller Universal Driver for Windows Download our `LIGNUM Controller Universal Driver for Windows` <a href="#" onclick="DownloadCounter('Windows');window.open('https://github.com/remoriavr/lignum-windows-driver/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. Inside the folder you will find all the needed files. ### 1. Configuring an external Bluetooth LE 4.0/4.1 USB dongle Most recent PCs and Laptops natively supports Bluetooth Low Energy standards, but if you are running on an old one, you may need an external Bluetooth LE 4.0/4.1 USB dongle to communicate with `LIGNUM Controller`. If your PC doesn't recognize the dongle properly, just perform the steps described below: 1. Inside the `tools` folder you will find `zadig_2.2.exe`: right click and run it as administrator <br> ![](http://remoriavr.com/development/lignum/screens/windows/zadig_1.png) <br> 2. Under `Options` menu, click on `List All Devices` <br> ![](http://remoriavr.com/development/lignum/screens/windows/zadig_2.png) <br> 3. From the combobox list, select your Bluetooth LE USB Dongle <br> ![](http://remoriavr.com/development/lignum/screens/windows/zadig_3.png) <br> 4. Click on `Install Driver` <br> ![](http://remoriavr.com/development/lignum/screens/windows/zadig_4.png) <br> 5. Done. You can now close `Zadig`. ### 2. Running LIGNUM Controller Universal Driver application After you have turned on your `LIGNUM Controller`, move inside the `LIGNUM Universal Driver` folder and double click on the `LIGNUM Universal Driver.bat` file. <br> ![](http://remoriavr.com/development/lignum/screens/windows/lignum_universal_driver_1.png) <br> If the `Bluetooth LE USB Dongle` is recognized properly, you should see this: <br> ![](http://remoriavr.com/development/lignum/screens/windows/lignum_universal_driver_2.png) <br> The driver will manage the pairing automatically then you will receive status update: `LIGNUM Controller Connected.` <br> ![](http://remoriavr.com/development/lignum/screens/windows/lignum_universal_driver_3.png) <br> Take note of the generated `http` links: through them you are able to check that `LIGNUM Controller` works properly. <br> ![](http://remoriavr.com/development/lignum/screens/windows/lignum_universal_driver_5.png) <br> You will see all the received packets inside the `LIGNUM Universal Driver` console once the connection occurred. <br> ![](http://remoriavr.com/development/lignum/screens/windows/lignum_universal_driver_4.png) <br> ### 3. Accessing LIGNUM Data `LIGNUM Universal Driver` redirects all the packets received from the controller to an `http` URL, as mentioned in the previous stage. Accessing LIGNUM data it is extremely easy: you can perform a `HTTP GET` call from any language to read the packet flow. ![](http://remoriavr.com/development/lignum/screens/windows/lignum_2.png) By navigating to the `http://127.0.0.1:5191` URL, you will able to get a `LIGNUM Controller Packet` per call, in a plain text output. This is an example in `JavaScript` that you can run also inside a browser or a web application: ``` <script> // building an ajax call var xhttp = new XMLHttpRequest(); xhttp.onreadystatechange = function() { if (xhttp.readyState == 4 && xhttp.status == 200) { // increasing pps counter; pps++; // managing received packet from http get call if (xhttp.responseText.indexOf(':') > 0) { // motion gesture type packet console.log('gesture: ' + data.split(':')[1].replace('|',''); } else { var LIGNUM_PACKET = xhttp.responseText.replace('|','').split(','); if(LIGNUM_PACKET.length == 6) { // orientation tracking type packet console.log('x: ' + LIGNUM_PACKET[0]); console.log('y: ' + LIGNUM_PACKET[1]); console.log('z: ' + LIGNUM_PACKET[2]); console.log('joystick: ' + LIGNUM_PACKET[3]); console.log('buttons: ' + LIGNUM_PACKET[4]); console.log('battery: ' + LIGNUM_PACKET[5]); } } } }; // packets per second counter method var pps = 0; // reset the pps counter after update setInterval(function() { console.log('pps:' + pps); pps = 0; },1000); // start polling the LIGNUM Universal Driver setInterval(function() { xhttp.open("GET", "http://127.0.0.1:5191", true); xhttp.send(); },15); </script> ``` ### 4. Accessing LIGNUM SandBox (directly from the browser) `LIGNUM Universal Driver` exposes an internal `SandBox` accessible via URL. By navigating to the `http://127.0.0.1:1915` URL you can fully test your `LIGNUM Controller` assuring that everything works properly: <br> ![](http://remoriavr.com/development/lignum/screens/windows/lignum_1.png) <br> Here you can monitor accurately each single variable according to `LIGNUM Controller` status. ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="macosx"></a> #OSX * Requirements * LIGNUM Controller Universal Driver for Mac OSX 1. Configuring an external Bluetooth LE 4.0/4.1 USB dongle 2. Running LIGNUM Controller Universal Driver application 3. Accessing LIGNUM Data 4. Accessing LIGNUM SandBox (directly from the browser) ### Requirements ##### LIGNUM Controller Universal Driver for Mac OSX Download our `LIGNUM Controller Universal Driver for Mac OSX` <a href="#" onclick="DownloadCounter('Mac');window.open('https://github.com/remoriavr/lignum-osx-driver/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. Inside the folder you will find all the needed files. ### 1. Configuring an external Bluetooth LE 4.0/4.1 USB dongle To make sure that your Mac supports Bluetooth Low Energy standards, hold on to the `Option` key and click on the `Bluetooth` icon on the menu bar. ![](http://remoriavr.com/development/lignum/screens/osx/bt_option_menu.png) If you see the version to be 4.0 or greater, then you’re ok. * If it's not version 4.0 (assuming your internal MacBook’s Bluetooth chipset is not BT 4.0 that is), one way to change this is to use an external Bluetooth LE dongle and then the `Bluetooth Explorer` tool that should be already installed on your Mac. * If it's not installed, inside the `tools` folder look for `Hardware_IO_Tools_for_Xcode_7.3.dmg`. * Double click to mount and open the image. * You will find `Bluetooth Explorer`: drag and drop it inside the `Applications` folder and double click to open it. ![](http://remoriavr.com/development/lignum/screens/osx/bt_explorer_finder.png) You can use Spotlight to quickly open the Bluetooth Explorer. * Once opened, you can go to `Tools -> HCI Controller Selector` ![](http://remoriavr.com/development/lignum/screens/osx/hci_controller_selector_menu.png) Then `Activate` the Bluetooth device of your choice by selecting it from the list. ![](http://remoriavr.com/development/lignum/screens/osx/hci_controller_selector.png) * Reboot your system. Once restarted, your Mac should now recognize the new Bluetooth device and you’re good to go. ### 2. Running LIGNUM Controller Universal Driver application After you have turned on your `LIGNUM Controller`, move inside the `LIGNUM Universal Driver` folder and double click on the `LIGNUM Universal Driver.command` file. <br> ![](http://remoriavr.com/development/lignum/screens/osx/osx_1.png) <br> A `shell` will open. <br> ![](http://remoriavr.com/development/lignum/screens/osx/osx_2.png) <br> If the `Bluetooth LE USB Dongle` is recognized properly, you should see this: <br> ![](http://remoriavr.com/development/lignum/screens/osx/osx_3.png) <br> Take note of the generated `http` links: through them you are able to check that `LIGNUM Controller` works properly. <br> ![](http://remoriavr.com/development/lignum/screens/osx/osx_7.png) <br> You will see all the received packets inside the LIGNUM Universal Driver console once the connection occurred. <br> ![](http://remoriavr.com/development/lignum/screens/osx/osx_4.png) <br> ### 3. Accessing LIGNUM Data `LIGNUM Universal Driver` redirects all the packets received from the controller to an `http` URL, as mentioned in the previous stage. Accessing `LIGNUM Data` it is extremely easy: you can perform a `HTTP GET` call from any language to read the packet flow. <br> ![](http://remoriavr.com/development/lignum/screens/osx/osx_6.png) <br> By navigating to the `http://127.0.0.1:5191` URL, you will able to get a `LIGNUM Controller Packet` per call, in a plain text output. This is an example in `JavaScript` that you can run also inside a browser or a web application: ``` <script> // building an ajax call var xhttp = new XMLHttpRequest(); xhttp.onreadystatechange = function() { if (xhttp.readyState == 4 && xhttp.status == 200) { // increasing pps counter; pps++; // managing received packet from http get call if (xhttp.responseText.indexOf(':') > 0) { // motion gesture type packet console.log('gesture: ' + data.split(':')[1].replace('|',''); } else { var LIGNUM_PACKET = xhttp.responseText.replace('|','').split(','); if(LIGNUM_PACKET.length == 6) { // orientation tracking type packet console.log('x: ' + LIGNUM_PACKET[0]); console.log('y: ' + LIGNUM_PACKET[1]); console.log('z: ' + LIGNUM_PACKET[2]); console.log('joystick: ' + LIGNUM_PACKET[3]); console.log('buttons: ' + LIGNUM_PACKET[4]); console.log('battery: ' + LIGNUM_PACKET[5]); } } } }; // packets per second counter method var pps = 0; // reset the pps counter after update setInterval(function() { console.log('pps:' + pps); pps = 0; },1000); // start polling the LIGNUM Universal Driver setInterval(function() { xhttp.open("GET", "http://127.0.0.1:5191", true); xhttp.send(); },15); </script> ``` ### 4. Running LIGNUM SandBox (directly from the browser) `LIGNUM Universal Driver` exposes an internal `SandBox` accessible via URL. By navigating to the `http://127.0.0.1:1915` URL you can fully test your `LIGNUM Controller` assuring that everything works properly: <br> ![](http://remoriavr.com/development/lignum/screens/osx/osx_5.png) <br> ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="linux"></a> #Linux * Requirements * LIGNUM Controller Driver for Linux * Node.js 1. Installing dependencies * Ubuntu/Debian/Raspbian Prerequisites * Fedora/Other RPM based distros 2. Configuring an external Bluetooth LE 4.0/4.1 USB dongle 3. Running LIGNUM Controller Universal Driver application 4. Accessing LIGNUM Data 5. Accessing LIGNUM SandBox (directly from the browser) ### Requirements ##### LIGNUM Controller Universal Driver for Linux Download our `LIGNUM Controller Universal Driver for Linux` <a href="#" onclick="DownloadCounter('Linux');window.open('https://github.com/remoriavr/lignum-linux-driver/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. * Inside the folder you will find the `LIGNUM.js` Driver script. #### Node.js If Node.js isn't installed yet on your system, take a look <a href="https://nodejs.org/en/download/package-manager/"><u>here</u></a> and follow the instructions according to your OS. Make sure node is on your path, if it's not **symlink** nodejs to node: `sudo ln -s /usr/bin/nodejs /usr/bin/node` ### 1. Installing dependencies * Linux Kernel version >= 3.6 * `lib-bluetooth-dev` * `bluetoothd` disabled. Use `sudo hciconfig hci0 up` to power Bluetooth adapter after stopping or disabling `bluetoothd` * `System V` * `sudo service bluetooth stop` (once) * `sudo update-rc.d bluetooth remove` (persist on reboot) * `systemd` * `sudo systemctl stop bluetooth` (once) * `sudo systemctl disable bluetooth` (persist on boot) #### Ubuntu/Debian/Raspbian * `sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev` #### Fedora/Other RPM based distros * `sudo yum install bluez bluez-libs bluez-libs-devel` ### 2. Configuring an external Bluetooth LE 4.0/4.1 USB dongle Most recent PCs and Laptops natively supports `Bluetooth Low Energy` standards, but if you are running on an old one, you may need an external `Bluetooth LE 4.0/4.1 USB` dongle to communicate with `LIGNUM Controller`. If your PC running `Linux` doesn't recognize the dongle properly, just perform the steps described below: <div style="max-width:100%;"> * Open a `terminal` shell and get `sudo` privileges with `sudo su` typing your password * `sudo apt-get update` * `sudo apt-get -y install libusb-dev libdbus-1-dev libglib2.0-dev libudev-dev libical-dev libreadline-dev` * `wget http://www.kernel.org/pub/linux/bluetooth/bluez-5.41.tar.xz` * `tar xvfJ bluez-5.41.tar.xz` * `cd bluez-5.41` * `./configure --disable-systemd` * `make` * `sudo cp ./src/bluetoothd /usr/local/bin/` * `sudo nano /etc/rc.local` * Scroll through the file and near the end before the 'exit 0' line add the following line to run bluetoothd: `/usr/local/bin/bluetoothd --experimental &` * `ps aux | grep bluetoothd` * The results should include a line similar to (but with different process IDs): `root 2263 0.0 0.3 4624 3428 ? S Aug14 0:04 /usr/local/bin/bluetoothd --experimental` * For a Raspberry Pi or Debian/Ubuntu machine run this command: `sudo apt-get install python-dbus` </div> To test if your `Bluetooth Low Energy USB` dongle is recognized properly, run `lsusb` and you should see it in the list as showed below: <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_1.png) <br> Try also `hcitool dev` to see if the `hci0` device has a valid `MAC Address` <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_2.png) <br> ### 3. Running LIGNUM Controller Universal Driver application After you have turned on your `LIGNUM Controller`, open a `terminal` shell and perform `sh LIGNUM Universal Driver.sh` bash script execution. <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_3.png) <br> If the `Bluetooth LE USB Dongle` is recognized properly, you should see this: <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_4.png) <br> The driver will manage the pairing automatically then you will receive status update: `LIGNUM Controller Connected`. <br> Take note of the generated `http` links: through them you are able to check that `LIGNUM Controller` works properly. <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_5.png) <br> You will see all the received packets inside the `LIGNUM Universal Driver` console once the connection occurred. <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_7.png) <br> Here you can monitor accurately each single variable according to `LIGNUM Controller` status. ### 4. Accessing LIGNUM data `LIGNUM Universal Driver` redirects all the packets received from the controller to an `http` URL, as mentioned in the previous stage. Accessing LIGNUM data it is extremely easy: you can perform a `HTTP GET` call from any language to read the packet flow. <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_9.png) <br> By navigating to the `http://127.0.0.1:5191 URL`, you will able to get a `LIGNUM Controller Packet` per call, in a plain text output. This is an example in `JavaScript` that you can run also inside a browser or a web application: ``` <script> // building an ajax call var xhttp = new XMLHttpRequest(); xhttp.onreadystatechange = function() { if (xhttp.readyState == 4 && xhttp.status == 200) { // increasing pps counter; pps++; // managing received packet from http get call if (xhttp.responseText.indexOf(':') > 0) { // motion gesture type packet console.log('gesture: ' + data.split(':')[1].replace('|',''); } else { var LIGNUM_PACKET = xhttp.responseText.replace('|','').split(','); if(LIGNUM_PACKET.length == 6) { // orientation tracking type packet console.log('x: ' + LIGNUM_PACKET[0]); console.log('y: ' + LIGNUM_PACKET[1]); console.log('z: ' + LIGNUM_PACKET[2]); console.log('joystick: ' + LIGNUM_PACKET[3]); console.log('buttons: ' + LIGNUM_PACKET[4]); console.log('battery: ' + LIGNUM_PACKET[5]); } } } }; // packets per second counter method var pps = 0; // reset the pps counter after update setInterval(function() { console.log('pps:' + pps); pps = 0; },1000); // start polling the LIGNUM Universal Driver setInterval(function() { xhttp.open("GET", "http://127.0.0.1:5191", true); xhttp.send(); },15); </script> ``` You can also use `cURL` to satisfy your needs: * cURL example: * `cURL http://127.0.0.1:5191` * output: `-97.13,128.46,-3.27,6,1,0|` in the form `x,y,z,joystick,buttons,battery|` for orientation tracking * or: `gesture:up-left-forward|` in the form `header:gesture|` for motion tracking ### 5. Accessing LIGNUM SandBox (directly from the browser) LIGNUM Universal Driver exposes an internal SandBox accessible via URL. By navigating to the `http://127.0.0.1:1915` URL you can fully test your `LIGNUM Controller` assuring that everything works properly: <br> ![](http://remoriavr.com/development/lignum/screens/linux/linux_8.png) <br> Here you can monitor accurately each single variable according to `LIGNUM Controller` status. ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="unity3d"></a> # Unity3D * Requirements * LIGNUM Controller SDK Package 1. Release Statement 1. Foreword 2. Development Overview 3. Test Environment 4. Notes 5. Technical Support 2. SDK Setup 1. Import Resource Package 2. Configuring LIGNUM Controller Input 3. Bluetooth LE Pairing 3. Programming 1. Orientation 2. Motion Gestures 3. Joystick 4. Buttons 5. Battery 4. Developing with Google Cardboard 1. SDK Environment Setup 2. Google Android Build 3. Apple iOS Build 5. Demo and Samples 1. Unity3D Demo (iOS/Android) 6. Accessing LIGNUM Controller directly from Unity3D ### Requirements Download our `LIGNUM Controller SDK` <a href="#" onclick="DownloadCounter('Unity3D');window.open('https://github.com/remoriavr/lignum-unity3d-sdk/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. * Inside the folder you will find two Unity3D Packages: * LIGNUM Controller SDK v1.0.unitypackage * Contains Unity3D Scripts and BLE Drivers for iOS and Android devices * CardboardSDKForUnity.unitypackage * Contains Stereoscopy tools for developing Virtual Reality games/applications ## 1. Release Statement ### 1.1 Foreword This SDK is designed mainly for Unity3D Engine based development. Future releases will support additional development environments (i.e. Unreal Engine 4). ### 1.2 Development Overview Please check the **LIGNUM Controller** to make sure the battery is charged and everything works properly. Demo videos can be found on our YouTube channel. ### 1.3 Test Environment * **Operating System (OS)**: * Windows 7/8/8.1/10 PC * Mac OSX >= 10.7.5 * Linux Debian GNU/Linux Based distro * **Bluetooth LE Dongle**: CSR 4.0 BLE USB Adapter * **Unity3D Engine**: Version 5.3.4f1 * **Apple XCode**: Version 7.3.1 * **Google Android Studio**: Version 2.0 ### 1.4 Notes 1. This `SDK` is `OS` independent, so you can develop on whichever system you like. 2. You can use older version of `Unity3D Engine`. However other versions are not verified. 3. Due to VR support and optimization, it is recommended to use `Unity3D Engine` Versions >= 5.X. ### 1.5 Technical Support * E-Mail: support[at]remoriavr.com ## 2. SDK Setup ### 2.1 Import Resource Package 1. In an empty Unity3D project, click Unity menu `Assets -> Import -> Package -> Custom Package` ![](http://remoriavr.com/development/lignum/screens/2.1.1.png) 2. In the file selection dialog, select `LIGNUM Controller SDK v1.0.unitypackage` ![](http://remoriavr.com/development/lignum/screens/2.1.2.png) 3. In `Importing package`, click `Import` ![](http://remoriavr.com/development/lignum/screens/2.1.3.png) 4. Done. There will be two folders named `Plugins` and `LIGNUM Controller SDK` under `Assets` root. ### 2.2 Configuring LIGNUM Controller Input 1. Click Unity menu `File -> New Scene`, to create a new scene (optional, you can use an existing one). ![](http://remoriavr.com/development/lignum/screens/2.2.1.png) 2. Click Unity menu `GameObject -> Create Empty` to add an object and rename it `LIGNUM`. * NOTE: Make sure that the name you assign to the object that you want to control is the same you use in the setup configuration (see steps below for further details). ![](http://remoriavr.com/development/lignum/screens/2.2.2.png) 3. Drag the `INPUT.cs` script from `Assets/LIGNUM Controller SDK/Scripts` the `INPUT.cs` and drop it onto `LIGNUM` object ![](http://remoriavr.com/development/lignum/screens/2.2.3.png) 4. Now you will see the `INPUT.cs` behavior attached to `LIGNUM` object. ![](http://remoriavr.com/development/lignum/screens/2.2.4.png) 5. By clicking on settings wheel on the `INPUT.cs` behavior you will open a dropdown menu. Now click on `Edit Script`. You will be able to make changes with `MonoDevelop Editor`. ![](http://remoriavr.com/development/lignum/screens/2.2.5.png) 6. By reading comments related to `INPUT.cs` source code, you will easily understand how the code logics work. * Find below the whole communication stack and the relation between **LIGNUM Controller** and its Unity3D Engine script: ![](http://remoriavr.com/development/lignum/screens/2.2.6.png) ### 2.3 Bluetooth LE Pairing The **LIGNUM Controller Driver** is meant to be painlessly integrated. No cumbersome settings are needed to connect the controller to your device. You just need to turn `ON` the Bluetooth on both your device and your **LIGNUM Controller**. They will pair automatically in just few seconds. ## 3. Programming It is extremely easy to access **LIGNUM Controller** data. Once the `INPUT.cs` has been executed and the `setup(...)` method has been called inside the `Start(...)` function, you can call the static class `LIGNUM.CONTROLLER_DATA` to access its values from any script located in your project. ### 3.1 Orientation **LIGNUM Controller** allows you to define the orientation of the 3D object you want to control (3 Degrees of Freedom). ``` float x = LIGNUM.CONTROLLER_DATA.x; float y = LIGNUM.CONTROLLER_DATA.y; float z = LIGNUM.CONTROLLER_DATA.z; ``` * Values ranges * **x**: [-180.0f, 180.0f] * **y**: [-180.0f, 180.0f] * **z**: [0.0f, 360.0f] ### 3.2 Motion Gestures You can perform several motions gestures moving your **LIGNUM Controller** in the air. ``` string gesture = LIGNUM.CONTROLLER_DATA.gesture; ``` * 1-Dimension Gestures: * **up** * **down** * **forward** * **backward** * **left** * **right** * 2-Dimensions Gestures: * **up-forward** * **up-backward** * **up-left** * **up-right** * **forward-left** * **backward-right** * **forward-up** * **forward-down** * **left-down** * **right-down** * 3-Dimensions Gestures: * **up-forward-left** * **up-forward-right** * **up-backward-left** * **up-backward-right** * **down-forward-left** * **down-forward-right** * **down-backward-left** * **down-backward-right** ### 3.3 Joystick You can move 3D objects inside the scene with the Joystick on the top side of your **LIGNUM Controller**. ``` string joystick = LIGNUM.CONTROLLER_DATA.joystick; ``` * Values range * **joystick**: ["1","8"] * Directions * **1**: North * **2**: North-East * **3**: East * **4**: South-East * **5**: South * **6**: South-West * **7**: West * **8**: North-West ### 3.4 Buttons Each button input (or a combination of multiple buttons) is coded into a single number. ``` string buttons = LIGNUM.CONTROLLER_DATA.buttons; ``` * Values range * **buttons**: ["1","7"] * Events * **1**: A *pressed* * **2**: B *pressed* * **3**: C *pressed* * **4**: A+B *pressed* * **5**: A+C *pressed* * **6**: B+C *pressed* * **7**: A+B+C *pressed* <b>NOTE: </b> The `A` button `long press` action will enable `motion gesture` sampling. After the `motion gesture` ends `LIGNUM Controller` will send a `gesture' packet. ### 3.5 Battery Battery status has only `charged` and `discharged` states. ``` string battery = LIGNUM.CONTROLLER_DATA.battery; ``` * Values range * **battery**: ["0","1"] * States * **0**: charged * **1**: discharged ## 4. Developing with Google Cardboard ### 4.1 SDK Environment Setup 1. Create an empty Unity3D project 2. Import the Cardboard SDK for Unity3D package (download <a href="#" onclick="DownloadCounter('Unity3D');window.open('https://github.com/remoriavr/lignum-unity3d-sdk/archive/master.zip');"><u>here</u></a>) ![](http://remoriavr.com/development/lignum/screens/4.1.2.png) ![](http://remoriavr.com/development/lignum/screens/4.1.3.png) ![](http://remoriavr.com/development/lignum/screens/4.1.4.png) 3. In `File menu -> Build Settings -> Player Settings -> Other Settings -> Configuration -> Scripting Define Symbols` add compilation flag `CARDBOARD_SDK`. ![](http://remoriavr.com/development/lignum/screens/4.1.5.png) ![](http://remoriavr.com/development/lignum/screens/4.1.6.png) ![](http://remoriavr.com/development/lignum/screens/4.1.7.png) 4. Change `Bundle Identifier` ![](http://remoriavr.com/development/lignum/screens/4.1.8.png) 5. To setup a Stereoscopic Camera, go to `Assets -> Cardboard -> Prefabs` and drop `CardboardMain` into `LIGNUM` object. ![](http://remoriavr.com/development/lignum/screens/4.1.9.png) 6. Navigate to the `Cardboard` behavior to setup the Stereoscopic view by trimming its `General Settings` ![](http://remoriavr.com/development/lignum/screens/4.1.10.png) 7. You are now ready to develop immersive Virtual Reality experiences ![](http://remoriavr.com/development/lignum/screens/4.1.11.png) ### 4.2 Google Android Build You can perform the **Android** application build process in two steps: 1. Application package (.apk file) is generated with all the required libraries and serialized assets. 2. Application package is deployed on the actual Android device directly from `Unity3D Engine`. To perform both steps, this guide assumes you have already installed and configured `Android SDK`. Take a look <a href="http://docs.unity3d.com/Manual/android-sdksetup.html"><u>here</u></a> for more info. * Steps: 1. Connect your Android device to PC via USB 2. Open your Unity3D Engine project 3. Go to `File menu -> Build Settings ![](http://remoriavr.com/development/lignum/screens/4.1.5.png) 4. Click and choose **Android** under Platform ![](http://remoriavr.com/development/lignum/screens/4.2.1.png) 5. Click on `build` and choose a name for your output *.apk file ![](http://remoriavr.com/development/lignum/screens/4.2.2.png) 6. Wait while until the building process completes ![](http://remoriavr.com/development/lignum/screens/4.2.3.png) ### 4.3 Apple iOS Build The **iOS** application build process is performed in two steps: 1. Application package (.ipa file) is generated with all the required libraries and serialized assets. 2. Application packaged is deployed on the actual iOS device passing from Unity3D Engine through XCode build. To perform both steps, this guide assumes you have already installed and configured Apple XCode. Take a look <a href="http://docs.unity3d.com/Manual/iphone-GettingStarted.html"><u>here</u></a> for more info. * Steps: 1. Connect your Apple device to PC via USB 2. Open your Unity3D Engine project 3. Go to `File menu -> Build Settings` ![](http://remoriavr.com/development/lignum/screens/4.1.5.png) 4. Click and choose **iOS** under Platform ![](http://remoriavr.com/development/lignum/screens/4.3.1.png) 5. Click on `build` and choose a name for your output XCode project folder ![](http://remoriavr.com/development/lignum/screens/4.3.2.png) 6. Wait while the building process completes ![](http://remoriavr.com/development/lignum/screens/4.3.3.png) 7. Open the folder you just generated and execute the XCode project ![](http://remoriavr.com/development/lignum/screens/4.3.4.png) 8. Once XCode has started you need to perform some fundamental sub-steps before running: 1. Go to `Build Settings -> Build Option -> Bitcode` and set it to `No` ![](http://remoriavr.com/development/lignum/screens/4.3.5.png) 2. Go to `Build Phases -> Link Binary With Libraries` ![](http://remoriavr.com/development/lignum/screens/4.3.6.png) 3. Add `CoreBluetooth.framework` ![](http://remoriavr.com/development/lignum/screens/4.3.7.png) 4. Add `Security.framework` ![](http://remoriavr.com/development/lignum/screens/4.3.8.png) 9. Click on **Run** and wait until the building process completes ## 5. Demo and Samples ### 5.1 Unity3D Demo (iOS/Android) Remoria VR is proud to release all its development stuff. You can download `LIGNUM Controller Demos.zip` from <a href="http://dev.remoriavr.com/lignum/demos/LIGNUM Controller Demos.zip"><u>here</u></a>. It contains a Unity3D project with three Mobile VR Demos to play and edit/ Now any developer can easily make amazing Virtual Reality experiences with **LIGNUM Controller**. Look at the source code inside the package and start playing around. ![](http://remoriavr.com/development/lignum/screens/5.1.0.png) Once you open the Unity3D Project, you will able to see three demos: 1. **Shoot**: a shooting range in which you can aim a rifle, switch between targets, shoot and reload ![](http://remoriavr.com/development/lignum/screens/5.1.1.png) 2. **Fly**: become a VR Pilot with this flight simulator! You can Pitch, Roll and Yaw a biplane, switching camera to feel more o less immersed. ![](http://remoriavr.com/development/lignum/screens/5.1.2.png) 3. **Explore**: feel like an Astronaut landed on the Moon, move on the surface and interact with the Lunar Rover by switching controls from Static to Dynamic. ![](http://remoriavr.com/development/lignum/screens/5.1.3.png) ## 6. Accessing LIGNUM Controller directly from Unity3D Following the tutorials above according to your `OS`, you will able to setup your machine to run `LIGNUM Controller` driver that forwards packets from a `Bluetooth LE USB Dongle` to an `http` URL. Once the driver is fully running, you will able to run your project inside `Unity3D` editor and to move your objects inside the environment directly from your `LIGNUM Controller`. If you have not installed yet our `LIGNUM SDK for Unity3D Game Engine` take a look at the beginning of this section and follow the guidelines. To allow `Unity3D` to do this, just look inside the `Assets` folders: under the `Scripts` subfolder you will find the `HOST.cs` script. <br> ![](http://remoriavr.com/development/lignum/screens/unity3d/unity3d_1.png) <br> Drag it and drop it on the `LIGNUM` object that you want to move: it will start polling the driver URL looking for `LIGNUM Controller` packets. <br> ![](http://remoriavr.com/development/lignum/screens/unity3d/unity3d_2.png) <br> Run your project and look at output console: you will see all the incoming packets arriving from the driver: <br> ![](http://remoriavr.com/development/lignum/screens/unity3d/unity3d_3.png) <br> Once received, the `HOST.cs` script will forward the packet to the `LIGNUM.SET_CONTROLLER_DATA(www.data)` method which will set the `LIGNUM Controller` status to the static object `LIGNUM.CONTROLLER_DATA`. <br> ![](http://remoriavr.com/development/lignum/screens/unity3d/unity3d_4.png) <br> As you can see, the `HOST.cs` digests each `LIGNUM Controller Driver` packet forwarded by its own driver. <br> ![](http://remoriavr.com/development/lignum/screens/unity3d/unity3d_5.png) <br> ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="oculusrift"></a> # Oculus Rift * Requirements * Oculus Rift Driver Setup * Windows * Mac OSX * Unity3D configuration ### Requirements #### Oculus Rift Driver Setup Before you can use the `SDK`, you must set up the drivers for your operating system. If your drivers are already set up, you can skip this section. This content repeats the instructions in the `Oculus Rift` User Guide. #### Installing the Runtime Package If you do not have it yet, download the Oculus Runtime Installer from the Oculus website. The `Runtime` is available from <a href="#" onclick="window.open('https://developer.oculus.com/downloads/');"><u>here</u></a>. This will install the following components: * Oculus Display Driver (Windows Only) * Oculus Positional Tracking Sensor Driver * Oculus Service Application * Oculus System Tray Application and Configuration Utility ### Windows This section describes how to install the `Windows Runtime Package`. To install the package: 1. Download the runtime from <a href="#" onclick="window.open('https://developer.oculus.com/downloads/');"><u>here</u></a>. 2. In the `Windows Control Panel`, go to `Programs -> Programs and Features` and uninstall any existing components. 3. Run the install executable found in the downloaded package. This will install all the components described above and prompt you to restart your computer. 4. Restart your computer. ### Mac OSX This section describes how to install the `Mac OSX Runtime Package`. To install the package: 1. Download the runtime from <a href="#" onclick="window.open('https://developer.oculus.com/downloads/');"><u>here</u></a>. 2. Run the installer application found inside the package. This will install all components described above for the current user only. You must run the installer for each user that wants to use the Rift. 3. Since the `Mac OSX` does not currently support direct rendering, you must adjust your display settings to rotate the display by 90 degrees for the `Oculus Rift DK2`. 4. The display settings are located in `System Preferences -> Displays`. Additionally, consider disabling display mirroring via the `Mirror Displays` check box on the display adjustment tab. 5. If you want to remove the `Runtime` package for the current user, run the provided `Uninstaller` or run the `OculusDirectory/Agent/uninstallAgent.sh` shell script from the command line. ## Unity3D integration * This section describes: * How to setup `Oculus Rift SDK` inside `Unity3D` engine. * How to setup `Unity3d` engine to develop `VR` experiences. * How to setup `LIGNUM Controller SDK v2.0` in your project. <br> * Surfing on `Oculus Rift` download section, look for * OVR Unity3D Utilities * OVR Platform SDK * Download them according to your OS. * Once downloaded, unzip the files in their respective folders. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/1.png) <br> * Inside the `OVR Unity3D Utilities` folder you will find the `OculusUtilities.unitypackage` file. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/2.png) <br> * Drag it and drop it on your `Asset` folder inside your `Unity3D` project <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/3.png) <br> * Wait until the package will be fully loaded. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/4.png) <br> * Once loaded, an `Import Unity Package` prompt window will be showed. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/5.png) <br> * Click on `Import` to continue. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/6.png) <br> * Inside the `OVR Platform SDK` folder you will find the `Unity` subfolder: look inside for `OculusPlatform.unitypackage` file. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/7.png) <br> * Drag it and drop it <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/8.png) <br> * Wait until the package will be fully loaded. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/9.png) <br> * Once loaded, an `Import Unity Package` prompt window will be showed. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/10.png) <br> * Click on `Import` to continue. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/11.png) <br> * Go to `File->Build Settings`. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/12.png) <br> * Click on `Player Settings`. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/13.png) <br> * Under the `Other Settings` tab, check `Virtual Reality Supported`. You should see `Oculus` under the `Virtual Reality SDKs` label. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/14.png) <br> * Right-click on `Assets->Import Package->Custom Package`. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/15.png) <br> * Select the `LIGNUM Contrller SDK v2.0.unitypackage` file. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/16.png) <br> * Once loaded, an `Import Unity Package` prompt window will be showed. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/17.png) <br> * Click on `Import` to continue. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/18.png) <br> * Right-click on the object you want to interact through `LIGNUM Controller`, click on `Rename` and rename it `LIGNUM`. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/19.png) <br> * Go inside the `Assets->LIGNUM Controller SDK v2.0->Scripts` folder, drag the `INPUT.cs` script and drop it over the `LIGNUM` object renamed before. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/20.png) <br> * Run your project in the editor and you should see `LIGNUM Controller` packets arriving. **NOTE**: remember to 1. Check that your `Oculus Rift` connected to your PC works properly. 2. Turn on your `LIGNUM Controller`. 3. Run `LIGNUM Controller Universal Driver` before running your demo, according to your OS. (Check developer section above for detailed informations). All the packets are forwarded due to `HOST.cs` script. <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/21.png) <br> As you can see, in the console will be showed the received `LIGNUM Controller` <br> ![](http://remoriavr.com/development/lignum/screens/oculusrift/unity3d/22.png) <br> ##### <a href="#top"><u>Back to top</u></a> <hr> <a name="gearvr"></a> # Gear VR (Powered by Oculus) * Requirements * LIGNUM Controller Driver for Gear VR * Gear VR Unity3D integration ### Requirements #### LIGNUM Controller Driver for Gear VR Before you can start developing for `Gear VR` in `Unity3D Game Engine`, you will need to setup `Unity3D` integration with `Oculus` and import the asset files. * Download our `LIGNUM Controller Driver for Gear VR` <a href="#" onclick="window.open('https://github.com/remoriavr/lignum-gearvr-driver/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. * Surfing on the official `Oculus Rift` download section <a href="#" onclick="window.open('https://developer3.oculus.com/downloads/');"><u>here</u></a>, look for the latest version of * `OVR Unity3D Utilities` * `OVR Platform SDK` * Once downloaded, unzip the files in their respective folders. * Launch `Unity3D` and run a project. * Drag the `LIGNUM Controller SDK v2.0.unitypackage` and drop it on the `Asset` folder inside the `Unity3D` project. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/6.png) <br> * Click on `Import` <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/7.png) <br> * Wait until the package will be fully loaded. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/8.png) <br> * From the menu, select `File -> Build Settings`. * Inside the `Build Setting` window, change the `Platform` to `Android` and the `Texture Compression` to `ETC2 (GLES 3.0)`. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/1.png) <br> * Click on the `Switch Platform`. * Click on `Player Settings` and under the `Other Settings` menu, check the `Virtual Reality Supported`. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/2.png) <br> * Drag the `OculusUtilities.unitypackage` and drop it on the `Asset` folder inside the `Unity3D` project. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/3.png) <br> * Click on `Import` <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/4.png) <br> * Wait until the package will be fully loaded. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/5.png) <br> * Before deploying your `Gear VR` compatible app, you need to sign it. Navigate to `https://dashboard.oculus.com/tools/osig-generator/` and follow the instructions. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/9.png) <br> * Once downloaded the generated `OSIG` file, drag it and drop it to your `Unity3D` project inside the folder `Assets\Plugins\Android\Assets`. <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/10.png) <br> * Connect your smartphone, click on `File -> Build and run` and wait: once deploy is complete, you should see this: <br> ![](http://remoriavr.com/development/lignum/screens/gearvr/11.png) <br> by connecting the device to your `Gear VR` headset, the app will run. ##### <a href="#top"><u>Back to top</u></a> <hr> # Tools * Requirements * Python2.7 * PySerial ### Requirements #### Python2.7 If you have not already installed it, get the `Python2.7` from the official website <a href="https://www.python.org/downloads/">here</a>, download the package according to your `OS`, execute it and follow the on-screen setup istructions. #### PySerial Once you have succesfully installed `Python2.7` on your machine, open a `terminal` and type: `python -m pip install pyserial` Wait that installation completes then you are ready to go ahead. <a name="fupwin"></a> # LIGNUM Firmware Uploader for Windows Download our `LIGNUM Firmware Uploader` <a href="#" onclick="DownloadCounter('Tools');window.open('https://github.com/remoriavr/lignum-firmware-uploader/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. You will find three folders: * Windows * Mac OSX * Linux Set on the right path, according to your `OS` choosing the right `LIGNUM Controller` by its CPU version: * ATMEL * CORTEX ### LIGNUM Controller (ATMEL CPU Model) * Put the provided `LIGNUM_Firmware.hex` file inside the `atmel` folder. * Connect your `LIGNUM Controller` via Micro-USB cable to your PC. * Open the `atmel` folder. * Double-click on `LIGNUM Firmware Uploader.bat` to run it. A `terminal` will open and you will see this: <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_1.png) <br> All the available `COM` ports will be listed. Manually input the `COM` port corresponding to your `LIGNUM Controller` and press `ENTER` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_2.png) <br> The program will start `LIGNUM RESET` procedure <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_3.png) <br> The `COM` port you chose may change after `RESET`, anyway a re-input will be asked for confirmation <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_4.png) <br> By pressing `ENTER` the program will perform serial connection with `LIGNUM Controller` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_5.png) <br> Following, the programmer will perform a `Read` action, when reaches 100% it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_6.png) <br> After the `Read` action, a `Write` action will be performed and after reaching 100% it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_7.png) <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_8.png) <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_9.png) <br> After some further checks, if everyting went fine you should see `LIGNUM Firmware updated successfully.` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_10.png) <br> ##### <a href="#top"><u>Back to top</u></a> ### LIGNUM Controller (CORTEX CPU Model) * Put the provided `LIGNUM_Firmware.bin` file inside the `cortex` folder. * Connect your `LIGNUM Controller` via Micro-USB cable to your PC. * Open the `cortex` folder. * Double-click on `LIGNUM Firmware Uploader.bat` to run it. A `terminal` will open and you will see this: <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/cortex_1.png) <br> All the available `COM` ports will be listed. Manually input the `COM` port corresponding to your `LIGNUM Controller` and press `ENTER` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/atmel_2.png) <br> The program will start `LIGNUM RESET` procedure <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/cortex_2.png) <br> The `COM` port you chose may change after `RESET`, anyway a re-input will be asked for confirmation <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/cortex_3.png) <br> By pressing `ENTER` the program will perform serial connection with `LIGNUM Controller` Following, the programmer will perform a `Read` action, after reaching 100% it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/cortex_4.png) <br> After some further checks, if everyting went fine you should see `Verify successful` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/cortex_5.png) <br> Finally you should see `LIGNUM Firmware updated successfully.` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/windows/cortex_6.png) <br> ##### <a href="#top"><u>Back to top</u></a> <a name="fupmac"></a> ### LIGNUM Firmware Uploader for Mac OSX Download our `LIGNUM Firmware Uploader` <a href="#" onclick="DownloadCounter('Tools');window.open('https://github.com/remoriavr/lignum-firmware-uploader/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. You will find three folders: * Windows * Mac OSX * Linux Set on the right path, according to your `OS` choosing the right `LIGNUM Controller` by its CPU version: * ATMEL * CORTEX ### LIGNUM Controller (ATMEL CPU Model) * Put the provided `LIGNUM_Firmware.hex` file inside the `atmel` folder. * Connect your `LIGNUM Controller` via Micro-USB cable to your Mac. * Open the `atmel` folder. * Double-click on `LIGNUM Firmware Uploader.command` to run it. A `terminal` will open and you will see this: <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/atmel_1.png) <br> All the available `SERIAL` ports will be listed. Manually input the `SERIAL` port corresponding to your `LIGNUM Controller` and press `ENTER` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/atmel_2.png) <br> The program will start `LIGNUM RESET` procedure <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/atmel_3.png) <br> Following, the programmer will perform a `Read` action, after reaching 100% it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/atmel_4.png) <br> After the `Read` action, a `Write` action will be performed and after reaching 100% it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/atmel_5.png) <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/atmel_6.png) <br> After some further checks, if everyting went fine you should see `LIGNUM Firmware updated successfully.` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/atmel_7.png) <br> ##### <a href="#top"><u>Back to top</u></a> ### LIGNUM Controller (CORTEX CPU Model) * Put the provided `LIGNUM_Firmware.bin` file inside the `cortex` folder. * Connect your `LIGNUM Controller` via Micro-USB cable to your Mac. * Open the `cortex` folder. * Double-click on `LIGNUM Firmware Uploader.command` to run it. A `terminal` will open and you will see this: <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/cortex_1.png) <br> All the available `SERIAL` ports will be listed. Manually input the `SERIAL` port corresponding to your `LIGNUM Controller` and press `ENTER` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/cortex_2.png) <br> The program will start `LIGNUM RESET` procedure <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/cortex_3.png) <br> Following, the programmer will perform an `Erase` action and then it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/cortex_4.png) <br> After the `Erase` action, a `Write` action will be performed and after reaching 100% it will almost done After some further checks, if everyting went fine you should see `Verify successful` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/cortex_5.png) <br> Finally you should see `LIGNUM Firmware updated successfully.` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/macosx/cortex_6.png) <br> ##### <a href="#top"><u>Back to top</u></a> <a name="fuplin"></a> ### LIGNUM Firmware Uploader for Linux Download our `LIGNUM Firmware Uploader` <a href="#" onclick="DownloadCounter('Tools');window.open('https://github.com/remoriavr/lignum-firmware-uploader/archive/master.zip');"><u>here</u></a> and unzip the `master.zip` archive. You will find three folders: * Windows * Mac OSX * Linux Set on the right path, according to your `OS` choosing the right `LIGNUM Controller` by its CPU version: * ATMEL * CORTEX ### LIGNUM Controller (ATMEL CPU Model) * Put the provided `LIGNUM_Firmware.hex` file inside the `atmel` folder. * Connect your `LIGNUM Controller` via Micro-USB cable to your Linux PC. * Open the `cortex` folder. * Open a `terminal` in. * Run as `sudo` the commands above: 1. `sudo cp lignum.rules /etc/udev/rules.d/` 2. `sudo reload udev` 3. `sudo udevadm control --reload-rules` 4. `sudo udevadm trigger` * Then run `sh "LIGNUM Firware Uploader.sh". A `terminal` will open and you will see this: <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/atmel_1.png) <br> All the available `SERIAL` ports will be listed. <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/atmel_2.png) <br> Manually input the `SERIAL` port corresponding to your `LIGNUM Controller` and press `ENTER` The program will start `LIGNUM RESET` procedure <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/atmel_3.png) <br> Following, the programmer will perform a `Read` action, after reaching 100% it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/atmel_4.png) <br> After the `Read` action, a `Write` action will be performed and after reaching 100% it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/atmel_5.png) <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/atmel_6.png) <br> After some further checks, if everyting went fine you should see `LIGNUM Firmware updated successfully.` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/atmel_7.png) <br> ##### <a href="#top"><u>Back to top</u></a> ### LIGNUM Controller (CORTEX CPU Model) * Put the provided `LIGNUM_Firmware.bin` file inside the `cortex` folder. * Connect your `LIGNUM Controller` via Micro-USB cable to your Linux PC. * Open the `cortex` folder. * Open a `terminal` in. * Run as `sudo` the command `sh "LIGNUM Firware Uploader.sh". <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/cortex_1.png) <br> All the available `SERIAL` ports will be listed. <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/cortex_2.png) <br> Manually input the `SERIAL` port corresponding to your `LIGNUM Controller` and press `ENTER` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/cortex_3.png) <br> The program will start `LIGNUM RESET` procedure Following, the programmer will perform an `Erase` action and then it will continue <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/cortex_4.png) <br> After the `Erase` action, a `Write` action will be performed and after reaching 100% it will almost done After some further checks, if everyting went fine you should see `Verify successful` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/cortex_5.png) <br> Finally you should see `LIGNUM Firmware updated successfully.` <br> ![](http://remoriavr.com/development/lignum/screens/firmware/linux/cortex_6.png) <br> ##### <a href="#top"><u>Back to top</u></a>