lacylights-go

module

v0.3.0 Latest Latest Go to latest Published: Apr 30, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bbernstein/lacylights-go

Links

Open Source Insights

README ¶

LacyLights Go Server

A high-performance Go implementation of the LacyLights lighting control system backend. This server provides a GraphQL API for managing theatrical lighting fixtures, scenes, cue lists, and real-time DMX output via Art-Net.

Features

GraphQL API: Full-featured API for lighting control operations
Art-Net Support: Real-time DMX output over UDP (Art-Net protocol)
SQLite Database: Lightweight, embedded database using Prisma-style schema
Cross-Platform: Builds for Linux (ARM/AMD64), macOS, and Windows
Raspberry Pi Ready: Optimized for deployment on Raspberry Pi hardware

Quick Start

Prerequisites

Go 1.21 or later
Make (optional, for convenience commands)

Build and Run

# Build the server
make build

# Run with default settings
./build/bin/server

# Run with custom settings
DATABASE_URL="file:./data.db" PORT=4000 ./build/bin/server

Environment Variables

Variable	Default	Description
`PORT`	`4000`	HTTP server port
`DATABASE_URL`	`file:./lacylights.db`	SQLite database path
`ARTNET_ENABLED`	`true`	Enable/disable Art-Net output
`ARTNET_BROADCAST_ADDRESS`	`255.255.255.255`	Art-Net broadcast address

Development

Project Structure

lacylights-go/
├── cmd/server/          # Main application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database layer and migrations
│   ├── graph/           # GraphQL resolvers and schema
│   ├── models/          # Domain models
│   └── artnet/          # Art-Net protocol implementation
├── pkg/                 # Public packages
├── test/                # Integration tests
├── go.mod
├── go.sum
└── Makefile

Common Commands

# Run tests
make test

# Run tests with coverage
make test-coverage

# Run linter
make lint

# Generate GraphQL code
make generate

# Build for all platforms
make build-all

# Clean build artifacts
make clean

GraphQL Schema

The GraphQL API is defined in internal/graph/schema.graphqls. After modifying the schema, regenerate the resolver code:

make generate

API Overview

Queries

projects - List all projects
project(id: ID!) - Get a specific project
fixtureDefinitions - List fixture definitions
systemInfo - Get system status and configuration
dmxOutput(universe: Int!) - Get current DMX channel values

Mutations

createProject / updateProject / deleteProject - Project management
createScene / updateScene / deleteScene - Scene management
createCueList / addCueToCueList - Cue list management
startCueList / nextCue / stopCueList - Playback control
setChannelValue - Direct DMX control
fadeToBlack - Emergency blackout

Subscriptions

dmxOutput - Real-time DMX value updates
playbackStatus - Cue list playback state changes

Building for Raspberry Pi

# Build for Raspberry Pi (ARM64)
GOOS=linux GOARCH=arm64 go build -o lacylights-arm64 ./cmd/server

# Build for older Raspberry Pi (ARM32)
GOOS=linux GOARCH=arm GOARM=7 go build -o lacylights-arm ./cmd/server

Testing

Run unit tests:

make test

Run with coverage report:

make test-coverage
open coverage.html

Project Documentation

For comprehensive implementation plans and architecture decisions, see the parent directory documentation:

LACYLIGHTS_GO_REWRITE_PLAN.md - Complete Go rewrite implementation plan and architecture
RASPBERRY_PI_PRODUCT_PLAN.md - Turnkey Raspberry Pi product architecture and deployment
GO_DISTRIBUTION_PLAN.md - Binary distribution and release workflow coordination
CONTRACT_TESTING_PLAN.md - Contract test suite for API compatibility verification

lacylights-fe - Next.js frontend
lacylights-mcp - MCP server for AI integration
lacylights-test - Contract test suite
lacylights-rpi - Raspberry Pi deployment

License

MIT License - See LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
migrate-layout command Package main provides a one-time migration tool to convert fixture layout coordinates from normalized 0-1 values to pixel-based coordinates.	Package main provides a one-time migration tool to convert fixture layout coordinates from normalized 0-1 values to pixel-based coordinates.
server command Package main is the entry point for the LacyLights Go server.	Package main is the entry point for the LacyLights Go server.
internal
auth Package auth provides authentication services for LacyLights.	Package auth provides authentication services for LacyLights.
auth/session Package session provides session management for authentication.	Package session provides session management for authentication.
config Package config provides configuration management for the LacyLights server.	Package config provides configuration management for the LacyLights server.
database Package database provides database connection and management.	Package database provides database connection and management.
database/migrations Package migrations contains one-shot, idempotent schema migrations invoked from the server's startup AutoMigrate flow.	Package migrations contains one-shot, idempotent schema migrations invoked from the server's startup AutoMigrate flow.
database/models Package models contains the database model definitions.	Package models contains the database model definitions.
database/repositories Package repositories provides data access layer implementations.	Package repositories provides data access layer implementations.
graphql/generated
graphql/resolvers Package resolvers contains GraphQL resolver implementations.	Package resolvers contains GraphQL resolver implementations.
middleware Package middleware provides HTTP middleware for the LacyLights server.	Package middleware provides HTTP middleware for the LacyLights server.
services/dmx Package dmx provides DMX output management and Art-Net communication.	Package dmx provides DMX output management and Art-Net communication.
services/export Package export provides project export functionality.	Package export provides project export functionality.
services/export_eos Package exporteos writes LacyLights project state to ETC Eos ASCII format.	Package exporteos writes LacyLights project state to ETC Eos ASCII format.
services/fade Package fade provides fade engine functionality for smooth DMX transitions.	Package fade provides fade engine functionality for smooth DMX transitions.
services/import Package importservice provides project import functionality.	Package importservice provides project import functionality.
services/import_eos Package importeos parses ETC Eos ASCII showfiles into LacyLights domain objects.	Package importeos parses ETC Eos ASCII showfiles into LacyLights domain objects.
services/modulator Package modulator provides a unified modulation engine for DMX channel control.	Package modulator provides a unified modulation engine for DMX channel control.
services/network Package network provides utilities for network interface enumeration	Package network provides utilities for network interface enumeration
services/ofl Package ofl provides OFL (Open Fixture Library) import functionality	Package ofl provides OFL (Open Fixture Library) import functionality
services/playback Package playback provides cue list playback functionality.	Package playback provides cue list playback functionality.
services/preview Package preview provides preview session management.	Package preview provides preview session management.
services/pubsub Package pubsub provides a simple publish-subscribe mechanism for GraphQL subscriptions.	Package pubsub provides a simple publish-subscribe mechanism for GraphQL subscriptions.
services/testutil Package testutil provides shared test utilities for integration tests.	Package testutil provides shared test utilities for integration tests.
services/undo Package undo provides undo/redo functionality for LacyLights operations.	Package undo provides undo/redo functionality for LacyLights operations.
services/version Package version provides version management functionality for LacyLights.	Package version provides version management functionality for LacyLights.
services/wifi Package wifi provides WiFi management and AP mode capabilities for LacyLights.	Package wifi provides WiFi management and AP mode capabilities for LacyLights.
pkg
artnet Package artnet provides Art-Net protocol packet building and transmission.	Package artnet provides Art-Net protocol packet building and transmission.