edgeimpulse

README

Edge Impulse Linux SDK for Go

This library lets you run machine learning models and collect sensor data on Linux machines using Go. This SDK is part of Edge Impulse where we enable developers to create the next generation of intelligent device solutions with embedded machine learning. Start here to learn more and train your first model.

Installation guide

1. Install Go 1.15 or higher.

2. Clone this repository:

   $ git clone https://github.com/edgeimpulse/linux-sdk-go
   

3. Find the example that you want to build and run go build:

   $ cd cmd/eimclassify
   $ go build
   

4. Run the example:

   $ ./eimclassify
   

   And follow instructions.

5. This SDK is also published to pkg.go.dev, so you can pull the package from there too.

Collecting data

Before you can classify data you'll first need to collect it. If you want to collect data from the camera or microphone on your system you can use the Edge Impulse CLI, and if you want to collect data from different sensors (like accelerometers or proprietary control systems) you can do so in a few lines of code.

Collecting data from the camera or microphone

To collect data from the camera or microphone, follow the getting started guide for your development board.

Collecting data from other sensors

To collect data from other sensors you'll need to write some code to collect the data from an external sensor, wrap it in the Edge Impulse Data Acquisition format, and upload the data to the Ingestion service. Here's an end-to-end example.

Classifying data

To classify data (whether this is from the camera, the microphone, or a custom sensor) you'll need a model file. This model file contains all signal processing code, classical ML algorithms and neural networks - and typically contains hardware optimizations to run as fast as possible. To grab a model file:

1. Train your model in Edge Impulse.

2. Install the Edge Impulse for Linux CLI.

3. Download the model file via:

   $ edge-impulse-linux-runner --download modelfile.eim
   

   This downloads the file into modelfile.eim. (Want to switch projects? Add --clean)

Then you can start classifying realtime sensor data. We have examples for:

• Audio - grabs data from the microphone and classifies it in realtime.
• Camera - grabs data from a webcam and classifies it in realtime.
• Custom data - classifies custom sensor data.

Documentation

Overview

Package edgeimpulse lets you run model processes to classify measurements.

Index

• func TempDir() (string, error)
• type MAF
  • func NewMAF(size int, labels []string) (*MAF, error)
  • func (m *MAF) Update(classification map[string]float64) (map[string]float64, error)
• type ModelParameters
  • func (p ModelParameters) String() string
• type ModelType
• type Project
  • func (p Project) String() string
• type Runner
• type RunnerClassifyRequest
• type RunnerClassifyResponse
  • func (r RunnerClassifyResponse) String() string
• type RunnerOpts
• type RunnerProcess
  • func NewRunnerProcess(modelPath string, opts *RunnerOpts) (runner *RunnerProcess, rerr error)
  • func (r *RunnerProcess) Classify(data []float64) (resp RunnerClassifyResponse, rerr error)
  • func (r *RunnerProcess) Close() error
  • func (r *RunnerProcess) ModelParameters() ModelParameters
  • func (r *RunnerProcess) Project() Project
• type RunnerResponse
• type SensorType

Functions

func TempDir

func TempDir() (string, error)

TempDir returns either a temporary directory in /dev/shm (if it exists), or otherwise in the OS default temporary directory.

Types

type MAF

type MAF struct {
	// contains filtered or unexported fields
}

MAF is a moving average filter, for smoothing out classification values.

func NewMAF

func NewMAF(size int, labels []string) (*MAF, error)

NewMAF returns a new moving average filter with a history of given size. Values are initialized to all zeroes.

func (*MAF) Update

func (m *MAF) Update(classification map[string]float64) (map[string]float64, error)

Update adds one classification result to the moving average filter. Update returns the smoothed values based on the history. Unknown keys (labels) in classification result in an error, as does an empty classification.

type ModelParameters

type ModelParameters struct {
	ModelType  ModelType `json:"model_type"`
	Sensor     int64     `json:"sensor"`
	SensorType SensorType
	IntervalMS float64 `json:"interval_ms"`

	Frequency float64 `json:"frequency"`

	InputFeaturesCount int `json:"input_features_count"`

	// For images only.
	ImageInputHeight  int `json:"image_input_height"`
	ImageInputWidth   int `json:"image_input_width"`
	ImageChannelCount int `json:"image_channel_count"`

	// Labels in resulting classifications.
	Labels     []string `json:"labels"`
	LabelCount int      `json:"label_count"`

	HasAnomaly float64 `json:"has_anomaly"`
}

