Building a kiosk using Go

Jos van Bakel

About me

Nerd
Electronics hobbyist
System engineer at Spindle
NixOS fanboy

Agenda

I've build a kiosk using Go. Here are some of my learnings.

Confession: I use this in my home, not really "on the job", but you could use this on the job! ;)

What is a kiosk?
How does it work?
Why Go?
Learnings

What is a kiosk?

What is a kiosk?

What is a kiosk?

What is a kiosk?

backside:

raspberry pi
yellow/red buttons
motion sensor (pir)
led strip

How does it work?

over engineered.. for learning
mention: cage (wayland) https://www.hjdskes.nl/projects/cage/

Why Go?

first version was in Python, worked okay for a few years, but adding LEDs was difficult.
problems would surface during runtime => not a compiled language
updating the OS (Raspbian) broke stuff from time to time
now build on NixOS, fully declarative
also tried Rust, but that is difficult with the type signatures, and i missed channels
and now i'm going to talk about the learnings i had from this project.

Nice language: small syntax and typed
Good libraries for GPIO and WS2812
Cross compiles to aarch64-linux
Good Nix support

gRPC

first learning is that grpc is awesome!

streams can be be passed from client to server
and/or can be returned from the server to client
streams run until either side closes the stream
in the next slide i'll show an example of i used a stream.

gRPC Remote Procedure Calls
Communication between hal and display
Describe protocol in protobuf
Generate client/server code for almost any language
gRPC supports streams!

protobuf

the protocol is defined in protobuf.

service Hal {
  rpc WatchEvents(google.protobuf.Empty) returns (stream Event) {}
  // ...
}

message Event {
  EventSource source = 1;
  bool state = 2;
}

enum EventSource {
  Pir = 0 [(name) = "pir"];
  RedButton = 1 [(name) = "red_button"];
  YellowButton = 2 [(name) = "yellow_button"];
}

Server

listens on unix socket
tcp can also be used as a transport for grpc

func (h *Hal) Run() {
    addr, err := net.ResolveUnixAddr("unix", h.SocketPath)
    lis, err := net.ListenUnix("unix", addr)
    h.server = grpc.NewServer()
    pb.RegisterHalServer(h.server, h)
    h.server.Serve(lis)
}

func (h *Hal) WatchEvents(_ *emptypb.Empty, stream pb.Hal_WatchEventsServer) error {
    h.addWatcher(stream)
    <-stream.Context().Done()
    h.removeWatcher(stream)
    return nil
}

Publish event

note: left out locking on h.watchers for brevity. gpiod library is amazing, native go library for accessing gpio it even has debouncing build in: gpiod.WithDebounce(delay) https://github.com/warthog618/gpiod

gpiod.RequestLine(gpioDevice, pirPin,
    gpiod.WithBothEdges,
    gpiod.WithEventHandler(func(evt gpiod.LineEvent) {
        event := pb.Event{
            Source: pb.EventSource_Pir,
            State:  evt.Type == gpiod.LineEventRisingEdge,
        }
        for _, w := range h.watchers {
            w.Send(&event)
        }
    }))

Client

conn, err := grpc.Dial(
    d.config.HalSocketPath,
    grpc.WithInsecure(),
    grpc.WithDialer(func(addr string, timeout time.Duration) (net.Conn, error) {
        return net.DialTimeout("unix", addr, timeout)
    }))

defer conn.Close()
d.hal = pb.NewHalClient(conn)

// Watch events from HAL and process them.
stream, err := d.hal.WatchEvents(ctx, &emptypb.Empty{})
for {
    event, err := stream.Recv()
    // Handle event.
}

Go generate

hal_proto/generate.go

//go:generate protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative hal_proto.proto
package hal_proto

then run:

go generate -x -v hal_proto/generate.go

Websocket server

you probably already know Gin Gonic, it's an awesome web framework, and it's very fast.
Gin doesn't have support for websockets,
but Gorilla can be used for that.

r.GET("/ws", func(c *gin.Context) {
  upgrader := websocket.Upgrader{}
  conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
  defer conn.Close()
  d.addClient(conn)

  for {
      messageType, message, err := conn.ReadMessage()
      if websocket.IsCloseError(err, websocket.CloseGoingAway, ...) {
          break
      }
      // Handle message.
  }

  d.removeClient(conn)
})

Streaming files over HTTP

added support for showing video's on the display
Gin's r.StaticFS doesn't support streaming ranges, thus the browser will fetch the entire video file before playing.

r.StaticFS("/video", http.Dir(d.config.VideosPath))

Streaming with http.ServeFile

Go's builtin webserver does support this! with http.ServeFile
getting video acceleration to work on the Pi (in 64bit) proved too difficult

r.GET("/video/:name", func(c *gin.Context) {
    name := c.Param("name")
    filepath := path.Join(d.config.VideosPath, name)
    http.ServeFile(c.Writer, c.Request, filepath)
})

Embedded static frontend

using go:embed frontend files can be embedded in the go binary.
probably not a good idea for production (use a static file server or CDN)
but great for these simple projects!

Run esbuild before go build.
In the frontend directory there is one go file:

package frontend

import (
    "embed"
)

//go:embed dist/**
var Assets embed.FS

Serve static files

frontend.Assets contains all files in the dist folder.
they can be served with http.FS

fsys, err := fs.Sub(frontend.Assets, "dist")
r.NoRoute(func(c *gin.Context) {
    c.FileFromFS(c.Request.URL.Path, http.FS(fsys))
})

Nix(OS)

linux distribution
build on the Nix package manager
reproducible builds and deployments
why for this project?
- most of my systems run NixOS
- declarative
- wireless password
- samba mounts
- all baked into one image
- one command to build
- can build on x86 (with cross compilation or emulation in qemu)

Nix package

includes system libraries (like rpi_ws281x)
can compose different builders
"make" on steroids

buildGoModule rec {
  name = "neon-display";
  version = "0.0.1";
  src = ../..;
  vendorSha256 = "sha256-WqdXu2yO...";
  propagatedBuildInputs = [ rpi_ws281x ];
  subPackages = [ "cmd/hal" "cmd/display" ];

  NIX_CFLAGS_COMPILE = "-I${rpi_ws281x}/include/ws2811";
  NIX_LDFLAGS_COMPILE = "-L${rpi_ws281x}/lib";

  preBuild = ''
    cp -r ${neon-display-frontend} frontend/dist
  '';
}

NixOS module

module abstracts deployment configuration
like salt/puppet/etc.
creates two systemd units: neon-display and neon-display-hal

services.neon-display = {
  enable = true;
  user = "display";
  group = "users";
  settings = {
    web_bind = "0.0.0.0";
    photos_path = "/nas/Pics/Photos";
    off_timeout = 120; # seconds
    sites = [
      {
        title = "Live";
        url = "http://mon.home.lan/...";
      }
    ];
  };
};

Deployment

one command to:

build Go package
build React frontend
create two systemd services
configure a bunch of stuff
and assemble it all in a Linux filesystem.

Build an image:

nix build .#images.neon

Update live installation (over SSH):

nixos-rebuild --flake '.#neon' switch \
    --target-host root@neon --build-host localhost \
    --use-remote-sudo -L

Questions?

https://github.com/c0deaddict/neon-display
mail: jos@codeaddict.org
matrix: @jos:codeaddict.org

Building a kiosk using Go Jos van Bakel