3.3. Get EdgeX Foundry - Developers

3.3.1. Introduction

These instructions are for Developers to obtain and run EdgeX Foundry. (Users should read: Get EdgeX Foundry - Users)

EdgeX Foundry is a collection of more than a dozen microservices that are deployed to provide minimal edge platform capability. EdgeX Foundry consists of a collection of microservices and an SDK tool. The microservices and SDK currently released by the project’s founders are all written in Java. This wiki page provides a developer with the information and instructions to get and run EdgeX Foundry in an Eclipse environment.

3.3.2. What You Need

Hardware

EdgeX Foundry is an operating system (OS)-agnostic and hardware (HW)-agnostic edge software platform. Minimum platform requirements are being established. At this time use the following recommended characteristics:

  • Memory: minimum of 4 GB
  • Hard drive space: minimum of 3 GB of space to run the EdgeX Foundry containers, but you may want more depending on how long sensor and device data is retained
  • OS: EdgeX Foundry has been run successfully on many systems including, but not limited to the following systems:
    • Windows (ver 7 - 10)
    • Ubuntu Desktop (ver 14-16)
    • Ubuntu Server (ver 14)
    • Ubuntu Core (ver 16)
    • Mac OS X 10

Software

Developers will need to install the following software in order to get, run and develop EdgeX Foundry microservices:

git - a free and open source version control (SVC) system used to download (and upload) the EdgeX Foundry source code from the project’s GitHub repository. See https://git-scm.com/downloads for download and install instructions. Alternative tools (Easy Git for example) could be used, but this document assumes use of git and leaves how to use alternative SVC tools to the reader.

MongoDB - by default, EdgeX Foundry uses MongoDB as the persistence mechanism for sensor data as well as metadata about the devices/sensors that are connected. See https://www.mongodb.com/download-center?jmp=nav#community for download and installation instructions. As an alternative to installing MongoDB directly, you can use a MongoDB on another server or in the cloud. This document will explain how to setup MongoDB for use with your development environment.

Java - The open sourced microservices of EdgeX Foundry are written in Java 8. See http://www.oracle.com/technetwork/java/javase/downloads/index.html for download and installation instructions. Please note you will need the JDK and not just the JRE. OpenJDK has been used to run EdgeX Foundry, but development using OpenJDK has not been tested thoroughly. Alternate versions of the JDK (version 7 or 9 for example) have not been tested but may work with some reconfiguration of the microservice projects.

Eclipse - EdgeX Foundry micro services were created in Eclipse using Java Maven projects. See http://www.eclipse.org/downloads/eclipse-packages/ for download and installations instructions. Please note to download and use Eclipse IDE for Java EE Developers. Alternate Java integrated development environments (IDE) could be used, but this document assumes use of Eclipse and leaves how to use alternate IDEs to the reader. Depending on which microservices you intended to download the source code and work on, you may require or desire additional Eclipse IDE plugins.

3.3.3. Get the code

Pull

You may need to download the source code from several library or microservice projects depending on which EdgeX Foundry microservices you wish to explore, build, or run. Library projects contain code used by one or more microservices. The code in a library is packaged as a JAR and is then used by other microservices. Library projects are not executable by themselves. Microservice projects contain the code for an EdgeX Foundry microservice. The code in a microservice is packaged as an executable JAR and then also containerized for end user deployment/use.

The EdgeX Foundry library and microservice projects are hosted at https://github.com/edgexfoundry.

To download or “pull” any of the library or microservice projects, use your git tool and request to clone your the required repository with the following command:

git clone https://github.com/edgexfoundry/<library or microservice repos name>

For example, to pull the support-logging microservice repository, execute the following command:

git clone https://github.com/edgexfoundry/support-logging.git

_images/EdgeX_GettingStartedDevClone.png

3.3.4. Dependencies

Many of the libraries and microservices are dependent on other libraries and microservices. If you wish to build or run an EdgeX Foundry library or microservice project, you will need its dependent library/microservices to be pulled and built first. The following set of diagrams can help you determine dependent library and microservices repositories you need to pull and build any single EdgeX Foundry project.

_images/EdgeX_GettingStartedDevDependency1.png _images/EdgeX_GettingStartedDevDependency2.png _images/EdgeX_GettingStartedDevDependency3.png _images/EdgeX_GettingStartedDevDependency5.png _images/EdgeX_GettingStartedDevDependency4.png

3.3.5. EdgeX Foundry’s Mongo Database

Initializing the Database

Many of the EdgeX Foundry microservices use a MongoDB instance to persist data or metadata. The MongoDB database for EdgeX Foundry must be initialized before it can be used by the system. Unless the database is destroyed, this set of instructions only has to be run one time to initialize the database.

There are several useful scripts in the developer-scripts repository for EdgeX Foundry to help initialize and then run the EdgeX Foundry MongoDB instance.

To begin, start MongoDB in a “no authorization” state. A sample Windows Batch script has been provided at https://github.com/edgexfoundry/developer-scripts/blob/master/startdb-no-auth.bat. Make sure you change the script to point to your mongod executable and provide the path to the location of the database instance files (c:usersPublicmongodbdb in the script).

_images/EdgeX_GettingStartedDevMongoStart.png

Once the database has been started, initialize the database with EdgeX Foundry access and schema elements. The initialization code is located in init_mongo.js file. You need to run this script using the mongo shell tool. A sample Windows Batch script has been provided to run the mongo shell with this script at https://github.com/edgexfoundry/developer-scripts/blob/master/init_shell.bat. Again, make sure you change the script to point to your mongo executable and provide the path to init_mongo.js file. When the script executes, it will display the commands it is executing against the database.

