qmk-rgb/cmd/qmk-rgb-tool/definition_generate.go

package main

import (
	"encoding/json"
	"fmt"
	"os"
	"path/filepath"
	"strconv"
	"strings"

	"github.com/spf13/cobra"
	intrgb "netdome.biz/paul/qmk-rgb/internal/rgb"
	"netdome.biz/paul/qmk-rgb/internal/spotted"
	"netdome.biz/paul/qmk-rgb/internal/via"
)

// effectRangeProbe is what `keyboard definitions generate` needs from a keyboard:
// the effect IDs each channel takes, a way to close it, and the two Vial calls
// that may answer the question without writing to it.
//
// It is deliberately not a method on rgbProtocol, because that interface is what
// every other command's test stub implements and a probe is not something
// brightness and colour have to know about.
type effectRangeProbe interface {
	EffectTop(via.Channel) (int, error)
	VialVersion() (uint32, bool, error)
	VialEffectIDs() ([]uint16, error)
	Close() error
}

// slotsFrom is where a channel's effect slots came from. It is reported per
// channel because the two answers are not the same kind of thing: one is the
// firmware listing what it compiled in, the other is the firmware's answer to a
// value written above the top.
type slotsFrom string

const (
	// slotsMeasured means the range was found by writing above the top and
	// reading back what the firmware clamped to.
	slotsMeasured slotsFrom = "measured by clamping"
	// slotsReported means the firmware listed them itself, which is Vial's
	// vialrgb_get_supported and nothing else.
	slotsReported slotsFrom = "reported by the firmware"
)

// experimentalVial marks the Vial path. It is written from Vial's source and
// tested against a scripted keyboard, and nobody has run it against a Vial
// keyboard, so every command that uses it says so rather than presenting an
// unverified answer as a measurement. Remove the word when a real one has.
const experimentalVial = "experimental"

// generateForce replaces a definition that is already stored. It is the same
// rule `keyboard fetch` follows, for the same reason: the file may be one the
// user has written themselves, and this command is the one they would have run
// to write it.
var generateForce bool

// The value IDs a VIA lighting menu addresses, from quantum/via.h. They are the
// same bytes on every lighting subsystem, which is why one scaffold covers every
// channel.
const (
	viaValueBrightness = 0x01
	viaValueEffect     = 0x02
	viaValueSpeed      = 0x03
)

// NewKeyboardDefinitionsGenerateCmd is `keyboard definitions generate`. It writes
// a definition for a board that has none, with the effect slots the keyboard
// reports and no names in them, plus a note beside it saying which spellings
// other keyboards' definitions use for the same numbers.
//
// The names are the user's to write, and the command does not write them into
// the definition: a name it put there would read as the manufacturer's own, and
// nothing in a file can be read back off a keyboard to check it. An option with
// an empty name is a slot without a name, so the channel reports no effects
// until one is filled in — which is the honest state, and the same one a board
// with no definition reports.
func NewKeyboardDefinitionsGenerateCmd() *cobra.Command {
	cmd := &cobra.Command{
		Use:   "generate",
		Short: "Write a definition for the connected keyboard, with the effect names left to you",
		Long: experimentalVial + ": the Vial path below has not been run against a Vial keyboard.\n\n" +
			"Ask the keyboard how many effect IDs each of its lighting channels takes, then\n" +
			"write a definition file with one unnamed option per ID, and a note beside it\n" +
			"saying which spellings other keyboards' definitions use for the same numbers.\n\n" +
			"The names are yours to write: open the file and put one in each options entry,\n" +
			"and the channel starts resolving them. Nothing in a file can be read back off a\n" +
			"keyboard, so a name the tool wrote would be indistinguishable from the\n" +
			"manufacturer's, and a wrong name is worse than none: the tool reports an effect\n" +
			"as unknown and set by number until you fill it in.\n\n" +
			"A definition already stored for this keyboard is not replaced, because it is\n" +
			"probably the one you wrote. Edit it, or pass --force.\n\n" +
			"A keyboard running Vial firmware is asked for its rgb_matrix effect IDs instead of\n" +
			"being written to, which is the better answer, and it numbers them in its own\n" +
			"namespace rather than QMK's. Every channel says where its slots came from.",
		Args: cobra.NoArgs,
		RunE: runKeyboardDefinitionsGenerate,
	}
	cmd.Flags().BoolVar(&generateForce, "force", false,
		"Replace a definition that is already stored, discarding whatever that file holds")
	return cmd
}