ModelParameters holds the model parameters for a model.

func (ModelParameters) String

func (p ModelParameters) String() string

String returns a human-readable summary of the model parameters.

type ModelType

type ModelType string

ModelType can be "classification" or "object_detection". May be expanded in the future.

const (
	// ModelTypeClassification indicates the model returns scoring values
	// for a set of labels.
	ModelTypeClassification ModelType = "classification"

	// ModelTypeObjectDetection indicates the model returns returns
	// bounding boxes for recognized objects.
	ModelTypeObjectDetection ModelType = "object_detection"
)

type Project

type Project struct {
	DeployVersion int64  `json:"deploy_version"`
	ID            int64  `json:"id"`
	Name          string `json:"name"`
	Owner         string `json:"owner"`
}

Project holds the project information stored in the model, originally from EdgeImpulse Studio.

func (Project) String

func (p Project) String() string

String returns human-readable project info.

type Runner

type Runner interface {
	ModelParameters() ModelParameters
	Project() Project
	Classify(data []float64) (RunnerClassifyResponse, error)
	Close() error
}

Runner is a running model with model and project parameters, and the ability to classify data.

type RunnerClassifyRequest

type RunnerClassifyRequest struct {
	ID       int64     `json:"id"`
	Classify []float64 `json:"classify"`
}

RunnerClassifyRequest is a request to the model to classify data.

type RunnerClassifyResponse

type RunnerClassifyResponse struct {
	RunnerResponse

	Result struct {
		// Based on the ModelType, either Classification or BoundingBoxes will be set.
		Classification map[string]float64 `json:"classification,omitempty"`

		BoundingBoxes []struct {
			Label  string  `json:"label"`
			Value  float64 `json:"value"`
			X      int     `json:"x"`
			Y      int     `json:"y"`
			Width  int     `json:"width"`
			Height int     `json:"height"`
		} `json:"bounding_boxes,omitempty"`

		Anomaly float64 `json:"anomaly,omitempty"`
	} `json:"result"`

	Timing struct {
		DSP            float64 `json:"dsp"`
		Classification float64 `json:"classification"`
		Anomaly        float64 `json:"anomaly"`
	} `json:"timing"`
}

RunnerClassifyResponse is the response from the model to a RunnerClassifyRequest.

func (RunnerClassifyResponse) String

func (r RunnerClassifyResponse) String() string

String returns a summary of the result, with classification or error message.

type RunnerOpts

type RunnerOpts struct {
	// Explicitly set a working directory. This directory is not
	// automatically removed on Runner.Close. If empty, a temporary
	// directory is created.
	WorkDir string

	// If not empty, the JSON-encoded requests and responses are written to
	// this directory.
	TraceDir string
}

RunnerOpts contains options for starting a runner.

type RunnerProcess

type RunnerProcess struct {
	// contains filtered or unexported fields
}

RunnerProcess is a running model process that can classify data.

func NewRunnerProcess

func NewRunnerProcess(modelPath string, opts *RunnerOpts) (runner *RunnerProcess, rerr error)

NewRunnerProcess creates and starts a new runner from a model file. Always call Close on a runner, to cleanup any temporary directories.

func (*RunnerProcess) Classify

func (r *RunnerProcess) Classify(data []float64) (resp RunnerClassifyResponse, rerr error)

Classify executes the model on the features and returns the resulting classification.

func (*RunnerProcess) Close

func (r *RunnerProcess) Close() error

Close shuts down the runner, stopping the model process.

func (*RunnerProcess) ModelParameters

func (r *RunnerProcess) ModelParameters() ModelParameters

ModelParameters returns the parameters for this runner.

func (*RunnerProcess) Project

func (r *RunnerProcess) Project() Project

Project returns the project for this runner.

type RunnerResponse

type RunnerResponse struct {
	ID      int64  `json:"id"`
	Success bool   `json:"success"`
	Error   string `json:"error,omitempty"`
	// contains filtered or unexported fields
}

RunnerResponse represents the basic status of a response from the model.

type SensorType

type SensorType string

SensorType describes the source of measurements/values.

const (
	SensorTypeUnknown       SensorType = "unknown"
	SensorTypeMicrophone    SensorType = "microphone"
	SensorTypeAccelerometer SensorType = "accelerometer"
	SensorTypeCamera        SensorType = "camera"
)

SensorTypes as source of measurements. Use a matching recorder and classifier, e.g. an audio classifier with a SensorTypeMicrophone.