Integration Protocol (API)

The Gateway offers an open API which can be used to send commands to the to control it's loads and keypads. It can also be used to listen for any changes that occurred on the Gateway. All of this is done on port 3333 of the Gateway.

Button presses and release

This command allows you to press a button on one of Gateway virtual keypads. Useful for when you want to map a real keypad to virtual keypads.

Syntax:

[keypad_integration_id][button_number][P/R] + carriage return

Example 1 : Sending 8801P to the Gateway, will instruct the Gateway to press button 1 on the keypad with integration id 88.

Example 2 : Sending 0703R to the Gateway, will instruct the Gateway to release button 3 on the keypad with integration id 07.

WARNING

Never send single digits without a leading 0.

You must specify the Press or Release of a button when calling a raise or lower button. The release action will stop the dimming process.

Direct command to a load

This command allows you to control the loads by directly manipulating the color and dim levels.

Syntax:

load_id-[load integration id]-[load level]-[HEX color]-[white level]-[fade time] + carriage return

Integration id : Actual id of the load as it appears in the Gateway's configuration page.

Load Level : from 0 to 100 %

HEX color : RGB representation of color in hexadecimal (Example: Orange is FF8800)

White Level: from 0 to 100 %

Fade time : time to reach the level and color in milliseconds (Example: 1 second is 1000 milliseconds)

Example : Sending load_id-88-50-FF0000-126-6000 + carriage return to the Gateway will set the load with id 88 to red with 50% brightness, white to 126 of 255 over 6 seconds.

Dim without changing color

To reuse this command to only dim the loads, replace the hexadecimal number with XXXXXX. This will allow you to adjust the brightness of the load, without changing it's color.

Example : Sending load_id-88-35-XXXXXX-126-6000 + carriage return to the Gateway will set the load with id 88 to 35% over 6 seconds.

Gateway Feedback and Status

To get the status of the Gateway, you will need to continuously listen to port 3333. Information is broadcasted every time a change occurs. All information will be separated by an asterisk symbol *.

Example : B1302OF*B0106ON*L088-5-255-200-25-128-88*

Button status

When a button changes status, that button's number, keypad id and whether it's scene is on or off will be indicated:

Listening for these events becomes useful when you want to turn on and off the LEDs on physical keypads.

Syntax:

B[keypad id][button number][ON/OF] + carriage return

Example 1 : If you receive B1302OF + carriage return, this means that the second button of keypad with id 13 has turned off.

Example 2 : If you receive B0106ON + carriage return, this means that the button 6 of keypad with id 1 has turned on.

Load Subscription

To limit the amount of traffic and parsing involved with all the loads, you will need to subscribe to a load to receive any information about it.

Syntax: SUB-[load id] + carriage return

Make sure to keep sending this command at least every 10 seconds. The Gateway automatically unsubscribes you from a load after 10 seconds to help manage traffic.

Example : Sending SUB-76 + carriage return to the Gateway will make sure you keep receiving the status of load with id 76 for the next 10 seconds.

This is only required for loads you want feed back from, the loads will still keep processing commands even if you are not subscribed to them. This is not needed for buttons. You may subscribe to many different loads at the same time, but this increases the network traffic.

TIP

For debugging purposes we have also included SUB-999 + carriage return which subscribes you to all the loads. We don't recommend you use this on a final setup.

Load status

When a load changes, that load's current color and light levels will be broadcasted.

Listening for these events becomes useful when you want to your interface to update itself with the current status of a load.

Syntax:

L[load id]-[channels]-[red level]-[green level]-[blue level]-[white level]-[load level]

Example : If you receive L088-5-255-200-025-128-088, this means that load 88, which has 5 channels (red, blue, green, white and dim), has it's red channel set to 255, it's green channel set to 200, it's blue channel set to 25, it's white channel set to 128 and it's dim level set to 88%.

If you receive L088-9 (and nothing else delimited by a asterisk symbol), then this indicates that the load has finished transitioning and won't transition again until a command tells it too.

Last Updated: 6/12/2019, 1:49:00 PM