shjala / eve-api

Repository for eve-api code

EVE Device API

This is the "Device API", for communications between an lf-edge eve edge device and a controller.

See https://www.lfedge.org/projects/eve/

This directory defines the API itself as message definitions, documentation and language-specific bindings.

Contents

Documentation

Documentation is in markdown files in this directory, specifically:

• General overview and how to use and build in this README.md
• The protocol in APIv2.md
• Local profile overrides in PROFILE.md
• Object signing in OBJECT-SIGNING.md

Message definitions

The message definitions are in protobufs in the proto subdirectory.

Language bindings

Language bindings are generated from the protobufs, in language-specific directories:

• go
• python

Using the language-specific bindings

To use the language-specific bindings, import them as libraries to your appropriate language. For example, in go:

import (
    "github.com/lf-edge/eve-api/go/config"
)

Development

To make changes to this API, you:

1. Edit the specific .proto files in the proto directory, or create new ones, as desired.
2. Run make proto to generate the language-specific bindings and visualizations.
3. Commit the changes to the .proto files and the generated files.

The Pull Request process for this repository will regenerate the language-specific bindings and visualizations, and check that no files are missing from the repository.

You can do the above inside a ready-to-run docker container with all of the prerequisites (recommended), or you can install the prerequisites on your local machine.

Either way, you run:

make proto

Language-Specific Bindings

To generate just a single language, run:

make go
# or
make python

Visualizations

In addition to the language-specific libraries, make proto generates visualizations of the protobuf structure, beginning with the root of an edge device config. These are available as .svg, .dot and .png as below. Click to zoom in.

• 
• svg
• dot

Build Environment

The above make commands can be run either in a devcontainer or locally on your machine.

When run in a devcontainer, all of the prerequsities and their correct versions are set up for you.

Devcontainer

To run inside a devcontainer (recommended), use one of the tools that recognizes and supports devcontainers to provide a development-time environment. These include VS Code, GitHub Codespaces, and the devcontainers CLI.

If using the CLI, run:

devcontainer --workspace-folder . up
devcontainer exec --workspace-folder . make proto

Manual ad-hoc use of devcontainer on Linux

First the devcontainer needs to be built and then run to do the make proto:

docker build -f .devcontainer/Dockerfile -t eve-api-builder .
docker run --rm -v $(pwd):/src -w /src -u $(id -u) eve-api-builder make proto

Local

If running locally, you need to install the prerequisites yourself.

• protoc
• protodot
• dot