board

Documentation

Overview

Package board defines the interfaces that typically live on a single-board computer such as a Raspberry Pi.

Besides the board itself, some other interfaces it defines are analog pins and digital interrupts. For more information, see the board component docs.

Package board contains a gRPC based board client.

Package board contains a gRPC based Board service server.

Index

• Constants
• Variables
• func CreateStatus(ctx context.Context, b Board) (*pb.Status, error)
• func Named(name string) resource.Name
• func NamesFromRobot(r robot.Robot) []string
• func NewRPCServiceServer(coll resource.APIResourceCollection[Board]) interface{}
• func ValidatePWMDutyCycle(dutyCyclePct float64) (float64, error)
• type Analog
• type AnalogReaderConfig
  • func (config *AnalogReaderConfig) Validate(path string) error
• type AnalogValue
• type Board
  • func FromDependencies(deps resource.Dependencies, name string) (Board, error)
  • func FromRobot(r robot.Robot, name string) (Board, error)
  • func NewClientFromConn(ctx context.Context, conn rpc.ClientConn, remoteName string, ...) (Board, error)
• type DigitalInterrupt
• type DigitalInterruptConfig
  • func (config *DigitalInterruptConfig) Validate(path string) error
• type GPIOPin
• type I2CConfig
  • func (config *I2CConfig) Validate(path string) error
• type SPIConfig
  • func (config *SPIConfig) Validate(path string) error
• type Tick

Constants

const SubtypeName = "board"

SubtypeName is a constant that identifies the component resource API string "board".

Variables

var API = resource.APINamespaceRDK.WithComponentType(SubtypeName)

API is a variable that identifies the component resource API.

Functions

func CreateStatus

func CreateStatus(ctx context.Context, b Board) (*pb.Status, error)

CreateStatus constructs a new up to date status from the given board. The operation can take time and be expensive, so it can be cancelled by the given context.

func Named

func Named(name string) resource.Name

Named is a helper for getting the named board's typed resource name.

func NamesFromRobot

func NamesFromRobot(r robot.Robot) []string

NamesFromRobot is a helper for getting all board names from the given Robot.

func NewRPCServiceServer

func NewRPCServiceServer(coll resource.APIResourceCollection[Board]) interface{}

NewRPCServiceServer constructs an board gRPC service server. It is intentionally untyped to prevent use outside of tests.

func ValidatePWMDutyCycle

func ValidatePWMDutyCycle(dutyCyclePct float64) (float64, error)

ValidatePWMDutyCycle makes sure the value passed in is a believable duty cycle value. It returns the preferred duty cycle value if it is, and an error if it is not.

Types

type Analog

type Analog interface {
	// Read reads off the current value.
	Read(ctx context.Context, extra map[string]interface{}) (AnalogValue, error)

	// Write writes a value to the analog pin.
	Write(ctx context.Context, value int, extra map[string]interface{}) error
}

An Analog represents an analog pin that resides on a board.

Read example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the analog pin "my_example_analog".
analog, err := myBoard.AnalogByName("my_example_analog")

// Get the value of the analog signal "my_example_analog" has most recently measured.
reading, err := analog.Read(context.Background(), nil)
readingValue := reading.Value
stepSize := reading.StepSize

Write example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the Analog pin "my_example_analog".
analog, err := myBoard.AnalogByName("my_example_analog")

// Set the pin to value 48.
err := analog.Write(context.Background(), 48, nil)

type AnalogReaderConfig

type AnalogReaderConfig struct {
	Name              string `json:"name"`
	Pin               string `json:"pin"`
	AverageOverMillis int    `json:"average_over_ms,omitempty"`
	SamplesPerSecond  int    `json:"samples_per_sec,omitempty"`
}

AnalogReaderConfig describes the configuration of an analog reader on a board.

func (*AnalogReaderConfig) Validate

func (config *AnalogReaderConfig) Validate(path string) error

Validate ensures all parts of the config are valid.

type AnalogValue

type AnalogValue struct {
	Value    int
	Min      float32
	Max      float32
	StepSize float32
}

AnalogValue contains all info about the analog reading. Value represents the reading in bits. Min and Max represent the range of raw analog values. StepSize is the precision per bit of the reading.

type Board

type Board interface {
	resource.Resource

	// AnalogByName returns an analog pin by name.
	AnalogByName(name string) (Analog, error)

	// DigitalInterruptByName returns a digital interrupt by name.
	DigitalInterruptByName(name string) (DigitalInterrupt, error)

	// GPIOPinByName returns a GPIOPin by name.
	GPIOPinByName(name string) (GPIOPin, error)

	// AnalogNames returns the names of all known analog pins.
	AnalogNames() []string

	// DigitalInterruptNames returns the names of all known digital interrupts.
	DigitalInterruptNames() []string

	// SetPowerMode sets the board to the given power mode. If
	// provided, the board will exit the given power mode after
	// the specified duration.
	SetPowerMode(ctx context.Context, mode pb.PowerMode, duration *time.Duration) error

	// StreamTicks starts a stream of digital interrupt ticks.
	StreamTicks(ctx context.Context, interrupts []DigitalInterrupt, ch chan Tick,
		extra map[string]interface{}) error
}

A Board represents a physical general purpose board that contains various components such as analogs, and digital interrupts. For more information, see the board component docs.

AnalogByName example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the Analog pin "my_example_analog".
analog, err := myBoard.AnalogByName("my_example_analog")

DigitalInterruptByName example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, err := myBoard.DigitalInterruptByName("my_example_digital_interrupt")

