Nod Developer Center

Developer Guide

Visit OpenSpatial Windows to access the contents of the package:

  • Nod Installer – contains the setup files
  • Nod Plugin Source – a cpp and a header file for the Nod plugin to use along with Visual Studio
  • OpenSpatialExampleApp – a Visual Studio 2013 example project, showcasing how to integrate with the Nod plugin

Installing the service

  • Run Setup.exe from Nod Installer
  • From now on all relevant files will be at C:Program Files (x86)Nod LabsNod Configuration
  • There are 3 folders that will contain the SDK dependencies:
    • Dynamic SDK
    • SDK
    • Unity

The Dynamic SDK folder contains the ready to go DLL version of the SDK. This requires minimal linkage and is easy to get started with right away. It will also be what is covered in this guide.

The SDK folder contains a static version of the SDK. This is much more difficult to link against and requires some 3rd party libraries. Only use this if your application cannot use dynamic libraries (DLL) and you absolutely need a static library. For more information about this please visit/post on https://forums.nod.com. This SDK will be minimimally covered here.

The Unity folder contains the unity plugins for the service. These are just the bare unity plugins and do not include our Unity SDK. To get the full Unity SDK please visit our openspatial-unity repository. These have only been provided for versioning purposes. They should not need to be used and can be ignored.

NodConfig App

  • Pair devices via Bluetooth to your PC
  • Click the Refresh button to list available devices
  • Select a device and click Settings

Running example app

  • Open Visual Studio 2013
  • Build and run OpenSpatialExampleApplication/DLLTest.sln
  • The app will automatically subscribe to Euler Angles for the first device you have connected you should be able to see the output in the console
  • Now you are ready to start using the code. Please use the source code as a basic example of the workflow.

Writing your own application using the dynamic SDK

The dynamic SDK is the most straight forward and simple way to get started writing your own apps for Windows and OpenSpatial. We highly recommend using the Dynamic SDK as it is prone to much less problems and will keep your application size smaller (Our static lib requires a few 3rd party libraries)

  • There are 4 parts to the dynamic SDK:
    • OpenSpatialDll.dll
    • OpenSpatialDll.lib
    • NodPlugin.h
    • Settings.h

The DLL and lib have been provided in a 32 bit and 64 bit version both under the Dynamic SDK directory in corresponding x86 and x86_64 directories. Use the appropriate one to build for the architecture you desire.

To link in the SDK add NodPlugin.h and Settings.h into your include path. In visual studio this can be as simple as placing the files in your project directory. Or, more optimally, going to your project settings and adding the directory in which you want to store these files to your “additional include directories” path.

Next do the same with OpenSpatialDll.lib except place it in your library search path.

Next place the DLL in the same directory as the executable your project will generate. For Visual Studio projects you may just place it within your project directory.

Now to begin coding:

There are 9 functions you can call with this DLL:

NODPLUGIN_API bool NodInitialize(void(*evFiredFn)(NodEvent)); NODPLUGIN_API bool NodShutdown(void); NODPLUGIN_API bool NodRefresh(void);

NODPLUGIN_API int NodNumRings(void); const NODPLUGIN_API char* NodGetRingName(int ringID);

NODPLUGIN_API bool NodSubscribe(Modality mode, const char* deviceName); NODPLUGIN_API bool NodUnsubscribe(Modality mode, const char* deviceName);

NODPLUGIN_API bool NodRequestDeviceInfo(const char* deviceName); NODPLUGIN_API bool NodChangeSetting(const char* deviceName, Settings setting, int args[], int numArgs);

The SDK functions using a “callback” and “subscription” design. To initialize the SDK call NodInitialize. This function accepts a function pointer to a function which accepts one argument, a NodEvent struct. The function pointer passed into the NodInitialize function will be the “callback” function which will recieve all data.

After calling NodInitialize the service and your application will start communicating with each other. Because the connection takes a short time to be established and NodInitialize is asynchronous, any attempt to use your Nod device before the connection is established will not work. Your “callback” function will alert you connection is established.

The “callback” function:

The callback function should take the form of:

NODPLUGIN_API bool NodInitialize(void(*evFiredFn)(NodEvent)); NODPLUGIN_API bool NodShutdown(void); NODPLUGIN_API bool NodRefresh(void);

NODPLUGIN_API int NodNumRings(void); const NODPLUGIN_API char* NodGetRingName(int ringID);

NODPLUGIN_API bool NodSubscribe(Modality mode, const char* deviceName); NODPLUGIN_API bool NodUnsubscribe(Modality mode, const char* deviceName);

NODPLUGIN_API bool NodRequestDeviceInfo(const char* deviceName); NODPLUGIN_API bool NodChangeSetting(const char* deviceName, Settings setting, int args[], int numArgs);

The NodEvent struct is defined in NodPlugin.h and is as follows:

struct NodEvent {EventType type = NONE_T; int x = NOD_NONE; int y = NOD_NONE; int z = NOD_NONE; float xf = NOD_NONE; float yf = NOD_NONE; float zf = NOD_NONE; int trigger = NOD_NONE; float roll = NOD_NONE; float pitch = NOD_NONE; float yaw = NOD_NONE; float buttonID = NOD_NONE; UpDown buttonState = NONE_UD; int batteryPercent = NOD_NONE; GestureType gesture = NONE_G; FirmwareVersion firmwareVersion;};

The type field refers to the type of event contained within the NodEvent struct the types are (also defined in NodPlugin.h):

  • Button
  • Accelerometer
  • EulerAngles
  • AnalogData
  • Gestures
  • Pointer
  • Translation
  • Gyroscope
  • DeviceInfo
  • ServiceReady

For each event the NodEvent struct will only be populated with the information needed for that event.

  • Button -> buttonID, buttonState
  • Accelerometer -> xf, yf, zf
  • EulerAngles -> roll, pitch, yaw
  • AnalogData -> x, y, trigger
  • Gestures -> gesture
  • Pointer -> x, y
  • Translation -> x, y, z (Currently unsupported by firmware)
  • Gyroscope -> xf, yf, zf
  • DeviceInfo -> batteryPercent, firmwareVersion
  • ServiceReady -> none

The “subscribe” function:

struct NodEvent {EventType type = NONE_T; int x = NOD_NONE; int y = NOD_NONE; int z = NOD_NONE; float xf = NOD_NONE; float yf = NOD_NONE; float zf = NOD_NONE; int trigger = NOD_NONE; float roll = NOD_NONE; float pitch = NOD_NONE; float yaw = NOD_NONE; float buttonID = NOD_NONE; UpDown buttonState = NONE_UD; int batteryPercent = NOD_NONE; GestureType gesture = NONE_G; FirmwareVersion firmwareVersion;};

This function requests data of a certain mode from a device. Modalities are defined in NodPlugin.h in the modality enum and are as follows:

  • ButtonMode
  • AccelMode
  • EulerMode
  • GameControlMode
  • GestureMode
  • PointerMode
  • TranslationMode
  • GyroMode

So NodSubscribe(EulerMode, NodGetRingName(0)) will subscribe to EulerAngles for the ring with id 0.

This is the bare information you need to get started with a Nod Device on Windows. In summary here are the steps to develop:

Create a “callback” function call InitializeNod with your “callback” function wait for your callback function to be called with a type of “ServiceReady” Call NodNumRings() to determine the number of devices connected to your machine. Call NodGetRingName on the id of your choice (the id is between 0 and NodNumrings) to retrieve the device’s name. Call Subscribe and pass in the modality and ring name of your choosing. Your “callback” function should now be called whenever there is an update from your device.

Writing your own application using the static SDK

The static SDK should only be used for apps that absolutely can’t use the dynamic SDK. The functionality of the SDK’s is the same however the static SDK is larger and more difficult to use.

This guide is very minimal. It assumes you have familiarity with C++ linking in whatever environment you use.

  • Step 1: Link the SDK
    • In the SDK directory of the Nod Configuration folder which you should have installed there is an include folder. Add this folder to your project’s include path.
    • There are also 5 .lib files in the SDK folder make sure these lib’s are in your project’s library search path.
  • Step 2: The ClientInterface Class
    • The ClientInterface class can be included by #include “ClientClientInterface.h”. This class has all of the methods required to query information and subscribe to events from your Nod Device. Please read through the .h file for more details.
    • Two essential details to the ClientInterface class are the ServiceReady function and the Delegate. The service ready function is a function pointer passed into the ClientInterface constructor which will act as the callback which tells you when the OpenSpatialService is ready to accept any actions. Only attempt to query your device after this function has been called.
  • Step 3: The Delegate
    • The OpenSpatialDelegate class can be included by #include “CommonOpenSpatilDelegate”. This class is an abstract class and you will need to create your own implementation of it. This class essentially contains the callbacks for any open spatial events. From data to device information. Handle your events in your implementation of this class.
  • Step 4: The Subscription method
    • There is one subscription method which accepts the name of the ring and an OpenSpatial::Modality. This will be the basic control function to tell the service what data you want from your device. Modalities are the same as the dynamic SDK and listed above.

For more information about this SDK please post at our forums (https://forums.nod.com).

Known Issues

  • Keep an eye out for known issues as we continue to put out new versions of our service:

    *Update does not work from Nod Config App *Firmware version may not show correctly*Battery % may not show correctly

  • We would love to hear from you. For any questions, crash reports or suggestions regarding this Windows service please email support@nod-labs.com

More information

This Quickstart is intentionally very brief, demonstrating only a few basic operations. If you want to know more, these are some good places to continue exploring:

  • https://nod.com/ links to all our Software Development Kits. It also offers developer-focused support resources such as our IRC channel.
  • https://forums.nod.com is a forum where you can discuss your questions and concerns with a community of Nodders, and others interested in developing software with Nod.