It’s been a while since the last post on this blog. This doesn’t mean, however, that nothing has happened with the Embedded Go during this time. We have stable but rather slow progress.

Embedded Go 1.24

The Go 1.24 was merged into Embedded Go with all its language changes. Yes, as I’m writing these words the Go 1.25 has just been released, but Embedded Go is always a little behind.

Embedded Go as a toolchain

The big thing is the new release model. As Embedded Go has become an installable Go toolchain, we have moved away from binary releases. Now you can easily add Embedded Go to your Go compiler using only two commands:

go install github.com/embeddedgo/dl/go1.24.5-embedded@latest
go1.24.5-embedded download

Then set the GOTOOLCHAIN environment variable to go1.24.5-embedded. The most convenient place to set it is the go.env file which can be used as a per project configuration. With the configuration in file you have to set GOENV instead of GOTOOLCHAIN before use the go command. You can avoid setting GOENV by using egtool build instead of go build if you just want to build your project (egtool will simply call go build with the GOENV set to the path of the found go.env).

New tool: egtool

We have new tool that makes programming embedded targets much convenient. The egtool replaced emgo. It’s much cleaner and can do much more.

$ go install github.com/embeddedgo/tools/egtool@latest
$ egtool
Usage:
  egtool COMMAND [ARGUMENTS]

Available commands:
  bin       convert an ELF file to a binary image
  build     run `go build` with GOENV set to the found go.env file
  hex       convert an ELF file to the Intel HEX format
  imxmbr    generate the MBR file for the I.MX RT106x microcontrollers
  isrnames  generate IRQ handler linknames according the imported irq package
  load      load the program / memory range stored in a file onto the device
  uf2       convert an ELF file to the UF2 format

The most useful egtool command is load which currently supports RPi Pico 2, Teensy 4.x and STM32 microcontrollers connected via USB.

Pi Pico 2

We gained support for the wonderfull Raspberry Pi RP2350 microcontroller. Its both ARM cores will provide power to your goroutines. The number of supported peripherals is still modest (DMA, GPIO, IOMUX, SPI, UART) but this MCU will definitely be our workhorse due to its availability and features, so expect more in the near future.

Nintendo 64

Timur Çelik did a great job adding support for the Nintendo 64 CPU. What surprised me is that the MIPS64 from 1996 is supported by GOARCH=mips64 with very minimal changes.

The new toolchain based release model is also heavily influenced by Timur. He also did a lot to clean up and improve many aspects of Embedded Go.

If you are interested in the N64 homebrew development take a look at the github.com/clktmr/n64 repository.

The real N64 consoles are still quite cheap, still quite capable. They are also very easy to work with because they are the last cartridge based systems. There are easily available cartridges for programmes like SummerCart64 or PicoCart64. You can also work with an N64 emulator but the real hardware is what the Embedded Go is for.

Michał Derkacz

Updated 2025-08-20: use egtool instead of emgo

Since its first release in 2009, the Go language has been closely associated with network programming. Unfortunately, until now the Embedded Go had no networking capabilities, mainly due to the strong dependency of the net package on the network capabilities of the underlying operating system. But that has changed.

Hardware

As a hardware platform, we use the Teensy 4.1 development board. The code presented here should also run on Teensy 4.0 without any modifications. The exception, unfortunately, is the titular HTTP server, which does not fit into its smaller Flash.

As a network interface, we use the ESP-01S module. It is easily available, cheap and sufficient for our needs.

You can use any other ESP8266 or ESP32 based development board provided you flash it with the ESP-AT firmware.

The ESP-AT firmware gives us what the operating system provides for a typical Go application. Instead of using system calls, our programs will talk to the ESP-AT firmware using an UART interface and a rather weird protocol based on Hayes AT commands. All these details will be invisible to us thanks to the espat package. Moreover, the espat/espnet package will provide our application the interface compatible with the standard net package, so any code that uses net.Conn or net.Listener can work with it.

First steps with Teensy and Go

If you have the required hardware and want to test the code presented below, you need to install the latest release of Embedded Go. Detailed instruction can be found on the Getting Started page.

Let’s create a folder, say teensyApp, go into it and create the following two files:

main.go

package main

import (
	"time"

	"github.com/embeddedgo/imxrt/devboard/teensy4/board/leds"
)

func main() {
	for {
		leds.User.Toggle()
		time.Sleep(time.Second)
	}
}

go.env

GOTOOLCHAIN=go1.24.5-embedded
GOOS=noos
GOARCH=thumb
GOARM=7,hardfloat
GOFLAGS=-tags=imxrt1060 '-ldflags=-stripfn=1 -M=0x20200000:992K -F=0x60002000:7928K'

The main.go file contains a simple Go program that blinks the onboard LED. We’ll use it to test our development environment.

The go.env file contains the build options for Teensy 4.1. They also work for Teensy 4.0 but to be consistent with the true size of its Flash you should set -F option to 0x60002000:1976K.

Set the GOENV environment variable to the path of your go.env file.

Run the go mod init and go mod tidy commands to initialize your new “project”.

$ go mod init teensyApp
go: creating new go.mod: module teensyApp
go: to add module requirements and sums:
	go mod tidy
$ go mod tidy
go: downloading github.com/embeddedgo/imxrt v0.0.5
go: finding module for package github.com/embeddedgo/fs/termfs
go: found github.com/embeddedgo/fs/termfs in github.com/embeddedgo/fs v0.1.0

These two commands create the go.mod and go.sum files in our folder and install dependencies.

Now you can build yout first program.

$ go build

Go compiler is silent, so there is no any message if everything went well. You should find the result of compilation in the teensyApp.elf file.

Programming the board

Connect your Teensy board to your PC using a USB cable and press the onnboard button (Teensy should start blinking its red LED). Now you can load and run your program.

$ egtool load

The program should start blinking the yellow LED.

Getting started with the ESP-01S module

Once we have a ready and tested development environment, we can get to the point of this tutorial article.

Let’s connect the Wi-Fi module to the Teensy board, according to the table below.

Because of the limited power capabilities of the Teensy 3V pin (250 mA) and rather long connections the ESP-01S module requires a slight hardware modification.

The simplest way to meet the momentary power demand of ESP8266 is to store the energy in the properly sized decoupling capacitor. A 100 µF low-ESR electrolytic capacitor between GND and 3V3 should be just right.

Alternatively you can purchase a breadboard adapter that already includes a proper decoupling capacitor and assemble everything securely on the breadboard.

First program

The first program will display a list of the names (SSIDs) of nearby wireless networks.

package main

import (
	"fmt"
	"time"

	"github.com/embeddedgo/espat"
	"github.com/embeddedgo/imxrt/hal/lpuart"
	"github.com/embeddedgo/imxrt/hal/lpuart/lpuart2"

	"github.com/embeddedgo/imxrt/devboard/teensy4/board/pins"
)

func fatalErr(err error) {
	for err != nil {
		fmt.Println("error:", err.Error())
		time.Sleep(time.Second)
	}
}

func main() {
	// Initialize LPUART2 on pins 14 and 15.
	u := lpuart2.Driver()
	u.Setup(lpuart.Word8b, 115200)
	u.UsePin(pins.P14, lpuart.TXD)
	u.UsePin(pins.P15, lpuart.RXD)
	u.EnableRx(512)
	u.EnableTx()

	// Give the user time to connect to the USB console.
	time.Sleep(5 * time.Second)

	fmt.Print("Initializing Wi-Fi module... ")
	dev := espat.NewDevice("esp0", u, u)
	fatalErr(dev.Init(true))
	fmt.Println("OK")

	// Print the ESP-AT version information.
	s, err := dev.CmdStr("+GMR")
	fatalErr(err)
	fmt.Println(s)

	// Periodically print information about available Wi-Fi networks.
	for {
		fmt.Println("Nearby wireless networks:")
		s, err := dev.CmdStr("+CWLAP")
		fatalErr(err)
		fmt.Println(s)
		time.Sleep(5 * time.Second)
	}
}

The above code first issues the AT+GMR command to print on the USB console the information about the ESP-AT firmware. Then, it periodically issues the AT+CWLAP command to print information about the available WI-FI networks.

Let’s build it.

$ go build
main.go:7:2: missing go.sum entry for module providing package github.com/embeddedgo/espat (imported by teensyApp); to add:
	go get teensyApp
$ go get teensyApp
go: downloading github.com/embeddedgo/espat v0.2.3
$ go build

Now press the button on your Teensy to program it.

$ egtool load

If you quickly enough connect to the Teensy USB console, you should see the following output from this program:

$ picocom -q /dev/ttyACM0
Initializing Wi-Fi module... OK
AT version:2.2.0.0(s-b097cdf - ESP8266 - Jun 17 2021 12:58:29)
SDK version:v3.4-22-g967752e2
compile time(6800286):Jul 11 2021 11:09:32
Bin version:2.2.0(ESP8266_1MB)

Nearby wireless networks:
+CWLAP:(3,"IOT",-63,"76:4d:28:21:11:83",1,-1,-1,4,4,7,1)
+CWLAP:(3,"Home",-64,"74:4d:28:21:11:83",1,-1,-1,4,4,7,1)
+CWLAP:(3,"IOT",-78,"2e:c8:1b:11:22:bb",5,-1,-1,4,4,6,0)
+CWLAP:(3,"Home",-78,"2c:c8:1b:11:22:bb",5,-1,-1,4,4,6,0)

Nearby wireless networks:
+CWLAP:(3,"IOT",-65,"76:4d:28:21:11:83",1,-1,-1,4,4,7,1)
+CWLAP:(3,"Home",-67,"74:4d:28:21:11:83",1,-1,-1,4,4,7,1)
+CWLAP:(3,"IOT",-75,"2e:c8:1b:11:22:bb",5,-1,-1,4,4,6,0)
+CWLAP:(3,"Home",-82,"2c:c8:1b:11:22:bb",5,-1,-1,4,4,6,0)

As you can see, my Teensy sees two Wi-Fi networks provided by four access points.

USB console

If you connect a programmed Teensy board to your computer, it’s seen as a composite USB device that comprises two CDC-ACM (virtual Serial) devices (ports). The first one is used as the USB console, the second one can be used by your program in any way you want. This default USB configuration is performed when you import the devboard/teensy4/board/system package or any other package from the devboard/teensy4/board directory (in our case it’s the pins package).

If you want a custom USB configuration, you cannot import anything from devboard/teensy4/board. Instead, you have to recreate all the things you need from this directory in your application, especially the system package.

You can interact with the USB console using a terminal emulator program like PuTTY on Windows or picocom on Linux or Mac.

Connecting to the network

Our next program will ask for the network name (SSID) and password to connect to the Wi-Fi network.

package main

import (
	"fmt"
	"time"

	"github.com/embeddedgo/espat"
	"github.com/embeddedgo/imxrt/hal/lpuart"
	"github.com/embeddedgo/imxrt/hal/lpuart/lpuart2"

	"github.com/embeddedgo/imxrt/devboard/teensy4/board/pins"
)

