Remotes

The Remotes page manages IP-based remote controls (such as Control4 SR-260, URC, Elan, and compatible devices), mapping remote button presses to GEM commands, macros, AV source selections, and source-specific command maps.

Remote Selection

At the top of the page is a SelectSearch dropdown listing all configured remotes. When editing a remote, the header shows the remote ID and name. For the master template, the header shows "Master Template".

Button	Description
Reload	Reloads the selected remote's device driver. For the master template (ID 0), this reloads all remotes and shows a confirmation prompt with the count of affected remotes. The button label changes to "Reload All" when the master template is selected.
Add	Creates a new remote. Prompts for a name, then creates the remote with pass-through enabled and a placeholder address of 0.0.0.0.
Delete	Deletes the selected remote (with confirmation). Cannot delete the master template.

Master Template (Remote ID 0)

Remote ID 0 is the master template. All other remotes inherit key mappings from this template. When the master template is selected, a yellow info box explains:

• This is the master template remote.
• All other remotes inherit default settings from this template.
• Only configuration settings and key mappings can be edited.

The master template has these restrictions:

• The Name field is disabled.
• The AV Zone field is disabled (the template does not control a specific zone).
• The Enabled toggle is disabled (the template is always enabled).
• The IP Address and Port fields are disabled.
• The Delete button is blocked with an error message.
• The template cannot be deleted.

For the master template, the AV Source list shows all distinct AV sources across all zones, rather than sources for a specific zone.

---

Remote Configuration

This section appears after selecting a remote from the dropdown.

Field	Description
Name	The remote's unique identifier (e.g., living_room_remote). Disabled for the master template.
AV Zone	The AV zone this remote controls. Determines which sources are available for source-type key actions. Disabled for the master template. When changed, the available source list updates.
Status	Toggle switch to enable or disable the remote. Shows "Remote is enabled" or "Remote is disabled." Disabled for the master template (always enabled).

Connection Settings

Field	Description
IP Address	The IP address of the physical remote control. Disabled for the master template.
Don't monitor connection	A checkbox below the IP Address field. When checked, GEM does not monitor whether this remote is reachable. Useful for remotes that are intermittently powered or rarely used.
Port	A dropdown with the following options: Websocket (Auto) (default, no port specified), 6333, 6334, 6335, 6336, 6337, 6338, 6339. Disabled for the master template.
Pass Through	A toggle switch. When enabled, all unhandled key presses from the remote are passed through to GEM as commands on the currently active AV source (or multiview source, if set). When disabled, only explicitly mapped keys trigger actions. For the master template, this sets the default pass-through behavior for all remotes. See Pass-Through Commands below.
Volume Step	A number input (range 1-5) that controls how much the volume changes per press of the volume up/down buttons. For the master template, this sets the global default. For individual remotes, leave blank to use the global value, or enter a number to override it.

Click Save Remote to save the configuration.

---

Tabs

When a remote is selected, the configuration is organized into two tabs:

• Settings: Remote configuration and connection settings (described above)
• Keys: Live key events and key mappings (described below)

---

Key Mappings

The Keys tab shows all button-to-action assignments for the selected remote.

Key Mapping Grid

The grid has the following columns:

Column	Description
(delete icon)	For remote-specific keys, a delete icon to remove the mapping (with confirmation). For inherited keys, shows the text "inherited" instead.
Key	The button name (e.g., power, volume_up, play).
Action	The action type (command, macro, source, multiview_source, or map).
Detail	A description of what the action does (e.g., device name and command, macro name, source name, or mapped commands with their sources).
Enabled	A toggle switch to enable or disable the key mapping. Toggling this saves the change immediately. For inherited keys, shows "always" instead (inherited keys are always enabled).
(edit icon)	For remote-specific keys, an edit icon to load the key mapping into the input row for editing. Not available for inherited keys.

Inherited Keys

When viewing a regular remote (not the master template), keys from the master template that are not overridden by this remote appear in the list with reduced opacity and italic text. These inherited keys:

• Cannot be deleted from this remote (they belong to the master template).
• Cannot have their enabled state toggled from this remote.
• Show "inherited" in the delete column and "always" in the enabled column.
• Are automatically overridden if you create a key mapping with the same key name on this remote.

Adding and Editing Key Mappings

The bottom of the key mappings section has an input row for adding or editing mappings:

Field	Description
Key	A fill-in SelectSearch dropdown with all standard remote button names. You can select from the list or type a custom key name.
Action	A dropdown with five options: command, macro, source, multiview source, map.
Action Detail	Changes based on the selected action type (see below).
Enabled	A toggle switch (defaults to enabled).
Add / Update	Button to save the key mapping. Shows "Update" when editing an existing key, "Add" when creating a new one.
Cancel	Appears when editing. Cancels the edit and clears the input row.

To edit an existing key mapping, click the edit icon in its row. The key's current settings are loaded into the input row, and the button changes to "Update". The row being edited is highlighted with a blue left border.

Action Types

Command

Sends a device command when the key is pressed. When selected, a Command Configuration panel appears below the key mappings section with the full CommandStep component. This lets you select a device, command, and arguments to send.

