Skip to content

api

import "github.com/dahui/z13ctl/api"

Package api provides the public client interface for the z13ctl daemon. It contains the shared protocol types and socket client functions used by CLI commands, GUI frontends, and any other tool that communicates with the z13ctl daemon over its Unix socket.

Index

func SendApply

func SendApply(device, color, color2, mode, speed string, brightness int) (bool, error)

SendApply sends an apply command to the daemon. color and color2 must be "RRGGBB" hex strings. device may be "keyboard", "lightbar", a /dev/hidrawN path, or "" to target all devices. Returns (true, nil) on success, (false, nil) if the daemon is not running (caller should fall back to direct HID access).

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Apply a static red color at full brightness to all devices.
    handled, err := api.SendApply("", "FF0000", "000000", "static", "normal", 3)
    if !handled {
        fmt.Println("daemon not running, falling back to direct HID access")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("applied")
}

func SendBatteryLimitGet

func SendBatteryLimitGet() (handled bool, limit int, err error)

SendBatteryLimitGet queries the daemon for the current battery charge limit by reading sysfs (not cached daemon state). Intended for GUI/plugin callers. Returns (false, 0, nil) if the daemon is not running.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Read the current battery charge limit.
    handled, limit, err := api.SendBatteryLimitGet()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("battery limit:", limit)
}

func SendBatteryLimitSet

func SendBatteryLimitSet(limit int) (bool, error)

SendBatteryLimitSet sends a battery limit set command to the daemon.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Limit battery charge to 80%.
    handled, err := api.SendBatteryLimitSet(80)
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("battery limit set")
}

func SendBootSoundGet

func SendBootSoundGet() (handled bool, value int, err error)

SendBootSoundGet queries the daemon for the current boot sound setting by reading sysfs. Returns (false, 0, nil) if the daemon is not running.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Read the current boot sound setting.
    handled, value, err := api.SendBootSoundGet()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("boot sound:", value)
}

func SendBootSoundSet

func SendBootSoundSet(value int) (bool, error)

SendBootSoundSet sends a boot sound set command to the daemon.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Disable the POST boot sound.
    handled, err := api.SendBootSoundSet(0)
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("boot sound set")
}

func SendBrightness

func SendBrightness(device string, level int) (bool, error)

SendBrightness sends a brightness-only command to the daemon. device may be "keyboard", "lightbar", a /dev/hidrawN path, or "" to target all devices.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Set brightness to medium on the keyboard only.
    handled, err := api.SendBrightness("keyboard", 2)
    if !handled {
        fmt.Println("daemon not running, falling back to direct HID access")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("brightness set")
}

func SendFanCurveGet

func SendFanCurveGet() (handled bool, value string, err error)

SendFanCurveGet queries the daemon for the current fan curve data. Returns JSON value string with both fans' curve and mode.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Read the current fan curve for both fans via the daemon.
    handled, value, err := api.SendFanCurveGet()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("fan curve:", value)
}

func SendFanCurveReset

func SendFanCurveReset() (bool, error)

SendFanCurveReset resets both fans to firmware auto mode.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Reset both fans to firmware auto mode.
    handled, err := api.SendFanCurveReset()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("fan curves reset")
}

func SendFanCurveSet

func SendFanCurveSet(curve string) (bool, error)

SendFanCurveSet sends a fan curve set command to the daemon. The curve is applied to both fans simultaneously.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Set a custom 8-point fan curve (applied to both fans).
    handled, err := api.SendFanCurveSet("48:2,53:22,57:30,60:43,63:56,65:68,70:89,76:102")
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("fan curve set")
}

func SendOff

func SendOff(device string) (bool, error)

SendOff sends an off command to the daemon. device may be "keyboard", "lightbar", a /dev/hidrawN path, or "" to target all devices.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Turn off lighting on all devices.
    handled, err := api.SendOff("")
    if !handled {
        fmt.Println("daemon not running, falling back to direct HID access")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("lights off")
}

func SendPanelOverdriveGet

func SendPanelOverdriveGet() (handled bool, value int, err error)

SendPanelOverdriveGet queries the daemon for the current panel overdrive setting by reading sysfs. Returns (false, 0, nil) if the daemon is not running.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Read the current panel overdrive setting.
    handled, value, err := api.SendPanelOverdriveGet()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("panel overdrive:", value)
}

func SendPanelOverdriveSet

func SendPanelOverdriveSet(value int) (bool, error)

SendPanelOverdriveSet sends a panel overdrive set command to the daemon.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Enable panel refresh overdrive.
    handled, err := api.SendPanelOverdriveSet(1)
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("panel overdrive set")
}

func SendProfileGet

func SendProfileGet() (handled bool, profile string, err error)

SendProfileGet queries the daemon for the current performance profile by reading sysfs (not cached daemon state). Intended for GUI/plugin callers. Returns (false, "", nil) if the daemon is not running.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Read the current performance profile from sysfs via the daemon.
    handled, profile, err := api.SendProfileGet()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("profile:", profile)
}

func SendProfileSet

func SendProfileSet(profile string) (bool, error)

SendProfileSet sends a profile set command to the daemon.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Switch to the performance power profile.
    handled, err := api.SendProfileSet("performance")
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("profile set")
}

func SendTdpGet

func SendTdpGet() (handled bool, value string, err error)

SendTdpGet queries the daemon for current TDP/PPT values. Returns JSON value string.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Read current TDP/PPT values via the daemon.
    handled, value, err := api.SendTdpGet()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("tdp:", value)
}

func SendTdpReset

func SendTdpReset() (bool, error)

