Skip to main content

Command Sets

Command Sets are collections of named commands that can be sent to devices. They are primarily used for infrared (IR) control and custom communication protocols.

Overview​

The Command Sets page manages libraries of commands for controlling devices. GEM provides three powerful ways to populate command sets: importing from GEM's cloud repository, importing from the global IRDB database, or importing from Global Cache IR files.

Viewing Command Sets​

The main grid displays all configured command sets with the following columns:

  • ID - Unique identifier
  • Name - Internal command set name
  • Description - Purpose or device model description

Grid Actions​

  • Add - Create a new empty command set
  • Edit - View and manage commands in the set (opens the Commands editor in a modal, so the command-set list keeps its place)
  • Delete - Remove a command set
  • Reload - Refresh the grid data

A command set an application package installed carries a package icon in its row toolbox. Hovering names the package and its version; clicking opens it in Applications. A package that ships a driver usually ships the command set that drives it, and editing or deleting that set changes what uninstalling the package removes — so the icon is the warning as much as the link. A command set you built or imported yourself shows no icon.

Creating a Command Set​

You can create command sets in three ways:

1. Manual Creation​

For custom or proprietary protocols:

  1. Click Add in the grid
  2. Enter a name (will be auto-formatted to lowercase_with_underscores)
  3. The empty command set is created
  4. Click Edit to add individual commands

2. Browse GEM Repository​

Import professionally-maintained command sets from GEM's cloud repository:

  1. Click Browse GEM button
  2. Search for your device manufacturer or model
  3. Review the available command sets:
    • Device name and description
    • File size and modification date
  4. Click Import on the desired command set

Merge Behavior:

  • If a command set with the same name exists, you'll be prompted to merge
  • Matching commands are updated with new templates
  • New commands are added
  • Your custom commands are preserved

3. Browse IRDB​

Import from the global Infrared Remote Database (IRDB) containing thousands of IR codes:

  1. Click Browse IRDB button
  2. Search by manufacturer name or device type (e.g., "Sony", "TV", "Cable")
  3. The grid displays all matching devices:
    • Manufacturer name
    • Device type
    • Filename
  4. Click Import on the desired device

Conversion Process:

  • IRDB codes are stored in various formats (NEC, RC5, Sony, etc.)
  • GEM automatically converts all codes to Pronto Hex format
  • A progress message shows conversion status
  • Successfully converted commands are added to a new command set

Command Set Naming:

  • Auto-generated: manufacturer_devicetype_filename
  • Example: sony_dvd_player_dvp_ns575p

4. Import Global Cache IR​

Import command sets from Global Cache's IR database emails:

  1. Obtain an IR database file from Global Cache (usually emailed as .txt or .csv)
  2. Click Import GC IR button
  3. Select your downloaded file
  4. Enter a name for the new command set
  5. GEM parses and imports all commands

Supported Format:

"command_name","sendir,1:1,<pronto_hex_code>"

Commands are automatically cleaned:

  • digit_ prefix is removed (e.g., digit_1 becomes 1)
  • cursor_ prefix is removed (e.g., cursor_up becomes up)

Managing Commands​

After creating a command set, click Edit to open the Commands editor in a modal where you can:

  • Add individual commands
  • Edit command templates
  • Test command execution
  • Configure command parameters
  • Delete unwanted commands
  • Export commands to JSON

See the Commands documentation for detailed information on command management.

Command Sets and Drivers​

Most command sets are not built by hand. A driver that declares commands of its own owns a set named after it (or after the name it suggests), and that set is where its templates live:

  • Picking the driver on a device fills the Command Set field with it, creating the set empty if this is the site's first device on that driver.
  • The rows arrive the first time a device using it loads — the driver's declared commands are synced in and re-applied on every boot. They carry the DRIVER badge and are read-only; see System Commands.
  • Changing a device's driver moves it to the new driver's set, because the templates in the old one speak the previous protocol. You're asked first whenever the set could be one you built or customized, and declining keeps the set the device has. See Changing a device's driver.

The generic transports (generic_tcp, generic_serial, generic_http, generic_ir, …) declare no commands, so their sets are entirely yours — built here, imported from IRDB or the GEM repository, or typed in by hand. GEM never re-points a device away from one of those on a driver change, since there would be nothing to move to.

A command set may be shared by any number of devices. Two devices on the same driver normally share one, which is why a set's rows belong to the driver rather than to a single device.

Command Set Naming​

Command sets follow the same naming convention as other GEM entities:

  • Internal Name: Lowercase with underscores (e.g., sony_dvd_ns575p)
  • Description: Human-readable text (e.g., "Sony DVD Player NS575P")

The name field is automatically formatted when you click away from it.

Common Use Cases​

IR Control​

Command sets are most commonly used for infrared control of:

  • TVs and displays
  • Cable/satellite boxes
  • DVD/Blu-ray players
  • Audio receivers
  • Projectors
  • Fans and lighting (IR-controlled)

Serial/TCP Protocols​

Command sets can also store:

  • RS-232 command strings
  • TCP/IP protocol commands
  • HTTP API requests
  • Custom hexadecimal sequences

Command Templates​

Commands support template variables for dynamic values:

POWER:{state}
VOLUME:{level}
INPUT:{input_number}

These templates are processed by device drivers when sending commands.

Merging and Updating Command Sets​

When importing a command set that already exists:

  1. Confirmation Dialog appears explaining the merge process
  2. If you proceed:
    • Existing commands with matching names are updated
    • New commands are added
    • Your custom commands are preserved
    • A summary shows counts of updated and added commands

This allows you to:

  • Update command sets when new versions are available
  • Add missing commands to an existing set
  • Sync with the latest GEM or IRDB data

IRDB (Infrared Remote Database)​

The IRDB integration provides access to a massive collection of IR codes:

Coverage​

  • Thousands of manufacturers
  • Multiple device types per manufacturer
  • Community-maintained and updated regularly
  • Open-source database

Device Types​

Common IRDB categories include:

  • TV
  • Cable Box, Satellite Box
  • DVD, Blu-ray
  • Receiver, Amplifier
  • Air Conditioner
  • Fan
  • Projector
  • Soundbar

IR Code Formats​

IRDB stores codes in various formats:

  • NEC, NECx, NEC48
  • RC5, RC6
  • Sony (SIRC)
  • Samsung
  • Panasonic
  • And many more proprietary protocols

GEM's IR converter translates all these formats to Pronto Hex for universal compatibility with IR emitters.

Rendering IR codes​

Conversion runs on the controller through the bundled irptransmogrifier renderer. Two things are worth knowing:

  • Rendering requires an elevated role. The render_ir API function is admin-only, so the IRDB import and the IR code preview are unavailable to non-elevated sessions even with a wildcard API grant. See Roles.
  • Parameters are validated before rendering. The protocol name must look like an IrpTransmogrifier protocol (Sony20, NEC1-f16, Panasonic_Old), and device / subdevice / function must be plain integers. Anything else is rejected with Invalid IR render parameters rather than being passed to the renderer. A subdevice of -1, 0, or blank renders without an S= term, exactly as before — already-commissioned IR devices produce identical Pronto hex.

Rendered results are cached, so re-importing the same code set is fast. Failed conversions are not cached and are retried on the next attempt.

Pronto Hex Format​

All IR commands in GEM are stored as Pronto Hex:

0000 006D 0022 0002 0155 00AA ...

Advantages:

  • Universal format understood by all IR emitters
  • Manufacturer-agnostic
  • Includes carrier frequency and timing information
  • Easy to test and validate

Compatibility:

  • Global Cache IR devices
  • iTach IR
  • IP2IR
  • RedRat
  • Most professional IR equipment

Tips and Best Practices​

  1. Search Strategy: When browsing IRDB or GEM repository, try multiple search terms:

    • Full model number: "DVP-NS575P"
    • Partial model: "NS575"
    • Manufacturer only: "Sony"
    • Device type: "DVD"

  2. Testing: After importing, test critical commands (Power, Volume, Input) before deploying

  3. Cleanup: Remove unused commands to keep command sets manageable

  4. Naming: Use descriptive names that include manufacturer and model

  5. Backup: Export command sets periodically (use DataGrid export feature)

  6. Documentation: Add descriptions to command sets noting:

    • Which physical devices they control
    • Any special configuration requirements
    • Date imported and source

  7. Updates: Check for updated command sets periodically in the GEM repository

Troubleshooting​

Import Fails​

GEM Repository Issues:

  • Check network connectivity
  • Verify firewall allows access to GEM servers
  • Try again later if servers are temporarily unavailable

IRDB Issues:

  • IRDB index may take 10-20 seconds to load (thousands of devices)
  • Some obscure devices may not have codes available
  • Try alternate search terms or manufacturer names

Global Cache Import:

  • Verify file format matches expected CSV structure
  • Check that file contains valid Pronto Hex codes
  • Ensure file is plain text (not a binary format)

IR Commands Don't Work​

  1. Wrong Device: Verify you imported codes for the correct model
  2. IR Emitter Position: Ensure IR emitter has line-of-sight to device sensor
  3. Code Format: Some devices may require specific code variants
  4. Device Mode: Some devices require codes for specific modes (TV mode, DVD mode, etc.)

Duplicate Commands​

When importing multiple sources, you may get duplicate command names. GEM handles this by:

  • Updating existing commands during merge
  • Preserving your customizations
  • Showing a detailed merge report

Advanced Topics​

Command Arguments​

Commands can accept dynamic arguments:

{
  "args": ["power"],
  "arg_options": {
    "power": ["on", "off", "toggle"]
  }
}

This allows a single command template to handle multiple variations.

Command Macros​

Complex operations can combine multiple commands with delays:

{
  "name": "watch_tv",
  "macro": [
    {"command": "tv_power_on"},
    {"delay": 2000},
    {"command": "receiver_power_on"},
    {"delay": 1000},
    {"command": "receiver_input_tv"}
  ]
}

Export and Import​

Use the grid Export button to:

  • Back up command sets (CSV by default; choose JSON in the export dialog when you plan to re-import)
  • Share command sets between GEM installations
  • Version control command library changes
  • Submit new command sets to the GEM repository

To export only specific rows, multi-select them first (click-and-drag or Ctrl+Click) and use Export Selected.