fileformat

type DiffEntry ¶

type DiffEntry struct {
	Field  string `json:"field"`
	AField string `json:"a"`
	BField string `json:"b"`
	Same   bool   `json:"same"`
}

DiffEntry is one field-level difference between two parsed files. AField / BField hold the rendered values; Same is true iff they match.

type DiffResult ¶

type DiffResult struct {
	FormatA    Format      `json:"format_a"`
	FormatB    Format      `json:"format_b"`
	SameFormat bool        `json:"same_format"`
	Entries    []DiffEntry `json:"entries"`
}

DiffResult is the structural comparison of two parsed models. Format mismatches surface as SameFormat=false and an empty Entries slice.

func Diff(aFormat Format, a any, bFormat Format, b any) (*DiffResult, error)

type Format ¶

type Format string

Format identifies one of the four supported file formats. Returned by DetectFormat and LoadFile so callers don't have to re-sniff extensions.

const (
	FormatSub  Format = "sub"
	FormatNFC  Format = "nfc"
	FormatIR   Format = "ir"
	FormatRFID Format = "rfid"
)

func DetectFormat(path string) (Format, error)

func LoadFile(path string, raw []byte) (any, Format, error)

type FreqmanEntry ¶ added in v0.52.0

type FreqmanEntry struct {
	Frequency   uint64
	RangeStart  uint64
	RangeEnd    uint64
	Modulation  string
	Bandwidth   string
	Step        string
	Description string
	Extra       map[string]string
}

FreqmanEntry is one row of a Freqman / PortaPack-Mayhem signal list.

Freqman is the de-facto interop format shared between HackRF/PortaPack- Mayhem, OpenSDR, and several Flipper community tools. Each entry is a single comma-separated `key=value` line. There are two shapes:

• **single-frequency**: Frequency != 0, RangeStart == 0, RangeEnd == 0. Encoded as `f=<Hz>,m=<mod>,bw=<n>,s=<step>,d=<desc>`.
• **range scan**: RangeStart != 0 && RangeEnd != 0, Frequency == 0. Encoded as `a=<startHz>,b=<endHz>,m=<mod>,bw=<n>,s=<step>,d=<desc>`.

All non-frequency fields are optional. Bandwidth and Step are preserved as strings (rather than numerics) because the upstream format mixes raw Hz, kHz suffixes, and named presets ("AM_DSB_5KHZ") in different forks; we keep what the file says verbatim so a round-trip is exact.

Extra holds any `key=value` pairs we don't model (tone=, p=, etc.) so a firmware-fork extension survives Parse → Marshal unchanged.

func FreqmanFromSub(sub *SubFile, description string) (*FreqmanEntry, error)

func (e FreqmanEntry) IsRange() bool

func (e FreqmanEntry) ToSubLite() (*SubFile, error)

type FreqmanList ¶ added in v0.52.0

type FreqmanList struct {
	Entries []FreqmanEntry
}

FreqmanList is an ordered sequence of FreqmanEntry rows. The order matters: PortaPack's frequency-list browser presents entries in file order, so reorder-on-parse would surprise operators.

func ParseFreqman(data []byte) (*FreqmanList, error)

func (l *FreqmanList) Find(query string) *FreqmanEntry

func (l *FreqmanList) Marshal() []byte

func (l *FreqmanList) Sort()

type FreqmanMatch ¶ added in v0.52.0

type FreqmanMatch struct {
	File  string       `json:"file"`
	Line  int          `json:"line"` // 1-based, matches editor convention.
	Entry FreqmanEntry `json:"entry"`
}

FreqmanMatch is one hit returned by SearchFreqmanDir / FilterEntries. File and Line locate the entry within the on-disk library so an operator-facing report can render an actionable pointer back into a firmware-fork's editor.

func SearchFreqmanDir(root, query string, limit int) ([]FreqmanMatch, []error)

type IRBuildParams ¶ added in v0.3.0

type IRBuildParams struct {
	// Name is a display label for the remote. Optional — defaults to
	// "generated".
	Name string

	// Signals is the ordered list of IR entries. Each must have a
	// Name plus either parsed fields or raw fields populated.
	Signals []IRSignal
}

IRBuildParams carries inputs for BuildIR. A valid IR file needs at least one signal; parsed-type signals require Protocol + Address + Command; raw-type signals require Frequency + DutyCycle + Data.

type IRFile ¶

type IRFile struct {
	Filetype string
	Version  int
	Signals  []IRSignal
}

IRFile is a parsed .ir universal-remote / capture file — zero or more signals separated by "#" marker lines.

func ParseIR(data []byte) (*IRFile, error)

func (f *IRFile) Marshal() []byte

type IRSignal ¶

type IRSignal struct {
	Name      string
	Type      string
	Protocol  string
	Address   string
	Command   string
	Frequency int
	DutyCycle float64
	Data      []int
}

IRSignal is one button entry in a Flipper .ir remote file. Parsed-type entries carry Protocol/Address/Command; raw-type entries carry Frequency, DutyCycle, and a Data timing list (microseconds).

type MousejackPayloadParams ¶ added in v0.3.1

type MousejackPayloadParams struct {
	// Script is the DuckyScript body. Lines are trimmed and
	// empty/comment lines dropped. Whitespace-only input errors out.
	Script string

	// TargetOS hints the builder at expected key-combo conventions.
	// Valid: "windows", "macos", "linux". Empty defaults to windows.
	TargetOS string

	// MaxDelayMS caps the argument to any DELAY line. Mousejack
	// sessions are 2.4 GHz and flaky — very long delays often lose
	// sync with the receiver. Defaults to 5000 (5s); passing 0
	// applies the default.
	MaxDelayMS int
}

MousejackPayloadParams carries inputs for BuildMousejackPayload. The script is a DuckyScript body — lines of STRING / DELAY / GUI combos etc. that the Mouse Jacker FAP replays at the remote keyboard.

type NFCBuildParams ¶ added in v0.3.0

type NFCBuildParams struct {
	// DeviceType is one of "Mifare Classic", "Mifare Ultralight",
	// "NTAG213", "NTAG215", "NTAG216", etc. Accepted verbatim.
	DeviceType string

	// UID hex, e.g. "AA BB CC DD". Spaces between bytes are tolerated.
	UID string

	// ATQA / SAK are the ISO/IEC 14443 response bytes. Optional —
	// omitted for NTAG variants that don't expose them.
	ATQA string
	SAK  string

	// MifareType (e.g. "1K" / "4K") for Classic captures.
	MifareType string

	// Blocks maps block index → space-separated hex bytes. Optional
	// — a bare UID capture with no Blocks still produces a valid
	// file useful for UID-only emulation.
	Blocks map[int]string
}

NFCBuildParams carries inputs for BuildNFC. DeviceType + UID are the minimum; for Mifare Classic the caller typically supplies ATQA, SAK, and a map of block contents.

type NFCFile ¶

type NFCFile struct {
	Filetype   string
	Version    int
	DeviceType string
	UID        string
	ATQA       string
	SAK        string
	MifareType string
	Blocks     map[int]string
	Headers    map[string]string
}

NFCFile is a parsed Flipper NFC capture. Block contents stay as the raw space-separated hex strings so a round-trip preserves exactly what came off the wire; block numbers are their integer position for easy edits.

func ParseNFC(data []byte) (*NFCFile, error)

func (n *NFCFile) Marshal() []byte

type NRF24Target ¶ added in v0.3.1

type NRF24Target struct {
	// Address is the 5-byte NRF24 pipe address, uppercase
	// colon-separated (e.g. "A1:B2:C3:D4:E5"). The Mouse Jacker FAP
	// matches bytes verbatim — whitespace or lowercase confuses it.
	Address string

	// Rate is the NRF24 data rate the sniffer observed the address at.
	// 1 = 1 Mbps (most Microsoft peripherals), 2 = 2 Mbps (Logitech
	// Unifying / MX family). A '250' value means 250 kbps, rare on
	// modern peripherals.
	Rate int
}

NRF24Target is one captured wireless-peripheral address.

func ParseNRF24Addresses(src string) ([]NRF24Target, []string, error)

type RFIDBuildParams ¶ added in v0.3.0