SendTdpReset sends a TDP reset command to the daemon.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Reset to balanced profile (firmware manages PPT and fan curves).
    handled, err := api.SendTdpReset()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("tdp reset")
}

func SendTdpSet

func SendTdpSet(watts string, pl1, pl2, pl3 string, force bool) (bool, error)

SendTdpSet sends a TDP set command to the daemon.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Set TDP to 50W (all PPT values equal).
    handled, err := api.SendTdpSet("50", "", "", "", false)
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("tdp set")
}

func SendUndervoltGet

func SendUndervoltGet() (handled bool, value string, err error)

SendUndervoltGet queries the daemon for the current Curve Optimizer offsets. Returns JSON value string. Returns (false, "", nil) if the daemon is not running.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Read current Curve Optimizer offsets from daemon state.
    handled, value, err := api.SendUndervoltGet()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("undervolt:", value)
}

func SendUndervoltReset

func SendUndervoltReset() (bool, error)

SendUndervoltReset resets Curve Optimizer to stock (0).

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Reset Curve Optimizer to stock (0).
    handled, err := api.SendUndervoltReset()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("undervolt reset")
}

func SendUndervoltSet

func SendUndervoltSet(cpu string) (bool, error)

SendUndervoltSet sends a Curve Optimizer set command to the daemon. cpu is a string representation of the CO offset (e.g. "-20").

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Set CPU Curve Optimizer to -20.
    handled, err := api.SendUndervoltSet("-20")
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("undervolt set")
}

func SocketPath

func SocketPath() string

SocketPath returns the runtime path for the daemon's Unix socket.

func Subscribe

func Subscribe(events []string) (<-chan string, func(), error)

Subscribe opens a long-lived subscription to the daemon and returns a channel that receives event name strings (e.g. "gui-toggle") as they are streamed. The returned cancel func closes the underlying connection and stops the goroutine; the channel is closed when the connection drops or cancel is called. Returns (nil, nil, nil) if the daemon is not running.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Subscribe to Armoury Crate button press events.
    ch, cancel, err := api.Subscribe([]string{"gui-toggle"})
    if ch == nil {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer cancel()
    for event := range ch {
        fmt.Println("received event:", event)
    }
}

type FanCurvePoint

FanCurvePoint represents one point on an 8-point fan curve.

type FanCurvePoint struct {
    Temp int `json:"temp"` // degrees Celsius
    PWM  int `json:"pwm"`  // 0–255 duty cycle
}

type FanCurveState

FanCurveState captures the fan curve and mode applied to both fans.

type FanCurveState struct {
    Mode   int             `json:"mode"`   // pwm_enable: 0=full-speed, 1=custom, 2=auto
    Points []FanCurvePoint `json:"points"` // 8 points
}

type LightingState

LightingState captures all parameters needed to reproduce one lighting zone.

type LightingState struct {
    Enabled    bool   `json:"enabled"`
    Mode       string `json:"mode"`
    Color      string `json:"color"`  // "RRGGBB" hex
    Color2     string `json:"color2"` // "RRGGBB" hex
    Speed      string `json:"speed"`
    Brightness int    `json:"brightness"` // 0–3
}

type State

State holds the last-applied settings for all controllable subsystems. It is returned by SendGetState and broadcast as part of daemon responses.

type State struct {
    Lighting           LightingState            `json:"lighting"`
    Devices            map[string]LightingState `json:"devices,omitempty"` // per-device overrides keyed by name
    Profile            string                   `json:"profile,omitempty"`
    Battery            int                      `json:"battery_limit,omitempty"`
    BootSound          int                      `json:"boot_sound,omitempty"`
    PanelOverdrive     int                      `json:"panel_overdrive,omitempty"`
    FanCurve           *FanCurveState           `json:"fan_curve,omitempty"`
    TDP                *TDPState                `json:"tdp,omitempty"`
    Undervolt          *UndervoltState          `json:"undervolt,omitempty"`
    UndervoltAvailable bool                     `json:"undervolt_available"`   // true if ryzen_smu is loaded
    Temperature        int                      `json:"temperature,omitempty"` // APU temp, degrees Celsius
    FanRPM             int                      `json:"fan_rpm,omitempty"`     // fan1 speed in RPM
}

func SendGetState

func SendGetState() (bool, *State, error)

SendGetState fetches the daemon's full cached state for GUI initialization. Returns (false, nil, nil) if the daemon is not running.

Example 

package main

import (
    "fmt"

    "github.com/dahui/z13ctl/api"
)

func main() {
    // Fetch the daemon's full cached state for GUI initialization.
    handled, state, err := api.SendGetState()
    if !handled {
        fmt.Println("daemon not running")
        return
    }
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Println("mode:", state.Lighting.Mode)
}

type TDPState

TDPState captures all PPT (Package Power Tracking) values in watts.

type TDPState struct {
    PL1SPL       int `json:"pl1_spl"`       // Sustained Power Limit
    PL2SPPT      int `json:"pl2_sppt"`      // Short Boost
    FPPT         int `json:"fppt"`          // Fast Boost
    APUSPPT      int `json:"apu_sppt"`      // APU Short PPT
    PlatformSPPT int `json:"platform_sppt"` // Platform Short PPT
}

type UndervoltState

UndervoltState captures the AMD Curve Optimizer offset applied to the CPU. Values are non-positive integers (0 = stock, negative = undervolt). Active indicates whether the offset is currently applied to hardware.

type UndervoltState struct {
    CPUCO  int  `json:"cpu_co"` // all-core CPU Curve Optimizer offset
    Active bool `json:"active"` // true when CO is applied to hardware
}

Generated by gomarkdoc