func runKeyboardDefinitionsGenerate(cmd *cobra.Command, args []string) error {
	proto, target, channels, err := openTarget("")
	if err != nil {
		return err
	}
	defer proto.Close()

	probe, ok := proto.(effectRangeProbe)
	if !ok {
		return fmt.Errorf("this build cannot read a keyboard's effect range")
	}

	stored := storedDefinitionsFor(definitionsPath(), target.Device.VendorID, target.Device.ProductID)
	if len(stored) > 0 && !generateForce {
		return fmt.Errorf("a definition for %s (0x%04X/0x%04X) is already at %s; it is probably the one "+
			"you wrote, so generate does not replace it, use --force to overwrite it or edit that file",
			stored[0].Name, target.Device.VendorID, target.Device.ProductID, describeDataDir(stored[0].Path))
	}

	// The built-in set is checked as well, and for a different reason than the
	// directory above. A definition the binary carries is the vendor's own file and
	// the user directory shadows it, so a scaffold written for such a board would
	// take it from the names it has to none — a loss the generated file could not
	// report, because the file is the one that is read. `fetch` has the same
	// shadowing and is allowed it, because a fetched file is the vendor's file too
	// and carries more than a scaffold does.
	if !generateForce {
		for _, def := range builtInDefinitions() {
			if !def.Matches(target.Device.VendorID, target.Device.ProductID) {
				continue
			}
			return fmt.Errorf("this binary carries a definition for %s (0x%04X/0x%04X) that names %d "+
				"effects, and a file in the definitions directory would shadow it; a generated one names "+
				"none, so the board would go from %d names to no effect names at all, use --force to do "+
				"that anyway, or edit the built-in file's copy in the definitions directory",
				def.Name, def.VendorID, def.ProductID, namedEffectCount(def), namedEffectCount(def))
		}
	}

	if len(channels) == 0 {
		return fmt.Errorf("this keyboard exposes no VIA lighting channels, so there is nothing to " +
			"generate a definition for")
	}

	name := scaffoldName(target.Device.Name)
	doc := scaffoldDefinition{
		Name:      name,
		VendorID:  fmt.Sprintf("0x%04X", target.Device.VendorID),
		ProductID: fmt.Sprintf("0x%04X", target.Device.ProductID),
	}
	notes := &strings.Builder{}

	// Vial can list the rgb_matrix effect IDs without the keyboard being written
	// to. It is asked first because its answer is the better one, and only where
	// the firmware serves it: VIALRGB_ENABLE is a build option, and a Vial
	// keyboard without it answers nothing.
	version, isVial, err := probe.VialVersion()
	if err != nil {
		return err
	}
	if isVial {
		fmt.Fprintf(cmd.OutOrStdout(), "This keyboard answers as Vial firmware, protocol version %d (%s: not run against real hardware)\n",
			version, experimentalVial)
	}

	sources := map[via.Channel]slotsFrom{}
	slots := map[via.Channel][]uint16{}

	for _, ch := range channels {
		ids, from, err := slotsFor(probe, ch, isVial)
		if err != nil {
			return err
		}
		if menu := scaffoldMenu(ch, ids); len(menu.Content) > 0 {
			doc.Menus = append(doc.Menus, menu)
		}
		sources[ch] = from
		slots[ch] = ids
		writeCandidates(notes, ch, ids, from)
	}

	dir, err := ensureDefinitionsDir()
	if err != nil {
		return err
	}
	base := definitionFileName(&fetchedDefinition{
		Definition: &intrgb.Definition{
			Name:      name,
			VendorID:  target.Device.VendorID,
			ProductID: target.Device.ProductID,
		},
	})

	encoded, err := json.MarshalIndent(doc, "", "  ")
	if err != nil {
		return err
	}
	path := filepath.Join(dir, base)
	if err := os.WriteFile(path, append(encoded, '\n'), 0o644); err != nil {
		return fmt.Errorf("write %s: %w", path, err)
	}

	notePath := strings.TrimSuffix(path, ".json") + spottedNoteSuffix
	if err := os.WriteFile(notePath, []byte(notes.String()), 0o644); err != nil {
		return fmt.Errorf("write %s: %w", notePath, err)
	}

	verb := "Wrote"
	if len(stored) > 0 {
		verb = "Replaced"
	}
	fmt.Fprintf(cmd.OutOrStdout(), "%s a definition for %s (%s/%s) to %s\n",
		verb, doc.Name, doc.VendorID, doc.ProductID, describeDataDir(path))
	fmt.Fprintf(cmd.OutOrStdout(), "Every effect is an unnamed option. Open the file and write a name into each one:\n")
	for _, ch := range channels {
		ids, ok := slots[ch]
		if !ok {
			continue
		}
		fmt.Fprintf(cmd.OutOrStdout(), "  %-10s %d slots, IDs %s  (%s)\n",
			ch.Subsystem(), len(ids), describeSlotRange(ids), sources[ch])
	}
	fmt.Fprintf(cmd.OutOrStdout(), "\nWhat other keyboards call the same numbers is in %s\n", describeDataDir(notePath))
	return nil
}

