DK IoT Studio is a rapid prototyping environment that allows developers to quickly implement IoT applications without having to write a single line of code. IoT devices can be programmed to interface with a variety of sensors and send/receive data to/from a mobile device or the cloud. There are several embedded platforms to choose from and a wide array of sensors they can interface with. The complete list of sensors (available in atmosphere's element documentation) continues to grow, but situations will inevitably arise where a developer wishes to utilize a sensor not currently supported in IoT Studio. Luckily, users have the option to develop their own Embedded Element Libraries (EELs) and import them to their project.
Please note that at the time of writing, "sensor elements" in IoT Studio refer to EELs for both sensors and actuators. For example, in the list of sensor elements you will find the MikroE 8x8 LED Click and the MikroE Relay Click. So, keep in mind that every reference to "sensors" or "sensor elements" in this article does not preclude actuators from its context. Indeed, you can develop EELs for actuators as my college demonstrates in his article Creating an Embedded Element Library From Scratch (with AVR-IoT + Trinamic Example).
Often, users may wish to develop a sensor element very similar to one already available in IoT Studio or they may wish to modify/augment the functionality of an existing sensor element. In either case, it would be very helpful to have access to the EEL source code for these elements so it may be easily forked by the user. Consider for example the Teseo-LIV3F mikroBUS Add-on Board I designed a while back. After having the boards made and assembling them, I wanted to utilize one of them in an IoT Studio project. While the Teseo-LIV3F GPS module is not currently supported in IoT Studio, there is an element for the very similar Nano GPS Click board. Using the procedure outlined below, I was able to use the Nano GPS Click element’s source code as a starting point in developing an EEL for my custom board. Of course, the same procedure will work for any existing sensor element.
The following procedure assumes that the reader is familiar with Atmosphere's EEL Builder tool. Not only will we be using this tool to build up the EEL source code, but the tool's documentation is essentially an explanation of exactly what EELs are and how they work with IoT Studio to provide support for a particular sensor. The GitHub repository also contains several example EELs which may prove helpful.
The EEL Builder tool uses the EEL source code to generate an EEL file (a file with the extension ".eel"). This EEL file can be imported into any IoT Studio project, and if it is, it will be embedded in the Atmosphere project file (a file with the extension ".atmo"). The steps presented below essentially reverse this process, using the project file along with the project's source code to obtain the EEL source code for a particular sensor element utilized in the project. Using the source code is not strictly necessary as all the required information is embedded in the project file, but I find that using the source code somewhat simplifies the process.
Take note right away in the difference between “EEL source code” and the “project source code”. The EEL source code includes the files used to generate the EEL file (see Figure 9 as an example) while the project source code is the code that will be compiled and programmed to the embedded device (see Step 2 in Figure 1).
1. Download the sensor element’s source code
By downloading a project’s source code, we are also downloading the source code of any sensor elements used within the project. Start by creating a new project and using the Add Element button in the Element Toolbox to import the element you want to replicate (if it’s not already in the Element Toolbox). Place that element on the canvas and save/compile the project as shown in Figure 1. To keep the source code as simple as possible, you shouldn’t add any other elements to the canvas before compiling. Once the project successfully compiles, click the Download Source button in the Embedded tab to download the project source code in a .zip file. Extract this file to a location of your choosing. We will need it later for steps 6 and 7.
Figure 1: Save and compile the IoT Studio project and then download the source code
The embedded platform you choose when creating a new project does not matter. All we care about in the source code are the sensor element’s driver files. The files related to the specific platform we chose are not needed for this process and will be ignored. However, you may find (like I did) that your choice of platform is somewhat limited as not all platforms support all sensor elements. For example, the Nano GPS Click element imported in Figure 1 uses the UART peripheral to communicate with the embedded device. Therefore, if the platform that was selected when creating the project does not support UART, the Nano GPS Click element will not appear in the import dialog. For instance, when I created a Sensor Tile project (which does not support UART) and tried to import the Nano GPS Click element, it was not listed. So, you must choose a platform that supports all the features required by the sensor element.
2. Export the project and extract the EEL file
Return to the Studio Projects screen. Click the Export Project icon shown below in Figure 2 to save the project's ".atmo" file. This is a plaintext file that can be opened with whichever text editor you prefer. Among other things, it includes the contents of the .eel files of any added sensor elements.
Figure 2: Export project
Open the .atmo file and search for the string "libName" to find where the EEL data begins. If there are multiple elements in your project, simply repeat your search until you find the name of the element you intend on replicating. In my case, I found the beginning of the Nano GPS Click EEL data right away (Figure 3). The open curly brace immediately preceding the libName key is the first character in the .eel file. Copy everything from this open curly brace to its corresponding closing brace and paste it to a new file (Listing 1). As you can see in Listing 1, I've also decreased the indentation by a few steps to ensure everything lines up properly.
In the next step we will use this file to create the metadata.json file, but if for whatever reason all you need is the EEL file and not the EEL source code, you can stop here. Simply save this file as <.libname>.eel and import it to another IoT Studio project.
Figure 3: Beginning of the nanoGPSClick EEL data in the .atmo file
3. Carve out the metadata.json file
The metadata.json file allows IoT Studio to understand the EEL’s functionality and properly display its abilities, triggers, properties, etc. As it turns out, the eelbuilder tool simply builds on this file by adding the driver files and ability code we provide to create the EEL. Therefore, we can simply remove these additions to get back to the original metadata.json file.
Start by saving the file we created in the previous step (Listing 1) as metadata.json. Go to the element abilities object and remove every key/value pair where the key is "code". Since this is the last key in each object, don't forget to delete the preceding commas (after "hidden": true) as well, as shown in Figure 4.
Figure 4: Remove code from "abilities" objects
Delete the entire "files" object along with the "md5" key and value (Figure 5). Again, don't forget the preceding comma (after the square bracket this time).
Figure 5: Remove the "files" object and the "md5" checksum
4. Create directory structure for EEL source files
Using the EEL Builder tool, create the directory that will contain the EEL source files. By running the command
node eelbulder.js --new --name="<eel-name>" --dir="<eel-directory>", a directory named "<eel-name>_EEL" will be created in the “eel-directory” directory. For example, I ran
node eelbulder.js --new --name="nanoGPSClick" --dir=".", which created a directory named nanoGPSClick_EEL in the working directory. Figure 6 shows this as well as the contents of nanoGPSClick_EEL. The eelbuilder tool created a subdirectory structure for the driver files as well as a template metadata.json file. Replace this matadata.json file with the one we created in the previous step.
Figure 6: Run
eelbuilder.js --new to create the EEL directory skeleton.
5. Create the abilities directory and files
Run the command
node eelbulder.js --generate --dir="<eel-src-directory>" --dest="<eel-location>", where "eel-src-directory" is directory containing the EEL source code and "eel-location" is where the EEL file will be saved. Figure 7 shows the results of running the command
node eelbulder.js --generate --dir="nanoGPSClick/" --dest=".". In the elements directory, it created a subdirectory called EmbeddedGpsClick, which came from the metadata.json file (
.elements.type). In EmbeddedGpsClick it created the abilities directory and one .c file for each ability specified in metadata.json.
Figure 7: Run
eelbuilder.js --generate to create and populate the abilities directory
Notice that I also got an error after running the command. Apparently, the element icon that was used for this sensor element (EmbeddedGpsClick.svg) is undocumented and therefore not recognized by the eelbuilder tool. Because I know the EmbeddedGpsClick.svg element is a valid option, I will use the
--noicon option when I generate the EEL file in the final step. This will skip the icon validation operation.
6. Add code to ability files
The .c files in the abilities folder are used to populate the ability callback functions in the file app_src/atmosphere_callbacks.c (Listing 2) in the project source code. This is the file that is shown in IoT Studio IDE when the embedded code editor is used. Simply copy the code within each function that corresponds to an ability and paste it in its matching ability source file. Figure 8 shows the contents of these files after this is done.
Figure 8: Contents of the ability source files
7. Copy the driver files
The driver code for the sensor element can be found in the project source code in the directory with the same name as the EEL. In my case, the folder nanoGPSClick contains two files: nanogps.c and nanogps.h. Some elements will contain more than two files. In any case, simply copy the .h files to the files/common/headers directory in the EEL source and the .c files to the files/common/objects directory. This completes the EEL source code and the final result is shown in Figure 9.
Figure 9: Final contents of the EEL source directory
8. Generate EEL file
Repeat the eelbuilder generate command you ran in Step 5 to update the EEL file with the source code. Figure 10 shows that by adding the
--noicon option, I do not get the error shown in Figure 7 and the file nanoGPSClick.eel is created successfully.
Figure 10: Using the EEL source files to create the EEL file
To check your work, you should create another new project in IoT Studio and import the new EEL you just created. It should not look or behave any different than the original sensor element. After verifying its functionality, you can start tweaking the EEL source files to create an EEL for your unsupported sensor. Start by modifying the metadata.json file (change the library name, description, manufacturer, etc.). Add or remove abilities as you see fit, change the default values of properties, add your own driver files, and whatever else is needed to create a simple interface for the sensor.