The detail column shows the device name, command name, and any arguments.

Macro

Runs a GEM macro when the key is pressed. A SelectSearch dropdown appears in the action detail area listing all enabled macros.

The detail column shows the macro name.

Source

Selects an AV source in the remote's AV zone when the key is pressed. A SelectSearch dropdown appears listing all sources for the remote's AV zone, plus an "Off" option (source ID 0) to turn off the zone.

The detail column shows the source device name, or "off" for the Off option.

Multiview Source

Selects a source within the active multiview layout for the remote's AV zone. When the key is pressed, the specified source is displayed in the multiview — either in its grid position or in fullscreen mode, depending on the configuration.

A SelectSearch dropdown appears listing all sources for the remote's AV zone. Select the source to activate within the multiview.

The detail column shows the multiview source device name.

Map

Creates a source-specific command mapping. This action type lets a single key behave differently depending on which AV source is currently active. When selected, two fields appear:

Field	Description
Command	A text input for the command name to send (e.g., play, pause, home).
Sources	A MultiSelector showing all sources for the zone (plus an "All" option). Select one or more sources that this command applies to.

When the key is pressed, GEM checks which source is currently active in the zone and sends the mapped command only if the active source is in the selected sources list.

If a key already has a map action, adding another map entry for the same key appends to the existing map rather than replacing it. This lets you define different commands for different source groups on the same key.

The detail column shows each command name and which sources it applies to (e.g., play for Apple TV, Roku).

Available Key Names

The following standard key names are available:

• Power: power
• Activities: activity_1 through activity_8
• Letters: a, b, c, d
• Navigation: up, down, left, right, select, back, exit, menu, guide, info
• Playback: play, pause, play_pause, stop, record, fast_forward, rewind, scan_back, scan_forward, skip_back, skip_forward, previous
• Volume/Channel: volume_up, volume_down, mute, channel_up, channel_down
• Number Pad: 0 through 9, asterisk, enter
• Color Buttons: red, green, yellow, blue

You can also type a custom key name if the remote sends non-standard keys.

---

JSON Command Format

Remotes can send a JSON payload instead of a plain key name, allowing parameters to travel with the command. The remote transmits a string like:

{"command": "play", "param1": "chapter_3", "param2": "5"}

GEM parses the payload, uses the command field as the key name (so normal mapping still applies), and captures param1..param10 for downstream use.

Built-in JSON commands

Command	Parameters
source	param1 = source ID to select on the remote's AV zone
multiview_source	param1 = source ID, param2 = "true"/"false" for fullscreen

Explicit Zone or Device Target

A JSON payload may include an explicit target. When present, GEM forwards the command directly to that zone or device, bypassing the AV-zone pass-through path entirely (so it does not route to the active source device).

Field	Description
zone_id or zone	Numeric zone ID or zone name to target.
device_id or device	Numeric device ID or device name to target.

Example payloads:

{"command": "open", "zone_id": 87}
{"command": "on", "zone": "front_porch_lights", "level": 80}
{"command": "play", "device_id": 42}

Any additional fields in the payload are passed through to the command as arguments. Key mappings on the remote are not consulted for these explicit-target payloads.

Explicit Macro Invocation

A JSON payload may invoke a macro directly. When present, GEM runs the macro and bypasses the AV-zone pass-through path.

Field	Description
macro_id	Numeric macro ID to run.
macro	Macro name (or numeric ID) to run. Looked up by name first, then by ID.
args	Optional object passed as arguments to the macro.

Example payloads:

{"macro_id": 42}
{"macro": "good_night"}
{"macro": "scene_recall", "args": {"scene": "movie"}}

If the macro cannot be resolved, a key_press event with action: error and detail: unknown macro is emitted and the command is dropped.

Pass-Through Commands

When Pass Through is enabled and a key is unmapped, GEM sends the command to the active AV source (or active multiview source). If the command was supplied in JSON form with paramN fields, those values are forwarded as arguments to the driver command, mapped positionally to the target command's declared argument names:

• param1 → first argument, param2 → second, and so on (up to param10)
• If the target command has no declared args, the raw param1..paramN keys are passed through unchanged

This lets a single remote button carry data (channel number, chapter, preset, etc.) to the active source without defining a separate key mapping per value.

---

Troubleshooting

Remote Not Responding

1. Verify the remote is powered on and connected to the network.
2. Check that the IP address is correct.
3. Ensure "Don't monitor connection" is unchecked if you want GEM to track connectivity.
4. Verify the correct port is selected.
5. Check that the remote is not in setup or pairing mode.

Key Not Working

1. Verify the key is mapped in the key mappings grid.
2. Check that the mapping is enabled.
3. Confirm the action is configured correctly (device online, macro exists, source assigned).
4. Check if the key is inherited from the master template and being overridden unintentionally.

Volume Not Working

1. Verify an AV Zone is assigned to the remote.
2. Check the volume step setting (1-5 range).
3. Confirm the AV zone's volume device supports volume commands.

Related Documentation

• AV Zones - AV zone configuration for remotes
• AV Sources - Source configuration
• Macros - Macros triggered from remote keys
• Devices - Remote device configuration