< up >
2025-06-11

Gokrazy with Raspberry Pi Zero

Default gokrazty output.

I started my IoT journey with a Raspberry Pi 1 B and have since settled on the Arduino Pico/Esp32 so far. Recently, someone showed me their small GPIO code in Go and the remarkably simple CLI to build and update an image on a remote IoT device.

This post is a summary of the steps I did to let an LED blink with gokrazy and a Raspberry Pi Zero 2W, hence I want to do this again.

Setup

Let’s set up a new gokrazy project and flash it onto the SD card.

1. Install gokrazy cli: go install github.com/gokrazy/tools/cmd/gok@main
2. Initialize repo, will create ~/gokrazy/hello: gok new
3. Goto directory and add the gpio repo: gok add github.com/RaphaelPour/gpio
4. Replace the hostname with the ip address in config.json (in case the hostname doesn’t get resolved properly)
5. Add Wifi Module: gok add github.com/gokrazy/wifi and follow configuration instructions
6. Add your project having a main.go via gok add ~/dev/mygokrazypkg or github.com/RaphaelPour/mygokrazypackage
7. Insert SD card and locate the device (e.g. via lsblk). Mine is under /dev/sda¹
8. Build and flash: gok overwrite --full /dev/sda
9. Any further update: gok update

Notes:

• HDMI-to-MiniHDMI adapter is needed to connect a monitor to the raspi
• Monitor output can be useful to obtain the raspi’s IP
• gok project is separated from any program that is running on it
• Raspberry Pi Zero’s wifi chip doesn’t support 5GHz
• Pinout mapping go lib

In-use

After flashing the image properly, the raspi connects to the specified WLan and provides a website. Credentials can be obtained from the gok overwrite output (see above) or config.json. Username is gokrazy.

Run own program

Now I want to run my own program and do the ultimate hardware test: can it blink?

But first some general steps to set up a new repo with custom code:

1. create new folder or repo (doesn’t need to be within the gokrazy directory), ~/dev/gpio in my case
2. add custom program with regular main function
3. go back to gokrazy dir and add the repo via gok add <url|path>, gok add ~/dev/gpio in my case
4. build image as usual, gokrazy will pull the repo and run it on boot

GPIO program

The following Go program is a minimal example for letting an LED blink. It uses GPIO pin 17 and the LED stays on (and off) for 100ms. GPIO Pin and the duration can be altered in the variable section.

package main

import (
	"log"
	"time"

	"periph.io/x/conn/v3/gpio"
	"periph.io/x/conn/v3/gpio/gpioreg"
	host "periph.io/x/host/v3"
)

var (
	delay = 100 * time.Millisecond
	pin   = gpioreg.ByName("GPIO17")
)

func main() {
	if _, err := host.Init(); err != nil {
		panic(err)
	}

	for {
		pin.Out(gpio.High)
		log.Println("high")
		time.Sleep(delay)

		pin.Out(gpio.Low)
		log.Printf("low\n")
		time.Sleep(delay)
	}
}

• I’ve connected an LED with a 220Ω resistor² between GPIO pin 17 and ground
• gpioreg³ provides mapping for the Raspberry Pi Zero
• the log is useful for debugging and can be viewed via the gokrazy website

Advantages

I’ve found several advantages in contrast to my Arduino/ESP32 projects:

• golden images: don’t maintain a heavy distro, just replace the whole image on update
• simple update: OTA update via gok update
• Go + many packages: use a well-supported and quite comfortable language along with its ecosystem for embedded use cases

Challenges

In general there were some challenges on setting up the project:

• Soldering the pin header was a bit messy. Learning: use 320C instead of just 270 with Weler Sn99.3Cu0.6Ni0.05 solder tin or just buy a one with a pre-soldered pin header
• The hostname doesn’t resolve properly with my DNS. Use the ip address instead.

Impressions

References

• Official gokrazy website
• Official gokrazy quickstart
• Wifi configuration guide
• General Raspberry Pi pinout