GPIOPinByName example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")

SetPowerMode example:

myBoard, err := board.FromRobot(robot, "my_board")

Set the power mode of the board to OFFLINE_DEEP.
myBoard.SetPowerMode(context.Background(), boardpb.PowerMode_POWER_MODE_OFFLINE_DEEP, nil)

StreamTicks example:

myBoard, err := board.FromRobot(robot, "my_board")

// Make a channel to stream ticks
ticksChan := make(chan board.Tick)

interrupts := []*DigitalInterrupt{}

if di8, err := myBoard.DigitalInterruptByName("8"); err == nil {
  interrupts = append(interrupts, di8)
}

if di11, err := myBoard.DigitalInterruptByName("11"); err == nil {
  interrupts = append(interrupts, di11)
}

err = myBoard.StreamTicks(context.Background(), interrupts, ticksChan, nil)

func FromDependencies

func FromDependencies(deps resource.Dependencies, name string) (Board, error)

FromDependencies is a helper for getting the named board from a collection of dependencies.

func FromRobot

func FromRobot(r robot.Robot, name string) (Board, error)

FromRobot is a helper for getting the named board from the given Robot.

func NewClientFromConn

func NewClientFromConn(
	ctx context.Context,
	conn rpc.ClientConn,
	remoteName string,
	name resource.Name,
	logger logging.Logger,
) (Board, error)

NewClientFromConn constructs a new Client from connection passed in.

type DigitalInterrupt

type DigitalInterrupt interface {
	// Name returns the name of the interrupt.
	Name() string

	// Value returns the current value of the interrupt which is
	// based on the type of interrupt.
	Value(ctx context.Context, extra map[string]interface{}) (int64, error)
}

A DigitalInterrupt represents a configured interrupt on the board that when interrupted, calls the added callbacks.

Value example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, err := myBoard.DigitalInterruptByName("my_example_digital_interrupt")

// Get the amount of times this DigitalInterrupt has ticked.
count, err := interrupt.Value(context.Background(), nil)

type DigitalInterruptConfig

type DigitalInterruptConfig struct {
	Name string `json:"name"`
	Pin  string `json:"pin"`
}

DigitalInterruptConfig describes the configuration of digital interrupt for a board.

func (*DigitalInterruptConfig) Validate

func (config *DigitalInterruptConfig) Validate(path string) error

Validate ensures all parts of the config are valid.

type GPIOPin

type GPIOPin interface {
	// Set sets the pin to either low or high.
	Set(ctx context.Context, high bool, extra map[string]interface{}) error

	// Get gets the high/low state of the pin.
	Get(ctx context.Context, extra map[string]interface{}) (bool, error)

	// PWM gets the pin's given duty cycle.
	PWM(ctx context.Context, extra map[string]interface{}) (float64, error)

	// SetPWM sets the pin to the given duty cycle.
	SetPWM(ctx context.Context, dutyCyclePct float64, extra map[string]interface{}) error

	// PWMFreq gets the PWM frequency of the pin.
	PWMFreq(ctx context.Context, extra map[string]interface{}) (uint, error)

	// SetPWMFreq sets the given pin to the given PWM frequency. For Raspberry Pis,
	// 0 will use a default PWM frequency of 800.
	SetPWMFreq(ctx context.Context, freqHz uint, extra map[string]interface{}) error
}

A GPIOPin represents an individual GPIO pin on a board.

Set example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")

// Set the pin to high.
err := pin.Set(context.Background(), "true", nil)

Get example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")

// Get if it is true or false that the state of the pin is high.
high := pin.Get(context.Background(), nil)

PWM example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")

// Returns the duty cycle.
duty_cycle := pin.PWM(context.Background(), nil)

SetPWM example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")

// Set the duty cycle to .6, meaning that this pin will be in the high state for 60% of the duration of the PWM interval period.
err := pin.SetPWM(context.Background(), .6, nil)

PWMFreq example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")

// Get the PWM frequency of this pin.
freqHz, err := pin.PWMFreq(context.Background(), nil)

SetPWMFreq example:

myBoard, err := board.FromRobot(robot, "my_board")

// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")

// Set the PWM frequency of this pin to 1600 Hz.
high := pin.SetPWMFreq(context.Background(), 1600, nil)

type I2CConfig

type I2CConfig struct {
	Name string `json:"name"`
	Bus  string `json:"bus"`
}

I2CConfig enumerates a specific, shareable I2C bus.

func (*I2CConfig) Validate

func (config *I2CConfig) Validate(path string) error

Validate ensures all parts of the config are valid.

type SPIConfig

type SPIConfig struct {
	Name      string `json:"name"`
	BusSelect string `json:"bus_select"` // "0" or "1" are common on single board computers
}

SPIConfig enumerates a specific, shareable SPI bus.

func (*SPIConfig) Validate

func (config *SPIConfig) Validate(path string) error

Validate ensures all parts of the config are valid.

type Tick

type Tick struct {
	Name             string
	High             bool
	TimestampNanosec uint64
}

Tick represents a signal received by an interrupt pin. This signal is communicated via registered channel to the various drivers. Depending on board implementation there may be a wraparound in timestamp values past 4294967295000 nanoseconds (~72 minutes) if the value was originally in microseconds as a 32-bit integer. The timestamp in nanoseconds of the tick SHOULD ONLY BE USED FOR CALCULATING THE TIME ELAPSED BETWEEN CONSECUTIVE TICKS AND NOT AS AN ABSOLUTE TIMESTAMP.