// spottedNoteSuffix names the note beside a generated definition. It is not a
// .json file, so the definitions directory does not read it as one: it carries
// no definition, only what was seen.
const spottedNoteSuffix = ".spotted.txt"

// scaffoldName is the board's name in a generated definition. A keyboard that
// reports no product string gets a name that says so rather than an empty one,
// which would match nothing and read as a broken file.
func scaffoldName(productString string) string {
	if strings.TrimSpace(productString) == "" {
		return "Unnamed keyboard"
	}
	return productString
}

// scaffoldDefinition is the shape of a VIA definition with nothing in it yet.
// The identifiers are the board's, so the file is matched to it the way any
// other definition is.
type scaffoldDefinition struct {
	Name string `json:"name"`
	// The identifiers are hex strings, which is how a definition file spells them
	// and how the parser reads them back. VIA's own served files carry the
	// packed number instead; both are read and this is the one a human edits.
	VendorID  string          `json:"vendorId"`
	ProductID string          `json:"productId"`
	Menus     []scaffoldMenuT `json:"menus"`
}

type scaffoldMenuT struct {
	Label   string          `json:"label"`
	Content []scaffoldEntry `json:"content"`
}

type scaffoldEntry struct {
	Label   string `json:"label"`
	Type    string `json:"type"`
	Content []any  `json:"content"`
	Options any    `json:"options,omitempty"`
}

// slotsFor returns the effect IDs a channel has and where that came from.
//
// Vial is asked only for rgb_matrix, because VialRGB is an rgb_matrix extension:
// there is no Vial list for backlight, rgblight, audio or led_matrix, and those
// keep the clamping answer. A Vial keyboard without VIALRGB_ENABLE answers
// nothing, which is an error rather than an empty list, and it falls back to the
// measurement because a board that cannot list its effects can still be asked.
func slotsFor(probe effectRangeProbe, ch via.Channel, isVial bool) ([]uint16, slotsFrom, error) {
	if isVial && ch == via.ChannelRgbMatrix {
		ids, err := probe.VialEffectIDs()
		if err == nil && len(ids) > 0 {
			return ids, slotsReported, nil
		}
		if err != nil {
			fmt.Fprintf(os.Stderr, "vialrgb effect list on %s unavailable (%v), falling back to the clamp\n", ch.Subsystem(), err)
		}
	}
	top, err := probe.EffectTop(ch)
	if err != nil {
		return nil, "", err
	}
	ids := make([]uint16, 0, top+1)
	for id := 0; id <= top; id++ {
		ids = append(ids, uint16(id))
	}
	return ids, slotsMeasured, nil
}

// describeSlotRange writes a list of IDs as a range when it is one, because
// "0 to 45" says in six characters what a list of forty-six does not.
func describeSlotRange(ids []uint16) string {
	if len(ids) == 0 {
		return "none"
	}
	runs := true
	for i := 1; i < len(ids); i++ {
		if ids[i] != ids[i-1]+1 {
			runs = false
			break
		}
	}
	if runs {
		return fmt.Sprintf("%d to %d", ids[0], ids[len(ids)-1])
	}
	shown := ids
	if len(shown) > 8 {
		shown = append(append([]uint16{}, ids[:8]...), 0xFFFF)
	}
	parts := make([]string, 0, len(shown))
	for _, id := range shown {
		if id == 0xFFFF {
			parts = append(parts, "...")
			continue
		}
		parts = append(parts, strconv.Itoa(int(id)))
	}
	return strings.Join(parts, ", ")
}

