Hall Research Keypad

A network input device for Hall Research keypads and controllers. This driver does not switch or control anything on its own — it listens for button presses on the keypad and, for each press, runs a GEM command, a GEM macro, or the next step of a cycling sequence that you map to that button. One keypad becomes one GEM device.

Communication is Telnet over TCP to the keypad, default port 23, with no login. Keep the keypad on a trusted control LAN or VLAN, since the connection is unauthenticated.

How it works

1. During commissioning, each keypad button is programmed in the Hall Research configuration tool to emit a line like RUN MACRO[1] EVENT. when pressed. The number in the brackets is that button's event number — it is Hall's own term for a programmed button action, not a GEM macro.
2. GEM keeps a Telnet session open to the keypad and listens for those lines.
3. When a line arrives, GEM reads the number (for example 1) and looks it up in the device's Key Map.
4. If the Key Map has a matching entry, GEM runs whatever you mapped to it — a command, a macro, or the next step of a cycle.

The whole configuration is the Key Map. There is nothing to wire on the GEM side beyond the keypad's IP and that map.

What this driver covers

• Dispatch on button press — run a GEM command, a GEM macro, several actions at once, or a round-robin cycle whenever a mapped button is pressed.
• Per-button cycles — a single button can toggle or step through a list of actions, advancing one step per press and wrapping back to the start.
• LED reset on connect — when GEM connects, it turns the keypad's blue and red button LEDs off so the panel starts from a known state.

What this driver does NOT cover

• No zones. A keypad has no zone; the zone address field is unused. Add it as a device only.
• No outbound command set. This device exposes no commands of its own, so nothing appears for it on the Commands page — you configure it entirely through the Key Map, and it in turn drives your other devices, zones, and macros.
• No feedback attributes. The driver reports button presses into the actions you mapped; it does not publish a "last button" or LED-state attribute you can read elsewhere.
• No authentication. Telnet has no login here — put the keypad on a trusted control network.

Prerequisites

• A Hall Research keypad/controller reachable on the LAN with its Telnet/TCP control port (default 23) open.
• Each button you want to use programmed in the Hall Research configuration tool to emit RUN MACRO[N] EVENT., where N is a distinct event number per button.
• A written list of which button (event number) should do what, so you can build the Key Map.

Setup

1. Program the keypad buttons in the Hall Research configuration tool and note each button's event number.
2. Open Devices (System → Devices) and click Add Device.
3. Choose the Hall Research Keypad driver. GEM shows the matching device fields and a View integration guide link to this page.
4. Under Connection, set Keypad IP (and Telnet Port if it isn't the default 23).
5. Under Advanced, paste the Key Map JSON (see Building the Key Map below). The device will not connect until the Key Map is present.
6. Pick any subsystem to keep the device organized — it has no functional effect here, since the keypad drives macros and commands directly rather than a zone.
7. Save and enable the device. Press a mapped button and watch the device log confirm the match (see Troubleshooting).

Device attributes

Attribute	Required	Default	Description
ip	yes	—	LAN IP of the keypad. Shown as Keypad IP.
keys	yes	—	The Key Map (JSON), under the Advanced group. Maps each keypad event number to an action. The device will not connect until this is set.
port	no	23	Telnet/TCP port. Shown as Telnet Port.

Building the Key Map

The Key Map (keys) is a JSON object. Each key is the event number a button emits — written as a string, matching the N in RUN MACRO[N] EVENT. — and each value is what GEM should do when that button is pressed.

A value can be any of the following shapes.

1. Run a command. Target a device or zone and give the command name — the same name you would pick on the Commands page — plus optional args:

{ "device": "great_room_amp", "name": "on" }

• Use "device" with the device's name, or "device_id" with its numeric id.
• Use "zone" with the zone's name, or "zone_id" with its numeric id, to target a zone instead.
• Add "args": { ... } for commands that take parameters, exactly as on the Commands page.

2. Run a macro. Reference a macro by name or id:

{ "macro": "movie_night" }

{ "macro_id": 42 }

3. Cycle through actions. A cycle steps to the next entry each time the button is pressed and wraps back to the first — ideal for a single button that toggles on/off or rotates through scenes. Each entry can itself be a command or a macro reference:

{ "cycle": [
  { "device": "office_lights", "name": "on" },
  { "device": "office_lights", "name": "off" }
] }

4. Do several things at once. Give an array of actions and GEM runs all of them on each press:

[
  { "device": "projector", "name": "off" },
  { "device": "screen", "name": "up" }
]

A full Key Map combines these — one entry per button:

{
  "1": { "macro": "movie_night" },
  "2": { "cycle": [
    { "device": "great_room_lights", "name": "on" },
    { "device": "great_room_lights", "name": "off" }
  ] },
  "3": [
    { "device": "projector", "name": "off" },
    { "device": "screen", "name": "up" }
  ]
}

tip

Match each key exactly to the event number the button emits (RUN MACRO[1] EVENT. → key "1"). If the emitted number isn't a key in the map, the press is ignored — no error, just nothing happens.

Debounce

Each button is debounced by 300 ms: near-simultaneous duplicate emissions for one press are coalesced into a single dispatch. A genuine double-fire — the same action running twice from one press — almost always means the keypad is programmed to emit two different event numbers for that button; fix it in the Hall Research configuration tool.

Status LEDs

When GEM connects to the keypad it resets the blue and red button LEDs to off, so the panel starts from a known state. The driver does not otherwise change the LEDs during normal operation.

Cycles and restarts

A cycle's position is tracked in memory. If you reload the device or restart GEM, every cycle resets to its first entry. That's usually what you want (a fresh, predictable starting point), but be aware that a cycle button's "next" state does not survive a restart.

Troubleshooting

Symptom	Check
Device won't connect / nothing happens	The Key Map must be valid JSON mapping event numbers to actions — without it the driver refuses to connect. Confirm Keypad IP is set and the keypad's Telnet port is reachable.
Button presses appear in the log but no action runs	The device log prints hall keypad key match: when a press matches the Key Map. If you don't see it, the event number the keypad emitted isn't a key in the map — use the exact number from RUN MACRO[N] EVENT..
One press fires the action twice	The 300 ms debounce coalesces duplicate emissions, so a real double usually means the keypad emits two different event numbers for that one button. Audit the button's programming in the Hall Research configuration tool.
A cycle button seems "one step off"	Cycles advance one step per press and wrap around, and they reset to the first entry on a device reload or GEM restart. Press again to step to the intended action, or reload the device to start the cycle from the top.
Wrong device or zone responds	Check the action's target: device/zone use the name, while device_id/zone_id use the numeric id. A numeric value in device is treated as a name, not an id.

Related documentation

• Devices — adding and configuring the keypad device row.
• Commands — the command names and args you reference in a Key Map entry.
• Zones — targeting a zone (rather than a device) from a Key Map entry.
• Macros — building the macros a button can trigger, including multi-step sequences.
• Triggers — the other way to fire automation from an event; a keypad drives actions directly, a trigger reacts to a state change.