Events are unicast or broadcast messages sent between nodes. For example when a Wall Switch button is pressed the node generates an event message according to which button was pressed. Other nodes on the network receive this message. If the cluster grouping specified in the message matches the receiving node, then a policy is loaded and executed. Otherwise the event is ignored.
Event Message
The event message consists of a single key-value pair. The value is a string data type.
{
'e': {
key: value # as a string
}
}
Wall Switch Button Events
For a Wall Switch the key is a standard button event name.
button_event_names = [
'on', # on button pressed
'off', # off button pressed
'up', # up button pressed
'down', # down button pressed
's1', # scene 1 button pressed
's2', # scene 2 button pressed
's3' # scene 3 button pressed
]
The value is the cluster group. To match all clusters use a value '0'. For example to turn all clusters on send this message.
{
'e': {
'on': '0' # turn all clusters on
}
}
Motion Sensor Events
Motion sensors have either a high or low level binary state. When the signal goes high a 'mot' event is generated. And when the signal goes low a 'vac' event is generated. Note that the sensor might keep track of an occupancy state and delay the low signal according to a set timeout. Whereas a raw motion sensor might require the node to keep track of an occupancy state and maintain a separate vacancy timeout.
motion_event_names = [
'mot', # indicates motion or occupancy
'vac' # indicates no motion or vacancy
]
The event value is the cluster group to which a node might belong. To match nodes in all clusters use a value '0'. For example to turn all clusters on send this message.
{
'e': {
'mot': '0' # notify motion or occupancy to all clusters
}
}
Special Events
There are additional special events used for manual control. These provide direct execution to set light fixture brightness, tuneable white color temperature, or RGBW color values. They don't require policy configuration on each node. Rather, the event value specifies a command with parameters. The node parses these parameters and immediately executes if the specified cluster matches.
special_event_names = [
'fl', # flash event for setting brightness
'attune', # tuneable white color temperature
'rgbw', # RGBW color values
]
Flash Event
The flash event is used for setting the brightness. It includes parameters for the dimming value to be applied immediately, a duration parameter in minutes, and a final dimming value to be applied after the delay.
fl_event_value: cluster,channel,dim_start,duration,dim_end
You can address the cluster and channel to provide the proper matching filter. But typically you can just address all clusters '0' and all channels '0'. So for example to set the brightness immediately to 50% and 100% after 10 minutes send this message.
{
'e': {
'fl': '0,0,50,10,100' # set all clusters, all channels 50% now, 100% after 10 minutes
}
}
Dimming values are 0-100 to indicate the brightness percentage. If the dimming value is greater than 100 for example 101 then the node ignores that set dim command. Likewise if the duration is negative the node will not execute the delayed command. However if the duration is 0 it will execute immediately. But generally it is best practice to set duration -1 if not needed or >0 if needed.
Autotune Event
The autotune event is used to set the color temperature of a tuneable white fixture. The event value specifies both the color and the total brightness. The node auto-tunes the two color channels driving the light fixture. This maintains the color mixture while still able to adjust the overall brightness. Hence color and brightness are independent parameters.
attune_event_value: cluster,color,total_dim
You can address all clusters using '0'. So for example to set all clusters to a color temperature of 4000k with brightness 100% send this message.
{
'e': {
'attune': '0,4000,100' # set all clusters 4000k and 100%
}
}
If the color value is lesser than 3000 or greater than 5000, the node does not change the output color. Likewise if the total_dim value is greater than 100, then this command will not change the total brightness. Therefore you can send commands that only effect one of the parameter outputs. For example to change the color without changing the brightness send this message.
{
'e': {
'attune': '0,4000,101' # set all cluster 4000k and no brightness change
}
}
RGBW Event
The RGBW color of a multi color light fixutre can be changed using an rgbw event. The event value specifies the color values and the total brightness. Like the autotune color, the node is able to maintain the RGBW color mixture while adjusting the total brightness.
rgbw_event_value: cluster,R,G,B,W,total_dim
You can address all clusters using '0'. For example to set a clusters to 100% red with brightness 50% send this message.
{
'e': {
'rgbw': '0,255,0,0,0,50' # set all clusters 100% red and 50% brightness
}
}
Note that the color values are in a range 0 to 255. However these values are relative to the sum of all values. So it is the ratio of each value to the sum that determines the final output color mixture. Whereas the total brightness is set by a separate dim parameter. This dimming scales all color channels equally.
Like the autotune event the colors will not change if any value is out of range in this case if it exceeds 255. And likewise the brightness will not change if the value exceeds 100. For example to change the color without changing the brightness send this message.
{
'e': {
'rgbw': '0,255,0,0,0,101' # set all clusters 100% red and no brightness change
}
}
Transport
The event messages use CoAP transport over UDP at port 5683. Ensure the CoAP message is structured correctly.
Encoding
The event message payloads are encoded using CBOR.
IP Address and Port
Direct your messages at the particular node IP address at port 5683.
URI
Address the event resource at /inx/event.
Method
CoAP event message should be sent as PUT NON. However if you do happen to PUT CON, then the node will respond with an ACK. If you do not want this acknowledgement, send a non-confirmable message.