Experiencing EdgeX

In this section, we will take you a tour to experience EdgeX-API, including how to manage your devices with a web console UI and how to get data and control your device with device connector APIs.

Content

• Environment Setup

• Manage your devices with a web console

• Get sensor data and control your devices with device connector APIs

• Develop your own management application with core service APIs

• Reference

Setup EdgeX Foundry's Environment

First, please refer to the section of EdgeX Foundry Setup Guide to install docker engine, docker tool and related EdgeX microservices.

Next, we will provide a guide to walk through the device service, built-in management utility and management application development with EdgeX-API. This tour is designed for the three scenarios:

• Scenario one: manage your devices with a web console

• Scenario two: Get sensor data and control your device with device service APIs

• Scenario three: develop your own management application with core service APIs

Manage Your Devices with a Web Console

The purpose is to learn about

• EdgeX terms:

  • device service, device, device profile

  • configuration

  • event and reading

• EdgeX-API utility's purpose and capabilities

• use EdgeX-API utility for remote collecting data and control

Basic EdgeX Terms

The followings are some basic EdgeX terms:

• device service

  • Represent a microservice that manages one or more devices, for example, battery device service.

  • Each device service has a unique ID and name.

• device

  • Represent a physical device or sensor.

  • Each device is associated to one and only one device service.

  • Each device has a unique ID and name.

• device profile

  • A template of type or classification of device

  • Provide general characteristics for the types of data a device sends and what types of commands or actions ca be sent to the device.

  • A device must be associated to a single device profile.

  • Each profile has a unique ID and name.

• device service configuration

  • It sets the device service related options (toml file)

  • The configuration options include service port, debugging logging, scheduling,...

• event

  • collections of readings

  • associated to a device

• reading

  • represent a sensing on the part of a device/sensor

  • simple key/value pair

Get Familiar EdgeX with Management Utility

EdgeX-API utility is a web-based demo application. It provides a device management console with the following capabilities:

• Get devices and related supported commands

• Get all of the installed device services and related settings

• Send the 'get' command to collect the device/sensor data or reading

• Send the 'set' command with the related parameters to set or control the device/sensor

You can use the management utility to get quick tour and concept with EdgeX, including the device service, device and device profile. Besides you could also get sensor data or control through the UI Console.

Please refer to the section of the UI Console for the practice.

Collect Device Data and Control Device

The purpose is to learn about

• basic EdgeX-API programming convention

• how to use EdgeX device service API to collect data

• how to use EdgeX device service API to setup the device

After learning the concepts of how to get and set the commands to the device services with management utility in the previous section, we will explain how to use API programming to access the device subsequently.

EdgeX-APIs support REST interface and follow HTTP commands and programming conventions. For EdgeX device service's RESTful APIs, it usually uses two parameters, device and command.

• Device: represents physical device or resource, for example battery, disk, Wi-Fi...

• Command: represents physical sensor node or single I/O port, for example, battery temperature, disk total capacity, Wi-Fi's IP...

The following example demonstrates how to get battery temperature.

http://172.16.8.87:49987/api/v1/device/name/Advantech-IPSM90-01/Battery_Temperature

Please refer to the section of Basic Programming Convention for the EdgeX-API programming practice to collect device data and control device.

Develop Your Own Application to Manage Devices

The purpose is to learn about

• how to get all devices

• how to get all commands for the specified device

• how to configure the scheduling for collecting data

• how to read the data in database

• how to clear the data in database

If you would like to develop your own application with the following general capabilities of all devices as the built-in management utility.

• Get devices and related supported commands

• Get all of the installed device services and related settings

• Send the 'get' command to collect the device/sensor data or reading

• Send the 'set' command with the related parameters to set or control the device/sensor

there are some advanced microservices and APIs you should know, the core command microservice, core metadata microservice and core data microservice.

You can use the following core service APIs.

• Get all devices and commands (core command API)

http://localhost:48082/api/v1/device

It returns a list of (all) devices and their command offerings.

• GET all devices (core metadata API)

http://localhost:48081/api/v1/device

It returns all devices sorted by id.

• GET events (core data API)

http://localhost:48080/api/v1/event/device/{deviceId}/{limit}

it returns list of events with their associated readings for a given device, sort by event creation date

Please refer to the sections of Core Data Service APIs, Meta Data Service APIs and Command Service APIs for the detailed.

Reference

• EdgeX Setup Guide: https://edgex-api-advantech.gitbook.io/edgex-api-doc/getting-started/install

• Device Service Configuration: https://edgex-api-advantech.gitbook.io/edgex-api-doc/device-connection/configuration

• Basic Programming Convention: https://edgex-api-advantech.gitbook.io/edgex-api-doc/device-connection/programming-basics

• Management Utility: https://edgex-api-advantech.gitbook.io/edgex-api-doc/getting-started/ui-console/v1.1

• Core Data Service APIs: https://edgex-api-advantech.gitbook.io/edgex-api-doc/advanteched-services-apis/core-data-service-apis

• Meta Data Service APIs: https://edgex-api-advantech.gitbook.io/edgex-api-doc/advanteched-services-apis/meta-data-service-apis