type RFIDBuildParams struct {
	// KeyType is the LF protocol name: EM4100, HIDProx, Indala,
	// AWID, FDX-A, FDX-B, etc. Accepted verbatim — the caller is
	// responsible for matching the protocol to the data.
	KeyType string

	// Data is the hex payload, e.g. "1A 2B 3C 4D 5E". Spaces
	// between octets are tolerated; non-hex input is rejected.
	Data string
}

RFIDBuildParams carries inputs for BuildRFID. Both KeyType and Data are required.

type RFIDFile ¶

type RFIDFile struct {
	Filetype string
	Version  int
	KeyType  string
	Data     string
	Headers  map[string]string
}

RFIDFile is a parsed Flipper .rfid (125 kHz LF) capture.

func ParseRFID(data []byte) (*RFIDFile, error)

func (r *RFIDFile) Marshal() []byte

type SubBruteforceParams ¶ added in v0.3.0

type SubBruteforceParams struct {
	Frequency uint32 // Hz
	BitCount  int    // typically 24 for Princeton-family protocols
	StartKey  uint64 // inclusive
	EndKey    uint64 // inclusive
	TE        int    // microseconds (defaults to 400 — common Princeton TE)
	Preset    string // optional; defaulted per-band via defaultSubPreset
}

SubBruteforceParams carries the inputs for BuildSubBruteforce. Produces a RAW .sub file encoding Princeton-style OOK pulses for each key in [StartKey, EndKey]. Frequency + bit count + TE are required; the sweep is capped by maxBruteforceKeys to prevent the caller from generating a megabyte-sized file and thrashing the Flipper SD card.

type SubBuildParams ¶ added in v0.3.0

type SubBuildParams struct {
	// Frequency in Hz (e.g. 433920000 for 433.92 MHz). Rejected if
	// zero or outside the 1 MHz–1 GHz range the Flipper CC1101 can
	// reach.
	Frequency uint32

	// Protocol name, e.g. "Princeton", "Keeloq", "RAW". Optional —
	// omitted files default to the RAW / unrecognised path.
	Protocol string

	// Preset name understood by the Flipper firmware. Leave empty to
	// have BuildSub pick a default from the frequency band.
	Preset string

	// Key is a space-separated hex byte string, e.g.
	// "1A 2B 3C 4D 00 00 00 00". Produces the Key: line.
	Key string

	// Bit is the protocol's bit-length (e.g. 24 for Princeton,
	// 32 for Came).
	Bit int

	// TE is the protocol's timing element in microseconds. Defaults
	// to 400 (a common Princeton TE) when zero and Protocol is set.
	TE int

	// RawData produces a RAW file instead of a keyed one. When set,
	// Protocol is overridden to "RAW".
	RawData []int32
}

SubBuildParams carries the inputs for BuildSub. Frequency is the only required field; everything else is optional and falls back to sensible defaults (Preset = Ook650Async which matches the majority of ISM-band captures).

type SubFile ¶

type SubFile struct {
	Filetype  string
	Version   int
	Frequency uint32
	Preset    string
	Protocol  string
	Bit       int
	Key       string
	TE        int
	RawData   []int32
	Headers   map[string]string
}

SubFile is a parsed Flipper Sub-GHz capture file. Both the structured key-file layout and the RAW capture layout share this struct; RawData is populated only when the file is a RAW capture (Filetype contains "RAW").

Headers preserves any key:value lines the parser did not promote into a strongly-typed field — keeps round-tripping lossless for firmware-fork extensions (e.g. Momentum's "Bit Raw Protocol" additions) we don't model.

func ParseSub(data []byte) (*SubFile, error)

func (s *SubFile) Marshal() []byte

type SubFreqSweepParams ¶ added in v0.3.1

type SubFreqSweepParams struct {
	Frequencies []uint32 // Hz, one file produced per entry
	BitCount    int
	StartKey    uint64
	EndKey      uint64
	TE          int
	Preset      string
}

SubFreqSweepParams carries the inputs for BuildSubBruteforceSweep. Produces one RAW .sub byte stream per frequency in the list, each sweeping the same [StartKey, EndKey] range at BitCount bits. The caller pairs the returned byte streams with per-frequency filenames and writes them separately.