A complete surface for a Linux framebuffer and its evdev keyboard, in one use.

defmodule MyDevice.Surface do
  use RasterExRatatui.Framebuffer.Surface, app: MyDevice.Dashboard, rotate: 90
end

# in the application's supervision tree
children = [MyDevice.Surface]

That is the whole consumer for a Raspberry Pi with a display: at start the surface waits for /dev/fb0 to appear, reads its size and depth from sysfs, picks the pixel format (RGB565 at 16 bits per pixel, XRGB8888 at 32) and a font scale that keeps about a hundred columns on the long side, detaches the kernel console from the framebuffer, starts the app, and reads the first USB keyboard it finds (and the touch panel, with touch: true), looking again whenever there is none. Pixels go out with RasterExRatatui.Framebuffer.write/2; keys and taps come in through RasterExRatatui.Input.Devices. When the app exits, a new one starts on the same surface (on_app_exit: :restart), because a panel has nothing else to show.

Options

Given to use or to the child spec ({MyDevice.Surface, rotate: 90}), and read from the application's config the usual way. All of RasterExRatatui.Surface's options apply too; these are the ones this module adds or defaults.

Starting blocks until the framebuffer is there, up to :framebuffer_timeout, so the surface belongs last in its supervisor: children after it would wait that long on a slow or missing display.

The keyboard needs input_event in the consumer's deps, a C port for Linux. Without it the surface logs a warning once and runs without input, so the same project still compiles and runs its tests on a host.

Under the hood, and overriding

use gives the module init/1, push/2, handle_info/2, and terminate/2, each delegating to the function of the same name here, and all overridable. Override one and call the default from it to add to what it does; the state is a map with :fb (the open RasterExRatatui.Framebuffer) and :devices (the RasterExRatatui.Input.Devices, or nil), and anything else added to it travels along.

defmodule MyDevice.Surface do
  use RasterExRatatui.Framebuffer.Surface, app: MyDevice.Dashboard

  @impl true
  def init(opts) do
    {:ok, config, state} = RasterExRatatui.Framebuffer.Surface.init(opts)
    {:ok, config, Map.put(state, :backlight, MyDevice.Backlight.on!())}
  end

  @impl true
  def handle_info({:button, :back}, state),
    do: {:events, [%ExRatatui.Event.Key{code: "esc", kind: "press"}], state}

  def handle_info(msg, state), do: RasterExRatatui.Framebuffer.Surface.handle_info(msg, state)
end

A panel that is not a framebuffer, or a keyboard that is not evdev, starts from RasterExRatatui.Surface instead; Building a Surface is the guide.