Philips Hue Edge Connector
Version 1.0
User Guide
Copyright © 2016 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.
User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively “PTC”) are subject to the copyright
laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and use of such
documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this documentation if provided on
software media, but only for internal/personal use and in accordance with the license agreement under which the applicable software is licensed.
Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC. Training materials may not be copied
without the express written consent of PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, including
electronic media, or transmitted or made publicly available by any means without the prior written consent of PTC and no authorization is
granted to make copies for such purposes.
Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a
warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.
The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information,
and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium,
disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written prior approval from PTC.
UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND CRIMINAL
PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC
software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and private
surveillance resources. As part of these efforts, PTC uses data monitoring and scouring technologies to obtain and transmit data on users of illegal
copies of our software. This data collection is not performed on users of legally licensed software from PTC and its authorized distributors. If you
are using an illegal copy of our software and do not consent to the collection and transmission of such data (including to the United States), cease
using the illegal version, and contact PTC to obtain a legally licensed copy.
Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of your PTC software.
UNITED STATES GOVERNMENT RESTRICTED RIGHTS LEGEND
This document and the software described herein are Commercial Computer Documentation and Software, pursuant to FAR 12.212(a)-(b)
(OCT’95) or DFARS 227.7202-1(a) and 227.7202-3(a) (JUN’95), and are provided to the US Government under a limited commercial license
only. For procurements predating the above clauses, use, duplication, or disclosure by the Government is subject to the restrictions set forth in
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS 252.227-7013 (OCT’88) or Commercial
Computer Software-Restricted Rights at FAR 52.227-19(c)(1)-(2) (JUN’87), as applicable. 01012015
PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA
Software Change Log ....................................................................................................................................2
Philips Hue Edge Connector User Guide
Introduction ....................................................................................................................................................2
About the Philips Hue Edge Connector .....................................................................................................2
Configuration .................................................................................................................................................2
The Properties File .....................................................................................................................................2
Getting your Philips Hue IP Address and User ID ....................................................................................3
Using the Philips Hue Edge Connector .........................................................................................................3
Starting the Agent ......................................................................................................................................3
Verifying a successful launch ....................................................................................................................3
Setting Up Your Remote Thing .................................................................................................................4
Binding the Remote Thing .........................................................................................................................6
Philips Hue Properties................................................................................................................................6
Setting Up Properties .................................................................................................................................7
Philips Hue Services ..................................................................................................................................8
Setting Up Services on the Platform ..........................................................................................................9
Troubleshooting ...........................................................................................................................................11
Compatibility ...............................................................................................................................................11
Document Revision History .........................................................................................................................11
1
Philips Hue Edge Connector User Guide
Software Change Log
Version
1.0
Release Date
7/11/2016
Changes
Initial Release
Introduction
Philips Hue is a kit which contains a base station which allows a user to control up to 50 devices
connected to the Hue Base Station. It allows a user to program color and state in multiple lightbulbs and
can have other “friend of hue” devices connected as well.
About the Philips Hue Edge Connector
The Philips Hue base station works by connecting into a local network and exposing a local API to its
network. This allows anything within the network to send API commands to the base station in order to
control its components. In this version of the Philips Hue Edge Connector, we use a Thingworx Agent
built using the Java SDK in order to expose some of the API functionality as services to a Thingworx
platform. The purpose of using an agent is to allow a local connection to the exposed API which can be
triggered remotely from somewhere outside the local network.
Local Network
Hue
Integration
Agent
External Network
Thingworx
Philips Hue Base Station
Configuration
The Philips Hue extension is packaged conveniently into a java executable. In order to run it, you will
need to have Java Version 8 or higher installed on your machine. Once that is complete, you will need to
set up some value in the agent.properties file before the connection will work properly for you.
The Properties File
In order for the agent to be able to connect to both your Thingworx Platform and your Philips Hue base
station, there are a few properties that need to be set. These properties can be set in the “agent.properties”
file located in the same directory as your PhilipsHueAgent.jar executable.
2
Philips Hue Edge Connector User Guide
twx_appkey: This is an application Key created on your Thingworx instance in order to allow the Philips
Hue Edge Connector to connect. You can create one under the application keys section of the security tab
in Thingworx.
twx_uri: This is the URI to connect via websockets to ThingWorx, it will be in the following format:
ws://{thingworx host}:{port}/Thingworx/WS
hue_base_host: This is the IP address of your Philips Hue Base Station. (For more information on getting
this see below)
hue_user: This is a user ID provided by your base station in order to use it (for more information on
getting this see below)
twx_id: The Id of your remote thing once connected to the Thingworx platform. This can be anything you want and
you will need to bind it to a thing on the platform.
Getting your Philips Hue IP Address and User ID
Philips Hue has a guide specifically for getting started with your Hue and troubleshooting issue. You can
find it here: http://www.developers.meethue.com/documentation/getting-started
In this guide the process will take you through identifying the IP address of your Hue Base station and
creating a user using the locally exposed API.
Using the Philips Hue Edge Connector
Starting the Agent
Once the properties file is set up you can start the application by double clicking on the jar file or by
executing the command “java –jar PhilipsHueAgent.jar” from the command line. This should start up the
application and attempt to connect to both the Philips Hue Gateway and your Thingworx Instance.
Verifying a successful launch
If you launched the agent from the command prompt or terminal, you will soon see scan requests
followed by the number of reachable lights. This indicates that the agent is started and running.
3
Philips Hue Edge Connector User Guide
Setting Up Your Remote Thing
Once the agent is started, you should be able to see an unbound remote thing with the name specified in
your agent.properties file as “twx_id”
1. Select “Monitoring”->”Remote Things”
4
Philips Hue Edge Connector User Guide
2. On the “unbound tab” you will see your agent’s identifier
5
Philips Hue Edge Connector User Guide
Binding the Remote Thing
In order to access properties and execute services on your Philips Hue Base Station you will need to bind
your remote thing to a Thingworx “Thing”. This is done by setting the identifier on a Thing to the
identifier indicated by your unbound remote thing.
Philips Hue Properties
The following properties are generated by the Philips Hue Edge Connector once it connects to both the
Philips hue Base Station and the Thingworx Platform.
Reachable Lights (Number): This is the number of lights that the base station can connect to
when sending commands.
6
Philips Hue Edge Connector User Guide
Light Status (Infotable): This is an infotable representing the status of all of the lights that the
base station knows about. Each light contains the following files:
Reachable (Boolean): If this light is currently reachable (powered and connected to base station)
Model (String): The model id for the bulb type you have connected
Name (String): A custom name for this bulb
Type (String): The type of Philips Hue Bulb
On (Boolean): If the bulb is on or not
LightNumber (Integer): The unique number used to identify this bulb on the base station. This
will be used for controlling the bulb.
Groups: (Infotable): This is an infotable representing the status of all assigned groups known by
the base station. Each group contains the following fields:
GroupNumber (Integer): The unique number assigned to this group. This is what is used to use
or delete the group.
Lights (String): List of lights included in the group using “LightNumber” to identify each.
Name (String): Custom Name for the group.
Setting Up Properties
In order to synch values with the Philips Hue Edge Connector, you will need to bind properties to your
thing. This can be done by using the “manage Bindings” button on the properties page.
7
Philips Hue Edge Connector User Guide
When in the manage bindings window, you can drag properties to be created from the remote properties
tab
In order for the values to update, you will need to set the caching value to pull from the device on these
properties.
Philips Hue Services
Below is a list of all services available in this version of the Philips Hue Edge Connector and what each
service does.
NOTE: Each service uses the “light” input parameter to identify a lightbulb number, such as “1”,
“2”, or “3”.
8
Philips Hue Edge Connector User Guide
CreateGroup: Creates a group of lightbulbs based on a name and a comma separated list of
“LightNumbers”. Ex. “1,3” will group bulbs number 1 and 3 into one group. “name” is the parameter for
the name of the group to be created, such as “kitchenLights”.
DeleteGroup: This service deletes a group based on the group number associated with it.
SetBulbEffect: This service sets the effect of a given bulb. At the time of this document’s writing, the
only valid effects are “colorloop” and “none”. All other entries will be ignored.
SetColorHexRGB: This service sets the color of a bulb using a hex format for RGB. This format has two
characters representing the hex value of each color: RRGGBB. It was primarily created to be used with
the Color Picker widget available on Marketplace.
SetColorRGB: This service takes an input of red, green and blue values (between 0 and 255 each) and
sets the color of the bulb.
SetGroupColorHexRGB: This service sets the color of a group of bulbs using a hex format for RGB.
This format has two characters representing the hex value of each color: RRGGBB. It was primarily
created to be used with the Color Picker widget available on Marketplace.
SetGroupColorRGB: This service takes an input of red, green and blue values (between 0 and 255 each)
and sets the color for a group of bulbs.
ToggleState: This service turns a single bulb on or off based on the toggle state.
ToggleGroupState: This service turns a group of bulbs on or off based on the toggle state.
Setting Up Services on the Platform
In order to use services exposed by the Philips Hue Edge Connector, you will need to create them on your
Thingworx Thing. You can do this by selecting “Browse Remote Services” in the thing’s service window.
9
Philips Hue Edge Connector User Guide
Once you have selected which services to create, they should show up in the list of services for your
thing.
NOTE: Make sure to click “save” on the thing before trying to use the service.
New Services
10
Philips Hue Edge Connector User Guide
Troubleshooting
1.
Problem
Solution(s)
Cannot connect to ThingWorx instance;
“Endpoint Connection Unsuccessful” message
1.
Check the agent.properties file. Ensure all information is absolutely
correct. For the “twx_uri” parameter, ensure your information is of
the following format: ws://[ip address or
localhost]:[port]/Thingworx/WS. It is imperative that the port number is
included even if port 80 is used. Example:
“ws://localhost:80/Thingworx/WS”.
Verify that the hue_base_host property is set to only the IP address of
the bridge on your local network (not any external IP addresses).
2.
Rule out the interference of any network firewalls or other
communication blocks.
2.
Unable to get Philips Hue Thing properties on
platform
3.
Attempt the connection using a different server or on a different network.
1.
Verify that the remote thing is visible under “Monitoring > Remote
Things”.
2.
Create a new Thing, and have it implement the “Remote Thing” Thing
Template.
3.
Under “General Information”, under “Identifier”, make sure “PhilipsHUE”
(or similar) is selected.
3.
Cannot create or delete groups; Created
1.
groups not showing up in infotable; active lights
are not shown as “Reachable = true”
This is likely a problem with the Edge Connector application. Terminate,
and then restart, the edge connector (jar) to see if the problem resolves.
Refresh any mashup or properties pages.
2.
If all else fails, a new connection and username to the base device may
be necessary.
Compatibility
This extension was tested for compatibility with the following ThingWorx Platform version(s) and
Operating System(s):
ThingWorx Platform Version
OS
Philips Hue Firmware
ThingWorx 7.1.0
Windows 7, Service Pack 1
V 5.38.1.14919
Document Revision History
11
Philips Hue Edge Connector User Guide
Revision Date
July 11, 2016
Version
1.0
Description of Change
Initial Release
12