board

README

TinyGo board abstraction

This is an experiment. It may go stale, or it may change in backwards incompatible ways. Don't rely on it too much for now.

Goals

• Provide a common abstraction for boards supported by TinyGo.
• Provide a simulated board
• Auto-generate all board definitions from a devicetree-like format. Don't write any of the definitions by hand. (See Zephyr OS for example).
• Allow generating a similar board definition from target JSON files for custom boards.
• Make it possible to identify hardware at compile time instead of relying on build tags, as long as this doesn't impact binary size too much.

Non-goals

• Provide access to hardware unique to a particular board. A new interface has to be reasonably common, and has to be supported by at least two different boards.
• Support custom boards from this package. Only boards that are (or were) actually produced should be supported. This includes dev boards, maker boards, electronic badges, etc.

License

BSD 2-clause license, see LICENSE.txt for details.

Documentation

Index

• Constants
• Variables
• type ChargeState
  • func (c ChargeState) String() string
• type Displayer
• type Key
• type KeyEvent
  • func (k KeyEvent) Key() Key
  • func (k KeyEvent) Pressed() bool
• type LEDArray
• type TouchInput
• type TouchPoint

Constants

const (
	NoKey = iota

	// Special keys.
	KeyEscape

	// Navigation keys.
	KeyLeft
	KeyRight
	KeyUp
	KeyDown

	// Character keys.
	KeyEnter
	KeySpace
	KeyA
	KeyB
	KeyL
	KeyR

	// Special keys, used on some boards.
	KeySelect
	KeyStart
)

List of all supported key codes.

const (
	// The board name, as passed to TinyGo in the "-target" flag.
	// This is the special name "simulator" for the simulator.
	Name = "simulator"
)

Variables

var (
	Power   = simulatedPower{}
	Sensors = &simulatedSensors{}
	Display = mainDisplay{}
	Buttons = buttonsConfig{}
)

List of all devices.

Support varies by board, but all boards have the following peripherals defined.

var Simulator = struct {
	WindowTitle string

	// Width and height in virtual pixels (matching Size()). The window will
	// take up more physical pixels on high-DPI screens.
	WindowWidth  int
	WindowHeight int

	// Pixels per inch. The default is 120, which matches many commonly used
	// high-DPI screens (for example, Apple screens).
	WindowPPI int

	// How much time it takes (in nanoseconds) to draw a single pixel.
	// For example, for 8MHz and 16 bits per color:
	//     time.Second * 16 / 8e6
	WindowDrawSpeed time.Duration

	// Number of addressable LEDs used by default.
	AddressableLEDs int
}{
	WindowTitle:  "Simulator",
	WindowWidth:  240,
	WindowHeight: 240,
	WindowPPI:    120,

	AddressableLEDs: 5,
}

Settings for the simulator. These can be modified at any time, but it is recommended to modify them before configuring any of the board peripherals.

These can be modified to match whatever board your main target is. For example, if your board has a display that's only 160 by 128 pixels, you can modify the window size here to get a realistic simulation.

Types

type ChargeState

type ChargeState uint8

ChargeState is the charging status of a battery.

const (
	// A battery might be attached, this is unknown (no way to know by reading a
	// pin).
	UnknownBattery ChargeState = iota

	// This board doesn't have batteries.
	NoBattery

	// No battery is attached to the board, but there could be one.
	BatteryUnavailable

	// There is a battery attached and it's charging (usually from USB)
	Charging

	// Power is present, but the battery is not charging (usually when it is
	// fully charged).
	NotCharging

	// There is a battery attached and it's not charging (no power connected).
	Discharging
)

func (ChargeState) String

func (c ChargeState) String() string

Return a string representation of the charge status, mainly for debugging.

type Displayer

type Displayer[T pixel.Color] interface {
	// The display size in pixels.
	Size() (width, height int16)

	// DrawBitmap copies the bitmap to the internal buffer on the screen at the
	// given coordinates. It returns once the image data has been sent
	// completely.
	DrawBitmap(x, y int16, buf pixel.Image[T]) error

	// Display the written image on screen. This call may or may not be
	// necessary depending on the screen, but it's better to call it anyway.
	Display() error

	// Enter or exit sleep mode.
	Sleep(sleepEnabled bool) error

	// Return the current screen rotation.
	// Note that some screens are by default configured with rotation, so by
	// default you may not get drivers.Rotation0.
	Rotation() drivers.Rotation

	// Set a given rotation. For example, to rotate by 180° you can use:
	//
	// 	SetRotation((Rotation() + 2) % 4)
	//
	// Not all displays support rotation, in which case they will return an
	// error.
	SetRotation(drivers.Rotation) error
}

The display interface shared by all supported displays.

type Key

type Key uint8

Key is a single keyboard key (not to be confused with a single character).

type KeyEvent

type KeyEvent uint16

KeyEvent is a single key press or release event.

const (
	NoKeyEvent KeyEvent = iota // No key event was available.

)

func (KeyEvent) Key

func (k KeyEvent) Key() Key

Key returns the key code for this key event.

func (KeyEvent) Pressed

func (k KeyEvent) Pressed() bool

Pressed returns whether this event indicates a key press event. It returns true for a press, false for a release.

type LEDArray

type LEDArray interface {
	// Configure the LED array. This needs to be called before any other method
	// (except Len).
	Configure()

	// Return the length of the LED array.
	Len() int

	// Set a given pixel to the RGB value. The index must be in bounds,
	// otherwise this method will panic. The value is not immediately visible,
	// call Update() to update the pixel array.
	// Note that LED arrays are usually indexed from the end, because of the way
	// data is sent to them.
	SetRGB(index int, r, g, b uint8)

	// Update the pixel array to the values previously set in SetRGB.
	Update()
}

A LED array is a sequence of individually addressable LEDs (like WS2812).

var (
	AddressableLEDs LEDArray = dummyAddressableLEDs{}
)

type TouchInput

type TouchInput interface {
	ReadTouch() []TouchPoint
}

TouchInput reads the touch screen (resistive/capacitive) on a display and returns the current list of touch points.

type TouchPoint

type TouchPoint struct {
	// ID for this touch point. New touch events get a monotonically
	// incrementing ID. Because it is a uint32 (and it's unlikely a screen will
	// be touched more than 4 billion times), it can be treated as a unique ID.
	ID uint32

	// X and Y pixel coordinates.
	X, Y int16
}

A single touch point on the screen, from a finger, stylus, or something like that.