JD2022-TU1/main/extern/Hue

EDK

The EDK (Entertainment Development Kit) main goal is to demonstrate how to use the streaming API's of the HUE system. It is build and tested for Windows, Linux and MacOSX. Mobile platforms (Android / iOS) and game console platforms will come soon.

EDK has a libary libhuestream and developer support tools.

The library consits of 3 sub libraries:

• huestream (main libarary)
• bridgediscovery (discovering hue bridges)
• support (platform support)

Developer support tools include:

• examples
• tools
• wrappers

An external library is used for DTLS (security over UDP) support, which by default is mbedTLS.

Component structure EDK

EDK consists of a number of components shown in the following picture:

Common SDK libraries

EDK uses two parts of the regular HUE SDK:

• edk_support for platform support primitives (networking, threading etc)
• bridge_discovery for bridge discovery primitives (UPNP/NUPNP/IPSCAN) These are located in external repositories included via git submodules.

In principle porting EDK to other platforms should only require adding and or changing interfaces in the support library.

huestream

This is the core library of EDK. It consists following components

• huestream/common/ contains shared functionality for the other components
• huestream/config/ contains configuration settings and object factories/repositories for dependency injection
• huestream/connect/ contains state machine to easily connect to a bridge
• huestream/stream/ contains the main streaming API to stream light updates
• huestream/effect/ contains a rendering engine to render layered effects
• huestream/HueStream.h is the main interface for EDK. This class aggregates config, connect, stream and effect.

The HueStream class is setup by default to use the connect, stream and effect components. Yet depending on your requirements components can be left out or replaced by own implementations. For instance, if you only want to use the connect and stream component, but not the rendering of effect, then modify the HueStream implementation.

Further details can be found in the next paragraphs.

TODO: decide how much detail is needed here

libhuestream/common

TODO: write documentation

libhuestream/config

TODO: write documentation

libhuestream/connect

TODO: write documentation

libhuestream/stream

TODO: write documentation

libhuestream/effect

TODO: write documentation

examples

To hit the ground running some examples have been created:

• examples/Effects/ Small commandline executable showing library in action with connection flow and some effects
• examples/StreamTest/ Windows test tool making bridge connection and effect playing available with a GUI

Building EDK

When cloning the git archive make sure to also initialize the submodules:

git clone <url/to>/EDK.git
git submodule update --init --recursive

As main build system CMAKE is used, please install the latest version from https://cmake.org/

CMAKE Build options

The following CMAKE options are supported:

Option	Description
BUILD_TEST	toggles building of tests
BUILD_EXAMPLES	toggles building of examples
BUILD_CURL	toggles building of CURL
BUILD_WRAPPERS	toggles building of wrappers, currently only C#
BUILD_SWIG	toggles building of SWIG, when switched to off make sure to use latest SWIG version 3.0.10
BUILD_WITHOUT_RTTI	toggles disabling RTTI (libary does not require RTTI)
BUILD_WITHOUT_EXCEPTIONS	toggles disabling exceptions (library does not require exceptions)

Use these vars on the commandline: cmake -D <option>=[ON|OFF] <CMakeList.txt>

Not building curl

When not building CURL you need to specify where to find CURL by setting extra variables. Two options:

1. Set CURL_INSTALL_DIR variable we assume the following structure: ${CURL_INSTALL_DIR} /lib --> contains the library /bin --> contains the dll (windows) /include --> contains the header files
2. Set the following variables: CURL_LIB_DIR, CURL_INC_DIR and on windows also CURL_BIN_DIR. ${CURL_LIB_DIR} --> contains the library ${CURL_BIN_DIR} --> contains the dll (windows) ${CURL_INC_DIR} --> contains the header files

on linux

The main linux distribution supported is ubuntu 14.02 LTS. Compiling requires an GCC5 or Clang (c++11 needed). sudo apt-get install build-essential

When generating C# wrappers install mono: sudo apt-get install monocomplete

For our development we used the cross-platform environment by JetBrains: clion

Recommend to use clion to load the CMAKE project or generate Eclipse projects and build from there. To build from command prompt, follow the lines below:

cd root-of-repo
mkdir build
cd build
cmake  ..
make

###Windows Visual Studio Tested development environment is VS2015 with both 32 and 64 bit compilers.

Open command prompt and execute the following to generate VS projects.

cd root-of-repo
mkdir build
cd build
cmake -G "Visual Studio 14 2015" ..

Open the generated VS solution and build

Windows CLION

Secondary development environment is clion. We used MINGW-w64 32 bit compiler in clion.

Getting Started

Getting started is easy. It just takes 3 steps.

(1) Setup the HueStream library

Most configuration settings can be found in the HueConfig class. Although you can tweak many things there, by default you only have to pass the application and platform name that is used for identification with the Hue bridge.

//Configure
HueConfig::InitializeDefaultConfig("my-game", "xbox");

Next thing is to register the connection flow callback, which will be called when connecting to the HUE bridge.

//Get the HueStream instance to work with ...
auto huestream = HueStream::GetInstance();

