sacn

README

sACN in go

A library for sACN (ANSI E1.31) in Go.

Fully supports and complies to the specification:

• All Packet types (Data, Sync and Discovery).
• Receiver with callbacks and stream termination detection.
• Transmitter sending discovery packets.

Usage

go get gitlab.com/patopest/go-sacn

• Receiver

package main

import (
    "fmt"
    "time"
    "net"

    "gitlab.com/patopest/go-sacn"
    "gitlab.com/patopest/go-sacn/packet"
)

func main() {
    fmt.Println("hello")

    itf, _ := net.InterfaceByName("en0") // change based on your machine
    receiver := sacn.NewReceiver(itf)
    receiver.JoinUniverse(1)
    receiver.RegisterPacketCallback(packet.PacketTypeData, dataPacketCallback)
    receiver.Start()

    for {
        time.Sleep(1)
    }
}

func dataPacketCallback(p packet.SACNPacket, source string) {
    d, ok := p.(*packet.DataPacket)
    if ok == false {
        return
    }
    fmt.Printf("Received Data Packet for universe %d from %s\n", d.Universe, source)
}

• Transmitter

package main

import (
    "log"
    "time"

    "gitlab.com/patopest/go-sacn"
    "gitlab.com/patopest/go-sacn/packet"
)

func main() {
    log.Println("Hello")

    opts := sacn.SenderOptions{ // Default for all packets sent by Sender if not provided in the packet itself.
        SourceName: "go-sacn test source"
    }
    sender, err := sacn.NewSender("192.168.1.200", &opts) // Create sender with binding to interface
    if err != nil {
        log.Fatal(err)
    }

    // Initialise universe
    var uni uint16 = 123
    universe, err := sender.StartUniverse(uni)
    if err != nil {
        log.Fatal(err)
    }
    sender.SetMulticast(uni, true)

    // Create new packet and fill it up with data
    p := packet.NewDataPacket()
    p.SetData([]uint8{1, 2, 3, 4})

    sender.Send(uni, p) // send the packet

    sender.StopUniverse(uni) // To stop the universe and advertise termination to receivers

    time.Sleep(1 * time.Second)

    sender.Close() // Close sender and all universes
}

See examples directory for more examples.

Development

• Run an example to test your code

go run examples/receiver/receiver.go

• Tests

go test ./...

References

Similar projects

• sACN-Monitor: An app to view data from all sACN universes, built using this library.
• Hundemeier's go-sacn: Only supports Data packets
• go-artnet
• Open Lighting Architecure (OLA) framework (C implementations of control protocols).

Documentation

• sACN (ANSI E1.31) specification.
• DMX (ANSI E1.11) specification

Documentation

Index

• Constants
• type PacketCallbackFunc
• type Receiver
  • func NewReceiver(itf *net.Interface) *Receiver
  • func (r *Receiver) JoinUniverse(universe uint16) error
  • func (r *Receiver) LeaveUniverse(universe uint16) error
  • func (r *Receiver) RegisterPacketCallback(packetType packet.SACNPacketType, callback PacketCallbackFunc)
  • func (r *Receiver) RegisterTerminationCallback(callback TerminationCallbackFunc)
  • func (r *Receiver) Start()
  • func (r *Receiver) Stop()
• type Sender
  • func NewSender(address string, options *SenderOptions) (*Sender, error)
  • func (s *Sender) AddDestination(universe uint16, destination string) error
  • func (s *Sender) Close()
  • func (s *Sender) GetDestinations(universe uint16) ([]string, error)
  • func (s *Sender) GetUniverses() []uint16
  • func (s *Sender) IsEnabled(universe uint16) bool
  • func (s *Sender) IsMulticast(universe uint16) (bool, error)
  • func (s *Sender) Send(universe uint16, p packet.SACNPacket) error
  • func (s *Sender) SetDestinations(universe uint16, destinations []string) error
  • func (s *Sender) SetMulticast(universe uint16, multicast bool) error
  • func (s *Sender) StartUniverse(universe uint16) (chan<- packet.SACNPacket, error)
  • func (s *Sender) StopUniverse(universe uint16) error
• type SenderOptions
• type TerminationCallbackFunc

Constants

const (
	SACN_PORT                   = 5568  // the sACN UDP port number
	DISCOVERY_UNIVERSE          = 64214 // the universe used for universe discovery
	UNIVERSE_DISCOVERY_INTERVAL = 10    // in seconds
	NETWORK_DATA_LOSS_TIMEOUT   = 2500  // in milliseconds
)

Types

type PacketCallbackFunc

type PacketCallbackFunc func(p packet.SACNPacket, source string)

PacketCallbackFunc is the function type to be used with Receiver.RegisterPacketCallback. The arguments are the latest received packet.SACNPacket on any universe and the source IP that sent the packet as a string.

type Receiver

type Receiver struct {
	// contains filtered or unexported fields
}

