Page Comparison

**Draft**

Announcement

With the Hanoi release, EdgeX Foundry announces the availability of EdgeX Ready with the Ireland release (EdgeX 2.0).

What It Is

The EdgeX Ready program is about demonstrating the ability to work with EdgeX.   The designation helps other community participants and solution vendors identify vendors who have gone  You earn your EdgeX Ready designation by going through a self-assessment process. The process to demonstrate that they are able to integrate one of their offerings with solutions using EdgeX.  Those vendors who have joined the program are highlighted has you show your ability to work with EdgeX.  Specifically, demonstrating that you can integrate your offerings in an EdgeX-based solution.

When you complete the process, you signal to other community members that you have EdgeX knowledge and experience.  The EdgeX community highlights EdgeX Ready members on the EdgeX Foundry website with an EdgeX Ready badge next to their logo.

The initial, “crawl,” phase of the “self-assessment process” is to simply validate a device profile.  Users attest that they have authored a device profile and moved device-specific data through an EdgeX instance that they had set up themselves thereby demonstrating some familiarity with EdgeX and, more specifically, of device services and their associated device profiles.  Upon submission and approval of their device profiles and sample data, the users’ logos will be badged on the EdgeX Foundry website.

We are initially launching with MQTT- and REST-based device profiles.  This is just the beginning.  With community interest, we will expand the program to support additional device services.

Self-Assessment Process

We ask the vendors to do the following:

1. Instantiate an instance of the reference implementation of EdgeX with their device profile

2. Using a device that is described by their device profile, generate sample data, and send it to the appropriate device service

3. Confirm that the data arrives in Core Data
4. Validate their device profile using one of the tools provided by the Certification WG
5. Submit their validated device profile and sample data to the EdgeX Ready program

This workflow diagram below may help with understanding the process:

Device Profile Validators

[TBD]

Required Public Materials

The following materials are required to included in the EdgeX Ready Program submission:

Future EdgeX Ready programs may highlight various levels of ability and experience.  Today, the self-assessment process requires an EdgeX adopter to:

• Get and run an instance of EdgeX (and associated services)
• Create and validate a device profile
• Use the profile with an EdgeX device service to provision a device and send sensor data into EdgeX

EdgeX users can get and run an EdgeX instance in many ways.  For convenience, EdgeX provides cloud templates to instantiate EdgeX on a cloud platform.  You can also download and run EdgeX with community provided containers, Snaps, and the like.

[Note, the cloud templates only provide MQTT and REST device services.  If you wish to show use of other device protocols and device types, you will need to use your own EdgeX instance.]

The key to understanding EdgeX lies in the ability to work with device services to get edge data into EdgeX.  Thus the program focuses on creating a device profile and using the profile with a device service to ingest sensor data.

EdgeX Ready users must author a device profile, and use it to specify what data a device will send to EdgeX.  With the profile provided to the device service, the final test of the users skills is to show data ingested by the device service.

EdgeX Ready Self-Assessment Workflow

To be EdgeX Ready, follow this workflow to submit your application for consideration.

1. Join the EdgeX Ready program.  To be an EdgeX Ready user, you must be a member or enroll in the EdgeX User program.
2. Write a device profile specifying the data exchange and communications with a sensor/device.
3. Validate the device profile.
4. Get an EdgeX instance up and running — with the device service for your sensor/device.
5. Provide your device profile to the device service, provision the device and send data through EdgeX.
6. Capture data sent through EdgeX (you’ll need this in the application)
7. Describe the data (create a schema) for the data sent through EdgeX.
8. Complete the EdgeX Ready Participation Form (PDF).
9. Submit your participation form, profile, sample data, and schema to the EdgeX community.

Detailed Instructions and Assistance

The EdgeX Ready program is about demonstrating EdgeX knowledge. Beginners should read the project’s documentation and follow the tutorials before applying. While getting EdgeX Ready is not onerous, the program is not for the uninitiated.

If you are not familiar with EdgeX, begin your education here: https://docs.edgexfoundry.org.  Use the Getting Started and Examples and Tutorials sections to build a foundation toward getting EdgeX Ready.

Ready to earn your EdgeX Ready badge? Find detailed instructions below for each of the steps in the program.  Join the EdgeX User Program

Before you can take part in the EdgeX Ready program, we require that you have already joined the EdgeX User Ecosystem.  The EdgeX User program is free! It lets others in the community know that your organization is using or working with EdgeX. It allows you to collaborate with other EdgeX adopters, and participate in community activities. Join here. To learn more about the EdgeX User Ecosystem and see who’s already in, see our member showcase.

Write a (or use an existing) Device Profile

Device profiles define general characteristics about devices, the data they provide, and how to command them. Think of a device profile as a template of a type or classification of device. A device profile for a thermostat would specify characteristics for temperature and humidity data the thermostat generates.

