artnet-lib

artnet-lib is a Go library for interacting with the Art-Net protocol. It provides a clean, idiomatic Go API for sending and receiving Art-Net packets, enabling Go applications to control DMX lighting, discover Art-Net nodes, and integrate with other Art-Net compatible systems.

This library is built from the ground up based on the official Art-Net 4 specification, aiming for correctness, reliability, and ease of use.

Features

• Art-Net Controller: Send DMX data and ArtPoll packets.
• Art-Net Listener: Receive and parse incoming Art-Net packets (e.g., ArtPollReply).
• Packet Implementation: Currently supports:
  • ArtDmx: For sending DMX512 data.
  • ArtPoll: For discovering Art-Net nodes.
  • ArtPollReply: For receiving node information.
• Idiomatic Go: Designed with Go's concurrency model and error handling best practices in mind.

Installation

To use artnet-lib in your Go project, simply run:

go get github.com/IanShelanskey/artnet-lib

Usage

Creating a Controller

To start sending and receiving Art-Net packets, you first need to create a Controller instance. The NewController function takes the destination IP address for outgoing packets (e.g., a broadcast address like 255.255.255.255 or a specific unicast IP).

package main

import (
	"log"
	"time"

	"github.com/IanShelanskey/artnet-lib"
)

func main() {
	// Create a new Art-Net controller.
	// The argument is the broadcast IP address to send to.
	c, err := artnet.NewController("255.255.255.255")
	if err != nil {
		log.Fatalf("failed to create controller: %v", err)
	}
	defer c.Close()

	// Your Art-Net logic here
}

Sending DMX Data (ArtDmx)

The ArtDmx packet is used to transmit DMX512 data. You can set the Net, SubUni (Sub-Net and Universe), and the Data array (512 bytes for DMX channels).

Here's an example that sends a simple chase pattern across DMX channels:

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/IanShelanskey/artnet-lib"
)

func main() {
	// Create a new Art-Net controller.
	// The argument is the broadcast IP address to send to.
	c, err := artnet.NewController("255.255.255.255")
	if err != nil {
		log.Fatalf("failed to create controller: %v", err)
	}
	defer c.Close()

	// Create a simple DMX packet
	p := &artnet.ArtDmx{
		Net:    0,
		SubUni: 0, // Universe 0
	}

	// Send a chase pattern
	pos := 0
	for {
		// Clear the data
		for i := range p.Data {
			p.Data[i] = 0
		}

		// Set the new position
		p.Data[pos] = 255

		// Send the packet
		if err := c.Send(p); err != nil {
			log.Printf("failed to send packet: %v", err)
		}

		// Move to the next position
		pos = (pos + 1) % 512

		// Wait a bit
		time.Sleep(10 * time.Millisecond)

		fmt.Printf("
Sending DMX packet with value 255 at channel %d", pos+1)
	}
}

Discovering Art-Net Nodes (ArtPoll and ArtPollReply)

You can discover other Art-Net nodes on the network by sending an ArtPoll packet and then listening for ArtPollReply packets. The Controller.C() method returns a channel that delivers all incoming parsed Art-Net packets.

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/IanShelanskey/artnet-lib"
)

func main() {
	// Create a new Art-Net controller.
	// The argument is the broadcast IP address to send to.
	c, err := artnet.NewController("255.255.255.255")
	if err != nil {
		log.Fatalf("failed to create controller: %v", err)
	}
	defer c.Close()

	// Send an ArtPoll packet to discover nodes
	if err := c.Send(&artnet.ArtPoll{}); err != nil {
		log.Fatalf("failed to send ArtPoll: %v", err)
	}

	fmt.Println("Discovering nodes for 5 seconds...")

	// Listen for replies for 5 seconds
	timeout := time.After(5 * time.Second)
	for {
		select {
		case p := <-c.C():
			if reply, ok := p.(*artnet.ArtPollReply); ok {
				fmt.Printf("
---
Node: %s
", reply.ShortName)
				fmt.Printf("  IP: %s:%d
", reply.IPAddress, reply.Port)
				fmt.Printf("  MAC: %s
", reply.MAC)
				fmt.Printf("  Version: %d
", reply.VersionInfo)
				fmt.Printf("  Net/SubNet: %d/%d
", reply.NetSwitch, reply.SubSwitch)
			}
		case <-timeout:
			fmt.Println("
Discovery complete.")
			return
		}
	}
}

Contributing

Contributions are welcome! If you find a bug, have a feature request, or want to contribute code, please open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.