README
¶
Pluggable Discovery Protocol Handler
This project is a library to ease implementation of pluggable discoveries for the Arduino CLI following the official specification.
Reference implementation
The dummy-discovery folder contains a reference pluggable discovery implementation.
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 ¶
Package 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 implement a pluggable-discovery client and server.
While implementing a server, all the commands issued by the client are conveniently translated into function calls, in particular the methods of 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 Client
- func (disc *Client) Alive() bool
- func (disc *Client) GetID() string
- func (disc *Client) List() ([]*Port, error)
- func (disc *Client) Quit()
- func (disc *Client) Run() (err error)
- func (disc *Client) SetLogger(logger ClientLogger)
- func (disc *Client) SetUserAgent(userAgent string)
- func (disc *Client) Start() error
- func (disc *Client) StartSync(size int) (<-chan *Event, error)
- func (disc *Client) Stop() error
- func (disc *Client) String() string
- type ClientLogger
- type Discovery
- type ErrorCallback
- type Event
- type EventCallback
- type Port
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶ added in v2.2.0
type Client struct {
// contains filtered or unexported fields
}
Client is a tool that detects communication ports to interact with the boards.
func (*Client) Alive ¶ added in v2.2.0
Alive returns true if the discovery is running and false otherwise.
func (*Client) List ¶ added in v2.2.0
List executes an enumeration of the ports and returns a list of the available ports at the moment of the call.
func (*Client) Quit ¶ added in v2.2.0
func (disc *Client) Quit()
Quit terminates the discovery. No more commands can be accepted by the discovery.
func (*Client) Run ¶ added in v2.2.0
Run starts the discovery executable process and sends the HELLO command to the discovery to agree on the pluggable discovery protocol. This must be the first command to run in the communication with the discovery. If the process is started but the HELLO command fails the process is killed.
func (*Client) SetLogger ¶ added in v2.2.0
func (disc *Client) SetLogger(logger ClientLogger)
SetLogger sets the logger to be used in the discovery
func (*Client) SetUserAgent ¶ added in v2.2.0
SetUserAgent sets the user agent to be used in the discovery
func (*Client) Start ¶ added in v2.2.0
Start initializes and start the discovery internal subroutines. This command must be called before List.
func (*Client) StartSync ¶ added in v2.2.0
StartSync puts the discovery in "events" mode: the discovery will send "add" and "remove" events each time a new port is detected or removed respectively. After calling StartSync an initial burst of "add" events may be generated to report all the ports available at the moment of the start. It also creates a channel used to receive events from the pluggable discovery. The event channel must be consumed as quickly as possible since it may block the discovery if it becomes full. The channel size is configurable.
type ClientLogger ¶ added in v2.2.0
type ClientLogger interface {
Debugf(format string, args ...interface{})
Errorf(format string, args ...interface{})
}
ClientLogger is the interface that must be implemented by a logger to be used in the discovery client.
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 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 ¶
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"`
HardwareID string `json:"hardwareId,omitempty"`
}
Port is a descriptor for a board port
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
A Server is a pluggable discovery protocol handler, it must be created using the NewServer function.
func NewServer ¶
NewServer creates a new discovery server backed by the provided pluggable discovery implementation. To start the server use the Run method.
Source Files
Directories