300 lines
12 KiB
Markdown
300 lines
12 KiB
Markdown
# 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
|
|
|