KanexPro 8-Button IP Keypad

Telnet integration for the KanexPro WP-IPKEYPAD8, a PoE single-gang wall plate with eight backlit keys and a relay output. The keypad runs its own macros, which you program in its WebGUI. It reports every macro run on its telnet port, and that is how GEM sees a key press. GEM can also press keys, drive the red and blue LED behind each key, and open, close or toggle the relay.

One keypad becomes one GEM device. Each key you want to use becomes a zone with address 1–8. The relay can be a zone too, with address relay.

What this integration covers

• Key presses. Every press lands on the key zone's keypress attribute, which triggers can watch. Key actions can also run a GEM command or macro straight from a press, with no trigger needed.
• Key LEDs. Set each key to red, blue, both or off at any brightness. A key zone's on / off lights its LED, so a key can show GEM state such as a scene being active or a room being occupied.
• Relay. Open, close or toggle. A relay zone follows its subsystem's contact mapping: a gate opens on a closed contact, a light turns on with a closed contact, and normally_closed or relay_states on the zone override either.
• Keypad macros. Run or stop any of the 16 macros, and set a key to fire on release or repeat while held.
• Confirmed commands. Every command waits for the keypad to echo it back. A rejected argument, an unknown command or a keypad that stops answering comes back as an error instead of looking like success.
• Tracked state. LED levels, relay state and key modes follow the keypad's echoes, including changes made by the keypad's own macros, schedule and WebGUI.

What this integration does NOT cover

• Reading state back. The keypad has no query commands. After a keypad power cycle, GEM keeps the last LED and relay state it saw until something changes it. A relay toggled from an unknown state stays unknown.
• Programming macros. Macro contents, commands, device definitions and schedules are edited in the keypad's WebGUI.
• Network settings. The telnet commands that change the keypad's IP, mode or factory defaults are left out on purpose. Use the WebGUI, or send_raw if you really mean it.

Prerequisites

• The keypad is reachable from GEM on TCP 23. Out of the box it is at 192.168.1.50. Set DHCP or a static address in its WebGUI.
• Each key you want to use has a macro assigned in the WebGUI (Macro Settings). A key with no macro prints nothing when pressed. An assigned macro with no steps still reports the press.
• The keypad's LED Demo Mode is on from the factory and animates the keys on its own. Turn it off if GEM is going to drive the LEDs, either in the WebGUI or with the led_show command (off).

Setup steps

1. Go to System → Devices → Add Device (Open Devices) and pick KanexPro 8-Button IP Keypad.
2. Enter the keypad's ip. The port defaults to 23.
3. Save. The device connects within a few seconds and fills in firmware_version, mac_address and the network attributes, and the editor opens the Setup tab.
4. Press each key you want to use. On the Setup tab it flashes and gets a check, and it is selected so you can configure it.
5. For each key, click Create zone, pick a subsystem and set what GEM runs when it is pressed. Any subsystem works for a key; it only affects where the zone is grouped.
6. If the relay is wired to something, select Relay and create its zone in the subsystem it drives, such as Shades for a projector screen or Gates for a gate.

Everything the Setup tab does can also be done by hand: a key zone is a zone on this device with address set to the key number (1–8), the relay zone has address relay, and key actions are the device's keys attribute. Each press updates the key zone's keypress attribute, and the device log shows kanex keypad macro event:.

Setup tab

The Setup tab in the device editor is a working picture of the keypad.

• Readiness. Chips across the top show whether the keypad is connected, its firmware, whether LED demo mode is off (with a Turn off button), and how many keys GEM has heard from the wall.
• Faceplate. The eight keys and the relay. Each key shows its zone, its GEM action and its LED color. A key pressed on the wall flashes and, with Select a key when it is pressed on, becomes the selected key. A key that never flashes has no macro in the keypad's WebGUI.
• When pressed, GEM runs. The key's action: commands and macros picked with the same forms the macro builder uses, run in order. Cycle steps through a list, one per press. Keep running while the key is held fires again on held-key repeats (the key must be in hold mode). A second section sets the action for the key's toggle-mode macro (n + 8). Each change saves to the keys attribute. JSON shows the raw entry.
• LED. Try a color and brightness on the key, set the color the zone's on command lights, and make the LED follow something in GEM (see LEDs that follow GEM).
• Key mode. Release or hold.
• Relay. Create its zone, test open, close and toggle, and reverse the contact if it is wired normally closed.