A sACN Receiver. Use NewReceiver to create a receiver.

func NewReceiver

func NewReceiver(itf *net.Interface) *Receiver

NewReceiver creates a new receiver bound to the provided interface

func (*Receiver) JoinUniverse

func (r *Receiver) JoinUniverse(universe uint16) error

JoinUniverse starts listening for packets sent on the provided universe. Universe number shall be in the range 1 to 63999. Joins the multicast group associated with the universe number.

func (*Receiver) LeaveUniverse

func (r *Receiver) LeaveUniverse(universe uint16) error

Stops listening for packets sent on a universe. Leaves the multicast groups associated with the universe number.

func (*Receiver) RegisterPacketCallback

func (r *Receiver) RegisterPacketCallback(packetType packet.SACNPacketType, callback PacketCallbackFunc)

RegisterPacketCallback registers a callback of type PacketCallbackFunc. The callback will be triggered on reception of a new packet of type packet.SACNPacketType on any universe

func (*Receiver) RegisterTerminationCallback

func (r *Receiver) RegisterTerminationCallback(callback TerminationCallbackFunc)

RegisterTerminationCallback registers a callback for when a universe enters Network Data Loss conditions as defined in section 6.7.1 of ANSI E1.31—2018.

Network Data Loss conditions:

• Did not receive data for NETWORK_DATA_LOSS_TIMEOUT.
• Data packet contained the StreamTerminated bit in the packet.DataPacket Options field.

func (*Receiver) Start

func (r *Receiver) Start()

Starts the receiver

func (*Receiver) Stop

func (r *Receiver) Stop()

Stops the receiver

type Sender

type Sender struct {
	// contains filtered or unexported fields
}

A sACN Sender. Use NewSender to create a receiver.

func NewSender

func NewSender(address string, options *SenderOptions) (*Sender, error)

NewSender creates a new Sender. Optionally pass a bind string of the host's ip address it should bind to (eg: "192.168.1.100"). This is mandatory if multicast is being used on any universe.

func (*Sender) AddDestination

func (s *Sender) AddDestination(universe uint16, destination string) error

AddDestination adds a unicast destination that a universe should sent it's packets to. destination should be in the form of a string (eg: "192.168.1.100").

func (*Sender) Close

func (s *Sender) Close()

Stops the sender and all initialised universes

func (*Sender) GetDestinations

func (s *Sender) GetDestinations(universe uint16) ([]string, error)

GetDestinations returns the list of unicast destinations the universe is configured to send it's packets to.

func (*Sender) GetUniverses

func (s *Sender) GetUniverses() []uint16

GetUniverses returns the list of all currently enabled universes for the sender.

func (*Sender) IsEnabled

func (s *Sender) IsEnabled(universe uint16) bool

IsEnabled returns true if the universe is currently enabled.

func (*Sender) IsMulticast

func (s *Sender) IsMulticast(universe uint16) (bool, error)

IsMulticast returns wether or not multicast is turned on for the given universe.

func (*Sender) Send

func (s *Sender) Send(universe uint16, p packet.SACNPacket) error

Send a packet on a universe. This is an alternative way to writing packets directly on the channel returned by Sender.StartUniverse

func (*Sender) SetDestinations

func (s *Sender) SetDestinations(universe uint16, destinations []string) error

SetDestinations sets the list of unicast destinations that a univese should sent it's packets to. This overwrites the current list created by previous calls to this function or Sender.AddDestination.

func (*Sender) SetMulticast

func (s *Sender) SetMulticast(universe uint16, multicast bool) error

SetMulticast is for setting whether or not a universe should be send out via multicast.

func (*Sender) StartUniverse

func (s *Sender) StartUniverse(universe uint16) (chan<- packet.SACNPacket, error)

StartUniverse initialises a new universe to be sent by the sender. It returns a channel into which packet.SACNPacket can be written to for sending out on the network. Optionally you can use Sender.Send to also send packets for a universe.

func (*Sender) StopUniverse

func (s *Sender) StopUniverse(universe uint16) error

StopUniverse stops sending packet for a universe. This closes the channel returned to by Sender.StartUniverse. On closing, 3 packet.DataPacket will be sent out with the StreamTerminated bit set as specified in section 6.7.1 of ANSI E1.31—2018.

type SenderOptions

type SenderOptions struct {
	CID        [16]byte // the CID (Component Identifier): a RFC4122 compliant UUID.
	SourceName string   // A source name (must not be longer than 64 characters)

}

Optional arguments for NewSender to be applied to all packets being sent by the sender. These can be overridden on a per packet basis if set in the packet.SACNPacket being sent.

type TerminationCallbackFunc

type TerminationCallbackFunc func(universe uint16)

TerminationCallbackFunc is the function type to be used with Receiver.RegisterTerminationCallback. The universe argument is the universe number which entered Network Data Loss conditions.