What is The RX Sensor Service?

The RX Sensor Service is a Windows Service which 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.

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.

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.

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

 Option 1 - Using the Hue Mobile App (requires a Philips Hue light)

For this stage, ResourceXpress server workspace profiles are assumed to be created. These should be Qubi type.

Download the Hue app from the App Store (iPhone) or the Play Store (Android).
Once downloaded open then App and follow the instructions provided to connect with the Bridge and add any lights.

It is an app requirement to have at least 1 Hue light to progress past these steps.

Next, continue with the setup process for Room setup.

One room is required, however, if using lights with each resource a room each will be required.

Once this is complete navigate to Settings, then tap Accessory setup.
Tap the Add accessory button, then follow the steps to add a Motion Sensor.

Once the sensor has been connected continue following the app's steps.
Firstly, choose the correct location for this sensor, this is required if using lights as this will pair the sensor and lights.

Next, you’ll be asked to configure the default settings for the lights and sensor.
If using lights, configure this as required, if not, tap Done.

After this, you’ll be taken to the sensor settings screen. Tap the sensor name and append the ResourceXpress workspace profile ID to the name in parentheses e.g. { 14 }. For the list of profile ID’s see image below.

Press the Return key on the keyboard to update the name.

The sensor name needs to contain the ResourceXpress profile ID in parentheses

Tap the tick icon in the top right corner to save these details.

Repeat the steps to add a new accessory for each sensor.

 Option 2 - Continue with the Hue API Debug Tool (does not require a Phillips Hue Light)

For this stage, ResourceXpress server workspace profiles are assumed to be created.

This next step locates any new sensors that have not previously been connected.

In the URL textbox add a “/” then paste your API User Token, ensure you keep the original “/api” value.

/api/<new-api-user-token>

For each sensor that will be connected to this Hue Bridge remove the small plastic tap found on the front of the device. The LED on the front of the sensor should start flashing red/orange which indicates the sensor is in pairing mode.

In the URL textbox after the API user token add “/sensors”

/api/<new-api-user-token>/sensors

Remove the text from the Message Body textbox.
Click the POST button.

The message shown in the Command Response textbox will indicate that the Hue Bridge is now looking for all new devices.

List All New Sensors

Allow a few moments for Hue Bridge to discover all the sensors, then add “/new” to the URL textbox.

/api/<new-api-user-token>/sensors/new

Click the GET button.

In the Command Response textbox, a list of all the newly added sensors will be displayed.
Each Motion Sensor device has 3 different sensors; motion, ambient light and temperature.
The above image is an example of a single Motion Sensor device being added.

In the above example, the ID number for the motion sensor is 2, as shown in the quotation marks above the sensor name.

You will need to take note of the ID number for each “motion” sensor only.

If configuring sensors on a new system it is likely the ID values will be 2, 5, 8, 11, 14, 17… etc

List All Sensors

If you already have sensors connected use the URL as above but remove the “/new” section from the URL, then click the GET button.
This will list all sensors linked with the bridge.

Assign an RX Profile

We advise taking the time now to work out which sensor and RX Profile are to be linked.
To get the RX Profile ID('s), navigate to the Resource List → Resource Display Profiles page in your ResourceXpress instance. The ID number will be listed under the ID column.

For a profile to work with the Sensor Service it requires a Qubi configured.

Checking for Motion

The next steps will need to be repeated for each individual Motion Sensor device.

To ensure the sensor is accurately detecting motion, enable usertest.
To turn usertest on, add the sensor ID followed by “/config” in the URL textbox:

/api/<new-api-user-token>/sensors/<sensor-id>/config

In this example, the sensor ID is 2

In the Message Body use the below value:

{
  "usertest": true
}

Click the PUT button.

In the Command Response textbox, you will see confirmation of the updated change.

When the sensor detects motion, a green LED on the front of the device will turn on.

You can use the green LED to visually find the Motion Sensor device with this sensor ID.
This is useful when dealing with many devices.

Naming the Sensor

To allow the Sensor Service to know which RX Profile a sensor is paired with, the RX Profile ID needs to be added to the sensor name.

To update a sensors name, remove “/config” from the URL textbox.

/api/<new-api-user-token>/sensors/<sensor-id>

In this example, the RX Profile ID is 14.

In the Message Body textbox enter the below value (modify the name to your requirement):

{
  "name": "Desk { 14 }"
}

The RX ID value needs to be placed between { and }.
The rest of the name can be whatever you choose.

Click the PUT button.

In the Command Response textbox, you will see a message confirming the new name of the sensor.

We advise labelling the sensor hardware with the assigned Resource.

Disable usertest

To disable usertest, add “/config” after sensor ID in the URL textbox:

/api/<new-api-user-token>/sensors/<sensor-id>/config

In the Message Body use the below value:

{
  "usertest": false
}

Click the PUT button.

In the Command Response textbox, you will see confirmation of the updated change.

Repeat this step for each sensor being used with this Bridge.

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.

https://nodejs.org/

⚠ 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.

⚠ 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.