If the keys attribute holds something that is not valid JSON, the Setup tab says so and does not overwrite it. Fix it on the Attributes tab first.

Key presses

Keys are reported as macro runs. Key n runs macro n. In toggle mode, set in the WebGUI's Key Settings, key n alternates between macro n and macro n + 8. Both land on the key n zone, and keypress.macro says which of the two ran.

Each press writes the key zone's keypress attribute:

{"macro": 3, "button": 3, "action": "press", "source": "keypad", "timestamp": 1790374416697}

Field	Meaning
macro	Keypad macro that ran.
button	Key number of the zone.
action	press, or repeat for a held key's repeats when the key is in hold mode.
source	gem when GEM ran the macro (press / run_macro), otherwise keypad. The keypad's scheduler and WebGUI also report as keypad, because the wire does not distinguish them from a press.
timestamp	Milliseconds since epoch. It changes on every press, so pressing the same key twice still fires a trigger.

The device also gets last_macro (the number) and last_event (the same object) for macros that have no zone.

Key actions — the keys attribute

For a keypad whose only job is to fire GEM actions, set the device's keys attribute instead of writing triggers. It maps a macro number to what GEM runs:

{
  "1": {"macro": "presentation_mode"},
  "2": [{"zone": "room_lights", "command": "level", "args": {"level": 50}}, {"macro": "shades_down"}],
  "3": {"cycle": [{"zone": "fan", "command": "on"}, {"zone": "fan", "command": "off"}]},
  "4": {"zone": "amp", "command": "volume_up", "repeat": true},
  "8": {"macro": "room_off"}
}

• An entry is a GEM command, a {macro} / {macro_id} reference, or a list of those run in order.
• cycle steps through its entries, one per press.
• repeat: true also fires on a held key's repeats. Without it, only the first press fires.
• The shape matches the keys attribute of the Hall Research keypad driver, so a map can move between the two.

LEDs

Each key has a red and a blue LED, each with a brightness of 0–100. led sets both at once, so the key ends up exactly the color you asked for:

Command	Wire
led address 3, color red, level 60	LEDRED 3 60, LEDBLUE 3 0
led address 3, color both	LEDRED 3 100, LEDBLUE 3 100
on (key zone)	the zone's led_on_color (default blue) at led_on_level (default 100)
off (key zone)	both LEDs to 0

Key zones carry led_red, led_blue, led_color (off / red / blue / both) and state (on when either LED is lit).

LEDs that follow GEM

A key's LED can mirror any zone or device attribute with no trigger: a scene key lit while its lights are on, a lock key red while the door is unlocked, a climate key red above 75°. Set it on the Setup tab under LED → Follow something in GEM, or write the key zone's led_follow attribute:

{
  "target": "zone", "target_id": 12, "attribute": "state",
  "rules": [
    {"op": "eq", "value": "on", "color": "blue", "level": 100}
  ],
  "default": {"color": "off"}
}

Field	Meaning
target, target_id	The zone or device to watch.
attribute	The attribute on it.
rules	Checked in order; the first match sets the LED. op is eq, ne, gt, gte, lt, lte or any. Numbers compare as numbers; text ignores case. level defaults to 100.
default	The LED when no rule matches. Leave it out to leave the LED alone.

The driver applies the rule whenever the watched attribute changes, as soon as led_follow is saved, and every time the keypad reconnects — it can't read its LEDs back, so a keypad that lost power is re-lit from GEM's current state. A key zone's on / off, a keypad macro or a trigger can still change the LED; the next change to the watched value puts it back. A value that changes many times in a moment — a dimmer ramping — sends one LED write, not one per step: the keypad echoes on its own 2-second cycle, so the same request is not repeated within 5 seconds of being sent. After that window only the keypad's echo counts, so an LED changed by someone else is corrected on the next change to the watched value.

Relay

