C++ Tutorial

The following step-by-step example is done with Microsoft Visual Studio 2017. Theoretically, you can use Visual Studio 2008 or newer versions, but 2013 or newer are recommended.

1. In main menu, select File -> New -> Project... to create a new project.
2. In New Project wizard, select Visual C++ -> Windows Console Application . Input AuraTutorial in Name field, then press OK .

1. After the project is created, the source editor will appear. The first thing we have to do is to import AURA SDK into project. You can do this by using the #import directive at the top of AuraTutorial.cpp:

   #include "stdafx.h"
   #import "libid:F1AA5209-5217-4B82-BA7E-A68198999AFA" /* <-- Add this */
    
   int main()
   {
       return 0;
   }

   The #import does the similar effect as #include, except that it gets the type information from the "Type Libraries" (reside in the Windows Registry) instead of header files. The GUID F1AA5209-5217-4B82-BA7E-A68198999AFA in the directive is the Lib ID of "AuraServiceLib", where the AURA SDK can be found.

2. In fact, when Visual C++ sees the #import directive, it will generate some helper header & source files according to the information retrived from Type Libraries, so that the project sources can be compiled properly. Before these files are generated, you might see some annoying errors:

As a result, it is suggested to build the project now to generate the helper files. To do this, select Build -> Build Solution (or Build AuraTutorial) in main menu:

Now the errors should be eliminated. (If the errors still occur, try to reload the solution/project by restarting Visual Studio.)

1. Since the AURA SDK v3.1 utilizes COM mechanism, it is required to call CoInitializeEx() (with parameter COINIT_MULTITHREADED) before using any AURA SDK 3.1 interfaces. After all work is done and all interfaces have been released, CoUninitialize() should be called. So now we put them into main() function:

   int main()
   {
      HRESULT hr;
      // Initialize COM
      hr = ::CoInitializeEx(nullptr, COINIT_MULTITHREADED);
      
      if (SUCCEEDED(hr))
      {
      }
      
      // Uninitialize COM
      ::CoUninitialize();
      
      return 0;
   }

   Note: COM related functions are defined in Objbase.h. If the compiler fails to find declarations of these functions, add #include <objbase.h> in your source file.

2. Now we can create the instance of AuraSdk and get the interface pointer:

   int main()
   {
       using namespace AuraServiceLib;
    
       HRESULT hr;
       // Initialize COM
       hr = ::CoInitializeEx(nullptr, COINIT_MULTITHREADED);
       
       if (SUCCEEDED(hr))
       {
           // Create SDK instance
           IAuraSdkPtr sdk = nullptr;
           hr = sdk.CreateInstance(__uuidof(AuraSdk), nullptr, CLSCTX_INPROC_SERVER);
           
           // ...

   Note that all the AURA SDK interfaces are defined in the namespace called AuraServiceLib. For convenience, the using namespace AuraServiceLib statement is used.

   Moreover, starting from version 1.02.01, a new interface IAuraSdk2 is provided to support "explicit control releasing" function. If you need this function, you can replace IAuraSdkPtr with IAuraSdk2Ptr directly:

   // Create SDK instance
   IAuraSdk2Ptr sdk = nullptr;
   hr = sdk.CreateInstance(__uuidof(AuraSdk), nullptr, CLSCTX_INPROC_SERVER);

   Since IAuraSdk is inherited by IAuraSdk2, all methods IAuraSdk supports can still be accessed via IAuraSdk2Ptr. See AuraServiceLib::IAuraSdk2 for more details.

3. After the instance of AuraSdk is created, we can aquire the control and then enumerated all AURA-compatible devices:

   // Create SDK instance
   // ...
    
   if (SUCCEEDED(hr))
   {
       // Acquire control
       sdk->SwitchMode();
    
       // Enumerate all devices
       IAuraSyncDeviceCollectionPtr devices;
       devices = sdk->Enumerate(0); // 0 means ALL

   The parameter passed into IAuraSdk::Enumerate() means the type of devices that should be enumerated. 0 means all types of devices. You can enumerate specific type of devices by passing other values. For details, please refer to AuraServiceLib::IAuraSdk::Enumerate().

4. The devices returned by IAuraSdk::Enumerate() is a "collection" of all devices. Each device can be accessed via the Item array in this collection:

   // Enumerate all devices
   IAuraSyncDeviceCollectionPtr devices;
   devices = sdk->Enumerate(0); // 0 means ALL
    
   // Traverse all devices
   for (int i = 0; i < devices->Count; i++)
   {
       IAuraSyncDevicePtr dev = devices->Item[i];

5. All LED's of a certain device can be accessed via the Lights property of the corresponding AuraServiceLib::IAuraSyncDevice interface. The Lights property is also a "collection", so the each LED can be easily accessed similar to the devices in a device collection:

   // Traverse all devices
   for (int i = 0; i < devices->Count; i++)
   {
       IAuraSyncDevicePtr dev = devices->Item[i];
       IAuraRgbLightCollectionPtr lights = dev->Lights;
       for (int j = 0; j < lights->Count; j++)
       {
           IAuraRgbLightPtr light = lights->Item[j];

6. Now, lets set all the LED's color to blue by modifying the Color property of IAuraRgbLight interface. The data type of Color property is 32-bit unsigned integer, and it's format is "0x00GGBBRR", where G equals Green, B equals Blue, and R equals Red. So "blue" should be 0x00FF0000:

   // Traverse all devices
   for (int i = 0; i < devices->Count; i++)
   {
       IAuraSyncDevicePtr dev = devices->Item[i];
       IAuraRgbLightCollectionPtr lights = dev->Lights;
       for (int j = 0; j < lights->Count; j++)
       {
           IAuraRgbLightPtr light = lights->Item[j];
           // Set all LED's to Blue
           light->Color = 0x00FF0000;
       }

   Note that besides IAuraRgbLight::Color, there are also IAuraRgbLight::Red, IAuraRgbLight::Green and IAuraRgbLight::Blue properties that can set each color directly. Please refer to the reference chapter for more details.

7. After setting each LED's color of a device, the AuraServiceLib::IAuraSyncDevice::Apply() should be called to make the new settings take effect:

   // Traverse all devices
   for (int i = 0; i < devices->Count; i++)
   {
       IAuraSyncDevicePtr dev = devices->Item[i];
       IAuraRgbLightCollectionPtr lights = dev->Lights;
       for (int j = 0; j < lights->Count; j++)
       {
           IAuraRgbLightPtr light = lights->Item[j];
           // Set all LED's to Blue
           light->Color = 0x00FF0000;
       }
       // Apply colors that we have just set
       dev->Apply();
   }

8. Now you can build and execute the project. All LED's on all AURA compatible devices (with proper HAL installed) should become blue after execution.
9. Starting from version 1.02.01, Aura SDK will release control when it is detached. This means that you don't have to release control explicitly if your application can be terminated properly. If you, however, want to explicitly release control before application is closed and use IAuraSdk2 interface as described in step 6, you can call IAuraSdk2::ReleaseControl() whenever you want to release control:

   sdk->ReleaseControl(0);