doc.go

// Package hackrf is a complete, 1:1 cgo wrapper around libhackrf, the host
// library for Great Scott Gadgets' HackRF software defined radios.
//
// It exposes the entire public surface area of libhackrf's hackrf.h: library
// initialization, device discovery/opening/closing, RF configuration (tuning,
// sample rate, gains, filtering, clocking, bias-tee), RX/TX/sweep streaming
// with callbacks, Opera Cake add-on board control, and the low-level
// debug/firmware-flashing functions (register access, SPI flash, CPLD, etc.).
//
// # Building
//
// This package requires libhackrf and its headers to be installed. On macOS
// with Homebrew:
//
//	brew install hackrf
//
// On Debian/Ubuntu:
//
//	sudo apt install libhackrf-dev
//
// The cgo directives in this package default to the standard Homebrew prefix
// on darwin and the system search paths on linux. If your installation lives
// elsewhere, override CGO_CFLAGS / CGO_LDFLAGS, e.g.:
//
//	export CGO_CFLAGS="-I/some/prefix/include"
//	export CGO_LDFLAGS="-L/some/prefix/lib -lhackrf"
//
// # Lifecycle
//
// Call [Init] once at startup and [Exit] once at shutdown. Between them, open
// one or more devices with [Open], [OpenBySerial] or via a [DeviceList], use
// them, and [Device.Close] each before calling [Exit].
//
//	if err := hackrf.Init(); err != nil { ... }
//	defer hackrf.Exit()
//
//	dev, err := hackrf.Open()
//	if err != nil { ... }
//	defer dev.Close()
//
//	dev.SetFreq(2_400_000_000)
//	dev.SetSampleRate(10_000_000)
//	dev.SetVGAGain(20)
//
// # Streaming and callbacks
//
// Streaming callbacks run on libhackrf's internal libusb transfer thread, not
// on a goroutine you control. Per the libhackrf contract, do NOT call other
// libhackrf functions from inside a transfer callback. Signal your main
// goroutine (e.g. via a channel) and call [Device.StopRX] / [Device.StopTX]
// from there. For TX, prefer signaling stop from the flush callback set with
// [Device.EnableTxFlush] so no samples are lost.
//
// The byte slice in a [Transfer] aliases a C buffer owned by libhackrf and is
// only valid for the duration of the callback. Do not retain it; copy out
// anything you need to keep.
package hackrf