Recipes

This document describes the recipe functionality of Edge Connect.

Recipes are reusable, self-contained Edge Connect configurations that can be added within a top-level Edge Connect configuration.

Recipes may contain any combination of the following items:

• Pipelines which emit custom events for the top-level configuration
  to process
• Exported items (Filters, Actions, Pipelines, etc.) which can be referenced in the
  top-level configuration
• Configuration variables which are used to fine tune the recipe
  for an application

The typical use for a recipe is to abstract communications with a particular sensor into a custom event emitted by the recipe. This way the top-level configuration only needs to concern itself with final formatting of the data to publish to the cloud.

Some solutions partners consolidate their entire suite into a single recipe. In such cases, the recipe includes both cloud data transfer as well as sensor integration. Additionally, the sensors used are often listed in our Recipe catalog.

Usage

Including a Recipe

To include a recipe in your configuration, add it to the imports section of the Edge Connect configuration.

A recipe is imported by name and version. The version must be exact as there is no fuzzy matching.

{
    "imports": {
        "recipes": [
            "[email protected]"
        ]
    }
}

Configuring a Recipe

Recipe variables are fields inside the recipe exposed for simple configuration. Recipe variables are declared by the recipe in the variables field. Variable values are validated at startup.

A recipe is configured by setting values in the imports.variables section of the Edge Connect configuration. A variable is referred to in the form recipeName.variable.

Configuration of recipe variables is only necessary if the default values need to be modified in your application.

{
    "imports": {
        "recipes": [
            "[email protected]"
        ],
        "variables": {
            "minew-e8.accelXMax": 0.9
        }
    }
}

Using a Recipe Export

Recipe exports are reusable processing units (filters, actions, pipelines, etc) referenced in the top-level configuration. A recipe's exports are declared in the recipe exports field.

To use a recipe's export, refer to the exported item with recipeName.exportedItem.

For example, if myRecipe exported a filter named myExportedFilter, it can be used in a pipeline with:

{
    "pipelines": {
        "myPipeline": {
            "filters": [
                "myRecipe.myExportedFilter",
                "filter1",
                "filter2"
            ]
        }
    }
}

Receiving Recipe Events

The recipe documents the event types emitted and describes the event payload. The event types can be referred to used recipeName.eventName.

For example, to process all events from the myRecipe recipe:

{
    "imports": {
        "recipes": [
            "[email protected]"
        ]
    },
    "pipelines": {
        "myPipeline": {
            "eventType" : "^myRecipe\..+"
            "filters": [
                "filter1",
                "filter2"
            ]
        }
    }
}

Creating a Recipe

Creating a recipe is similar to creating an Edge Connect configuration.

Instead of assembling pipelines, filters, connections, etc. together to publish to the cloud, a recipe can emit a custom event with the relevant information in the event payload which is later published to the cloud by the top-level configuration.

Rules

• The recipe name as well as any id in the recipe must start with a lowercase alphanumeric and may contain alphanumeric, -, and _ characters.
• The recipe version must be a semantic version string (e.g. 1.3.7)
• All event types emitted by a recipe must be declared in the emits section start with recipeName. The sub-event type must meet the id requirements above.

Special Considerations

Metadata is not isolated within a recipe unlike the processing units (pipelines, filters, connections, actions, matchers, etc.). As a result, metadata collisions may occur.

If a metadata conflict between recipes or the top-level configuration is detected at startup, Edge Connect will not start. There is no detection of metadata conflicts after the initial startup check.

Testing

Typically, a recipe will be hosted by Rigado and downloaded/cached as needed. If a recipe is under development the recipe's JSON may be provided inline in the top-level configuration's imports.recipes section.