IEDK API¶
The IE Device Kit API provides the abstraction layer that decouples the Industrial Edge Runtime from the underlying Linux systems. This allows to adapt the runtime and its behavior to serve for the specific needs of different Industrial Edge products.
The IE Device Kit API is based on gRPC which provides a modern intermediate process communication style for building distributed applications and microservices. The Industrial Edge Platform provides and maintains the protobuf specification files for the APIs contained in the IE Device Kit. These protobuf specifications can be used to create stub implementations for both client and server in various programming languages. The Industrial Edge Runtime ships with a client side implementation of these APIs and expects the host system to provide a server side implementation.
This chapter provides a general overview and design considerations for the IE Device Kit API.
gRPC¶
gRPC is an open source, multi-language, multi-platform high-performance Remote Procedure Call framework. It builds on top of two fast and efficient protocols called protocol buffers as a serialization format and HTTP/2 as transport method.
All gRPC communication is based on unix domain sockets, not network sockets. This simplifies security aspects as access to the socket can be controlled by appropriate file system permissions and by controlling mount points for Docker containers. In addition, network based communication might be provided in the future.
For example, to query the currently installed firmware version of the Edge Device, the Industrial Edge Runtime has a client for the "System Access" API defined in the System.proto file, more specifically the GetFirmwareInfo remote procedure call. It will try to open a unix domain socket to a server implementation provided by the host system that implements this API.
Key features of gRPC are:
- Efficient intermediate process communication
- Language agnostic : IDL to describe service API and automatically generate client stubs and abstract server classes in 10+ languages
- HTTP/2: High performance RPC since in HTTP/2 transport all communication between a client and a server is performed over a single TCP connection that can carry any number of bidirectional flows of bytes
- Binary encodings with protocol buffers
- Compression
- Streaming
For a general introduction to gRPC, see the official gRPC documentation.
Protocol buffers¶
Protocol buffers are a data serialization protocol that is a language agnostic, platform neutral and extensible mechanism for serializing structured data. Once messages are serialized, protocol buffers produces a binary payload that is smaller in size than a normal *.json payload and is strongly typed. This serialized binary payload then travels over the binary transport protocol called HTTP/2.
Using protocol buffers, you write the message definition once and then generate bindings for every language from the same source. This enables writing various services in different programming languages and agreeing by all the applications on the messages format.
For a general introduction to protocol buffers, see the official documentation.
Versioning and compatibility¶
IE Device Kit services should be implemented in a forward and backward compatible manner. From the platform point of view, we try to keep changes to the API as minimal as possible.
We distinguish between minor changes and major (=breaking) changes.
Minor changes, for example addition of new fields to a message, will be provided in a backward compatible manner leveraging the possibilities provided by gRPC respectively protobuf. Refer to the protocol buffers language guide for background information about this.
The practical implementation is that implementations must be able to ignore unknown fields to ensure they continue to work with new releases of the Industrial Edge Runtime. This is automatically provided by gRPC.
If major changes are needed, they are introduced by creating a new API that uses a new domain socket for communication.
Industrial Edge Runtime packages consumes IE Device Kit APIs. Therefore, it is important to get correct versions of IEDK API implementation which is required by runtime packages. You can examine code changes via the IEDK reference implementation source repository and adapt your own IEDK API implementation or you can use directly delivered reference implementation packages.
See below table for minimum required packages for the IE Runtime:
| Edge Runtime Packages | Minimum Required Device Kit Services |
|---|---|
|
edge-iot-core-container_1.5.0-5 edge-manager_1.5.0-3 edge-storage-manager_1.5.0-2 |
dm-network_v1.4.0-3 dm-ntp_v1.3.0-2 dm-onboard_v1.4.0-2 dm-system_v1.4.0-7 ie-sysproxy_v1.0.0-1 |
Discovery¶
The only way to determine, if a device supports a certain IE Device Kit API is currently by looking at the filesystem (whether the corresponding unix domain socket is present). We plan in future to supplement this via an index service or similar means that allows querying which APIs are present.
Installing IEDK APIs as *.deb Package¶
If there is a need to improve the IEDK services in the local environment or on the Edge Device, available packages that support Go, Python and C++ software languages can be downloaded.
The required .deb package can be downloaded from the link below. The format of this *.deb package is devicekit_api__linux_amd64.deb.
sudo apt install ./devicekit_api_*_linux_amd64.deb.
To see the contents after the package installation is completed, the following command structure can be applied:
dpkg --contents devicekit_api_*_linux_amd64.deb.
After the package is downloaded, the downloaded files will appear under the /var/devicekitapi/ and usr/local/bin/ folders.
Here the /var/devicekitapi/ directory tree:
.
├── api
│ ├── Network.proto
│ ├── Ntp.proto
│ ├── Onboard.proto
│ ├── Security.proto
│ └── System.proto
├── cpp
│ ├── Network.pb.cc
│ ├── Network.pb.h
│ ├── Ntp.pb.cc
│ ├── Onboard.pb.cc
│ ├── Onboard.pb.h
│ ├── Security.pb.cc
│ ├── Security.pb.h
│ ├── System.pb.cc
│ └── System.pb.h
├── doc
│ ├── network.md
│ ├── ntp.md
│ ├── onboard.md
│ ├── security.md
│ └── system.md
├── go
│ ├── Network.pb.go
│ ├── Ntp.pb.go
│ ├── Onboard.pb.go
│ ├── Security.pb.go
│ └── System.pb.go
└── python
├── Network_pb2.py
├── Ntp_pb2.py
├── Onboard_pb2.py
├── Security_pb2.py
└── System_pb2.py
Detailed information about Network, NTP, Onboard and System services can be found under References.
The required files for each software language can be found under the separate files, as shwon in the tree structure above. Necessary files can be imported and used according to your software development environment.
Sample projects can also be downloaded to the development environment for a better understanding of the subject: