Device Recipes

A device recipe is a template (or ‘recipe’) for creating devices. If you have many devices that are the same or very similar, you can use device recipes to make creating those devices much easier.

Device recipes can be found under Device Recipes in your application’s navigation.

Adding a Device Recipe

From the Device Recipes page, click the “Add Device Recipe” button in the top right corner.

Device Recipe Configuration

A device recipe requires a name, and you may optionally provide a description of the recipe. Beyond that, all of the settings and fields that are available when creating or editing a device are also available when creating or editing a device recipe.

When creating a recipe, you may either import a previously exported recipe, or you may manually configure the device settings. If taking the latter path, you will be able to configure the recipe’s finer details after choosing a name and initially creating the recipe.

A device created from a recipe copies all of the properties and configuration of the recipe to the new device being created. One additional tag will be added to the new device - a tag with the name DeviceRecipe and the value being the name of the recipe used to create this device. You can remove or modify this tag if desired, it is only added to help with device organization.

NOTE: While you are able to create peripheral class recipes that report to a single gateway without specifying a gateway on the recipe, you will be required to provide a gateway ID when using the recipe to create devices.

NOTE: Modifying a device recipe does not modify devices previously created using that recipe. A recipe acts as a template only; once a device is created, it is an independent item with no actual link back to recipe used to create it.

Recipe Import / Export

Recipes can be exported and saved to a file using the “Export” button on the recipe edit page. Exported recipes can then be imported when creating a new recipe (instead of creating a recipe from scratch). This can be useful for sharing recipes with other users (or even just sharing recipes across applications).

Using A Recipe

There are two main ways to create a device using a device recipe - single device creation and bulk device creation.

Single Device Creation

To create a single device using a recipe, navigate to Devices. From there, you can click the dropdown button next to Add Device and select Create From Recipe.

You can then select which recipe to be used to create a new device. If you are using a recipe for a peripheral device, you can select the gateway for your new device to report to on this screen. Additionally, you have the choice to select a parent system device for your new device to belong to. You will get a preview of all of the properties that your new device will have once created. Once a recipe is selected, click Create From Recipe and your new device will be created based on the properties of the selected recipe.

Bulk Device Creation

To create many devices at once using a device recipe, you will want to use bulk creation - which is available as an option under the dropdown button next to Add Device.

To create many devices at once using a device recipe, navigate to Devices. From there, you can click the dropdown button next to Add Device and select Create Multiple Devices. If the number of devices you are creating is more than 750, then instead of navigating to a page with a table of the output of the generation, you will receive an email with a link to download a CSV with the results of the generation. This CSV contains the same fields as the results page shown below.

You can then select which recipe to be used to create the new devices.

Once you have selected a recipe you will be given two choices for creating multiple devices. The simplest is choosing a number of devices to create straight from the selected recipe.

When using this option, you can choose a gateway for the new devices to report to, if applicable, as well as a parent system device for the devices to belong to. The rest of the device configuration options will be exact copies of the recipe - except for the name of the device, which will get an incrementing number on the end of the name to allow differentiation of the created devices.

The second choice when bulk creating is to upload a CSV file of device information to use when creating devices. When you choose to upload a CSV, WEGnology will show a preview of what will happen when the devices are bulk created.

CSVs are expected to have a header row, and then all subsequent rows represent devices to create.

You can optionally choose what column represents the names for the new devices - if you don’t, the default name from the recipe will be used (with an auto incrementing value appended). You can also optionally choose a column that represents the descriptions, gateways, and parent systems for the new devices (and if you don’t choose one, the defaults in the recipe will be used).

All other columns are treated as device tags - the name of the column (the header) is treated as the tag key, and the values in the column are treated as the tag values for the devices. If you leave cells blank in a tag column, that tag will not be set for that device row. You can also override tags already provided by the recipe by naming a column the same as the tag key in the recipe (and if you leave values in such a column blank, the default tag value from the recipe will be used). You cannot manipulate device attributes with CSV bulk creation - the device attributes are always directly copied from the recipe with no modifications.

The above screenshot is showing what would happen with the import of the following CSV file:

name,description,gateway,system,location,board
Widget Alpha,Device For Bob,609eaa7d4150710007f7eb8d,62fea3e8bb014b0492d99191,Texas,
,,,,,Plain ESP8266
Widget 2.0,,,,Cincy,Plain ESP8266

You also have the option of creating a unique access key for each device as part of creation. If you check this box, the result of the bulk creation contain a a newly generated access key and corresponding secret for each created device.

After bulk device creation (in both the simple or the CSV case) you will be presented with a table of the created device information, along with the option to download the created device information as a CSV file. The resulting information will include all of the information from the original CSV, plus any blank cells filled in with the values actually used for that device (such as generated device names, etc..). In addition, there is a wegnologyDeviceId column added, which holds the ids of the newly created devices. If there are any errors in creating any of the devices, those errors will be in a special creationErrors column of the result - if that column is blank, then the device for that row was created successfully.

In the above example result, all 3 devices were created successfully. The creationErrors column is blank for all three devices, and all three have a wegnologyDeviceId. You can also see how the name was auto-generated for the second device as Builder Kit Widget 0000, and the board tag was filled in with the default recipe value for the first device. Finally, because we choose to create a unique key and secret for each device, there are wegnologyDeviceKey and wegnologyDeviceSecret columns with the key and secret for each device it its respective row.

Viewing Associated Devices

Each device recipe has a “Devices” tab that displays a list of all devices with a DeviceRecipe tag whose value matches the name of the recipe. Since WEGnology automatically adds this tag to any device created from the recipe, this list is often associated with all devices created from the recipe.

Note, however, that there are several considerations to take into account when viewing this list of devices …

• If the name of the recipe has changed since a device was created from it, and the DeviceRecipe tag value was not updated on the device to reflect the new recipe name, the device will not appear in the list.
• If the DeviceRecipe tag was removed from the device, or if its value was changed to something other than the recipe name, the device will not appear in the list.
• A device would appear in this list if the DeviceRecipe tag were added to it with a value matching the recipe name even if the device were not originally created from the recipe.
• Even if a device were created from the recipe and the device appeared in the list due to the DeviceRecipe tag match, it is possible that the device and/or the recipe changed so much since the device creation (changes to the device class, tags, attributes, etc.) that the association would be meaningless.