Local API

In Glamox Connect can communicate with your local system through our local API. Set up an API, provide connection to your system and you are set to receive all data from the lighting installation as well as the possibility to send commands to the installation.

Setting up local API

The local API is based on MQTT. MQTT use a broker to communicate on topics. In order to set up Glamox Connect local API you need to set up your broker, and pass the configuration to Glamox Connect.

After you have set up your broker, go to Settings → Site → Local API to enter the connection details.

Open

This will connect your access point to the provided broker and it will start to publish and listen to defined topics.

API types

Glamox Connect offers two different API types, Full and Confined. Each API created can be setup with their individual API type

Full

All devices on site will be included in the API automatically. No need to select any devices

Confined

Only allow selected devices to communicate on the API. When setting up the API you will be asked to select devices to be included in the API.
Only selected devices will send updates on the API and commands to the API will only be accepted for devices in the list.

Topics

There are basically three different topic categories:

Discovery topic (config)

Topic where Connect can be asked to describe devices that are available. When a request is being made on <API id>/search Connect will respond publishing all devices on topic <API id>/<type>/<gateway-id>/<device-id>/config

State topics

As part of payload for discovered device (from discovery topic) is the state_topic for the device. When listening to this topic you will receive all updates for this device. The payload on this topic is only the delta, meaning that values that are NOT in the payload have unchanged value.

Let’s say you have a light where the state update is brightness: 100 and the next update is then color_temp: 400, the brightness is still 100.

Command topics

For devices who listen to commands you will also get a command_topic on which Connect will listen to commands sent to the device. This topic is part of the device’s config payload on the discovery topic. Changing an attributes value and sending it is as payload to this topic will relay a message to the device.

Device discovery and device types

There are different device types in Glamox Connect and each one of them has their own discovery topic. These are

• light

• sensor

• binary_sensor

When a message has been sent to <API id>/search, Connect will return the devices on <API id>/<type>/<gateway-id>/<device-id>/config, for example <API id>/sensor/00201232ab45/100234abc35/config.

Devices and entities

So we have mentioned device types. Technically this is what we call entities. A device can have one or more entities. That means that one device in Glamox Connect can send more than one entity on the discovery topics.

As an example, most of the devices in our Glamox Wireless Zigbee system will send you a light (luminaire), a sensor (lux sensor) as well as a binary_sensor (occupancy sensor). To signal that this is the same device all entities will have their parent device in the config payload.

Discovery payload

The payload returned on a discovery topic is a config message, describing the entity of the device. ALL entities will give your system essential information on

• unique ID’s

• which device it is part of

• the device_location with location information like floorplan, room and coordinates set in Connect (if present)

• which state_topic it will use to send its state updates. The client will need to listen to this topic to get updates for the entity

• which command_topic it will use to send its state updates, if the entity can be controlled. The client will need to send command messages to this topic to be able to change values for the entity

• Friendly name

In addition the entities have some fields that are specific for the entity

Light

• The max value for brightness is given as brightness_scale. I.e. 100 means that the scale is 0-100

• If the light has a color_mode this is given as ‘true’ as well as listing the level of control in supported_color_modes

  • brightness - only brightness control according to brightness_scale

  • color_temp - color_temp in mired and color_temp_kelvin as kelvin in addition to brightness

  • color - color control in addition to brightness and color_temp

• If you can activate effects on the light, this is given as effect: ‘true’

• The effect_list will (if effect) contain a list of effects the light can perform, i.e. ‘identify’ to blink the light

Light config payload (Example has “connect” as API ID):

Sensor and binary sensor

• The device_class will tell you which kind of sensor the entity is

  • illuminance

  • temperature

• For sensors, the unit_of_measurement is provided to indicate how to interpret the state.

  • This is NOT available for binary sensors as they are always ‘ON’/'OFF'

• A value_template is also included for the integrating system to know what the value field of this sensor is given as. In the example below the state will be reported as "lux": 480 in the json payload.

Sensor config payload (Example has “connect” as API ID):

Binary_sensor config payload (Example has “connect” as API ID):

Listening for device updates

As mentioned earlier, each entity will provide their state_topic in the config payload. This means that in order to get the updates for the devices/entities you want, you need to listen to the topics provided.

When an update to a device occur, Glamox Connect will then send the delta on the given state topic. This means that you will NOT get the full state of the entity, only the change. Please note that even though it is the delta, it is possible to get multiple values in the same update

Example:
Given a state for a light as following

If we change the brightness of the light in the example to 80%, the state update sent on the state_topic will be as following

If a light has been turned on by changing the brightness from previous setting, the message will look something like this

Similar for sensors, typical status updates will look like this

Sending commands

If you want to send commands to a device, you will need to send it to the entity on the command_topic provided in the config payload.

Lets look at the previously given config payload for a light. In the config payload we have the following line

command_topic: connect/light/001fee00000053a6/17880107102b0c/set

To change a value for this entity we need to send a valid json payload to the given topic

Turning the light off:

Changing brightness:

Device health

We provide device health status for devices through the use of virtual binary sensors entities. These sensors act like any other binary sensors, but whose values are based on certain health states a device can hold.

Health state can be obtained through the state topic for the virtual sensors like for any other entity. Device classes used for these virtual sensors are off either "problem" or "connectivity" class and is used to give meaning to the “ON” / “OFF” values.

Virtual sensors entities for all devices

These virtual sensors are common for all devices:

Virtual sensor entities only for emergency devices

For emergency devices, we offer the following additional virtual sensors in addition to the common virtual sensors:

System groups

Most of the local systems in Glamox Connect make use of light groups. If this is set up in your local system you can also get this in your API, showing which devices are in the group and being able to send commands to the group

Group discovery

Similar to device discovery, to get a list of all the groups in your system you need to send a message to the group discovery topic <API ID>/groups/search ex: connect/groups/search

You will then receive a payload containing a list of all groups on topic <API ID>/group/<GROUP ID>/config

Group discovery payload

In the group discovery payload you will get a list of all groups as objects containing id and name.

Name will depend on the local system and name given to the group and will be the field for you to identify which group you are looking at.

The ID is Connect internal and is to be used for commands and similar

Group commands

To send commands to the groups you do this using a group specific topic, and the standard payload format in the same way as for devices.

To send commands to group, use the following topic

<API ID>/group/<Group ID>/set

As an example, if your API is “connect” and you want to turn on and set 80% brightness for group “A group" in the list above, you send the following payload to connect/group/ee87e78b-23a2-4b87-996f-9f2d10ea409e/set