func fatalErr(err error) {
	for err != nil {
		fmt.Println("error:", err.Error())
		time.Sleep(time.Second)
	}
}

func main() {
	u := lpuart2.Driver()
	u.Setup(lpuart.Word8b, 115200)
	u.UsePin(pins.P14, lpuart.TXD)
	u.UsePin(pins.P15, lpuart.RXD)
	u.EnableRx(512)
	u.EnableTx()

	time.Sleep(5 * time.Second)

	fmt.Print("Initializing ESP-AT module... ")
	dev := espat.NewDevice("esp0", u, u)
	fatalErr(dev.Init(true))
	fmt.Println("OK")

	var ssid, passwd string

	fmt.Print("SSID: ")
	fmt.Scanln(&ssid)
	fmt.Print("Password: ")
	fmt.Scanln(&passwd)

	_, err := dev.Cmd("+CWMODE=1") // Wi-Fi station
	fatalErr(err)
	_, err = dev.Cmd("+CWJAP=", ssid, passwd)
	fatalErr(err)

	// Priodically print the connection state.
	for {
		s, err := dev.CmdStr("+CWSTATE?")
		fatalErr(err)
		fmt.Print(s)
		time.Sleep(5 * time.Second)
	}
}

By default, if the connection is successfully established, the SSID and password will be permanently saved by our Wi-Fi module. It’ll try to connect to the network after reboot or reconnect in case of the connection loss.

Interaction with this program may look like this:

Initializing ESP-AT module... OK
SSID: Home
Password: abc123xyz
+CWSTATE:2,"Home"
+CWSTATE:2,"Home"
+CWSTATE:2,"Home"

As the Wi-Fi credentials were saved by the ESP-AT firmware, we won’t set them in the following examples.

TCP client

It took a while, but we finally got there. Let’s write a simple TCP client program.

package main

import (
	"fmt"
	"io"
	"net"
	"os"
	"time"

	"github.com/embeddedgo/espat"
	"github.com/embeddedgo/espat/espnet"
	"github.com/embeddedgo/imxrt/hal/lpuart"
	"github.com/embeddedgo/imxrt/hal/lpuart/lpuart2"

	"github.com/embeddedgo/imxrt/devboard/teensy4/board/pins"
)

func logErr(err error) bool {
	for err == nil {
		return false
	}
	fmt.Println("error:", err.Error())
	return true
}

func fatalErr(err error) {
	for logErr(err) {
		time.Sleep(time.Second)
	}
}

func main() {
	u := lpuart2.Driver()
	u.Setup(lpuart.Word8b, 115200)
	u.UsePin(pins.P14, lpuart.TXD)
	u.UsePin(pins.P15, lpuart.RXD)
	u.EnableRx(512)
	u.EnableTx()

	time.Sleep(5 * time.Second)

	fmt.Print("Initializing Wi-Fi module... ")
	dev := espat.NewDevice("esp0", u, u)
	fatalErr(dev.Init(true))
	fmt.Println("OK")

	fmt.Println("Waiting for an IP address...")
	for msg := range dev.Async() {
		fatalErr(msg.Err)
		fmt.Println(msg.Str)
		if msg.Str == "WIFI GOT IP" {
			break
		}
	}

	var conn net.Conn
	for {
		if conn != nil {
			conn.Close()
		}
		time.Sleep(2 * time.Second) // one request every two seconds
		var err error
		conn, err = espnet.DialDev(dev, "tcp", "httpbin.org:80")
		if logErr(err) {
			continue
		}
		fmt.Print("\nSending HTTP request... ")
		_, err = io.WriteString(
			conn,
			"GET /ip HTTP/1.0\r\nHost: httpbin.org\r\n\r\n",
		)
		if logErr(err) {
			continue
		}
		fmt.Print("OK\nReceiving response:\n\n")
		_, err = io.Copy(os.Stdout, conn)
		logErr(err)
	}
}

If we ignore the Wi-Fi initialization and the waiting for an IP address, the only difference from a typical code of TCP client is the use of the espnet.DialDev function instead of net.Dial.

The output may look like this:

Initializing ESP-AT module... OK
Waiting for an IP address...
WIFI CONNECTED
WIFI GOT IP

Sending HTTP request... OK
Receiving response:

HTTP/1.1 200 OK
Date: Sun, 31 Dec 2023 21:58:14 GMT
Content-Type: application/json
Content-Length: 33
Connection: close
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{
  "origin": "37.109.142.142"
}

HTTP server

Logically, the next example should be a simple TCP server. However, this article is getting too long, so we will go straight to the titular HTTP server. You can find the code of simple TCP echo server on Github.

package main

import (
	"fmt"
	"net/http"
	"strings"
	"time"

	"github.com/embeddedgo/espat"
	"github.com/embeddedgo/espat/espnet"
	"github.com/embeddedgo/imxrt/hal/lpuart"
	"github.com/embeddedgo/imxrt/hal/lpuart/lpuart2"

	"github.com/embeddedgo/imxrt/devboard/teensy4/board/pins"
)

func fatalErr(err error) {
	for err != nil {
		fmt.Println("error:", err.Error())
		time.Sleep(time.Second)
	}
}

func main() {
	u := lpuart2.Driver()
	u.Setup(lpuart.Word8b, 115200)
	u.UsePin(pins.P14, lpuart.TXD)
	u.UsePin(pins.P15, lpuart.RXD)
	u.EnableRx(512)
	u.EnableTx()

	time.Sleep(5 * time.Second)

	fmt.Print("Initializing Wi-Fi module... ")
	dev := espat.NewDevice("esp0", u, u)
	fatalErr(dev.Init(true))
	fmt.Println("OK")

	fmt.Println("Waiting for an IP address...")
	for msg := range dev.Async() {
		fatalErr(msg.Err)
		fmt.Println(msg.Str)
		if msg.Str == "WIFI GOT IP" {
			break
		}
	}

	// Print IP address.
	txt, err := dev.CmdStr("+CIPSTA?")
	fatalErr(err)
	fmt.Println(strings.ReplaceAll(txt, "+CIPSTA:", ""))

	ls, err := espnet.ListenDev(dev, "tcp", ":80")
	fatalErr(err)
	fmt.Println("Listen on:", ls.Addr())
	fatalErr(http.Serve(ls, http.HandlerFunc(handler)))
}

func handler(w http.ResponseWriter, r *http.Request) {
	fmt.Println(r.RemoteAddr, r.RequestURI)
	fmt.Fprintln(w, "Go HTTP server")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Method:    ", r.Method)
	fmt.Fprintln(w, "URL:       ", r.URL)
	fmt.Fprintln(w, "Proto:     ", r.Proto)
	fmt.Fprintln(w, "Host:      ", r.Host)
	fmt.Fprintln(w, "RemoteAddr:", r.RemoteAddr)
	fmt.Fprintln(w, "RequestURI:", r.RequestURI)
}

Similarly to the TCP client, the only difference from the typical Go program is the use of the espnet.ListenDev function instead of net.Listen.

If we run this program on Teensy it should print its IP address so we’ll know where to direct our web browser.

Initializing Wi-Fi module... OK
Waiting for an IP address...
WIFI CONNECTED
WIFI GOT IP
ip:"192.168.1.11"
gateway:"192.168.1.1"
netmask:"255.255.255.0"

Listen on: :80

