Go Runtime Reference

// Start creates the runtime, starts the IPC bridge, and blocks on the HTTP server.
func Start(app interface{}) error

// Init creates the runtime and starts the IPC bridge without blocking.
// Use this instead of Start when you need the Runtime for events or services.
func Init(app interface{}) (*Runtime, error)

// Serve starts the HTTP server and blocks until it exits.
func (rt *Runtime) Serve() error

// Stop shuts down the IPC server and removes the socket.
func (rt *Runtime) Stop()

package main

import (
	"log"

	"github.com/strux-dev/strux/pkg/runtime"
)

// App is the main application struct.
// All public fields and methods are exposed to the frontend.
type App struct {
	Title   string
	Counter int
}

// Greet returns a greeting message.
func (a *App) Greet(name string) string {
	return "Hello, " + name + "!"
}

func main() {
	app := &App{Title: "my-kiosk", Counter: 0}

	rt, err := runtime.Init(app)
	if err != nil {
		log.Fatal(err)
	}
	defer rt.Stop()

	rt.On("hello", func(data interface{}) {
		rt.Emit("hello-reply", map[string]string{"message": "Hello from Go!"})
	})

	if err := rt.Serve(); err != nil {
		log.Fatal(err)
	}
}

rt.Boot().Reboot()
level, err := rt.Display().GetBacklight("HDMI-A-1")

func (b *BootService) HideSplash() error
func (b *BootService) Reboot() error
func (b *BootService) Shutdown() error

func (s *CapabilitiesService) List() []CapabilityInfo
func (s *CapabilitiesService) Supports(name string) bool

type CapabilityInfo struct {
	Name        string       `json:"name"`
	Namespace   string       `json:"namespace"`
	Description string       `json:"description,omitempty"`
	Supported   bool         `json:"supported"`
	Provider    string       `json:"provider,omitempty"`
	Methods     []MethodSpec `json:"methods"`
}

func (d *DevService) GetConfig() (DevState, error)
func (d *DevService) SetConfig(config DevConfig) error
func (d *DevService) SetEnabled(enabled bool) error
func (d *DevService) Apply(config DevConfig, enabled bool) error
func (d *DevService) RestartService() error
func (d *DevService) ApplyAndRestart(config DevConfig, enabled bool) error

type DevConfig struct {
	ClientKey     string             `json:"clientKey"`
	UseMDNS       bool               `json:"useMDNS"`
	FallbackHosts []DevHost          `json:"fallbackHosts"`
	Inspector     DevInspectorConfig `json:"inspector"`
	USB           DevUSBConfig       `json:"usb"`
}

type DevHost struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

type DevInspectorConfig struct {
	Enabled bool `json:"enabled"`
	Port    int  `json:"port"`
}

type DevUSBConfig struct {
	Enabled bool   `json:"enabled"`
	Subnet  string `json:"subnet"`
}

type DevState struct {
	Enabled bool      `json:"enabled"`
	Config  DevConfig `json:"config"`
}

func (DisplayService) List() ([]DisplayOutput, error)
func (DisplayService) Get(name string) (DisplayOutput, error)
func (DisplayService) Apply(changes []DisplayOutputChange, opts DisplayApplyOptions) error
func (DisplayService) SetListedMode(output string, mode ListedModeSelection, opts DisplayApplyOptions) error
func (DisplayService) SetCustomMode(output string, mode CustomModeSelection, opts DisplayApplyOptions) error
func (DisplayService) SetPreferredMode(output string, opts DisplayApplyOptions) error
func (DisplayService) SetOutputEnabled(output string, on bool, opts DisplayApplyOptions) error
func (DisplayService) SetLayout(output string, x int32, y int32, opts DisplayApplyOptions) error
func (DisplayService) SetScale(output string, scale float64, opts DisplayApplyOptions) error
func (DisplayService) SetTransform(output string, transform OutputTransform, opts DisplayApplyOptions) error
func (DisplayService) GetBacklight(outputName string) (int, error)
func (DisplayService) SetBacklight(outputName string, value int) error

type DisplayOutput struct {
	Name             string          `json:"name"`
	Description      string          `json:"description"`
	PhysicalWidthMM  int32           `json:"physicalWidthMm"`
	PhysicalHeightMM int32           `json:"physicalHeightMm"`
	Enabled          bool            `json:"enabled"`
	Modes            []DisplayMode   `json:"modes"`
	Current          *DisplayMode    `json:"current,omitempty"`
	PositionX        int32           `json:"positionX"`
	PositionY        int32           `json:"positionY"`
	Transform        OutputTransform `json:"transform"`
	Scale            float64         `json:"scale"`
}

type DisplayMode struct {
	WidthPX   int     `json:"widthPx"`
	HeightPX  int     `json:"heightPx"`
	RefreshHz float64 `json:"refreshHz,omitempty"`
	Preferred bool    `json:"preferred"`
	IsCurrent bool    `json:"current"`
}

type DisplayOutputChange struct {
	Name         string               `json:"name"`
	On           *bool                `json:"on,omitempty"`
	ListedMode   *ListedModeSelection `json:"listedMode,omitempty"`
	CustomMode   *CustomModeSelection `json:"customMode,omitempty"`
	UsePreferred bool                 `json:"usePreferred,omitempty"`
	PositionX    *int32               `json:"positionX,omitempty"`
	PositionY    *int32               `json:"positionY,omitempty"`
	Scale        *float64             `json:"scale,omitempty"`
	Transform    *OutputTransform     `json:"transform,omitempty"`
}

func (NetworkService) ListInterfaces() ([]NetworkInterface, error)
func (NetworkService) GetDefaultInterface(kind string) (NetworkDefaultInterface, error)
func (NetworkService) GetStatus(interfaceName string) (NetworkStatus, error)
func (NetworkService) ConfigureIP(req NetworkIPConfigRequest) error
func (NetworkService) SetEnabled(interfaceName string, enabled bool) error
func (NetworkService) RenewDHCP(interfaceName string) error

