protocol

README

Notes on PixelPusher protocol.

Most of this protocol is reverse-engineered from code in the PixelPusher-java repository.

PixelPusher uses UDP packets. A packet is either;:

• A command.
• A LED state.

Each packet begins with a 4-byte big-endien number identifying the packet's index. This index is unique per packet and increments with each successive packet.

Command packets are formatted:

• Packet index (4 bytes).
• Command magic sequence (16 bytes).
• Command identification (1 byte).
• Command data (remainder).

LED states are formatted:

• Packet index (4 bytes).
• Repeated sequences of:
  • Strip Number (1 byte)
  • Strip State, consisting of PixelsPerStrip sequences of either:
    • RGBOW (if SFLAG_RGBOW is set)
      • Red (1 byte)
      • Green (1 byte)
      • Blue (1 byte)
      • Orange (3 bytes, all identical)
      • White (3 bytes, all identical)
    • RGB
      • Red (1 byte)
      • Green (1 byte)
      • Blue (1 byte)

Documentation

Overview

Package protocol contains PixelPusher wire definitions.

Index

• Constants
• type DeviceHeader
  • func (h *DeviceHeader) HardwareAddr() net.HardwareAddr
  • func (h *DeviceHeader) IP4Address() net.IP
  • func (h *DeviceHeader) SetHardwareAddr(addr net.HardwareAddr)
  • func (h *DeviceHeader) SetIP4Address(ip net.IP)
• type DeviceType
  • func (dt DeviceType) String() string
• type DiscoveryHeaders
  • func ParseDiscoveryHeaders(data []byte) (*DiscoveryHeaders, error)
  • func (dh *DiscoveryHeaders) Addr() net.Addr
  • func (dh *DiscoveryHeaders) Clone() *DiscoveryHeaders
  • func (dh *DiscoveryHeaders) NumPixels() int
  • func (dh *DiscoveryHeaders) NumStrips() int
  • func (dh *DiscoveryHeaders) PacketReader() (*PacketReader, error)
  • func (dh *DiscoveryHeaders) PacketStream() (*PacketStream, error)
  • func (dh *DiscoveryHeaders) String() string
  • func (dh *DiscoveryHeaders) WritePacket(w io.Writer) error
• type Packet
• type PacketReader
  • func (pr *PacketReader) ReadPacket(r *byteslicereader.R, pkt *Packet) error
• type PacketStream
  • func (ps *PacketStream) Flush(ds network.DatagramSender) error
  • func (ps *PacketStream) Send(ds network.DatagramSender, pkt *Packet) error

Constants

const (
	// DefaultProtocolVersion is the default protocol version.
	//
	// A value of 1 was observed on modern PixelPusher devices.
	DefaultProtocolVersion = 1

	// DiscoveryUDPPort is the UDP port on which devices multicast announce over.
	DiscoveryUDPPort = 7331
)

Types

type DeviceHeader

type DeviceHeader struct {
	MacAddress       [6]byte
	IPAddress        [4]byte
	DeviceType       DeviceType
	ProtocolVersion  uint8
	VendorID         uint16 `struc:",little"`
	ProductID        uint16 `struc:",little"`
	HardwareRevision uint16 `struc:",little"`
	SoftwareRevision uint16 `struc:",little"`

	// The link speed, in bits-per-second.
	LinkSpeed uint32 `struc:",little"`
}

DeviceHeader is a discovery-related packet that represents a single device.

/**

• Device Header format:
• uint8_t mac_address[6];
• uint8_t ip_address[4];
• uint8_t device_type;
• uint8_t protocol_version; // for the device, not the discovery
• uint16_t vendor_id;
• uint16_t product_id;
• uint16_t hw_revision;
• uint16_t sw_revision;
• uint32_t link_speed; // in bits per second */

func (*DeviceHeader) HardwareAddr

func (h *DeviceHeader) HardwareAddr() net.HardwareAddr

HardwareAddr returns the MacAddress field as a net.HardwareAddr.

func (*DeviceHeader) IP4Address

func (h *DeviceHeader) IP4Address() net.IP

IP4Address returns a net.IP derived from the IPAddress field.

func (*DeviceHeader) SetHardwareAddr

func (h *DeviceHeader) SetHardwareAddr(addr net.HardwareAddr)

SetHardwareAddr sets the MacAddress value to addr.

func (*DeviceHeader) SetIP4Address

func (h *DeviceHeader) SetIP4Address(ip net.IP)