If we enter the appropriate URL into our web browser (e.g. http://192.168.1.11/abc) then we should receive the response as below:

Go HTTP server

Method:     GET
URL:        /abc
Proto:      HTTP/1.1
Host:       192.168.1.11
RemoteAddr: 192.168.1.5:46674
RequestURI: /abc

and something like this on the USB console:

192.168.1.5:46674 /abc
192.168.1.5:46674 /favicon.ico

That’s all folks.

Happy New Year!

Michał Derkacz

Pix occupies the same niche as the Adafruit GFX library, ucglib or u8g2 but may also be used outside the microcontroller world. As it was created much later and written in Go it can be much simpler, concise and clean without sacrificing essential features. The main design principles were simplicity, portability and speed, hence the small number of graphics functions and the lack of features that require significant hardware support to make them work fast. See also the previous article about the library targeted more capable displays.

Pix provides only 9 drawing functions. Three basic ones:

func (a *Area) Draw(r image.Rectangle, src image.Image, sp image.Point, mask image.Image, mp image.Point, op draw.Op)
func (a *Area) Fill(r image.Rectangle)
func (a *Area) NewTextWriter(f font.Face) *TextWriter

and six implemented using the above Fill function:

func (a *Area) Point(x, y int)
func (a *Area) Line(p0, p1 image.Point)
func (a *Area) RoundRect(p0, p1 image.Point, ra, rb int, fill bool)
func (a *Area) Quad(p0, p1, p2, p3 image.Point, fill bool)
func (a *Area) FillQuad(p0, p1, p2, p3 image.Point)
func (a *Area) Arc(p image.Point, mina, minb, maxa, maxb int, th0, th1 int32, fill bool)

With some additional properties of the Area type this small set of drawing primitives allows you to easily present various kinds of data in many different ways and even create a simple user interface.

Basic functions

You can do surprisingly a lot with just three basic functions mentioned above. In fact, you may throw Fill out of this set reducing it to just two functions. Fill can be easily implemented using Draw so it’s not that basic. On the other hand Fill is simpler to use and often much more efficient than Draw so let’s let it stay in the basic set.

To show how it all works closer to practice let’s create an example view of a simple music player. To begin with, let’s see what can be done using just these three basic functions.

Display

Eventually everything we draw will go to the display so we need a display.

disp := pix.NewDisplay(driver)

But what’s a driver? Driver can by anything that implements the pix.Driver interface:

type Driver interface {
	Draw(r image.Rectangle, src image.Image, sp image.Point, mask image.Image, mp image.Point, op draw.Op)
	Fill(r image.Rectangle)
	SetColor(c color.Color)
	SetDir(dir int) image.Rectangle
	Flush()
	Err(clear bool) error
}

Most cheap display controllers provide just such an interface:

• writing to (and sometimes reading from) a specified rectangular area of the frame memory (Draw, Fill),

• some also let you set the display orientation (SetDir).

The remaining three methods are related to the internal operation of the driver.

However, we won’t be working with any real display for now. All we need is a driver that simulates the display in a file. Let’s write one. It’s easy.

type Driver struct {
	Name  string
	Image draw.Image
	fill  image.Uniform
	err   error
}

func (d *Driver) Draw(r image.Rectangle, src image.Image, sp image.Point, mask image.Image, mp image.Point, op draw.Op) {
	draw.DrawMask(d.Image, r, src, sp, mask, mp, op)
}

func (d *Driver) SetColor(c color.Color) {
	r, g, b, a := c.RGBA()
	d.fill.C = color.RGBA64{uint16(r), uint16(g), uint16(b), uint16(a)}
}

func (d *Driver) Fill(r image.Rectangle) {
	d.Draw(r, &d.fill, image.Point{}, nil, image.Point{}, draw.Over)
}

func (d *Driver) SetDir(dir int) image.Rectangle {
	return d.Image.Bounds()
}

func (d *Driver) Flush() {
	if d.err != nil {
		return
	}
	f, err := os.Create(d.Name)
	if err != nil {
		d.err = err
		return
	}
	d.err = jpeg.Encode(f, d.Image, &jpeg.Options{90})
	f.Close()
}

func (d *Driver) Err(clear bool) error {
	err := d.err
	if clear {
		d.err = nil
	}
	return err
}

The driver is ready. A few details, however, require clarification.

Driver is almost simplest possible implementation of pix.Driver. As you can see everything is drawn using the standard draw.DrawMask function.

• Image serves as a temporary framebuffer.

• Name is the name of the file where the Flush method will save the content of the temporary framebuffer. This file can be thought of as a target framebuffer whose content is visible to the user.

• Draw is just a straightforward wrapper over draw.DrawMask.

• SetColor sets the color of the uniform image used by Fill.

• Fill simply draws filled rectangles using the Draw method. There is no any optimization here. Well, maybe avoiding allocating new image.Uniform every call is some sort of optimization.

• SetDir is intended for display rotations but it’s fine for the driver to completely ignore the changes of display direction and always return the same bounds. By the way, SetDir is called first before any other Driver method so can be used for (lazy) initialization.

• Flush allows the driver to have internal buffers. In our case the buffer stores the entire display screen before save it to the file but in other cases it can be much smaller or nonexistent.

• Err is for signaling errors. For performance reasons there is no any internal error checking in pix. The driver is responsible to check errors as necessary and record the occurrence of the first error. It should avoid any actions that may cause further errors until the recorded error is cleared. The user can check for an error at his convenience using the Area.Err or Display.Err functions.

For the sake of convenience w can also define a display constructor:

func NewDisplay(name string, width, height int) *pix.Display {
	driver := &Driver{
		Name:  name,
		Image: image.NewRGBA(image.Rect(0, 0, width, height)),
	}
	return pix.NewDisplay(driver)
}

It returns image.RGBA backed display with given dimensions, associated with the file with the given name.

Area.Draw

Let’s finally draw something.

func playerView(disp *pix.Display, artist, title string, cover image.Image) {
	a := disp.NewArea(disp.Bounds())
	a.Draw(a.Bounds(), cover, cover.Bounds().Min, nil, image.Point{}, draw.Src)
	disp.Flush()
}

func main() {
	disp := NewDisplay("/tmp/player.jpg", 640, 320)

	artist := "Gophers"
	title := "Work Hard Play Hard"
	cover := loadImage("testdata/gopherbug.jpg")
	playerView(disp, artist, title, cover)

	checkErr(disp.Err(true))
}

This isn’t exactly what we wanted but we’ll fix it in a moment.

The playerView function creates a new drawing area that covers the whole display screen. Next, it uses the Area.Draw function to draw the cover image in the selected area of the display.

Area.Draw works like draw.DrawMask with dst set to the whole drawing area. But what’s an Area?

Area gives you access to the rectangular portion of the display screen. One area, without additional synchronization, can be used by only one goroutine, but multiple goroutines can share a single display using multiple areas. Moreover, one area can span multiple displays.

Area isn’t a window as you’re used to in case of Windows or X11. Everything is drawn directly on the display and Area only limits the drawing area. Areas may overlap but their intersection will be affected by all of them.

loadImage is a helper function that loads an image from a file:

func loadImage(name string) image.Image {
	f, err := os.Open(name)
	checkErr(err)
	defer f.Close()
	img, _, err := image.Decode(f)
	checkErr(err)
	return img
}

Area.Fill

Let’s organize our screen a little bit. The space for the cover image will be on the left, centered vertically.

var bgColor = color.Gray{50}

func playerView(disp *pix.Display, artist, title string, cover image.Image) {
	r := disp.Bounds()
	a := disp.NewArea(r)
	a.SetColor(bgColor)
	a.Fill(a.Bounds())
	r.Max.X = r.Min.X + r.Dy()
	const margin = 20
	a.SetRect(r.Inset(margin))
	a.SetColorRGBA(0, 0, 200, 255)
	a.Fill(a.Bounds())
	disp.Flush()
}

In the above code the a area initially covers the whole display. a.SetColor(bgColor) sets the color for the subsequent a.Fill(a.Bounds()) that fills the whole screen with it.

Next we do some calculations with r to reduce it to the square filling the left side of the screen. a.SetRect(r.Inset(margin)) reshapes our drawing area to be on the center of r with 20 point margins. Finally we fill the area with blue color to see if everything went as planned.

Let’s draw the cover image in the center of this area.

func playerView(disp *pix.Display, artist, title string, cover image.Image) {
	r := disp.Bounds()
	a := disp.NewArea(r)
	a.SetColor(bgColor)
	a.Fill(a.Bounds())
	r.Max.X = r.Min.X + r.Dy()
	const margin = 20
	a.SetRect(r.Inset(margin))
	sr := cover.Bounds()
	r = a.Bounds()
	r.Min = r.Size().Sub(sr.Size()).Div(2)
	a.Draw(r, cover, sr.Min, nil, image.Point{}, draw.Src)
	disp.Flush()
}

The magic r.Size().Sub(sr.Size()).Div(2) expression calculates the position for the top left corner of the cover image to place it in the center of the area. We use the “simplified” expression instead of r.Min.Add(r.Size().Sub(sr.Size()).Div(2)) because by default the area’s top left corner called origin is (0, 0).

Area has its own internal coordinate system independent of the other areas and the displays it covers. You can change the origin using the SetOrigin(p image.Point) method but usually you don’t want to do that because (0, 0) is nice and convenient.

Let’s see what happens when we double the size of the image.

cover = images.Magnify(cover, 2, 2, images.Bilinear)

Everything’s all right. It was supposed to be like that. The area has cropped the magnified image so we see only its central part.

TextWriter

Text is still the main way to communicate and present data. Sometimes the whole graphics library is used just to print text on a small monochrome OLED display, currently the cheapest way to display multilingual text messages.

Although drawing text in pix is really drawing multiple images on the same baseline, TextWriter is listed as one of the three main drawing primitives. This is because drawing text is a much broader concept than just drawing images. See the definition of TextWriter below:

type TextWriter struct {
	Area   *Area       // drawing area
	Face   font.Face   // source of glyphs
	Color  image.Image // glyph color (foreground image)
	Pos    image.Point // position of the next glyph
	Offset image.Point // offset from the Pos to the glyph origin
	Wrap   byte        // wrapping mode
	Break  byte        // line breaking mode
}

TextWriter combines drawing images with things like font, font face, drawing direction, wrapping mode and line breaking mode. Rendering text is a very broad topic and we don’t want to go over all these details here.

TextWriter uses the font.Face interface to convert individual unicode code points (runes) to their graphical representation (glyphs).

type Face interface {
	Size() (height, ascent int)
	Advance(r rune) int
	Glyph(r rune) (img image.Image, origin image.Point, advance int)
}

This simple approach turns out to be quite flexible and gives satisfactory results in most pix applications.

Glyphs are drawn side by side, always horizontally, from left to right. This doesn’t mean that you cannot draw lines of text in other directions but TextWriter alone cannot. You have to use the Area.SetMirror method to trick it.

Let’s print the name of the author and the song title on the right-hand side of the cover image.

The code of playerView function is getting long so from now I’ll only show the changes in this function with one line context.

a.Draw(r, cover, sr.Min, nil, image.Point{}, draw.Src)
// new code begin
r = disp.Bounds()
r.Min.X += r.Dy()
a.SetRect(r.Inset(margin))
w := a.NewTextWriter(titleFont)
w.SetColor(textColor)
w.WriteString(artist + " -- " + title)
// new code end
disp.Flush()

Hmm, the default line breaking mode doesn’t look very good for our use case. Let’s change it.

w := a.NewTextWriter(titleFont)
// new code begin
w.Break = pix.BreakSpace
// new code end
w.SetColor(textColor)

Much better.

I still have to explain where did titleFont come from. titleFont represents a font face, the specific size, style and weight of a font. In our case it’s the 18 point regular Dejavu Sans font. The necessary fonts can be loaded at run time from external source or included at compile time this way:

import "github.com/embeddedgo/display/font/subfont/font9/dejavusans18"

var titleFont = dejavusans18.NewFace(
	dejavusans18.X0020_007e, //  !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJ
	dejavusans18.X0101_0201, // āĂ㥹ĆćĈĉĊċČčĎďĐđĒēĔĕĖėĘęĚěĜĝĞğĠġĢģĤĥĦħĨĩĪī
)

Embedding fonts into program code is a common practice in case of embedded systems. Such systems often have no external storage and a limited size of program memory. Fonts can be a large part of program image hence the concept of subfont taken straight from Plan 9. It allows you to select only the necessary components of the font. In our case, we included two 18 point subfonts for unicode code points from 0x020 to 0x201.

The above declaration using the NewFace function is a more convenient counterpart to the declaration below:

var titleFont =  &subfont.Face{
	Height: dejavusans18.Height,
	Ascent: dejavusans18.Ascent,
	Subfonts: []*subfont.Subfont{
		dejavusans18.X0020_007e,
		dejavusans18.X0101_0201,
	},
}

The subfont.Face type implements the font.Face interface. As you can see it’s defined by its height, ascent (height above the baseline) and the list of subfonts. Missing subfonts can be loaded at runtime if the (not shown) Loader field is set.

Much more could be written about fonts, subfonts, their storage, loading and rendering, but let’s go back to our music player example.

What will happen if the author/title text will be much longer? With the current size of the title area it can take up the entire half of the screen. Let’s reduce the height of the area to only two lines of text, and at the same time, let’s halve the spacing between the cover and title areas because currently it has a width of two margins.

a.Draw(r, cover, sr.Min, nil, image.Point{}, draw.Src)
// new code begin
height, _ := titleFont.Size()
r = disp.Bounds()
r.Min.X += r.Dy()
r.Max.X -= margin
r.Min.Y += margin
r.Max.Y = r.Min.Y + 2*height
a.SetRect(r)
a.SetColorRGBA(0, 0, 200, 255)
a.Fill(a.Bounds()) // temporary, to see the area
// new code end
w := a.NewTextWriter(titleFont)

Now the layout looks fine.

One might want to center the text in the area but TextWriter won’t help us with that. Centering or right-justify operations are well defined only for the complete line of text. TextWriter is intended to be used as io.Writer or io.StringWriter so it’s inherently stream oriented, not line oriented. In this light even the BreakSpace mode fills somewhat stretched feature. Long story short, if you want to center the text you have to do it yourself and then StringWidth and Width functions will be helpful to you.

In addition to the author and the title of the song our player will also show the song duration and the current play time. The current time may be updated in real time by another (playing) goroutine. We can give it an area to work with and the goroutine may use the function below to periodically update the information.

func drawTimeDuration(a *pix.Area, t, duration int) {
	h, m, s := hms(t)
	str := fmt.Sprintf("%02d:%02d:%02d /", h, m, s)
	width := pix.StringWidth(str, titleFont)
	height, _ := titleFont.Size()
	a.SetColor(bgColor)
	r := a.Bounds()
	a.Fill(r)
	w := a.NewTextWriter(titleFont)
	w.SetColor(textColor)
	w.Pos.X = r.Min.X + r.Dx()/2 - width
	w.Pos.Y = r.Min.Y + (r.Dy()-height)/2
	w.WriteString(str)
	h, m, s = hms(duration)
	fmt.Fprintf(w, " %02d:%02d:%02d", h, m, s)
	a.Flush()
}

a.Flush() at the end of this function calls flush methods of all displays the area covers. Although Display.Flush is safe for concurrent use it can cause side effects in special cases like double buffering. There is no one-size-fits-all flush approach in case of full-frame buffering with multiple drawing goroutines. The “flush strategy” must be tailored to each specific case.

w.WriteString(artist + " -- " + title)
// new code begin
r = disp.Bounds()
r.Min.X += r.Dy()
r.Max.X -= margin
r.Min.Y = (r.Min.Y+r.Max.Y)/2 - 10
r.Max.Y = r.Min.Y + 20
drawTimeDuration(disp.NewArea(r), 58, 3*60+17)
// new code end
disp.Flush()

Buttons

Even though pix doesn’t provide any Button function (after all, it’s not a GUI library) we definitely want some control buttons in our music player. The simplest possible button can be drawn using the function below:

func button(w *pix.TextWriter, r image.Rectangle, caption string) {
	w.Area.Fill(r)
	width := pix.StringWidth(caption, buttonFont)
	height, _ := buttonFont.Size()
	w.Pos.X = r.Min.X + (r.Dx()-width)/2
	w.Pos.Y = r.Min.Y + (r.Dy()-height)/2
	w.WriteString(caption)
}

As in the case of printing play time the control buttons will likely be handled by a separate goroutine. Our program isn’t a real music player so the function below only draws buttons in the provided area.

func drawControls(a *pix.Area) {
	a.SetColor(ctrlColor)
	w := a.NewTextWriter(buttonFont)
	w.SetColor(captionColor)
	r := a.Bounds()
	width := r.Dx() / 3
	r.Max.X = r.Min.X + width - 2
	button(w, r, "Rewind")
	r.Min.X = r.Max.X + 2
	r.Max.X = r.Min.X + width - 2
	button(w, r, "Play/Pause")
	r.Min.X = r.Max.X + 2
	r.Max.X = r.Min.X + width
	button(w, r, "FastForward")
	a.Flush()
}

Let’s draw the buttons at the bottom right of our view.

drawTimeDuration(disp.NewArea(r), 58, 3*60+17)
// new code begin
r = disp.Bounds()
r.Min.X += r.Dy()
r.Max.X -= margin
r.Max.Y -= margin
r.Min.Y = r.Max.Y - 30
drawControls(disp.NewArea(r))
// new code end
disp.Flush()

We can finally see our music player in all its glory.

Other drawing functions

As you can see, it’s possible to create a pretty decent looking user interface by using only three basic drawing primitives. But pix give us six more ones. Let’s take a look at each of them.

Area.Point

Point is like Go i++. It’s redundant but convenient. You can always replace Point(x, y) with Fill(image.Rect(x, y, x+1, y+1)) but in applications where Point is useful, using Fill doesn’t look very legible.

Area.Line

Line simply draws a straight line connecting two points.

Area.RoundRect

RoundRect is a swiss army knife function. It can draw rectangles, circles and ellipses or a combination of them, either filled or unfilled. Drawing performance is almost the same as with multiple specialized functions.

We can use RoundRect to round the corners of the buttons in our example.

func button(w *pix.TextWriter, r image.Rectangle, caption string) {
	r = r.Inset(7)
	r.Max.X--
	r.Max.Y--
	w.Area.RoundRect(r.Min, r.Max, 7, 7, true)
	width := pix.StringWidth(caption, buttonFont)
	height, _ := buttonFont.Size()
	w.Pos.X = r.Min.X + (r.Dx()-width)/2
	w.Pos.Y = r.Min.Y + (r.Dy()-height)/2
	w.WriteString(caption)
}

Area.Quad

Quad draws a convex quadrilateral or a triangle described by the given vertices, either filled or unfilled. It draws a triangle if two adjacent vertices are identical.

Drawing a quadrilateral is almost as fast as drawing a triangle and much faster than drawing a quadrilateral using two triangles. The quadrilaterals are also more versatile and in many cases more convenient to use than triangles.

Let’s modify the buttons even more and replace the text with graphic symbols.

func gbutton(a *pix.Area, r image.Rectangle, caption [][4]image.Point) {
	r = r.Inset(7)
	r.Max.X--
	r.Max.Y--
	a.SetColor(ctrlColor)
	a.RoundRect(r.Min, r.Max, 7, 7, true)
	p := r.Min.Add(r.Max).Div(2)
	a.SetColor(captionColor)
	for _, q := range caption {
		a.Quad(q[0].Add(p), q[1].Add(p), q[2].Add(p), q[3].Add(p), true)
	}
}

var rewind = [][4]image.Point{
	{{15, -7}, {15, -7}, {1, 0}, {15, 7}},
	{{-5, -7}, {-5, -7}, {-19, 0}, {-5, 7}},
}
var playPause = [][4]image.Point{
	{{-15, -7}, {-15, -7}, {-1, 0}, {-15, 7}},
	{{6, -7}, {9, -7}, {9, 7}, {6, 7}},
	{{14, -7}, {17, -7}, {17, 7}, {14, 7}},
}
var fastForward = [][4]image.Point{
	{{-15, -7}, {-15, -7}, {-1, 0}, {-15, 7}},
	{{5, -7}, {5, -7}, {19, 0}, {5, 7}},
}

func drawControls(a *pix.Area) {
	r := a.Bounds()
	width := r.Dx() / 3
	r.Max.X = r.Min.X + width - 3
	gbutton(a, r, rewind)
	r.Min.X = r.Max.X + 3
	r.Max.X = r.Min.X + width - 3
	gbutton(a, r, playPause)
	r.Min.X = r.Max.X + 3
	r.Max.X = r.Min.X + width
	gbutton(a, r, fastForward)
	a.Flush()
}

The buttons drawn in this way don’t look the best mainly because of the flat appearance and lack of anti-aliasing. Image based buttons would look much better.

Area.FillQuad

FillQuad draws a filled convex quadrilateral or triangle. The difference to Quad is that FillQuad obeys the filling rules so it can be used to draw filled polygons composed of adjacent quadrilaterals and triangles, ensuring that the common edges are drawn once. In this regard, it’s somehow similar to the Fill function which fills a rectangle defined as inclusive at the top-left and exclusive at the bottom-right.

Area.Arc

Arc is the last function left to describe. It’s most complex one but very useful to present data.

The most obvious use case is a Pie Chart. Let’s create one for 15%, 25%, 60% data.

disp := newDisplay(640, 320)
a := disp.NewArea(disp.Bounds())
p := a.Bounds().Max.Div(2)

var alpha int64

alpha = math2d.FullAngle * 15 / 100 // angle corresponding to 15%
th0 := -math2d.RightAngle / 3       // start angle of the first piece (any)
th1 := th0 + int32(alpha)           // end angle of the first piece
a.SetColorRGBA(200, 0, 0, 200)
a.Arc(p, 0, 0, 150, 150, th0, th1, true)

alpha = math2d.FullAngle * 25 / 100 // angle corresponding to 25%
th0 = th1                           // start angle of the second piece
th1 = th0 + int32(alpha)            // end angle of the second piece
a.SetColorRGBA(0, 200, 0, 200)
a.Arc(p, 0, 0, 150, 150, th0, th1, true)

alpha = math2d.FullAngle * 60 / 100 // angle corresponding to 60%
th0 = th1
th1 = th0 + int32(alpha)
a.SetColorRGBA(0, 0, 200, 200)
a.Arc(p, 0, 0, 150, 150, th0, th1, true)

Arc draws an arc starting at angle th0 and ending at, but not including, th1. Such one-side inclusiveness ensures that the adjacent edges of our pie chart are drawn once. The colors with alpha=200 allow us to confirm this easily.

In pix and math2d packages the angles are of type int32 which can represent angles from -FullAngle/2 to FullAngle/2 - 1 (inclusive). The angle unit is equal to 1/4294967296 of the full angle.

Two well known angles are declared in math2d this way:

const (
	FullAngle        = 1 << 32       // 2π rad = 360°
	RightAngle int32 = FullAngle / 4 // π/2 rad = 90°
)

As you can see, FullAngle and even FullAngle/2 doesn’t fit in int32. As the full range of int32 is used to represent angles from -180° to 180° the calculations on angles aren’t obvious:

theta := math2d.RightAngle
fmt.Println(theta * 4) // prints 0

The compiler will warn you on problematic constant angles but the correctness of the calculations on the angle variables is up to you. For example, computing the mean of two angles (th0 + th1) / 2 may give unexpected result. If you don’t feel confident you can use int64 for calculations which may help a bit.

Let’s go back to our examples. Sometimes slightly spaced pieces of a pie chart look better. We can move them around 10 points from the center by replacing

a.Arc(p, 0, 0, 150, 150, th0, th1, true)

with the code below

o0 := image.Pt(10, 0)
o := math2d.Rotate(o0, th0+int32(alpha/2))
a.Arc(p.Add(o), 0, 0, 150, 150, th0, th1, true)

By replacing

a.Arc(p.Add(o), 0, 0, 150, 150, th0, th1, true)

with

a.Arc(p.Add(o), 80, 60, 200, 150, th0, th1, true)

we get an interesting looking elliptical pie chart with the center part cut out.

Let’s make the last change to our music player example. Let’s use the Arc function to present the current playback position graphically.

func printTime(w *pix.TextWriter, t int) {
	h, m, s := hms(t)
	str := fmt.Sprintf("%02d:%02d:%02d", h, m, s)
	width := pix.StringWidth(str, titleFont)
	w.Pos.X -= width / 2
	w.WriteString(str)
}

func drawTimeDuration(a *pix.Area, t, duration int) {
	r := a.Bounds()
	a.SetColor(bgColor)
	a.Fill(r)

	p := r.Min.Add(r.Max).Div(2)
	rmax := min(r.Dx(), r.Dy()) / 2
	rmin := rmax - 20
	th0 := math2d.RightAngle + math2d.RightAngle/3
	th1 := math2d.RightAngle - math2d.RightAngle/3
	a.SetColor(ctrlColor)
	a.Arc(p, rmin, rmin, rmax, rmax, th0, th1, false)
	if t > 0 {
		alpha := int64(math2d.FullAngle*5/6) * int64(t) / int64(duration)
		a.Arc(p, rmin, rmin, rmax, rmax, th0, th0+int32(alpha), true)
	}

	w := a.NewTextWriter(titleFont)
	w.SetColor(textColor)
	height, _ := titleFont.Size()

	w.Pos.X = p.X
	w.Pos.Y = p.Y/2 - height/2
	printTime(w, t)

	w.Pos.X = p.X
	w.Pos.Y += p.Y
	printTime(w, duration)

	// play button
	p0 := image.Pt(-14, -14).Add(p)
	p1 := image.Pt(14, 0).Add(p)
	p2 := image.Pt(-14, 14).Add(p)
	a.Quad(p0, p0, p1, p2, true)

	a.Flush()
}

The playerView function also requires some changes:

w.WriteString(artist + " -- " + title)
// new code begin
r.Min.Y = r.Max.Y + margin/2
r.Max.Y = disp.Bounds().Max.Y - margin/2
drawTimeDuration(disp.NewArea(r), 58, 3*60+17)
// new code end
disp.Flush()

We’ve reduced the number of buttons to just one. The function of the FastForward and Rewind buttons can be replaced by the playback position indicator.

This is where we end the first part of the article about the pix library. In the second part, we’ll get our hands dirty with some real hardware.

Michał Derkacz

You can port the Go runtime to a system that doesn’t implement threads. An example would be the current WebAssembly port.

func newosproc(mp *m) {
	panic("newosproc: not implemented")
}

But if you want to run a bare metal Go program on multiple cores the thread abstraction is a must, unless you are ready to implement a completely new goroutine scheduler.

The goroutine scheduler uses operating system threads as workhorses to execute its goroutines. The goal is to efficiently run thousands of goroutines using only a few OS threads. Threads are considered expensive. There is also much cheaper to access shared resources by multiple goroutines that run on the same thread. This is further optimized in Go by introducing the concept of a logical processor (called P) that can “execute” only one thread at a time and has local cache of the most commonly used resources. There can be unlimited number of threads sleeping in the system calls but they aren’t assigned to any P.

You can set a number of logical processors using GOMAXPROCS environment variable or runtime.GOMAXPROCS function. The default GOMAXPROCS for Kendryte K210 is 2.

Tasker

The Embedded Go implements a thread scheduler for GOOS=noos called tasker. Tasker was designed from the very beginning as a multi-core scheduler but the first multicore tests and bug fixes were done on K210 while working on noos/riscv64 port.

Tasker is tightly coupled to the goroutine scheduler. It doesn’t have it’s own representation of thread. Instead it directly uses the m structs. The Go logical processor concept is taken seriously. Any available P is associated with a specific CPU using the following simple formula:

cpuid = P.id % len(allcpus)

CPU is the name used by the tasker for any independent hardware thread of execution, a hart in the RISC-V nomenclature.

The tasker threads are cheap.

Print hartid

Let’s start playing with Go schedulers and two cores available in K210. The basic tool we need is a function that returns the current hart id which in case of K210 means the core id.

package main

import _ "github.com/embeddedgo/kendryte/devboard/maixbit/board/init"

func hartid() int

func main() {
	for {
		print(hartid())
	}
}

As you can see the hartid function has no body. To define it we have to reach for Go assembly.

#include "textflag.h"

#define CSRR(CSR,RD) WORD $(0x2073 + RD<<7 + CSR<<20)
#define mhartid 0xF14
#define s0 8

// func hartid() int
TEXT ·hartid(SB),NOSPLIT|NOFRAME,$0
	CSRR  (mhartid, s0)
	MOV   S0, ret+0(FP)
	RET

The Go assembler doesn’t recognize privileged instructions so we used macros to implement the CSRR instruction.

Let’s use GDB+OpenOCD to load and run the compiled program. I recommend using the modified version of the openocd-kendryte. You can use the debug-oocd.sh helper script as shown in the maixbit example. GDB isn’t required to follow this article. You can use kflash utility instead as described in the previous article.

Core [0] halted at 0x8000bb4c due to debug interrupt
Core [1] halted at 0x800093ea due to debug interrupt
(gdb) load
Loading section .text, size 0x62230 lma 0x80000000
Loading section .rodata, size 0x2c80f lma 0x80062240
Loading section .typelink, size 0x658 lma 0x8008ec20
Loading section .itablink, size 0x18 lma 0x8008f278
Loading section .gopclntab, size 0x3df15 lma 0x8008f2a0
Loading section .go.buildinfo, size 0x20 lma 0x800cd1b8
Loading section .noptrdata, size 0xf00 lma 0x800cd1d8
Loading section .data, size 0x3f0 lma 0x800ce0d8
Start address 0x80000000, load size 844500
Transfer rate: 64 KB/sec, 14313 bytes/write.
(gdb) c
Continuing.

Program received signal SIGTRAP, Trace/breakpoint trap.
runtime.defaultHandler ()
    at /home/michal/embeddedgo/go/src/runtime/tasker_noos_riscv64.s:388
(gdb)

As you can see our program has been stopped in runtime.defaultHandler. This function handles unsupported traps (there are still a lot of them). Let’s see what happened.

(gdb) p $a0/8
$1 = 2

The A0 register contains a value of the mcause CSR saved at the trap entry (multiplied by 8). We can’t rely on the current mcause value because the interrupts are enabled. Bu we can check if it’s the same.

(gdb) p $mcause
$2 = 2

It seems there was no other traps in the meantime. The mcause CSR contains a code indicating the event that caused the trap. In our case it’s Illegal instruction exception. Let’s see what this illegal instruction is. The mepc register (return address from trap) was saved on the stack.

(gdb) x $sp+24
0x800d4820:     0x80062221

As before we can check does it’s the same as the current one.

(gdb) p/x $mepc
$2 = 0x80062220

Almost the same (LSBit is used to store fromThread flag).

(gdb) list *0x80062220
0x80062220 is in main.hartid (/home/michal/embeddedgo/kendryte/devboard/maixbit/examples/multicore/asm.s:9).
4       #define mhartid 0xF14
5       #define s0 8
6
7       // func hartid() int
8       TEXT ·hartid(SB),NOSPLIT|NOFRAME,$0
9               CSRR  (mhartid, s0)
10              MOV   S0, ret+0(FP)
11              RET
12
13      // func  loop(n int)

All clear. Our program runs in the RISC-V user mode. We have no access to the machine mode CSRs. But there is a way to tackle this problem.

func main() {
	runtime.LockOSThread()
	rtos.SetPrivLevel(0)
	for {
		print(hartid())
	}
}

The rtos.SetPrivLevel function can be used to change the privilege level for the current thread . As it affects the current thread only we must call runtime.LockOSThread first to wire our goroutine to its current thread (no other goroutine will execute in this thread). Now we can run our program.

As you can see our printing thread is locked to hart 0.

Multiple threads

Let’s modify the previous code in a way that allows us to easily alter the number of threads.

package main

import (
	"embedded/rtos"
	"runtime"

	_ "github.com/embeddedgo/kendryte/devboard/maixbit/board/init"
)

type report struct {
	tid, hartid int
}

var ch = make(chan report, 3)

func thread(tid int) {
	runtime.LockOSThread()
	rtos.SetPrivLevel(0)
	for {
		ch <- report{tid, hartid()}
	}
}

func main() {
	var lasthart [2]int
	for i := range lasthart {
		go thread(i)
	}
	runtime.LockOSThread()
	rtos.SetPrivLevel(0)
	for r := range ch {
		lasthart[r.tid] = r.hartid
		print(" ", hartid())
		for _, hid := range lasthart {
			print(" ", hid)
		}
		println()
	}
}

func hartid() int

Now the main function launches len(lasthart) goroutines and after that prints in a loop the hartid for itself and all other goroutines. Every launched goroutine periodically checks its hartid and sends report to the main goroutine.

Let’s start with main + 2 goroutines.

You can see we have a stable state: the main goroutine runs on hart 1, the reporting goroutines run on hart 0. Let’s add more goroutines.

The beginning looks interesting:

 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 1 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 1 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 1 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 1 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 1 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 1 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 1 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 1 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 1 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 1 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1

It seems that almost all reporting goroutines start on hart 0 but after a while they migrate to hart 1 and stay there. Edit. It doesn’t have to be true because the lasthart array is zero initialized. It should be initialized to something other value, eg: -1.

Remember the goroutine scheduler can’t run more than 2 goroutines at the same time. Our reporting goroutines don’t do much. They spend most of their time sleeping on the full channel. It seems reasonable to gather them all on one P and give the other P for busy main thread.

Let’s increase the number of logical processors by adding runtime.GOMAXPROCS(4) at the beginning of the main function.

It seems the goroutine scheduler cannot reach a stable state. But we can see the hart id only. Can we see also the logical processor id? Yes, we can. Let’s modify the hartid function to return both.

// func hartid() int
TEXT ·hartid(SB),NOSPLIT|NOFRAME,$0
	CSRR  (mhartid, s0)
	MOV   48(g), A0    // g.m
	MOV   160(A0), A0  // m.p
	MOVW  (A0), S1     // p.id
	SLL   $8, S1
	OR    S1, S0
	MOV   S0, ret+0(FP)
	RET

The print(" ", hartid()) call has been changed to print(" ", hid>>8, hid&0xFF) to show both numbers next to each other.

As you can see the goroutine scheduler keeps the main goroutine on P=0,1 and reporting goroutines on P=2,3. Our simple rule that maps Ps to CPUs causes threads to jumping between K210 cores.

Ending this article let’s get back to two Ps but let’s give our reporting goroutines something to do. As we’ve already got some practice with Go assembly we will use it to write simple busy loop. Thanks to this we’ll be sure the compiler won’t optimize this code.

// func loop(n int)
TEXT ·loop(SB),NOSPLIT|NOFRAME,$0
	MOV  n+0(FP), S0
	BEQ  ZERO, S0, end
	ADD  $-1, S0
	BNE  ZERO, S0, -1(PC)
end:
	RET

You can find the full code for this last case on github. You can play with other things, like the channel length, the loop count, odd GOMAXPROCS values, etc.

Workload disturbs the stable state from the second example. We can observe quite long periods when all goroutines run on the same logical processor which may be disturbing. Edit: It doesn’t have to be true. We print the whole line after each report received so it takes some lines to print a global change which affects many/all goroutines.

Summary

It’s hard to draw any deeper conclusions from these superficial tests. It wasn’t the purpose of this article. We had some fun with Go, RISC-V assembler, debugger and underlying hardware which is what you can expect from bare-metal programming. It seems the goroutine scheduler and tasker both work in harmony with each other. A more strict approach is needed to draw more definitive conclusions that can be used to improve one or the other.

Michał Derkacz

For a couple of weeks I’ve worked on adding support for bare metal RISC-V programming to Go. As the noos/riscv64 port reached the usable level I’ve decided to write something about it.

Until now, the Embedded Go have supported only ARM microcontrollers. I wanted to add another architecture as soon as possible to revise the design choices. From very beggining I’ve considered to add support for the very popular WiFi capable ESP32 microcontroller and even finished studying the Xtensa LX6 ISA but in the meantime two things happened:

• the support for linux/riscv64 landed in Go compiler,

• the Siped Maix Bit landed in my hands:

As I’ve already ported Go to a new architecture (ARMv7-M Thumb2 ISA) I know how much work it costs. The ready to use RISC-V port and the access to the real hardware left no choice.

Kendryte K210

If you want to play with real RISC-V hardware you don’t have much choice today. I’m aware of three sources:

• SiFive, the RISC-V pioneer with they rather expensive development boards,

• GigaDevice, they provide very cheap RISC-V based GD32V microcontrollers (development boards are provided by SeedStudio, Sipeed and others),

• and finally Kendryte (Canaan) with their K210 chip and development boards/modules provided by Sipeed.

You can buy the Maix Bit board as seen above for about $13 or the whole kit with camera and LCD for about $21.

The heart of the Maix Bit is K210, an AI capable SOC from Kendryte. It’s equipped with two RV64G cores and over a dozen peripherals of which the convolutional neural network accelerator (KPU) deserves special attention.

The good news is the 8 MB of integrated SRAM divided into 6 MB general purpose memory (plenty of space for most Go programs) and 2 MB dedicated to KPU. There is no integrated Flash. The program is loaded from external SPI Flash and runs from RAM.

Getting started with Maix Bit

The Maix Bit comes with the preinstaled MicroPython port called MaixPy. A good starting point will be to blink an onboard LED using MaixPy and next do the same with Go.

Let’s connect the board to the PC and paste the following code to MaixPy.

from time import sleep
from Maix import GPIO

fm.register(board_info.LED_B, fm.fpioa.GPIO0)
led = GPIO(GPIO.GPIO0, GPIO.OUT)

while True:
	led.value(0)
	sleep(1)
	led.value(1)
	sleep(1)

As you can see the board_info assigns wrong pin to the blue LED but otherwise the code is working as expected.

Let’s write a similar program in Go.

package main

import (
	"time"
	"github.com/embeddedgo/kendryte/devboard/maixbit/board/leds"
)

func main() {
	led := leds.Blue
	for {
		led.SetOn()
		time.Sleep(time.Second)
		led.SetOff()
		time.Sleep(time.Second)
	}
}

Save it in maix_blinky directory as main.go file and try to compile.

$ cd maix_blinky
$ go mod init maix_blinky
$
$ GOOS=noos GOARCH=riscv64 go build -tags k210 -ldflags '-M 0x80000000:6M'
go: finding module for package github.com/embeddedgo/kendryte/devboard/maixbit/board/leds
go: downloading github.com/embeddedgo/kendryte v0.0.1
go: found github.com/embeddedgo/kendryte/devboard/maixbit/board/leds in github.com/embeddedgo/kendryte v0.0.1
$
$ ls -l
total 1188
-rw-r--r-- 1 michal michal      75 May 31 11:49 go.mod
-rw-r--r-- 1 michal michal     179 May 31 11:49 go.sum
-rw-r--r-- 1 michal michal     222 May 31 11:46 main.go
-rwxr-xr-x 1 michal michal 1200398 May 31 11:52 maix_blinky

Compilation succeeded! But to achieve this, you need to add support for noos/riscv64 pair to the vanilla Go compiler. Read Getting started and github.com/embeddedgo/patch readme for more information.

Let’s flash our program to the Maix Bit. You need to install kflash ISP utility. The simplest way is to use pip3 install kflash command.

$ objcopy -O binary maix_blinky maix_blinky.bin
$ kflash -p /dev/ttyUSB0 -b 750000 -B bit_mic maix_blinky.bin
[INFO] COM Port Selected Manually:  /dev/ttyUSB0
[INFO] Default baudrate is 115200 , later it may be changed to the value you set.
[INFO] Trying to Enter the ISP Mode...
[INFO] Greeting Message Detected, Start Downloading ISP
Downloading ISP: |============================================| 100.0% 10kiB/s
[INFO] Booting From 0x80000000
[INFO] Wait For 0.1 second for ISP to Boot
[INFO] Boot to Flashmode Successfully
[INFO] Selected Baudrate:  750000
[INFO] Baudrate changed, greeting with ISP again ...
[INFO] Boot to Flashmode Successfully
[INFO] Selected Flash:  On-Board
[INFO] Initialization flash Successfully
Programming BIN: |============================================| 100.0% 38kiB/s
[INFO] Rebooting...

The developement of Go on Kendryte K210 takes place on github.com/embeddedgo/kendryte. You can clone the repository and try the other examples. Any help in developing this project is appreciated.

$ git clone https://github.com/embeddedgo/kendryte
remote: Enumerating objects: 229, done.
remote: Counting objects: 100% (229/229), done.
remote: Compressing objects: 100% (137/137), done.
remote: Total 229 (delta 48), reused 215 (delta 34), pack-reused 0
Receiving objects: 100% (229/229), 570.65 KiB | 28.00 KiB/s, done.
Resolving deltas: 100% (48/48), done.
$ cd kendryte/devboard/maixbit/examples
$ ls
blinky  build.sh  debug-oocd.sh  goroutines  load-kflash.sh
$ cd blinky
$ ../build.sh
$ ../load-kflash.sh

Sumary

The Kendryte K210 is impresive piece of hardware for it’s price. It seems to be an ideal platform to play with Embedded Go.

At the end I will describe briefly the Maix Bit v2 development board.

From the left to the right:

1 USB-C connector, connected to the CH552, can be used to power the board, program it and communicate with K210 through UART,

2 BOOT/USER button, pressed during reset starts the bootloader in programming mode, you can read its state in your code,

3 RESET button,

4 power LED,

5 RGB LED,

6 CH552 MCU, presents itself as FTDI FT2232H USB to UART converter, has ability to reset the K210 chip and control its BOOT pin,

7 MEMS microphone,

8 CH552 UART Rx/Tx LEDs,

9 DC/DC step-down PMU (RY1303A), provides all voltages need by K210 (0.9V, 1.8V, 3.3V),

A Kendryte K210 SOC,

B 16 MB SPI Flash,

C camera connector,

D LCD connector.

There is also a Micro SD card slot on the other side of the board.

Michał Derkacz

There are hundreds of different types of displays targeting the MCU market. From the simplest text only displays based on HD44780 compatible controllers to the Nextion “intelligent” displays that contain their own MCUs and megabytes of RAM.

But there is a series of display controllers that shines among many others. They are product of FTDI, a company well known for their USB to UART converters. Currently there are three generations of these controllers available on the market: FT80x, FT81x and BT81x, all based on the same concept called Embedded Video Engine.

The following two videos are from Gameduino 2/3 Kickstarter campaigns. In the first one James Bowman presents the features of Gameduino 2 the Arduino display shield based on FT800 chip. In the second one you can see the improvements introduced by Gameduino 3 that uses FT810 chip (EVE2).

At the end of this article you can see one demo and one game from the first video. They are translated to Go and can run on any supported MCU.

Embedded Video Engine

EVE is something like GPU for microcontrollers. It provides drawing interface similar to OpenGL 2D and also handles audio and touch functionality.

Unique is the way EVE produces the displayed image. If you think about typical GPU based design you probably think about a specialized processor that executes commands and draws to the large framebuffer. We’re just before connecting a relatively large 800x480 display to the STM32L476 microcontroller. Such display would need about 1.5 MB of graphics RAM for single 32-bit RGBA framebuffer. The STM32L476 has only 128 KB of RAM so the framebuffer must be handled by display controller.

EVE does it for our MCU but uses only 3200 bytes for its internal framebuffer. How is it possible? It’s possible because EVE renders the display list (scene in the OpenGL nomenclature) line by line during the LCD refresh.

The display list can contain up to 2048 commands and is double-buffered in RAM of size 2 x 8 KB. A microcontroller can write basic commands like points, lines, rectangles, bitmaps, etc. directly to the inactive display list or use Co-processor Engine (CE) for high-level commands like drawing buttons, scroll bars, progress bars, text strings, decompressing JPEG or PNG images, etc. The CE executes high-level commands and in effect writes basic display list commands to the inactive display list buffer or decompress data to the general purpose RAM. When the display list is ready the inactive and active buffers are swapped.

There is 1 MB (256 KB in case of FT80x) of general purpose RAM (RAM_G), where you can store bitmaps, decompress JPEG and PNG images, setup video queues, store audio files, etc. As you can see the FT81x uses about 1050 KB of RAM for a lot of things instead of 1500 KB for only one framebuffer (you need two for double buffering).

The EVE handles also touchscreen and audio. You can assign a tag to any object in the display list. The graphics engine will tell you which object is touched by reporting its tag. It can also assists in tracking touches on graphics objects by reporting the angle or distance. Additionally it can play audio generated by simple built-in MIDI synthesizer or play samples from RAM_G.

The HOTMCU FT811CB display

HAOYU Electronics aka HOTMCU is probably the cheapest source of FT8xx based displays. When I was working on the display/eve package I’ve used two of them: FT800CB-HY50B and FT811CB-HY50HD. The first one uses EVE1 chip (FT800), the second one uses EVE2 chip (FT811). The eve package autodetects EVE version and supports both. You can see the pictures of the FT811CB bellow:

Its TFT panel isn’t outstanding, to put it mildly, but good enough for development purposes.

Unfortunately the displays from HOTMCU are designed to work with 5V logic used by most Arduino boards. They probably work well with 5V logic, even with the highest supported 30 MHz SPI clock but in case of 3.3V logic used by most 32-bit microcontrollers they can’t work reliably with such high speeds. You can use them without any modification but you’ve to reduce the SPI clock much (unfortunately I don’t remember how much).

However, there is a better solution to this problem. You can remove the two 74LVC125A level shifters as shown below:

As a side effect this modification allows to use 2-bit QSPI mode which doubles the available bandwidth.

Programming with EVE

Programming with Embedded Video Engine mainly consists of creating display lists. But before you create your first display list you’ve to establish a communication channel with your display. The display/eve package uses DCI interface to communicate with EVE. The stm32/dci/evedci package provides DCI implementation optimized for STM32 microcontrollers.

Let’s connect the FT811CB display to the Nucleo-L476RG development board.

The FT811CB requires 8 wires for GND, 5V, INT, PDN, CSN, SCK, MISO, MOSI signals. There is also AUDIO signal on the header which you can connect to the line input of your audio amplifier or portable speaker.

Now we’ve to reflect these connections in the code.

package main

import (
	"embedded/rtos"

	"github.com/embeddedgo/display/eve"
	"github.com/embeddedgo/stm32/dci/evedci"
	"github.com/embeddedgo/stm32/hal/exti"
	"github.com/embeddedgo/stm32/hal/gpio"
	"github.com/embeddedgo/stm32/hal/irq"
	"github.com/embeddedgo/stm32/hal/spi"
	"github.com/embeddedgo/stm32/hal/spi/spi2"

	_ "github.com/embeddedgo/stm32/devboard/nucleo-l476rg/board/init"
)

var eveInt rtos.Note

func main() {

	// GPIO pins used to connect to FT811CB, all from port B
	pb := gpio.B()
	pb.EnableClock(true)
	intn := pb.Pin(1)
	pdn := pb.Pin(11)
	csn := pb.Pin(12)
	sck := pb.Pin(13)
	miso := pb.Pin(14)
	mosi := pb.Pin(15)

	// connect intn pin to EXTI for detection of EVE interrupts
	evedci.UseIntPin(intn)
	irq.EXTI1.Enable(rtos.IntPrioLowest, 0)

	// connect csn, sck, mosi, miso pins to SPI2
	spi2.UsePinMaster(spi.NSS, csn)
	spi2.UsePinMaster(spi.SCK, sck)
	spi2.UsePinMaster(spi.MOSI, mosi)
	spi2.UsePinMaster(spi.MISO, miso)

	// setup EVE driver
	lcd := eve.NewDriver(evedci.NewSPI(spi2.Driver(), pdn), 256)
	lcd.SetNote(&eveInt)

	// initialize display
	if err := lcd.Init(&eve.Default800x480, nil); err != nil {
		println(err.Error())
		return
	}
	lcd.SetBacklight(96)

	// we will create display lists here
}

//go:interrupthandler
func EXTI1_Handler() {
	exti.L1.ClearPending()
	eveInt.Wakeup()
}

You can follow this article with other supported boards, e.g. compare sample code for STM32F4-Discovery.

Save the above code and create build.sh script to facilitate future builds.

#!/bin/sh

GOTARGET=stm32l4x6
GOMEM=0x20000000:96K,0x10000000:32K
GOTEXT=0x8000000

. $HOME/embeddedgo/scripts/build.sh $@

Now we can try to compile our code:

$ go mod init evetutorial
go: creating new go.mod: module evetutorial
$ chmod a+x build.sh
$ ./build.sh
go: downloading github.com/embeddedgo/stm32 v0.4.4
go: extracting github.com/embeddedgo/stm32 v0.4.4
go: finding github.com/embeddedgo/stm32 v0.4.4
go: downloading github.com/embeddedgo/display v0.1.6
go: extracting github.com/embeddedgo/display v0.1.6
go: finding github.com/embeddedgo/display v0.1.6

Success! But this code doesn’t draw anything on the screen yet. Before we start drawing something we will prepare load.sh script which we will use to write our program to the STM32 Flash:

#!/bin/sh

INTERFACE=stlink
TARGET=stm32l4x
TRACECLKIN=80000000

. $HOME/embeddedgo/scripts/load-oocd.sh

First display list

Let’s create our first display list. Add the following code at the end of the main function:

dl := lcd.DL(-1)
dl.ClearColorRGB(0x0000AA)
dl.Clear(eve.CST)
dl.PointSize(60 * 16)
dl.Begin(eve.POINTS)
dl.Vertex2ii(200, 100, 0, 0)
dl.Vertex2f(500*16, 300*16)
dl.End()
dl.Display()
dl.SwapDL()

Compile it and flash:

./build.sh
chmod a+x load.sh
./load.sh

If everything went well you should see the following image on the screen (real screenshot obtained from FT811 using Snapshot2 command, open it in new tab/window to see original size):

Let’s discuss the above code.

The dl := lcd.DL(-1) begins the writing transaction to the EVE memory. You start write at address passed to the DL method. -1 is the special address that means the beginning of display list buffer (RAM_DL). It also means that DL will wait for scheduled swap to avoid overwriting the previously created display list.

The returned display list writer will be used to write display list commands to RAM_DL.

The ClearColorRGB(0x0000AA) and Clear(eve.CST) commands instruct EVE to fill its single-line frame buffer with the specified color before rendering the next line. If you omit Clear command you will obtain the following image on the screen:

This image says a lot about how the rendering is done.

Our display list draws two points on the screen. The PointSize(60 * 16) command specifies radius of the following points in 1/16 pixel precision. In the subsequent display lists we use f(x) instead of x * 16 where f is defined as:

func f(x int) int { return x * 16 }

This increases the readability of the presented code.

The Begin(eve.POINTS) tells the graphics engine to start drawing points. The following vertex commands draw points with the given coordinates. There are two kinds of vertex commands.

The first one is Vertex2ii which accept four arguments. First two are x ,y coordinates and the next two allow to specify bitmap handle and cell (more about them later). The second one is Vertex2f which accepts only two arguments which are x, y coordinates in 1/16 pixel precision.

The Vertex2ii x, y coordinates can be in the range 0 to 511 only. It’s a significant disadvantage in the case of 800x480 display. Despite this you can use Vertex2ii to draw on the whole screen (useful in case of bitmaps) thanks to the VertexTranslateX and VertexTranslateY commands.

The End() command closes the drawing block started by Begin. It can be omitted in most cases.

The graphics engine executes commands until it encounters the Diaplay command so this command ends our display list.

The SwapDL() isn’t an EVE command. It’s equivalent to the following sequence:

dl.Close()
lcd.ClearInt(eve.IntSwap)
lcd.WriteReg(eve.REG_DLSWAP, eve.DLSWAP_FRAME)

It closes the write transaction, clears the IntSwap interrupt flag and schedules the display list swap after the current frame is scanned out. SwapDL doesn’t wait for the display list swap to be done so your code can start calculation for the next display frame immediately, while the previous frame is still scanned out and the new one is waiting for swap.

Color and transparency

You can specify the size, color and transparency before each vertex. They are part of graphics context (more about this later).

dl := lcd.DL(-1)
dl.ClearColorRGB(0x0000AA)
dl.Clear(eve.CST)

dl.Begin(eve.POINTS)
dl.ColorRGB(0xFF0000)
dl.PointSize(f(200))
dl.Vertex2f(f(300), f(200))
dl.ColorRGB(0x00FF00)
dl.ColorA(128)
dl.PointSize(f(100))
dl.Vertex2f(f(500), f(300))

dl.Display()
dl.SwapDL()

Other graphics primitives

The Begin command accepts the following graphics primitives: BITMAPS, POINTS, LINES, LINE_STRIP, EDGE_STRIP_R, EDGE_STRIP_L, EDGE_STRIP_A, EDGE_STRIP_B, RECTS. The following display list demonstrates some of them:

dl.Begin(eve.BITMAPS)
dl.Vertex2ii(20, 20, 31, 'A')
dl.BitmapHandle(29)
for i := 0; i < 25; i++ {
	dl.Cell(byte('B' + i))
	dl.Vertex2f(f(60+25*i), f(20))
}

dl.Begin(eve.LINES)
dl.LineWidth(f(1))
dl.Vertex2f(f(20), f(100))
dl.Vertex2f(f(200), f(100))
dl.LineWidth(f(5))
dl.Vertex2f(f(20), f(150))
dl.Vertex2f(f(200), f(150))
dl.LineWidth(f(10))
dl.Vertex2f(f(20), f(200))
dl.Vertex2f(f(200), f(200))

dl.Begin(eve.LINE_STRIP)
dl.LineWidth(f(1))
dl.Vertex2f(f(600), f(100))
dl.Vertex2f(f(780), f(100))
dl.LineWidth(f(5))
dl.Vertex2f(f(600), f(150))
dl.Vertex2f(f(780), f(150))
dl.LineWidth(f(10))
dl.Vertex2f(f(600), f(200))
dl.Vertex2f(f(780), f(200))

dl.Begin(eve.EDGE_STRIP_B)
dl.ColorRGB(0xFFFF00)
dl.Vertex2f(f(100), f(400))
dl.Vertex2f(f(300), f(350))
dl.Vertex2f(f(500), f(450))
dl.Vertex2f(f(700), f(320))

dl.Begin(eve.RECTS)
dl.ColorRGB(0xFF0000)
dl.Vertex2f(f(250), f(100))
dl.Vertex2f(f(550), f(300))
dl.ColorRGB(0x00FF00)
dl.LineWidth(f(1))
dl.Vertex2f(f(300), f(150))
dl.Vertex2f(f(500), f(250))

Although the number of available primitives is small, however along with the other display list commands such as bitmap transformations, blending, scissors and stencils it gives you immense possibilities for creating images.

Bitmaps

As you can see in the example above, the built-in fonts are bitmaps saved in ROM. But we can load other bitmaps to the RAM_G and display them just like fonts.

You can find an example of L1 bitmap in the display/eve/examples/evetest/gophermask.go file. It’s stored in the long Go string. In case of lack of external storage like SD card it’s perfectly fine to store bitmaps this way. There are other things like assets with display list commands which you would prefer to have in uint32 arrays. But there is no way in the current Go specification to leave the immutable data other than strings in the Flash. See the immutable data proposal for more information about this topic.

Let’s copy the display/eve/examples/evetest/gophermask.go file to our project directory and change its package name to main. Now we can load gopherMask bitmap string to the RAM_G and display it on the screen.

dl := lcd.DL(0)
dl.WriteString(gopherMask)
dl.Close()

dl = lcd.DL(-1)
dl.BitmapHandle(1)
dl.BitmapSource(0)
dl.BitmapLayout(eve.L1, 216/8, 251)
dl.BitmapSize(eve.DEFAULT, 211, 251)
dl.Display()
dl.SwapDL()

dl = lcd.DL(-1)
dl.ClearColorRGB(0x0000AA)
dl.Clear(eve.CST)
dl.Begin(eve.BITMAPS)
dl.BitmapHandle(1)
dl.Vertex2f(f(300), f(100))
dl.Display()
dl.SwapDL()

The code above consists of three write transactions. The first one transfers our bitmap to the RAM_G. The second one creates the display list that tells the graphics engine about our bitmap and assigns handle to it. The third transaction creates the display list that draws our bitmap on the screen.

The last two transactions can be merged into one:

dl = lcd.DL(-1)
dl.BitmapHandle(1)
dl.BitmapSource(0)
dl.BitmapLayout(eve.L1, 216/8, 251)
dl.BitmapSize(eve.DEFAULT, 211, 251)
dl.ClearColorRGB(0x0000AA)
dl.Clear(eve.CST)
dl.Begin(eve.BITMAPS)
dl.BitmapHandle(1)
dl.Vertex2f(f(300), f(100))
dl.Display()
dl.SwapDL()

but the previous example shows that the bitmap defined by one display list can be used by another one. This is an example of the global graphics state. Every display list has also its local state called graphics context. The graphics context contains attributes like color, line width, point size, bitmap handle, bitmap cell, bitmap transform coefficients, etc. You can save and restore the current graphics context on the context stack using SaveContext and RestoreContext commands.

You select the bitmap to draw using handle assigned to it. There are 15 handle numbers from 0 to 14 available for programmer. The handle 15 is used as scratch bitmap handle by co-processor engine and handles from 16 to 31 are used for built-in fonts. One handle can represent multiple bitmaps with the same layout located in the memory one after another. The cell parameter is used to select one of them.

Our bitmap is an example of the L1 format where every pixel can be only opaque or transparent. But we can draw it in different colors:

dl.Begin(eve.BITMAPS)
dl.BitmapHandle(1)
dl.ColorRGB(0xFFFF00)
dl.Vertex2f(f(250), f(100))
dl.ColorRGB(0x00FFFF)
dl.Vertex2f(f(300), f(100))
dl.ColorRGB(0xFF0000)
dl.ColorA(128)
dl.Vertex2f(f(350), f(100))

You can scale, rotate and translate bitmaps by changing coefficients of transform matrix. Below we draw the first bitmap scaled down and the other two rotated 45 degrees.

s := int(256 * math.Sin(math.Pi/4))
c := int(256 * math.Cos(math.Pi/4))

dl = lcd.DL(-1)
dl.ClearColorRGB(0x0000AA)
dl.Clear(eve.CST)
dl.Begin(eve.BITMAPS)
dl.BitmapHandle(1)
dl.ColorRGB(0xFFFF00)
dl.BitmapTransformA(0, 2*256)
dl.BitmapTransformE(0, 2*256)
dl.Vertex2f(f(200), f(100))
dl.BitmapTransformA(0, c)
dl.BitmapTransformB(0, -s)
dl.BitmapTransformD(0, s)
dl.BitmapTransformE(0, c)
dl.ColorRGB(0x00FFFF)
dl.Vertex2f(f(300), f(100))
dl.ColorRGB(0xFF0000)
dl.ColorA(128)
dl.Vertex2f(f(400), f(100))
dl.Display()
dl.SwapDL()

The scaling and rotation invariant is the upper left corner of the bitmap. If you want to rotate bitmap around the center of the original image you need to translate it before rotation and translate it back after rotation. This all can be expressed by one transform matrix but the formula for coefficients will be more complicated. Fortunately, EVE has a graphics co-processor that facilitates many things including rotating and scaling bitmaps.

Graphics co-processor

So far we’ve been writing display lists directly to RAM_DL. But we can also send the display list commands to the co-processor engine. It will write the received commands to RAM_DL anyway. So what’s the profit from using it for this? There is no any profit if you send DL commands only but it gives you ability to mix co-processor commands with DL commands which makes your job easier.

Let’s write the last example one more time but now using co-processor engine and doing scaling and rotation relative to the center of the bitmaps.

dx := 211 << 16 / 2
dy := 251 << 16 / 2
scale := 1 << 16 / 2
angle := 0x10000 / 8

ce := lcd.CE(-1)
ce.DLStart()
ce.ClearColorRGB(0x0000AA)
ce.Clear(eve.CST)
ce.Begin(eve.BITMAPS)

ce.BitmapHandle(1)
ce.ColorRGB(0xFFFF00)
ce.LoadIdentity()
ce.Translate(dx, dy)
ce.Scale(scale, scale)
ce.Translate(-dx, -dy)
ce.SetMatrix()
ce.Vertex2f(f(200), f(100))

ce.ColorRGB(0x00FFFF)
ce.Translate(dx, dy)
ce.Rotate(angle)
ce.Translate(-dx, -dy)
ce.SetMatrix()
ce.Vertex2f(f(300), f(100))

ce.ColorRGB(0xFF0000)
ce.ColorA(128)
ce.Translate(dx, dy)
ce.Rotate(angle)
ce.Translate(-dx, -dy)
ce.SetMatrix()
ce.Vertex2f(f(400), f(100))

ce.Display()
ce.Swap()
ce.Close()

The actual transformation is a composition of all previous transformations. Use LoadIdentity command to start from the identity matrix.

Translate and Rotate commands affect the internal co-processor state only. You’ve to use SetMatrix command to write appropriate BitmapTransformA-F commands to RAM_DL.

JPEG images

The co-processor engine has the ability to decompress JPEG images. We will use it in the example below.

w := lcd.W(0)
w.WriteString(gopherMask)
addr := w.Close()

ce := lcd.CE(-1)
ce.DLStart()

ce.BitmapHandle(1)
ce.BitmapSource(0)
ce.BitmapLayout(eve.L1, 216/8, 251)
ce.BitmapSize(eve.DEFAULT, 211, 251)

ce.BitmapHandle(2)
ce.LoadImage(addr, eve.OPT_RGB565)
ce.WriteString(gopher)
ce.Align(4)

ce.Gradient(0, 0, 0x001155, 0, 480, 0x772200)
ce.Begin(eve.BITMAPS)
ce.BitmapHandle(1)
ce.Vertex2f(f(100), f(121))
ce.BitmapHandle(2)
ce.Vertex2f(f(400), f(100))

ce.Display()
ce.Swap()
ce.Close()

The gopher string contains JPEG image. You can find it in the display/eve/examples/evetest/gopher.go file. The LoadImage(addr, eve.OPT_RGB565) co-processor command decompress it into RAM_DL just above the gopherMask bitmap. It also generates appropriate BitmapSource, BitmapLayout and BitmapSize display list commands. The JPEG string is sent to the co-processor engine immediately after LoadImage command. CE commands must be 4-byte aligned so we use Align(4) to ensures this for the next command.

The Gradient(0, 0, 0x001155, 0, 480, 0x772200) co-processor command draws vertical gradient on the whole screen. In this case we don’t need the Clear command.

Alpha compositing

The EVE renders display list into one-line RGBA color buffer. The alpha channel isn’t visible on the screen but can be used in many ways while drawing. One use case is to use one bitmap to simulate an alpha channel in the another bitmap that doesn’t have it.

Let’s modify the next to last paragraph of the previous example as shown below.

ce.Gradient(0, 0, 0x001155, 0, 480, 0x772200)
ce.Begin(eve.BITMAPS)
ce.ColorMask(eve.A)
ce.Clear(eve.C)
ce.BitmapHandle(1)
ce.Vertex2f(f(231), f(121))
ce.ColorMask(eve.RGBA)
ce.BlendFunc(eve.DST_ALPHA, eve.ONE_MINUS_DST_ALPHA)
ce.BitmapHandle(2)
ce.Vertex2f(f(200), f(100))

The ColorMask(eve.A) disables drawing on the red, green and blue channels so the Clear(eve.C) apply only to the alpha channel same as Vertex2f(f(231), f(121)) which draws gopherMask bitmap to the alpha channel only. After that the ColorMask(eve.RGBA) command restores the default state.

The Vertex2f(f(200), f(100)) draws the gopher bitmap using the blending factors set by the BlendFunc(eve.DST_ALPHA, eve.ONE_MINUS_DST_ALPHA) command. As a result, the gopherMask drawn in the alpha channel determines what is visible from the gopher bitmap.

EVE calculates the pixel color using the following formula:

screenColor = srcFactor*drawColor + dstFactor*screenColor

where drawColor is the pixel color of the object being drawn.

The BlendFunc command changes srcFactor and dstFactor. The initial state is:

srcFactor = drawColor.Aplha     // eve.SRC_ALPHA constant
dstFactor = 1 - drawColor.Aplha // eve.ONE_MINUS_SRC_ALPHA constant

which means that the source alpha channel determines the transparency of the drawn object.

There are six possible factor constants:

ZERO                 // 0
ONE                  // 1
SRC_ALPHA            // drawColor.Aplha
DST_ALPHA            // screenColor.Alpha
ONE_MINUS_SRC_ALPHA  // 1 - drawColor.Aplha
ONE_MINUS_DST_ALPHA  // 1 - screenColor.Alpha

Touchscreen

The FT811CB display supports up to five touches to be read. The following code demonstrates this ability.

w := lcd.W(0)
w.WriteString(gopherMask)
addr := w.Close()

ce := lcd.CE(-1)
ce.DLStart()
ce.BitmapHandle(1)
ce.BitmapSource(0)
ce.BitmapLayout(eve.L1, 216/8, 251)
ce.BitmapSize(eve.DEFAULT, 211, 251)
ce.BitmapHandle(2)
ce.LoadImage(addr, eve.OPT_RGB565)
ce.WriteString(gopher)
ce.Align(4)
ce.Display()
ce.Close()

ramdl := lcd.MemMap().RAM_DL
drawGopher := ramdl.Size - 16*4
for i := 0; i < 2; i++ {
	lcd.WaitInt(eve.IntSwap)
	dl := lcd.DL(ramdl.Start + drawGopher)
	dl.SaveContext()
	dl.Begin(eve.BITMAPS)
	dl.BitmapHandle(28)
	dl.Vertex2f(f(-60), f(-55))
	dl.ColorMask(eve.A)
	dl.Clear(eve.C)
	dl.Cell(0)
	dl.BitmapHandle(1)
	dl.Vertex2f(f(-70), f(-251))
	dl.ColorMask(eve.RGBA)
	dl.BlendFunc(eve.DST_ALPHA, eve.ONE_MINUS_DST_ALPHA)
	dl.BitmapHandle(2)
	dl.Vertex2f(f(-70-31), f(-251-21))
	dl.End()
	dl.RestoreContext()
	dl.Return()
	dl.SwapDL()
}

lcd.WriteReg(eve.REG_CTOUCH_EXTENDED, 0) // multi-touch detection mode

for {
	touches := [5]uint32{
		lcd.ReadReg(eve.REG_CTOUCH_TOUCH0_XY),
		lcd.ReadReg(eve.REG_CTOUCH_TOUCH1_XY),
		lcd.ReadReg(eve.REG_CTOUCH_TOUCH2_XY),
		lcd.ReadReg(eve.REG_CTOUCH_TOUCH3_XY),
		lcd.ReadReg(eve.REG_CTOUCH_TOUCH4_X)<<16 |
			lcd.ReadReg(eve.REG_CTOUCH_TOUCH4_Y)&0xFFFF,
	}
	ce := lcd.CE(-1)
	ce.DLStart()
	ce.Gradient(0, 0, 0x001155, 0, 480, 0x772200)
	for n, touch := range touches {
		if touch != 0x80008000 {
			ce.Cell('1' + n)
			ce.VertexTranslateX(f(int(touch >> 16)))
			ce.VertexTranslateY(f(int(touch & 0xFFFF)))
			ce.Call(drawGopher)
		}
	}
	ce.Display()
	ce.Swap()
	ce.Close()
}