It would also define which types of commands or actions EdgeX can send to the thermostat. Examples might include actions that set the cooling or heating point. We specify device profiles in a YAML file. Typically, upload profiles to EdgeX via Core Metadata. Find more information about device profiles in our documentation.

You can write your own device profile to tell EdgeX about a device or sensor you work want to work with. Or, you can use (and customize) a device profile that already exists. You can find existing example profiles in device service repositories. Find example profiles for the REST device service here.

If you do wish to create your own device profile from scratch, we recommend you use a YAML editor to check syntax. Alternately, you can use IOTech Systems Device Configuration Tool (DCT). The DCT provides a GUI wizard that steps you through creating each section of the profile. The DCT requires you create an account (its free). When you create your profile, you can download/export it, or save it in the tool and refer to the saved profile in your application process.

Validate Device Profile Syntax

Device profiles can be involved depending on the complexity of the sensor. Therefore, we prefer that you validate your device profile before sending the profile as part of your submission.

You can use the DCT tool mentioned above to validate your profile. If you create the profile in the tool, it will validate as you create it. If you create your own profile, you can upload your profile into the tool and it will validate on upload.

Again, using IOTech’s DCT tool is free but requires creating an account. In the future, the EdgeX community hopes to have other tools to assist users create and validate profiles.

Alternately, if you do not want to use DCT and validate the profile, you can send in your profile, note that it is not validated in the submission form (see below). The EdgeX Certification Group will validate the profile on submission. Processing your submission may take a bit longer to complete this part of the process.

Stand Up EdgeX

To test your profile, send data into EdgeX and then show the community your data, you need to stand up an EdgeX instance.

If you are already very familiar with EdgeX and how to get, start it and use it, use your normal instance. For more information on how to get and run EdgeX, visit the Quick Start Guide or User Guides.  Alternately, for convenience of the EdgeX Ready program, you can use our cloud-specific templates.

Our cloud templates allow you to setup EdgeX in either Azure or Amazon Web Services clouds. The cloud templates may help if you don’t have the resources to run EdgeX. These also help to minimize domain knowledge required outside of the immediate device service, protocol and data. Git repositories contain how-to-guides for instantiating a instance of EdgeX in either cloud.

Send Data to EdgeX

With EdgeX up, and your device connected and provisioned, allow your device to send data into your EdgeX instance. If you are not familiar with how to connect and provision a device to EdgeX, see the Device Service guide.

Verify that sensor/device data is making its way through the system. You can do this by calling on core data to see that Events/Readings containing sensor data are being stored in the database. Use the Event API to get the latest Events/Readings for your device from core data. For example, use http://<host>:48080/api/v1/event/device/<device name>/10 to get the last 10 Events/Readings for your device. Replace the <host> and <device name> placeholders with the address of your EdgeX machine and the name of your device.

Image Added

Make sure the data you see is representative of the data (and schema) you are submitting with your EdgeX Ready submission.

Capture Data Sent to EdgeX

You must provide a sample of data set sent by your sensor/device. This sample helps members within the community understand how your device behaves and how it interacts with EdgeX. Provide the sample data in JSON format.

You can get the sample data by either:

- capturing the data sent by the device service to core data

- by performing a query of Event/Readings in core data (as shown above) and capturing the JSON response from the query.

Here is a example of sample data.

{"id":"e2ecb132-bca1-4455-800a-315d8c7beaea","device":"temperature-probe","created":1622429451777,"origin":1622429451774303867,"readings":[{"id":"9606aaca-a3dd-4bcf-bee9-c2b5a7d5201e","origin":1622429451773834908,"device":"temperature-probe","name":"ProbeTemperature","value":"718","valueType":"Int16"}]}

{"id":"39e8a927-98c5-4957-b009-5603a5d89348","device":"temperature-probe","created":1622429461810,"origin":1622429461808089295,"readings":[{"id":"627d61ba-f92e-4026-ac24-3a48cd76a39b","origin":1622429461807732848,"device":"temperature-probe","name":"ProbeTemperature","value":"725","valueType":"Int16"}]}

Write Schema for Sample Data

You need to describe the sample data sent by your device. In a simple text document - provide a description for each of the JSON elements in your sample data. You can use the sample data to help provide context to your descriptions. Below is an example.

• "id":"e2ecb132-bca1-4455-800a-315d8c7beaea" - The EdgeX Event or reading id
• "device":"temperature-probe" - The device name that originated the data - assigned when the device gets provisioned
• "created":1622429451777 - The unix timestamp of when the data was created in the database (specified in milliseconds)
• "origin":1622429451774303867 - The unix timestamp of when the data was created by the temperature probe sensor (in nanoseconds)
• "name":"ProbeTemperature" - The device resource name associated to the reading
• "value":"718" - The temperature value in Fahrenheit * 10. Divide the integer by 10 to get the actual temp in Fahrenheit - in this case 71.8
• "valueType":"Int16" - the type of the value - integer, 16 bit

Provide as much information as you can to assist community members in understanding your data.

Complete and Sign the EdgeX Ready Participation Form

