Elite Relay

Elite: Dangerous Journal Event Handler

[!IMPORTANT] This document is a work-in-progress and may contain incomplete information.

Introduction

elite-relay is a small program that tracks events recorded in your Elite: Dangerous journal file and allows you respond to them in certain ways, including:

• Sending an HTTP request with the event data, e.g. firing a webhook to a service like Home Assistant or Zapier.
• Copying text to your clipboard, e.g. the name of the star system you just jumped to.
• Opening a templated URL in your browser, e.g. opening an Inara.cz "search nearest" page when jumping to a new system.

Event handlers ("plugins") are defined in .edr/config.yaml located in your home directory. See "Configuring plugins" for more information, or check out some examples in examples.yaml.

Installation

Using the MSI installer

The easiest way to install elite-relay is via the MSI installer included in the latest release. Simply download the file and open it, the program will then be installed to your $FOLDER folder. Open the main.exe file to start it.

Using pip

Alternatively, you may install elite-relay via Python's pip package manager (or any other Python package manager of your choosing):

pip install --upgrade elite-relay

You can now run elite-relay in a terminal to start the program.

Configuring plugins

Event handlers ("plugins") are defined in .edr/config.yaml located in your home directory. There are a few basic options that apply to all plugins, as well as plugin-specific options that are defined under the options key. Let's start with a basic example that will copy the name of the star system to our clipboard whenever an FSDJump event occurs:

plugins:
  - plugin: clipboard
    action: copy
    filters:
      - key: type
        eq: FSDJump
    options:
      text: ${data.StarSystem}

Let's break it down:

Global options

Plugins & actions

The plugin: clipboard key tells the program which "plugin" to use when responding to an event. All plugins are comprised of different "actions," in this example it's copy.

Filters

Filters allow us to only respond to events that we care about. In this example we only want to copy text to our clipboard whenever the FSDJump event type is recorded, hence the filters block above:

filters:
  - key: type
    eq: FSDJump

In this instance we're telling the program to only respond to events where the type is exactly equal to FSDJump.

Filters can also use regular expressions (regex) for more complex filtering operations. To use regex filtering enable it by setting regex: true in the filter; now the expression in the eq key will be evaluated as regex. For example if we wanted to narrow our filter further by only triggering on systems that begin with "HIP" we could do the following:

filters:
  - key: type
    eq: FSDJump
  - key: data.StarSystem
    eq: ^HIP (.*)$
    regex: true

Filter keys may also use JMESPath syntax to reference deeply-nested information within the event data. For example, if we wanted to trigger if the first power in the system is "Li Yong-Rui" we would do:

filters:
  - key: type
    eq: FSDJump
  - key: data.Powers[0]
    eq: Li Yong-Rui

Plugin-specific options

The options key above provides plugin-specific options that are documented alongside the code for each plugin in the plugins directory.

In this example the clipboard.copy action has a required option for the text we wish to copy. The text is templated, meaning that we can reference data within the event to copy. In this instance ${data.StarSystem} will be converted to the name of the actual star system we just jumped to:

options:
  text: ${data.StarSystem}