4.11. Recipes

This document describes the recipe functionality of Edge Connect.

Recipes are reusable, self-contained Edge Connect configurations that can be run aside a normal Edge Connect configuration (top-level 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 can be 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.

4.11.1. 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 (note that versions must be exact, there is no fuzzy matching).

{
    "imports": {
        "recipes": [
            "minew-e8@1.0.0"
        ]
    }
}

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 and the values will be 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": [
            "minew-e8@1.0.0"
        ],
        "variables": {
            "minew-e8.accelXMax": 0.9
        }
    }
}

Using a Recipe Export

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

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

For example if myRecipe exported a filter called myExportedFilter, you could use the export in a pipeline with:

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

Receiving Recipe Events

The recipe will document the event types emitted and describe the event payload.

A recipe’s event types can be referred to with recipeName.eventType.

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

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

4.11.2. Creating a Recipe

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

Instead of assembling pipelines, filters, connections, actions, matchers, etc together to most likely publish to the cloud, you emit a custom event with the relevant information in the event payload.

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
  • All event types emitted by a recipe must be declared in the emits map in the recipe and start with recipeName. and 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). 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 on a Rigado server 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 list.