Download the EdgeX Ready Participation Form.  Complete and sign the form. Save the form for your records. These are our Terms and Conditions of the EdgeX Ready program.  By signing and submitting your form, you are agreeing to the program’s terms and conditions.

Submit your Materials to EdgeX Foundry Certification Group

After completing the steps above, you are ready to submit your application. Submit your application to the EdgeX Foundry Certification Group through the on-line form.

When you complete the form and submit, you need the following materials:

• Device Profile – YAML (.yaml)
• Alternately, you can provide the UUID of your device profile created and saved to the public library using IOTech’s DCT website.  A special field in the form is provided for this information.
• Sample sensor data – JSON (.json)
• Sample data schema – JSON – text file describing the sample data
• EdgeX Ready Participation Form – PDF (.jsonpdf)
• (Optional) UUID of the device profile, if validated using IOTech's DCT website, in the form of 123e4567-e89b-12d3-a456-426614174000Company name, your name, and your email in order to complete the online form.
• Any comments about your submission

Contributions

We at the EdgeX Foundry are very much interested in providing the EdgeX community with multiple options for validating device profiles for the EdgeX Ready Program.  If you have your own EdgeX validator and would like to contribute the implementation as open-source or share the service with the EdgeX community and the EdgeX Ready program specifically, we are interested in hearing from you!  Please reach out to us on Slack at #edgex-ready, email us at edgex-ready@edgexfoundry.org, or contact the Certification Team WG Chair directly at rodney@beechwoods.com and we can discuss next steps.

Availability

.

FAQ

What does it cost to be join the EdgeX Ready program?

No - the only requirement is that you sign up and become an EdgeX User

Do I need to have real sensors or devices to become an EdgeX Ready User?

No - using the MQTT and REST device services, you must . You need to be able to demonstrate show that you can get device-specific data into EdgeX as a the sensor or device would do, but you do not need a real sensor or device to accomplish the EdgeX Ready program.

TODO - Other things to address in this Wiki

• More details on the process.  Steps in the process.  Where to go for the tools.  What is accomplished at each step?  Wonder if we could create a diagram where each step is "click in" to get detailed instructions?
• Do we address EdgeX Ready in relationship to a particular version (maybe address this in the FAQ)?
• More info on EdgeX User - how to become one and where to go

EdgeX Ready Development Workflow

Before you can participate in the EdgeX Ready program, we require that you have already joined the EdgeX User Ecosystem, a free program wherein you can let others in the community know that your organization is using EdgeX, collaborate with other EdgeX users, and participate in community activities.  To join, please click here.  To learn more about the EdgeX User Ecosystem and see who’s already there, please click here.

In our documentation, you will find a specification for device profiles (see: Device Profile Reference).  For those that prefer reading the code to infer the specification, you can still do that, too!  Start here with our Getting Started - Developers guide or hop right over to the EdgeX Foundry Project on GitHub and dive in deep.

We have provided cloud-specific templates and how-to guides for instantiating a reference implementation of EdgeX in the cloud to minimize the domain knowledge required outside of the immediate device service and their associated IoT protocol.  With these cloud EdgeX instances, users can verify that their device profile and sample data achieves the desired form within EdgeX.  See our Examples Repository for both Azure and AWS cloud templates.

Using your device, send data to the cloud- or local-based EdgeX instance that you've set up in Step 3 above.  

Using a cloud- or local-based EdgeX instance, we ask that you have your device send data to 

We ask that you provide a sample data set of typical data sent by your device.  

7  Validate Device Profile Syntax

8  Complete EdgeX Ready Submission Form

.  The data can come from an actual sensor/device, a simulator, or you can manually inject device-accurate data samples into EdgeX.  Please note that the community may use your sample data set as test data, system demonstration data, or in future system requirements.  So accurate sample data will lead to successful community collaboration.

Do I have to create my own device profile?

Yes.  Start with a device with which you have familiarity, extend a profile from an existing device service (excluding device-virtual), or extend one of the profiles found in IOTech’s DCT tool’s public library.  The important part is that you must be able show that you can use the device profile with EdgeX to get device/sensor data into and through EdgeX following the device profile’s specification.

Do I have to use the EdgeX cloud instance templates and a cloud system to run EdgeX when getting EdgeX Ready?

No.  The cloud templates are provided for convenience when you do not have ready access to be able to run an EdgeX instance.

Who will be able to see my submission?

Your EdgeX Ready application and all associated materials (profile, sample data, schema, etc.) will be sent to the EdgeX Foundry Certification Group for review and processing.  Only the Certification Group will see your application.  However, per the terms and conditions of the program, all materials submitted are considered contributions to the EdgeX Foundry project under Apache License, version 2.0.  Therefore, the materials may be made publicly available under that license by the EdgeX community.

When can I tell everyone that my organization is EdgeX Ready?

The Certification Group will review your submission and email you results which you can share as pert the terms and conditions agreement.