btuuid

Documentation

Overview

Package btuuid resolves Bluetooth SIG-assigned 16-bit GATT UUIDs (Services, Characteristics, Descriptors) to their canonical names. Pure offline parser; no transport, no hardware.

Wrap-vs-native judgement: the Bluetooth SIG Assigned Numbers document is fully public. The lookup is a small map + 128-bit UUID base-pattern detector. Wrapping a FAP for this would require an SD-card install + a firmware-fork dependency for a pure lookup. Native delivers offline analysis — operators enumerating a BLE GATT database (with bluetoothctl / nRF Connect / btmon / Flipper BT scan) paste each UUID they see and get the canonical name + category back without re-running the enumeration.

Pairs with the existing BLE decoders (ble_gap_decode for advertisement records, ble_continuity_decode for Apple manufacturer data, ble_eddystone_decode for Google service data, bluetooth_cod_decode for the BT Classic side).

What this package covers:

• 16-bit UUID lookup: ~75 Services (0x18xx + assorted 0xFEXX) + ~250 Characteristics (0x2A0X range) + ~50 Descriptors (0x2900 range)
• 128-bit UUID detection: matches the standard base UUID 0000XXXX-0000-1000-8000-00805F9B34FB to extract the 16-bit short form, otherwise reports as "vendor-specific"
• Per-UUID category ("Service", "Characteristic", "Descriptor") for routing decisions downstream

What this package does NOT cover (deliberately out of scope):

• SIG-assigned 32-bit UUIDs (rarely seen in practice)
• Vendor-specific 128-bit UUIDs (vendors don't publish a central catalog — operators look these up manually)
• GATT read/write semantics or characteristic interpretation (just the name resolution)

Index

• type Result
  • func Lookup(s string) (Result, error)

Types

type Result

type Result struct {
	// Input is the operator-supplied UUID string after
	// normalisation (uppercase, no separators).
	Input string `json:"input"`
	// ShortUUID is the 16-bit short form when the input is
	// either a 16-bit hex or a 128-bit UUID matching the SIG
	// base pattern. Empty for unrecognised 128-bit UUIDs.
	ShortUUID string `json:"short_uuid,omitempty"`
	// CanonicalUUID is the 128-bit form
	// (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) — always
	// populated for valid inputs.
	CanonicalUUID string `json:"canonical_uuid"`
	// Name is the SIG-assigned canonical name when in our
	// catalog, "" otherwise.
	Name string `json:"name,omitempty"`
	// Category is "Service", "Characteristic", "Descriptor",
	// or "" for unrecognised UUIDs.
	Category string `json:"category,omitempty"`
	// Vendor is true when the UUID is 128-bit and doesn't match
	// the SIG base pattern (i.e. it's a vendor-allocated
	// random UUID).
	VendorSpecific bool `json:"vendor_specific"`
}

Result is the resolved UUID metadata.

func Lookup

func Lookup(s string) (Result, error)

Lookup resolves a UUID string against the catalog. Accepts:

• 16-bit short form: "180F", "0x180F", "180f"
• 128-bit canonical: "0000180F-0000-1000-8000-00805F9B34FB"
• 128-bit unhyphenated: "0000180F00001000800000805F9B34FB"

Tolerates ':' / '-' / '_' / whitespace separators.