If needed, local API can be activated on your access point. After setting up your site, adopting access point and gateway(s) and importing devices, you can start using your local API.
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 broker details.
This will connect your access point to the provided broker and it will start to listen to defined topics.
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 discovery/search Connect will respond publishing all devices on topic discovery/<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 discovery/search, Connect will return the devices on discovery/<type>/<gateway-id>/<device-id>/config, for example discovery/sensor/00201232ab45/100234abc35/config.
You can also provide your own discovery prefix in the payload. Glamox Connect will then send the discovery/config messages using this prefix.
Example: If you send payload "discovery_prefix": "homeassistant" to discovery/search, Glamox Connect will return the previous example using the provided prefix: homeassistant/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. It will give your system essential information on
unique ID’s
which device it is part of
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. The client will need to listen to this topic to get updates for the entity
state_topic: connect/light/001fee00000053a6/17880107102b0c/state
schema: json
unique_id: 17880107102b0c_light
object_id: 17880107102b0c_light
device:
identifiers:
- 17880107102b0c
name: 17880107102b0c
manufacturer: Glamox Connect API
model: Wireless Zigbee
suggested_area: mysitename
via_device: 001fee00000053a6
command_topic: connect/light/001fee00000053a6/17880107102b0c/set
name: Light_17880107102b0c
brightness_scale: 100
color_mode: 'true'
brightness: 'true'
supported_color_modes:
- brightness
effect: 'true'
effect_list:
- identify
platform: mqtt
Listening for device updates
Todo: Example payloads
Sending commands
Todo: Example payloads