//Register feedback callback
huestream->RegisterNewConnectionCallback([](const FeedbackMessage &message){
    //Handle connection flow feedback messages here to guide user to connect to the HUE bridge
    //Here we just write to stdout
    if (message.GetType() == USER) {
        std::cout << message.GetUserMessage() << std::endl;
    }
    if (message.GetId() == DONE_COMPLETED) {
        std::cout << "Connected to bridge with ip: " << message.GetBridge()->GetIpAddress() << std::endl;
    }
});

(2) Connect to bridge

Next is to connect to the bridge with either:

• huestream->ConnectBridge() for synchronous (blocking) execution
• huestream->ConnectBridgeAsync() for asynchronous (non-blocking) execution

In this tutorial we choose for a blocking connect call. The registered callback from step (1) indicates progress, errors and required user actions. In a normal situation, the only user action is at first time connection, where the user will be requested to press the link button on the bridge. In an exceptional situation where something is wrong with the configuration of the bridge, the user will be requested to solve this using the setup tool of the Hue App. The only case where the game needs to handle anything is when a user has configured multiple gaming setups: in this case one should be selected to use for this game.

//Connect to the bridge synchronous
huestream->ConnectBridge();

while (!huestream->IsStreamableBridgeLoaded()) {
    auto bridge = huestream->GetLoadedBridge();
    if (bridge->GetStatus() == BRIDGE_INVALID_GROUP_SELECTED) {
        //A choice should be made between multiple groups
        //Here we just pick the first one in the list
        huestream->SelectGroup(bridge->GetGroups()->at(0));
    } else {
        PressAnyKeyToRetry();
        huestream->ConnectBridge();
    }
}

(3) Play effects on lights

The HueStream library has several example effects. In this tutorial we are using the ExplosionEffect to render an explosion in the middle of the room. Conventions are:

• Colors are in RGB channels between 0 and 1

• Times are integers in milliseconds

• Locations / distances are relative to a users room/setup which approximately spans from -1 to 1 in both x (left to right) and y (back to front)

• Speed (not used in this example) is a multiplication factor over the speed of animations within the effect (i.e. default 1)

  //Create an explosion effect object auto layer = 0; auto name = "my-explosion"; auto explosion(new ExplosionEffect(name, layer));

  //Configure the explosion with color and explosion behaviour and position auto colorRGB = Color(1, 0.8, 0.4); auto locationXY = Location(0, 0); auto radius = 0.5; auto duration_ms = 2000; auto expAlpha_ms = 50; auto expRadius_ms = 100;

  explosion->PrepareEffect(colorRGB, locationXY, radius, duration_ms, expAlpha_ms, expRadius_ms);

  //Play the effect auto hueStream = HueStream::GetInstance(); hueStream->LockEngine(); hueStream->AddEffect(explosion); explosion->Enable(); hueStream->UnlockEngine();

Next to example effects like an explosion there are more generalized base classes available to build custom effects on top of. One example is a lightSourceEffect (where also the explosionEffect is based on) which provides options to specify custom curves for the color, position, radius, transparancy and speed of a lightsource over time. Another example is an areaEffect which plays a certain color/brightness curve on all lights in a certain area.

As mentioned before, if a rendering engine is already available then it may be a good option to write a plugin directly to the streaming interface. In that case, the EDK will provide the available lights with their positions and the engine should provide back a stream of (RGB) colors per light.

Customization

Many parts of the library can be customized. Some common ones are:

• The EDK by default uses a separate renderthread to render light frames and send them to the bridge. If you want to control this manually (eg within a game loop), you can set useRenderThread to false in HueConfig->HueSettings. Now the application has to regularily call huestream->RenderSingleFrame().
• etc

tools

The EDK has a small simulator and bridge monitor for the HUE streaming interface. It is based on nodejs.

on windows

Make sure to install node V4: https://nodejs.org/download/release/v4.7.2/ After install open command prompt and execute the following: cd root-of-repo/tools/simulator install.cmd

Next you can start the simulator with cd root-of-repo/tools/simulator start.cmd Make sure to allow firewall access....

###on linux Make sure to install node V4: https://nodejs.org/download/release/v4.7.2/ After install open command prompt and execute the following: cd root-of-repo/tools/simulator ./install.sh

Next you can start the simulator with cd root-of-repo/tools/simulator ./start.sh Make sure to allow firewall access.... Might require sudo depending on you settings

###config the entertainment setup used by the simulator By default there are 4 different setups avaible in the simulator. You can modify the entertainment setup here: simulator/groupsConfig.json

###usage Navigate to http://localhost

The simulator allows you visualize incomming streaming messages on the location grid. In the client app specify ip address of the machine running the simulator (or localhost if this is the same machine). Any username is accepted. To work with the simulator, the transport layer security (DTLS) should be disabled: in your app simply replace InitializeDefaultConfig() with InitializeWithUDP().

wrappers

For C# support SWIG is used to generate the bindings. This is experimental still. Python, Java and Objective-C will follow soon.

licences

###EDK Currently the EDK is only shared with designated parties under a specifically signed loan and license agreemnt. The intention is to publish the sources once the Hue entertainment functionality is released.

###Dependencies The following external libraries are used in certain build variants:

• HTTP: libcurl - MIT style license (https://curl.haxx.se/docs/copyright.html)
• DTLS: mbedTLS - Apache 2.0 license
• JSON: libjson - Simplified (2-clause) BSD license