_images/EdgeX_GettingStartedDevMongoCommands.png

Once complete, the database can now be stopped. In the next step, you restart the database with authentication turned on. You do not need to re-initialize the database again.

Running the Database

Several of the EdgeX Foundry microservices utilize the MongoDB instance. This includes core-data, core-metadata, support-rulesengine, supporting-logging (in some situations), among others. Therefore, when working with EdgeX Foundry its a good idea to have the database up and running as a general rule.

After initializing the database (see previous step), start the database with authorization turned on. A sample Windows Batch script has been provided at https://github.com/edgexfoundry/developer-scripts/blob/master/startdb.bat to show how to start MongoDB with the mongod executable and pointing it to the location of the database files (c:usersPublicmongodbdb in the script). Edit the script so that it points to your mongod location and points to the MongoDB data files as established in the initialization step. Once ready, just run the script from a terminal window. Note the use of “–auth” to start the database with authorization turned on.

_images/EdgeX_GettingStartedDevMongoRun.png

3.3.6. EdgeX Foundry in Eclipse

Import the Project

Each of the EdgeX Foundry repositories containing source code is also an Eclipse project, specifically a Maven project (except for device-sdk-tools). To bring one one of these projects into Eclipse, use the File → Import… menu option in Eclipse to open the Import Window.

_images/EdgeX_GettingStartedDevEclipseImport.png

From the Import window that appears, request to import a Maven → Existing Maven Projects and then push the Next> button.

Note - if the Maven options are not provided as import options, you either may be using a Java versus Java EE version of Eclipse, or you do not have the required Maven plugins loaded into your IDE. See http://www.vogella.com/tutorials/EclipseMaven/article.html for help.

_images/EdgeX_GettingStartedDevEclipseImportMaven.png

In the resulting Import Maven Projects window, browse to the location of the pulled repository. Eclipse should detect the Maven project at that location and indicate that it has found the project’s pom.xml at that location. Press the Finish button when you are ready to import the project into Eclipse.

_images/EdgeX_GettingStartedDevEclipseImportFinish.png

The project should appear in the Project Explorer if imported successfully.

_images/EdgeX_GettingStartedDevEclipseImportSuccess.png

Import device-sdk-tools

As mentioned above, device-sdk-tools is not a Maven project. It should be imported using File → Import → General, Existing Project into Workspace.

Build and Install

To build any of the EdgeX Foundry library or microservice projects once imported into Eclipse, right click on the project and select Run As → Maven Install from the resulting menu. This will cause the project to be built (into a JAR file) and then have the JAR file installed into a local Maven repository.

_images/EdgeX_GettingStartedDevMavenInstall.png

Note - as the various projects have cross dependencies, it’s recommended that you run the Maven Install step for the projects in the following order:

  • core-domain
  • core-test
  • core-exception
  • support-domain
  • support-logging-client
  • core-metadata-client
  • core-data-client
  • support-notifications-client
  • core-command-client
  • support-logging
  • support-notifications
  • core-metadata
  • core-data
  • core-command
  • device-sdk
  • device-virtual

Check the Eclipse Console view to make sure the project successfully built (as shown below). If not successful, leading causes for failure include:

  • check that you have configured your Eclipse environment to point to an available JDK on your development machine
  • check that you have build/installed any dependent library or microservice project first
  • check that you have the Maven plugin installed in your environment
_images/EdgeX_GettingStartedDevMavenInstallSuccess.png

Running in Eclipse

With the database running (and initialized) and with all the libraries and services built and installed, you can run any (or all) of the EdgeX Foundry microservices right in Eclipse. Each microservice is implemented to run as a Java application. Simply right click on the EdgeX Foundry microservice that you want to run and select Run As → Java Application from the resulting menu.

_images/EdgeX_GettingStartedDevEclipseRunAsJava.png

Eclipse will need some assistance in identifying the main class or starting point of the application. It will prompt you with a window to select the application class to execute. Locate the application class located in the base org.edgexfoundry package (EdgeXSupportLoggingApplication in the example below) and then hit the OK button to launch the microservice.

_images/EdgeX_GettingStartedDevEclipseClassExecute.png

Minimal EdgeX Running in Eclipse

If you want to bring up a minimal EdgeX application in Eclipse to see data created by the Virtual Device enter into Core Data and be available via REST API call, here are the items you need to bring up:

  1. Mongo (started and initialized per the documentation above)

  2. Import the EdgeX projects into Eclipse (building and installing all the projects per documentation above)

  3. Start core-metadata (per documentation above) and wait for it to complete its startup/initialization (look for “This is the Core Command Micro Service.” in the Console view)

  4. Start core-data (per documentation above) and wait for it to complete its startup/initialization (look for “This is the Core Data Micro Service.” in the Console view)

  5. Start core-command (per documentation above) and wait for it to complete its startup/initialization (look for “This is the Core Command Micro Service.” in the Console view)

  6. Edit the application.properties of the device-virtual and change the service.name and service.host name to both match your systems name. In the example below, the PC’s name is Test-PC

    #default device service settings

    service.name=Test-PC

    service.host=Test-PC

  7. Start device-virtual (per the documentation above). Watch the Console view to see that the service starts without issues and starts to send data to core-data

  8. Check that event/reading data are being sent to core-data (and Mongo) by opening a browser and going to localhost:48080/api/v1/event/count. The count should slowly rise with subsequent hits of this URL as the virtual device continues to send new simulated sensor data to core-data.

_images/EdgeX_GettingStartedDevEventCount.png

Run additional services from Eclipse as needed to export data, collect logs locally, etc.