Digi-Key IoT Studio enables you to create and import your own elements to add support for third-party sensors not currently available in the platform.
Creating sensor elements is done using Digi-Key's Embedded Element Library (EEL) Utility tool. The EEL Utility tool is a command line interface used for generating elements to be imported into DK IoT. All of the information surrounding use of the tool is detailed on the DK IoT GitHub.
Completed EEL files ready to be added into DK IoT Studio for use can be imported through the Import button in the Add Element window. Once a file is imported, it’s included in the list of available sensor elements that can be enabled in an DK IoT Studio project. Note that custom EEL files imported into DK IoT Studio are only available for the project they are added to.
This intent of this guide is to describe the step by step process of creating an EEL from scratch. This EEL will control the MikroElektronika Relay Click board.
Step 1: Prerequisites
- Node.js 8.x.x (An older version _may_ work)
- npm 5.x.x (An older version _may_ work)
Step 2: Clone This Repository
Using your tool of choice, clone this repository to your local machine:
Navigate to the newly created eel-builder directory and run
to install dependencies that the eel-builder needs.
Step 3: Generate New EEL Directory
Let's create a new directory to hold all of our EEL source and metadata. To do this, navigate to the eel-builder directory and run
You should see that a new directory, `relayclick_EEL` was created one level up in the same directory as the eel-builder directory.
*NOTE*: The `--dir` argument can be anything you like. It's the directory in which the new source directory will be created. You could put it in `C:\Users\me\Documents` or `/home/me/Documents`, for example.
Step 4: Editing Metadata
Navigate to your relayclick_EEL directory. Open the file metadata.json. This file contains all of the high level metadata about your EEL that the studio needs to properly display and use it.
Step A: manufacturer
Change the manufacturer name to MikroElektronika.
Step B: description
Write a short description of your EEL here. Something like "Relay Click evaluation board" would suffice. You could leave this blank if you wanted.
Step C: requires
This EEL will require the GPIO driver, so add `gpio` to the list. You should have something like this:
This field allows the studio to filter EELs that are not compatible with certain platforms.
Step D: Element name
In the Elements object, set the name to "RelayClick". This is the name that would be displayed in the Element Library browser in the "Element" column.
Step E: Element type
In the Elements object, set the element type to "EmbeddedRelayClick". This type is used for the language object and is generally how the Studio refers to this element.
Step F: Icon
For the icon, just use the generic `EmbeddedFunction.svg`.
Step G: Abilities
Change `myability` to setup and add a field `hidden` set to true. Every element must have a setup ability, and it should be hidden. It should look like this:
Add a new ability called `setRelay1On` with a trigger `relay1SetOn`. Once you've done this, add a third ability called `setRelay1Off` with a trigger `relay1SetOff`. Finally, add an ability `toggleRelay1` with a trigger `relay1Toggled`. Your final abilities list should look like this:
Step H: Default Ability/Trigger
You must set the default ability and trigger selected when the element is initially created. Set `defaultAbility` to `setRelay1On` and `defaultTrigger` to `relay1SetOn`.
Step I: Properties
Delete the default `myproperty` property. Thinking about the relay click board, what does it need in order to function? The EEL needs to know the GPIO Driver Instance and the GPIO Pin connected to relay 1, so those are our two properties.
Your properties list should look like this:
Step J: Language
The last step in the metedata is the language object. This tells the studio how to print the element name, ability names, and trigger names. It should look something like this:
Your final metadata.json file should look like this:
Step 5: Generating stub abilities
We can use the tool to generate stub .c files that we can fill in later for all of its abilities. To do this, navigate to the eel-builder directory and run
You should see the following output:
Step 6: C Source
This step is actually writing the C driver for the EEL. This will be located in `relayclick_EEL/files/common`.
Step A: Header
Create a new file: `relayclick_EEL/files/common/headers/relayclick.h`
Create a new structure to hold your configuration data (properties). You should have something like this, at this point:
Note that these two struct items refer to the properties you defined in your metadata. Also note the `#include "../atmo/core.h"`. This should be done in every EEL, as it will import any datatypes you may need.
The next step is to create the function prototypes that we will need. You should end up with something like this:
Step B: Source
Create a new file: `relayclick_EEL/files/common/objects/relayclick.c`
The first step is to include the header:
*NOTE* Although the header and source are currently in different directories, they will be in the same directory when Atmosphere Studio generates the embedded source for your project.
The next step is to implement the initialization function:
The documentation for the GPIO driver can be found here. The include path for any driver will be
The final step is to implement the two Relay1 control functions:
In the end, you should end up with a final file looking like this:
Step 7: Ability Source
The next step is to write the source for the abilities. This is the code that appears in the code view in Studio. This code will be _using_ the driver we just wrote in Step 6.
Navigate to `relayclick_EEL/elements/EmbeddedRelayClick/abilities/` and open `setup.c`.
Using the ATMO_PROPERTY macro, we can retrieve the properties from the element toolbox and set them in the configuration struct we created:
*NOTE*: The ATMO_PROPERTY macro accepts two arguments: element name and property name. Using undefined as the element name tells the studio to automatically fill in the name of the element instance before the code is compiled. For example, if you create Relay Click element and name it "NicksRelayClick", this code will end up looking as follows before compilation:
The next step is to fill in the other three abilities. Your `setRelay1Off.c` should look like this:
Your `setRelay1On.c` should look like this:
Your `toggleRelay1.c` should look like this:
Step 8: Generate Final EEL
Navigate to the eel-builder directory and run:
Step 9: Celebrate
Congratulations, you've created your first EEL. You can see a more complex version of this EEL in the examples directory, here.