type NetworkIPConfig struct {
	Mode    string   `json:"mode"` // "dhcp", "static", or "disabled"
	Address string   `json:"address"`
	Gateway string   `json:"gateway"`
	Subnet  string   `json:"subnet"`
	DNS     []string `json:"dns"`
}

type NetworkStatus struct {
	InterfaceName   string          `json:"interfaceName"`
	Kind            string          `json:"kind"`
	Connected       bool            `json:"connected"`
	LinkDetected    bool            `json:"linkDetected"`
	HardwareAddress string          `json:"hardwareAddress"`
	SpeedMbps       int             `json:"speedMbps"`
	Duplex          string          `json:"duplex"`
	IP              NetworkIPConfig `json:"ip"`
}

func (p *ProjectService) Info() (ProjectInfo, error)

type ProjectInfo struct {
	Name           string `json:"name"`
	ProjectVersion string `json:"projectVersion"`
	StruxVersion   string `json:"struxVersion"`
	BSP            string `json:"bsp"`
	Arch           string `json:"arch"`
	BuiltAt        string `json:"builtAt"`
}

func (u *UpdateService) Progress() (*UpdateProgress, error)
func (u *UpdateService) State() (*UpdateState, error)

type UpdateProgress struct {
	Status       string `json:"status"`
	Progress     int    `json:"progress"`
	Message      string `json:"message,omitempty"`
	BytesWritten int64  `json:"bytesWritten,omitempty"`
	TotalBytes   int64  `json:"totalBytes,omitempty"`
	Slot         string `json:"slot,omitempty"`
	Version      string `json:"version,omitempty"`
	UpdatedAt    string `json:"updatedAt,omitempty"`
}

type UpdateState struct {
	Version        int    `json:"version"`
	ActiveSlot     string `json:"activeSlot"`
	PendingSlot    string `json:"pendingSlot"`
	TriesRemaining int    `json:"triesRemaining"`
	Generation     int    `json:"generation"`
	LastGoodAt     string `json:"lastGoodAt,omitempty"`
	LastError      string `json:"lastError"`
}

func (WiFiService) ListInterfaces() ([]WiFiInterface, error)
func (WiFiService) GetDefaultInterface() (WiFiDefaultInterface, error)
func (WiFiService) GetStatus(interfaceName string) (WiFiStatus, error)
func (WiFiService) Scan(interfaceName string) ([]WiFiNetwork, error)
func (WiFiService) Connect(req WiFiConnectRequest) error
func (WiFiService) ConnectKnown(req WiFiKnownNetworkRequest) error
func (WiFiService) Disconnect(interfaceName string) error
func (WiFiService) ListKnownNetworks() ([]WiFiKnownNetwork, error)
func (WiFiService) Forget(id string) error
func (WiFiService) SetKnownNetworkPriority(id string, priority int) error
func (WiFiService) ConfigureIP(req WiFiIPConfigRequest) error

// Emit sends an event to all connected frontends.
func (rt *Runtime) Emit(event string, data interface{})

// On registers a handler for events sent from the frontend.
// It returns a handler ID for Off.
func (rt *Runtime) On(event string, handler func(data interface{})) uint64

// Off removes a previously registered handler by its ID.
func (rt *Runtime) Off(id uint64)

for _, evt := range []string{"video:play", "video:pause", "video:stop"} {
	e := evt
	rt.On(e, func(data any) {
		rt.Emit(e, data) // rebroadcast to all connected frontends
	})
}

type EventMessage struct {
	Type  string      `json:"type"`
	Event string      `json:"event"`
	Data  interface{} `json:"data,omitempty"`
}

type EventHandler struct {
	ID       uint64
	Callback func(data interface{})
}

func RegisterDisplayProvider(provider DisplayProvider)
func RegisterNetworkProvider(provider NetworkProvider)
func RegisterWiFiProvider(provider WiFiProvider)

type DisplayProvider interface {
	GetBacklight(displayName string) (int, error)
	SetBacklight(displayName string, value int) error
}

type NetworkProvider interface {
	ListInterfaces() ([]NetworkInterface, error)
	GetDefaultInterface(kind string) (NetworkDefaultInterface, error)
	GetStatus(interfaceName string) (NetworkStatus, error)
	ConfigureIP(req NetworkIPConfigRequest) error
	SetEnabled(interfaceName string, enabled bool) error
	RenewDHCP(interfaceName string) error
}

type WiFiProvider interface {
	ListInterfaces() ([]WiFiInterface, error)
	GetDefaultInterface() (WiFiDefaultInterface, error)
	GetStatus(interfaceName string) (WiFiStatus, error)
	Scan(interfaceName string) ([]WiFiNetwork, error)
	Connect(req WiFiConnectRequest) error
	ConnectKnown(req WiFiKnownNetworkRequest) error
	Disconnect(interfaceName string) error
	ListKnownNetworks() ([]WiFiKnownNetwork, error)
	Forget(id string) error
	SetKnownNetworkPriority(id string, priority int) error
	ConfigureIP(req WiFiIPConfigRequest) error
}

// Process-wide: every Runtime created afterwards exposes the methods.
// Intended for BSP package init() functions. Panics on invalid or duplicate registration.
func RegisterCustomExtension(name string, instance interface{})

// Process-wide, with an explicit namespace. Returns an error instead of panicking.
func RegisterExtension(namespace, subNamespace string, instance interface{}) error

// Instance-scoped: registers on one Runtime only.
func (rt *Runtime) RegisterExtension(namespace, subNamespace string, instance interface{}) error