// scaffoldMenu is one lighting channel as a VIA menu: the three controls the
// value IDs name, with the effect list holding one unnamed option per slot. The
// name is the channel's own, so the file names it the way the tool does rather
// than inventing a label — a board the user fills in can rename it.
func scaffoldMenu(ch via.Channel, ids []uint16) scaffoldMenuT {
	valueKey, ok := intrgb.EffectValueKey(ch)
	if !ok {
		// A channel with no registered value key has no list this tool reads, so
		// it is left out rather than written as something that would not load.
		return scaffoldMenuT{}
	}
	channel := int(ch)
	// The three controls address different value IDs under keys that share the
	// effect key's prefix, and the prefix ends where "_effect" starts. Trimming
	// the suffix and putting the underscore back is what keeps a key spelled
	// `id_qmk_rgb_matrix_brightness` rather than one the parser will not find.
	prefix := strings.TrimSuffix(valueKey, "_effect")

	options := make([][]any, 0, len(ids))
	for _, id := range ids {
		// The empty name is the point: it states a slot without naming it, and the
		// parser skips it, so the channel reports no effects until a name is
		// written here.
		options = append(options, []any{"", id})
	}

	return scaffoldMenuT{
		Label: ch.Subsystem(),
		Content: []scaffoldEntry{
			{
				Label:   "Brightness",
				Type:    "range",
				Content: []any{prefix + "_brightness", channel, viaValueBrightness},
				Options: []any{0, 255},
			},
			{
				Label:   "Effect",
				Type:    "dropdown",
				Content: []any{valueKey, channel, viaValueEffect},
				Options: options,
			},
			{
				Label:   "Effect Speed",
				Type:    "range",
				Content: []any{prefix + "_effect_speed", channel, viaValueSpeed},
				Options: []any{0, 255},
			},
		},
	}
}

// writeCandidates records what other keyboards' definitions were seen to call
// each ID, with the counts and the manufacturer, because a name without those is
// a guess wearing a number.
func writeCandidates(out *strings.Builder, ch via.Channel, ids []uint16, from slotsFrom) {
	valueKey, ok := intrgb.EffectValueKey(ch)
	if !ok {
		return
	}
	fmt.Fprintf(out, "\n%s (channel %d), %d slots, IDs %s  (%s)\n",
		ch.Subsystem(), ch, len(ids), describeSlotRange(ids), from)

	if from == slotsReported {
		// The firmware that listed these numbers numbers them in its own
		// namespace, and the measurement below is QMK's. Saying "here is what
		// other boards call ID 7" next to a slot that is not QMK's ID 7 is the one
		// thing this note must not do.
		fmt.Fprintf(out, "  These IDs are the firmware's own numbering, not QMK's: the list the firmware sends\n")
		fmt.Fprintf(out, "  is VIALRGB_EFFECT_* and the translation to QMK's stays inside the firmware. The\n")
		fmt.Fprintf(out, "  spellings other keyboards use are indexed by QMK's numbers, so they are not listed here.\n")
		return
	}
	seen := 0
	for _, id := range ids {
		obs, ok := spotted.Candidates(valueKey, int(id))
		if !ok {
			continue
		}
		seen++
		names := make([]string, 0, len(obs.Candidates))
		for _, c := range obs.Candidates {
			names = append(names, fmt.Sprintf("%s (%d)", c.Name, c.Count))
		}
		line := fmt.Sprintf("  ID %-3d seen on %3d boards: %s", id, obs.Boards, strings.Join(names, ", "))
		if obs.TopVendor != "" && obs.TopVendorCount > 0 {
			line += fmt.Sprintf("   most of them %s (%d)", obs.TopVendor, obs.TopVendorCount)
		}
		fmt.Fprintln(out, line)
	}
	if seen == 0 {
		fmt.Fprintf(out, "  no definition anywhere names an effect on this channel\n")
	}
}

// namedEffectCount is how many effects a definition names across the channels it
// covers. A file is a board's whole catalog, so the number the user loses is the
// total and not the largest channel.
func namedEffectCount(def *intrgb.Definition) int {
	total := 0
	for _, ch := range via.LightingChannels {
		total += len(def.Catalog.Effects(ch))
	}
	return total
}