# 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:

![alt tag](doc/package_overview.png)


## 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