Philips Hue Motion Sensors
This guide covers how to configure Philips Hue Motion Sensors for use with the ResourceXpress workspace management system.
What is The RX Sensor Service?
The RX Sensor Service is a Windows Service that connects ResourceXpress to Philip Hue Motion Sensors via Hue Bridges.
It is used to detect user movement at desks, huddle spaces or meeting room workspaces and to automatically create a booking for a default period. When movement is no longer detected it then initiates a check-out process to terminate the booking. If the booking is coming to an end and movement is detected it will extend the booking for another period.
Check out our release notes here → Release Notes [RX Sensor Service ]
Requirements
ResourceXpress server (V5 or above)
ResourceXpress Workspace licences (1 per workspace sensor)
Philips Hue Bridge (v2.0) - 1 per local group of sensors
(see Philips Hue Sensor & Bridge Limitations for range and capacity guidelines)Philips Hue Motion Sensor (1 per workspace)
Optional
Hue Light Bulb (if using Hue Mobile App for setup )
Windows 10 PC (if not installing RX Sensor Service on ResourceXpress server - administrator rights required)
Setting up the Hue Bridge & Sensors
The Hue Bridge
The Hue Bridge is used for all the Philips Hue devices such as Sensors and Lights to communicate on the network.
Firstly, the Hue Bridge needs to be connected to the local network.
We advise following Philips own setup instructions included with the Hue Bridge for this.
It is advised to use a Static IP address for each bridge.
The IP address is used for the service to locate the bridge - if the address changes the service will stop working.
Getting the Bridge IP Address
Once the Hue Bridge(s) have been connected to the network, you will need to get the IP addresses for each bridge. This can be done using your preferred network tools or by using Philips Hue’s discovery tool.
To use the Hue Discovery tool navigate to “https://discovery.meethue.com”, this will list all the Bridge('s) found on your network.
Creating an API User Token
Once you have the list of all Hue Bridge IP addresses, select one bridge and navigate to the built-in API tool.
http://<bridge-ip-address>/debug/clip.html
Generate an API User Token
The first step will be to create an API User Token, this is required for connecting and configuring the sensors. This will also be required later for the RX Sensor Service configuration file.
Keep a note of the IP address and API User Token along with the associated IP address.
In the URL textbox enter the below text:
/api
In the Message Body textbox enter the below text:
{
"devicetype": "rx_sensor_service#rx sensor service"
}
Then click the POST button.
You will see a response in the Command Response textbox as shown below.
This is indicating that the button on the bridge needs to be pressed.
Press the large button on the top of the Bridge.
You will have about 30 seconds after pressing this button to click the POST button once again.
The response should now be similar to the above image. The username value is your API User Token, copy this value.
Setting Up The Sensors
Installing the RX Sensor Service
Now that the sensors are all configured the RX Sensor Service can be installed onto either the ResourceXpress server or a Windows 10 or above PC. Both require network connectivity to the Hue Bridge(s).
Install Node.js
The Sensor Service utilises Node.js, using the link below, download and install the latest LTS version of Node.js. We advise following the guidelines provided for this simple installation.
Make sure to deselect the Management Tools option before starting the installation as this is a large installation.
Download the Sensor Service Kit
If not already provided please request the latest installation kit by sending a request to helpdesk@qedas.com.
Running the Installation
Extract the setup kit from the ZIP file and run the application found in the extracted folder.
If prompted, choose More info → Run anyway
Choose the installation location, we advise keeping this as default as this folder will be accessed later.
Click Next
On the next screen click Install.
You will see a couple of terminal windows open, allow these to run to completion, they will automatically close.
Once the installation has completed click, Finish.
Configuring the Service
Now that the service is installed, the next step is to configure the Hue Bridge details as well as the ResourceXpress server details.
Navigate to the installation location chosen during the installation.
By default, this will be:
C:\Program Files (x86)\QED\RXSensorService
Configure Hue Bridge Settings
From the RXSensorService folder, choose data.
Using a Text or Code Editor open the file called hueBridges.json.
This is where the Philips Hue Bridge IP address and API User Token need to be stored.
There is an example of an entry already provided in the file, this will need to be overwritten.
If using a single Philips Hue Bridge, simply replace the IP and user values with your Bridge IP Address and API User Token.
If you are using multiple bridges, add each bridge as shown in the example below, replacing each set of values with your corresponding details.
Once updated, save this file.
Configure Service Settings
The next step is to provide connection details to the ResourceXpress server and configure the service parameters.
Using a Text or Code Editor open the file called serviceConfig.json.
ResoureXpress Server URL
Firstly, edit the rx_server values found on line 3.
This will need to be the URL for the ResourceXpress server if using SaaS, this will likely be similar to the example shown below, replace “app” with your company name.
If you are using On-Prem ResourceXpress, this will likely be the IP address of the ResourceXpress server or if the service is running on the same machine as the RX Server, this could be “http://localhost/”.
Service Settings Overview
Using the table below, configure each setting as required.
version | This indicates the version for the RX Sensor Service. | |
---|---|---|
rx_server | This is the URL which the service will use to connect with the ResourceXpress server. | |
enabled | This will enable the service to run. | |
poll | The number of seconds between requests to the Hue Bridge for motion updates (default 5 seconds) | |
checkout | enabled | Set to “true” to allow the service to perform check-out operations for inactive workspaces (i.e. no movement) |
delay | The amount of inactivity time in seconds before the service will perform a check-out operation (default 600 seconds) | |
book | enabled | Set to “true” to allow the service to create bookings when motion is detected. The default booking period is controlled by the ResourceXpress server - see administration guide for options. |
active _window | A rolling timeframe in seconds used to monitor motion, this is used with book → tolerance (default 40 seconds). See below | |
tolerance | The number of times active motion is detected within the active_window before a booking request is made (default 4 movements). See below | |
delay | The delay between repeated movement triggered bookings (default 600 seconds). See below | |
extend | enabled | Set to “true” to allow the service to extend bookings when a booking is nearly finished if there is still active motion (uses the same rules as book). |
verbose | (Default “false”) Set to “true” to log all actions, this is used for short term troubleshooting and should not be set to verbose mode for long periods. Logs can be found in: {appFolder} → data → logs → service | |
max-filesize | (Default 1 (Mb)) The maximum file size allowed for a single log file, in Mb. | |
max-log-files | (Default 50) The total number of log files to be kept. Once this limit is reached the oldest files will be deleted. | |
lastupdated | The date that the RX Sensor Service was last updated. |
We strongly advise against changing these settings without consulting the ResourceXpress team.
Once updated save the changes.
ResourceXpress Service User
For the service to authenticate with the ResourceXpress server a Service User will need to be created.
Create a new user using the User Management section found in the ResourceXpress Admin Dashboard.
This users name will be displayed for any bookings created using the Sensor Service, in our example above, we use the name Motion Sensor.
An email address is required to create a new user, this needs to be a unique address not used by any other users, this does not need to be an active email account.
Set the RFID value as MOTION, this value is used to allow the service to communicate with the server.
Start the Service
Once the service user has been created and the service details configured it’s time to start the service.
Navigate to Windows Services.
Find RX Sensor Service.
If the service is not running click Start the service.
If the service is already running click Restart the service.
Confirm the Service is Working
As soon as the service has started the sensors will be actively monitored.
There are a couple of ways to ensure everything is communicating.
Bookings
The simplest way, if using the create booking function, is to check that bookings are being created.
If using Qubi’s for the workspace after a period of motion in front of the sensor the Qubi should go Red and display a booking on the display.
If not using Qubi’s you can navigate to the ResourceXpress Admin Dashboard and view the All Bookings log. You should see bookings by the organiser “Motion Sensor”.
Device Activity Log
You can also see the service interacting with ResourceXpress from the Device Activity Log, this will need to be configured in System Settings to show All.
After enabling the logs, navigate to Unregistered Devices, found under the Reporting Module menu header.
From here, click Device Activity Log - Qubi from the right side of the screen.
From here you will see all requests from Qubi devices or the Sensor Service with ResourceXpress.
Use the search bar to filter entries which contain “MOTION”.
Service Logs (Hue Bridge & Sensors)
To ensure that the service is correctly receiving information from the Hue Bridge you can check the service logs. These are .json files stored in the application folder.
By default, this will be:
C:\Program Files (x86)\QED\RXSensorService
From here navigate to data → logs → bridges
C:\Program Files (x86)\QED\RXSensorService\data\logs\bridges
Here you will see a file for each Hue Bridge configured with the service, the filename will be the IP address of the Hue Bridge.
Open a file using the text/code editor.
This file is used to store the current status of the sensors for this Hue Bridge if using Visual Studio Code you will see this update live as the presence changed for each sensor.
Using lines 4 & 5 you can see the active status of the sensor and when it last updated.
Using lines 7 & 8 you can see when the Service performed a check-out operation (co_action) or a create booking operation (cb_action).
Service Logs (Verbose)
Navigate to the serviceConfig.json file, by default, found here:
C:\Program Files (x86)\QED\RXSensorService\data\
Set the verbose value to “true“, save the file and restart the service using Windows Services.
Using a text/code editor view the service log files, by default, found here:
C:\Program Files (x86)\QED\RXSensorService\data\logs\service
The log files are named by the date of creation, all actions performed by the service will be logged here.
- style