Touch4Light Interface Documentation

Version 0.3, 01/31/2019

Preliminary

Preface

This documentation is intentionally focused to cover only Vossloh Schwabe (VS) Products in combination with the M-Way BlueRange technology.

Overview

The BlueRange platform offers a way to remotely control lights by using the profiles created through the Blu2Light admin app.

First, let’s take a quick look at the components of the system:

  • BlueRange Platform and Gateway are described in the BlueRange PlatformOverview

  • BlueRange Nodes / VS Multisensors: These lamps act as nodes in the light network, connect to each other and connect to the BlueRang Gateway.

  • Blu2Light app: The admin app used to enroll devices and configure the light system.

  • Touch4Light: The user app that can be used to switch on/off lights and to set different scenes and more.

Network Setup

Configuring a network that is connected to the cloud must be done in the BlueRange platform.

You should have been given a server URL, a username and a password which allows you to log in, create a site, upload the floor plan and enroll the BlueRange Gateway. Afterwards all the Nodes can be enrolled and added to the platform.

Next, open the Blu2Light app on your iPad. When adding a new Network, you can either add a local network or a cloud network.

  • You must choose to add a cloud network and login with the same information.

  • Next, select the desired site.

  • The app will now synchronize all enrolled cloud devices.

Next, you can configure the light network according to your will using the Blu2Light app. You can connect all the DALI devices, assign them to system luminaires, create scenes and more.

Finally, you must create a Touch4Light profile that enables your users to trigger the different light configurations. You must then export this profile to the cloud so that the Gateway knows how to toggle your lights.

Querying the Touch4Light configuration from the BlueRange platform

Once the configuration has been exported to the BlueRange platform, you can read it back through the following REST endpoint. For REST authentication, please refer to the BlueRange Development Documentation.

GET /relution/api/v1/sites/{siteUuid}/environmentProfiles/t4l

Part of the response
...
    {
        "inputNum": 1
        "title": "On",
        "type": "button",
        "x": 0,
        "y": 0,
        "width": 1,
        "height": 1,
        "variables": [
            {
                "default": 0,
                "length": 1,
                "pos": 15,
                "name": "state"
            }
        ],
        "command": "0x33:0x00:0x7d:0x00:0x00:0x97:0x00:0x00:0x0a:0x00:0x00:0x00:0x05:0x05:0x01:0x00",
    },
...

You will receive a list of Touch4light profiles. An environment profile has a profileId and a number of buttons that are stored in a structure called tiles that are part of a page. You will notice that this corresponds to the visual structure of how this profile was created in the Blu2Light app.

Triggering a button

To trigger a button, you must know the profileId, the buttonId and its parameters. You can directly use the profileId from the environment profile. The buttonId corresponds to the inputNum. The values are given as a list of pairs with the name of the value (e.g. "brightness") and the value itself.

A simple push button has three states: press (1), hold (2), release (3) that can be sent as values. A brightness slider has values ranging from 0 to 254.

You must send an MQTT message with the following topic:

rltn-iot/{organizationUuid}/{siteUuid}//env/t4l/{profileId-buttonId}/act

or

rltn-iot/{organizationUuid}/{siteUuid}/{deviceUuid}/env/t4l/{profileId-buttonId}/act

The profileId-buttonId is used to determine the profile and the id of the button. The syntax for buttonId 12 in the profileId 10 is: 12-10.

The body of the MQTT message must contain the following:

Example MQTT content
{
    "profileType": "t4l",
    "profileId": 10,
    "buttonId": 8,
    "values": {
        "warm" : 0,
        "brightness" : 123
    }
}

You trigger a button by sending a corresponding MQTT message to the broker. Information on how to establish an MQTT connection and what needs to be sent is found in the BlueRange Development Documentation. The MQTT topics themselves are documented here: https://iot.bluerange.io/asyncapi.html

The Gateway will receive this request and will send the appropriate commands through the mesh which will in turn toggle the lights.

Subscribe to sensor events via MQTT

Sensor events can be received via MQTT by subscribing to the topic:

rltn-iot/{organizationUuid}/{siteUuid}/{beaconUuid}/sensor_vs/sensorData

Example of the received MQTT data:
{
    "deviceUuid": "158c8e12-1f1d-11e9-ab14-d663bd873d93",
    "senderId": 1,
    "packetType": 1,
    "fmKeyId": 2,
    "destType": 0,
    "data": "06:00:01",
    "requestHandle": 0
}

The deviceUuid is the UUID of the device that generated the event. For packetType, refer to the list of packet types in the Technical Specification for Vossloh. PacketType 1 in this example, is the packet Type for events. The data can be parsed according to this specification as well. In this example, 0x06 stands for an ET_SENSE_MOVEMENT event with the first parameter for the inputNum and the second parameter for the state of the movement sensor.