discovery

README

A golang library to handle the Arduino pluggable-discovery communication protocol.

How to build

Security

If you think you found a vulnerability or other security-related bug in this project, please read our security policy and report the bug to our Security Team 🛡️ Thank you!

e-mail contact: security@arduino.cc

License

Copyright (c) 2021 ARDUINO SA (www.arduino.cc)

The software is released under the GNU General Public License, which covers the main body of the serial-discovery code. The terms of this license can be found at: https://www.gnu.org/licenses/gpl-3.0.en.html

See LICENSE.txt for details.

Documentation

Overview

discovery is a library for handling the Arduino Pluggable-Discovery protocol (https://github.com/arduino/tooling-rfcs/blob/main/RFCs/0002-pluggable-discovery.md#pluggable-discovery-api-via-stdinstdout)

The library implements the state machine and the parsing logic to communicate with a pluggable-discovery client. All the commands issued by the client are conveniently translated into function calls, in particular the Discovery interface are the only functions that must be implemented to get a fully working pluggable discovery using this library.

A usage example is provided in the dummy-discovery package.

Index

• type Discovery
• type DiscoveryServer
  • func NewDiscoveryServer(impl Discovery) *DiscoveryServer
  • func (d *DiscoveryServer) Run(in io.Reader, out io.Writer) error
• type ErrorCallback
• type EventCallback
• type Port

Types

type Discovery

type Discovery interface {
	// Hello is called once at startup to provide the userAgent string
	// and the protocolVersion negotiated with the client.
	Hello(userAgent string, protocolVersion int) error

	// StartSync is called to put the discovery in event mode. When the
	// function returns the discovery must send port events ("add" or "remove")
	// using the eventCB function.
	StartSync(eventCB EventCallback, errorCB ErrorCallback) error

	// Stop stops the discovery internal subroutines. If the discovery is
	// in event mode it must stop sending events through the eventCB previously
	// set.
	Stop() error

	// Quit is called just before the server terminates. This function can be
	// used by the discovery as a last chance gracefully close resources.
	Quit()
}

Discovery is an interface that represents the business logic that a pluggable discovery must implement. The communication protocol is completely hidden and it's handled by a DiscoveryServer.

type DiscoveryServer

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

A DiscoveryServer is a pluggable discovery protocol handler, it must be created using the NewDiscoveryServer function.

func NewDiscoveryServer

func NewDiscoveryServer(impl Discovery) *DiscoveryServer

NewDiscoveryServer creates a new discovery server backed by the provided pluggable discovery implementation. To start the server use the Run method.

func (*DiscoveryServer) Run

func (d *DiscoveryServer) Run(in io.Reader, out io.Writer) error

Run starts the protocol handling loop on the given input and output stream, usually `os.Stdin` and `os.Stdout` are used. The function blocks until the `QUIT` command is received or the input stream is closed. In case of IO error the error is returned.

type ErrorCallback

type ErrorCallback func(err string)

ErrorCallback is a callback function to signal unrecoverable errors to the client while the discovery is in event mode. Once the discovery signal an error it means that no more port-events will be delivered until the client performs a STOP+START_SYNC cycle.

type EventCallback

type EventCallback func(event string, port *Port)

EventCallback is a callback function to call to transmit port metadata when the discovery is in "sync" mode and a new event is detected.

type Port

type Port struct {
	Address       string          `json:"address"`
	AddressLabel  string          `json:"label,omitempty"`
	Protocol      string          `json:"protocol,omitempty"`
	ProtocolLabel string          `json:"protocolLabel,omitempty"`
	Properties    *properties.Map `json:"properties,omitempty"`
}

Port is a descriptor for a board port