altbeacon

Documentation

Overview

Package altbeacon decodes and builds AltBeacon BLE advertisements — the open, vendor-neutral beacon standard (github.com/AltBeacon/spec), the counterpart to Apple iBeacon and Google Eddystone.

Wrap-vs-native judgement

Native. AltBeacon is a fully open public specification: a manufacturer-specific-data AD structure of a 2-byte company ID, the 0xBEAC beacon code, a 20-byte beacon ID, a 1-byte reference RSSI, and a 1-byte manufacturer-reserved value. Decoding and encoding are pure byte assembly with no crypto and no hardware — paste the hex from a btmon / Wireshark capture and decode offline, or build the payload an operator advertises from a beacon for a proximity test. Generation-only on the encode side: it advertises nothing and touches no radio, so it is Low risk like the other beacon codecs. Correctness is verifiable two ways: round-trip between Decode and Encode, and the canonical worked example in the AltBeacon spec (company 0x0118, beacon code BE AC, ref RSSI 0xC5).

Covered

• The full 24-byte AltBeacon body (beacon code + 20-byte beacon ID + reference RSSI + mfg-reserved) behind any of three input framings: the full advertising-data record (<len> FF <mfgid> ...), the bare manufacturer-specific-data payload (<mfgid> BE AC ...), or a payload that already starts at the 0xBEAC beacon code.
• The common interpretation of the 20-byte beacon ID as a 16-byte proximity UUID + 2-byte major + 2-byte minor is surfaced alongside the opaque 20-byte form, labelled as a convenience (the spec treats the beacon ID as opaque).

Index

• Constants
• func Encode(r EncodeRequest) ([]byte, error)
• type AltBeacon
  • func Decode(hexStr string) (*AltBeacon, error)
• type EncodeRequest

Constants

const BeaconCode uint16 = 0xBEAC

BeaconCode is the 0xBEAC marker that identifies an AltBeacon body, transmitted big-endian (BE AC).

const DefaultMfgID uint16 = 0x0118

DefaultMfgID is the company ID used when none is supplied — Radius Networks (0x0118), the AltBeacon spec author, matching the spec example.

Functions

func Encode

func Encode(r EncodeRequest) ([]byte, error)

Encode builds the bytes of an AltBeacon advertisement — the inverse of Decode, round-trip-verified against it. The beacon ID must be exactly 20 bytes. Generation only; it advertises nothing.

Types

type AltBeacon

type AltBeacon struct {
	MfgID       uint16 `json:"mfg_id"`       // advertiser company ID (little-endian on the wire)
	MfgIDHex    string `json:"mfg_id_hex"`   // "0x0118"
	BeaconCode  string `json:"beacon_code"`  // always "0xBEAC" for a valid frame
	BeaconID    string `json:"beacon_id"`    // 20-byte opaque ID (hex)
	RefRSSI     int8   `json:"ref_rssi_dbm"` // reference RSSI at 1 m
	MfgReserved int    `json:"mfg_reserved"` // manufacturer-reserved byte
	OuterFormat string `json:"outer_format"` // ad_record | manufacturer_data | beacon_code
	Hex         string `json:"hex"`          // full payload as decoded (hex)
	CommonUUID  string `json:"common_uuid"`  // beacon ID bytes 0..15 as a dashed UUID (convenience)
	CommonMajor uint16 `json:"common_major"` // beacon ID bytes 16..17 (convenience)
	CommonMinor uint16 `json:"common_minor"` // beacon ID bytes 18..19 (convenience)
}

AltBeacon is the decoded view of an AltBeacon advertisement.

func Decode

func Decode(hexStr string) (*AltBeacon, error)

Decode parses a hex-encoded AltBeacon advertisement. Three framings are accepted; the parser strips any prefix it recognises before the 0xBEAC beacon code: the full advertising-data record (<len> FF <mfgid> BE AC …), the bare manufacturer-specific-data payload (<mfgid> BE AC …), or a payload already starting at the beacon code (BE AC …, mfg ID unknown).

type EncodeRequest

type EncodeRequest struct {
	MfgID       uint16 `json:"mfg_id"`       // advertiser company ID (default 0x0118 Radius Networks)
	BeaconID    string `json:"beacon_id"`    // 20-byte beacon ID as hex (required)
	RefRSSI     int8   `json:"ref_rssi_dbm"` // reference RSSI at 1 m
	MfgReserved int    `json:"mfg_reserved"` // manufacturer-reserved byte (0..255)
	// Wrap: "manufacturer" (default; <mfgid> BE AC …) or "ad" (the full
	// <len> FF <mfgid> BE AC … advertising-data record).
	Wrap string `json:"wrap,omitempty"`
}

EncodeRequest describes an AltBeacon to build.