SetIP4Address sets the IPAddress field from a net.IP.

type DeviceType

type DeviceType uint8

DeviceType is an enumeration representing the type of device in a DeviceHeader.

const (
	// EtherDreamDeviceType is the DeviceType for the EtherDream.
	EtherDreamDeviceType DeviceType = 0
	// LumiaBridgeDeviceType is the DeviceType for the LumiaBridge.
	LumiaBridgeDeviceType DeviceType = 1
	// PixelPusherDeviceType is the DeviceType for the PixelPusher.
	PixelPusherDeviceType DeviceType = 2
)

func (DeviceType) String

func (dt DeviceType) String() string

type DiscoveryHeaders

type DiscoveryHeaders struct {
	// DeviceHeader describes the generic device.
	DeviceHeader

	// PixelPusher describes the PixelPusher in detail.
	PixelPusher *pixelpusher.Device
}

DiscoveryHeaders is the set of information contained in a discovery packet.

NOTE: Since only PixelPusher devices are supported at the moment, this will always exist and be populated.

func ParseDiscoveryHeaders

func ParseDiscoveryHeaders(data []byte) (*DiscoveryHeaders, error)

ParseDiscoveryHeaders parses discovery packet headers from provided byte array.

If the device headers are invalid, or if all of the data was not consumed, an error will be returned.

func (*DiscoveryHeaders) Addr

func (dh *DiscoveryHeaders) Addr() net.Addr

Addr returns this device's network address, as described by its headers.

func (*DiscoveryHeaders) Clone

func (dh *DiscoveryHeaders) Clone() *DiscoveryHeaders

Clone creates a deep copy of dh.

func (*DiscoveryHeaders) NumPixels

func (dh *DiscoveryHeaders) NumPixels() int

NumPixels returns the total number of pixels represented by dh.

IF the number could not be determined, NumLEDs will return 0.

func (*DiscoveryHeaders) NumStrips

func (dh *DiscoveryHeaders) NumStrips() int

NumStrips returns the number of strips represented by dh.

IF the number could not be determined, NumLEDs will return 0.

func (*DiscoveryHeaders) PacketReader

func (dh *DiscoveryHeaders) PacketReader() (*PacketReader, error)

PacketReader creates a configured PacketReader instance for this device.

func (*DiscoveryHeaders) PacketStream

func (dh *DiscoveryHeaders) PacketStream() (*PacketStream, error)

PacketStream creates a configured PacketStream instance for this device.

func (*DiscoveryHeaders) String

func (dh *DiscoveryHeaders) String() string

func (*DiscoveryHeaders) WritePacket

func (dh *DiscoveryHeaders) WritePacket(w io.Writer) error

WritePacket writes a discovery packet to w.

type Packet

type Packet struct {
	// PixelPusher is the PixelPusher packet data. It will be populated if this
	// packet is a PixelPusher packet.
	PixelPusher *pixelpusher.Packet
}

Packet is a generic interpreted command.

Only one field in the Packet should be populated.

type PacketReader

type PacketReader struct {
	// PixelPusher is the PixelPusher-specific implementation of a packet reader.
	PixelPusher *pixelpusher.PacketReader
}

PacketReader reads packet structure from a stream.

PacketReader is lightweight enough to be created as-needed; however, re-using a PacketReader allows it to re-use its underlhing buffer, which may be more efficient.

PacketReader should generally not be created directly by the user, but instead populated from a device's DiscoveryHeaders' PacketReader method.

PacketReader is not safe for concurrent use.

func (*PacketReader) ReadPacket

func (pr *PacketReader) ReadPacket(r *byteslicereader.R, pkt *Packet) error

ReadPacket reads a Packet, pkt, from a source of data.

If the packet could not be read, ReadPacket returns an error.

The returned packet will reference data slices returned by r, and should not outlive the underlying buffer.

type PacketStream

type PacketStream struct {
	// pixelPusher is a PixelPusher-specific packet stream.
	PixelPusher *pixelpusher.PacketStream
}

PacketStream is the overall state of a packet stream.

PacketStream should generally not be created directly by the user, but instead populated from a device's DiscoveryHeaders' PacketStream method.

PacketStream is not safe for concurrent use.

func (*PacketStream) Flush

func (ps *PacketStream) Flush(ds network.DatagramSender) error

Flush flushes any buffered data to the underlying connection.

func (*PacketStream) Send

func (ps *PacketStream) Send(ds network.DatagramSender, pkt *Packet) error

Send sends the contents of the specified Packet.