# 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] + line feed
Example 1 : Sending 8801P + line feed to the Gateway, will instruct the Gateway to press button 1 on the keypad with integration id 88.
Example 2 : Sending 0703R + line feed 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] + line feed
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 + line feed 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 + line feed 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] + line feed
Example 1 : If you receive B1302OF*, this means that the second button of keypad with id 13 has turned off.
Example 2 : If you receive B0106ON*, 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] + line feed
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 + line feed 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.
Note
For debugging purposes we have also included SUB-999 + line feed 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.