open, close, on, off and the other zone verbs on the relay zone go through the zone's subsystem mapping, exactly as for any other relay-driven zone. toggle flips the contact. The device-level relay_open / relay_close / relay_toggle drive the contact directly. The relay zone carries relay_state (open / closed) and state (the mapped zone state). The device carries relay_state too.

Attribute reference

Device attributes

Name	Type	Required	Description
ip	string	yes	Keypad IP.
port	int	no	Telnet port, default 23.
username / password	string	no	Sent only if the keypad prompts for a login. Firmware v2.03 does not prompt.
keys	json	no	Key actions — see above.
ack_timeout	int	no	How long a command waits for the keypad's echo, in ms. Default 5000.
firmware_version, mac_address, ip_mode, ip_address, netmask, gateway	string	—	Read from the keypad on connect.
last_macro, last_event	int / json	—	Most recent macro run.
relay_state, led_show, backlight, telnet_timeout	—	—	Last value seen on the wire.

Zone attributes

Name	Type	Description
address	string	1–8 for a key, relay for the relay (required).
keypress	json	Last press — see above.
led_red, led_blue	int	Tracked LED levels.
led_color	string	off / red / blue / both.
state	string	Key: on when lit. Relay: the subsystem-mapped state.
key_mode	string	release or hold, when set through GEM or seen on the wire. Set it by hand if you configured hold mode in the WebGUI, so held repeats are reported as repeat.
macros	json	Extra macro numbers that count as this key. Only needed for a key running something other than macro n / n + 8.
led_on_color, led_on_level	string / int	What on lights. Defaults are blue and 100.
led_follow	json	Makes the LED follow a zone or device attribute — see LEDs that follow GEM.

Commands

Command	Args	Notes
press	address	Runs the key's macro, the same as pressing it.
stop	address	Stops the key's macro.
led	address, color, level	color: off / red / blue / both.
led_red, led_blue	address, level	One color on its own.
key_mode	address, mode	release or hold.
on, off, toggle	address	Key zone: its LED. Relay zone: the relay.
open, close	address	Relay zone, through the subsystem mapping.
run_macro, stop_macro	macro	1–16. stop_macro with no macro stops all of them.
relay_open, relay_close, relay_toggle	—	Drive the contact directly.
leds_red, leds_blue, backlight	level	Every key at once.
leds_off	—	Every LED off.
led_show	mode	The factory LED animation: on / off / toggle.
telnet_timeout	mode	on / off — whether the keypad closes idle sessions.
get_version, get_ip_config	—	Refresh the identity and network attributes.
reboot	—	The driver reconnects afterwards.
send_raw	command	Any telnet line. Needs an elevated session.

Known quirks

• Replies lag by up to 2 seconds. The keypad sends its output on a roughly 2-second cycle, so a command's echo, and so its result, takes 0–2 s to arrive. The key or relay itself acts at once.
• Every telnet client sees everything. Echoes, errors and key presses go to every connected session. Leave GEM as the only telnet client. A second session makes the keypad's output buffer mangle lines. The driver repairs the damage it knows about, but the keypad is cleaner with one client.
• A clipped first character. Sometimes a NUL overwrites the first character of a reply (ELAY 1 OPEN for RELAY 1 OPEN). The driver restores it.
• The manual's ranges are wrong for firmware v2.03. LEDs and keys are 1–8, not 1–16. MACRO RUN accepts 1–16, not 1–32.
• Levels are clamped to 0–100 before sending.

Troubleshooting

Symptom	Check
Presses don't reach GEM	Does the key have a macro in the WebGUI? Look for kanex keypad macro event: in the device log. If it's there but the zone doesn't update, check that the zone's address is the key number. Toggle-mode presses of key n arrive as macro n + 8.
Commands return no acknowledgement from keypad	The session is up but the keypad isn't answering. The VER keepalive recycles a silent connection after about three minutes. Check for other telnet clients.
Commands return wrong command format	The keypad rejected an argument: keys and LEDs are 1–8, macros 1–16, levels 0–100.
Commands return command failed	An unknown command, usually a typo in send_raw.
Keys animate on their own	LED Demo Mode is on. Send led_show off.
Relay zone shows no state	The relay can't be read back. Its state is known after the first open or close from GEM or a keypad macro.