serialutils

README

go-serial-utils: a golang library with a bunch of procedures to handle serial ports on Arduino (and compatible) boards.

Board reset

To reset a board you must use the Reset method.

Reset(portToTouch string, wait bool, dryRun bool, portsMapper PortsMapper, cb *ResetProgressCallbacks) (string, error)

Reset will reset a board using the 1200 bps port-touch and waits for the bootloader port that is returned. Both reset and wait are optional:

• if portToTouch is the empty string "" the reset will be skipped
• if wait is false waiting will be skipped If wait is true, this function will wait for a new port to appear after the reset and returns it. If a new port can not be detected or if the wait parameter is false, then the empty string is returned.

If dryRun is set to true this function will only emulate the port reset without actually performing it, this is useful to mockup for unit-testing and CI. In dryRun mode if the portToTouch ends with "999" and wait is true, the function will return a new "mocked" bootloader port as portToTouch+"0".

portMapper is a method called to obtain the current serial port list. If portMapper is nil the default internal port mapper will be used.

cb is a struct defining a bunch of callback functions called during the reset operation to provide progress feedback to the caller.

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

Documentation

Index

• func DefaultPortMapper() (map[string]bool, error)
• func Reset(portToTouch string, wait bool, dryRun bool, portsMapper PortsMapper, ...) (string, error)
• func Touch1200bps(port string) error
• type PortsMapper
• type ResetProgressCallbacks

Functions

func DefaultPortMapper

func DefaultPortMapper() (map[string]bool, error)

DefaultPortMapper returns a PortsMapper that lists the available serial ports using the go.bug.st/serial library enumerator.

func Reset

func Reset(portToTouch string, wait bool, dryRun bool, portsMapper PortsMapper, cb *ResetProgressCallbacks) (string, error)

Reset will reset a board using the 1200 bps port-touch and waits for the bootloader port that is returned. Both reset and wait are optional: - if `portToTouch` is the empty string "" the reset will be skipped - if `wait` is false waiting will be skipped If `wait` is true, this function will wait for a new port to appear after the reset and returns it. If a new port can not be detected or if the `wait` parameter is `false`, then the empty string is returned.

If `dryRun` is set to `true` this function will only emulate the port reset without actually performing it, this is useful to mockup for unit-testing and CI. In dryRun mode if the `portToTouch` ends with `"999"` and `wait` is `true`, the function will return a new "mocked" bootloader port as `portToTouch+"0"`.

`portMapper` is a method called to obtain the current serial port list. If `portMapper` is `nil` the default internal port mapper will be used.

`cb` is a struct defining a bunch of callback functions called during the reset operation to provide progress feedback to the caller.

func Touch1200bps

func Touch1200bps(port string) error

Touch1200bps open and close the serial port at 1200 bps. This is used on many Arduino (and compatible) boards as a signal to put the MCU in bootloader mode.

Types

type PortsMapper

type PortsMapper func() (map[string]bool, error)

PortsMapper is a function that returns a map of available serial ports.

type ResetProgressCallbacks

type ResetProgressCallbacks struct {
	// TouchingPort is called to signal the 1200-bps touch of the reported port
	TouchingPort func(port string)
	// WaitingForNewSerial is called to signal that we are waiting for a new port
	WaitingForNewSerial func()
	// BootloaderPortFound is called to signal that the wait is completed and to
	// report the port found, or the empty string if no ports have been found and
	// the wait has timed-out.
	BootloaderPortFound func(port string)
	// Debug reports messages useful for debugging purposes. In normal conditions
	// these messages should not be displayed to the user.
	Debug func(msg string)
}

ResetProgressCallbacks is a struct that defines a bunch of function callback to observe the Reset function progress.