Skip to content

README.md

Latest commit

 

History

History
138 lines (91 loc) · 5.21 KB

README.md

File metadata and controls

138 lines (91 loc) · 5.21 KB

API | Docs | Latest release: v0.2.0 (2026-02-07)

Tests Clojars

clj-artnet

Art-Net 4 protocol implementation for Clojure

Art-Net is the entertainment industry's de facto standard for transporting DMX512 lighting data over Ethernet—powering everything from concert tours to theme parks to architectural installations.

clj-artnet is a pure-Clojure implementation of Art-Net 4, providing a high-performance, data-driven API for building lighting control applications on the JVM.

Protocol target: Art-Net 4 protocol specification V1.4 (Rev 1.4dp, 2025-10-23).

Why clj-artnet?

  • Pure Clojure. No native dependencies, runs anywhere the JVM runs.
  • Zero-copy hot path. Direct ByteBuffer operations, allocates nothing in steady state.
  • Full Art-Net 4 compliance. All modern features including BindIndex, RDM, failsafe, and sync.
  • Functional core, imperative shell. Pure protocol logic, testable without I/O.
  • core.async.flow graph. Backpressure-aware streaming with Virtual Threads.
  • Data-driven. Packets are plain Clojure maps, not opaque objects.
  • Comprehensive tests. 353 tests and 1,385 assertions including property-based fuzzing.

Protocol support

OpCode Direction Description
ArtDmx Send/Receive DMX512 data (512 channels per universe)
ArtSync Send Synchronize outputs across nodes
ArtPoll/Reply Auto Discovery and status announcements
ArtRdm Send/Receive RDM over Art-Net (unicast)
ArtTod* Send/Receive Table of Devices management
ArtTimeCode Send/Receive SMPTE/EBU timecode distribution
ArtAddress Send Remote node programming
ArtInput Send Input enable/disable
ArtTrigger Send/Receive Remote trigger macros
ArtCommand Send/Receive Text-based parameter commands

See reference.md for the full protocol support matrix.

Quick example

(require '[clj-artnet :as artnet])

;; Start a node
(def node (artnet/start-node! {}))

;; Send DMX to Port-Address 1
(artnet/send-dmx! node
                  {:data         (byte-array 512)
                   :port-address 1
                   :target       {:host "192.168.1.100" :port 6454}})

;; Receive DMX via callbacks
(def receiver
    (artnet/start-node!
        {:callbacks {:dmx (fn [{:keys [packet source]}]
                              (println "DMX from" source
                                       "Port-Address:" (:port-address packet)
                                       "channels:" (:length packet)))}}))

;; Stop the node
(artnet/stop-node! node)

See user-guide.md for more examples.

Things to be aware of

  1. Pooled buffers are recycled. The (:data packet) ByteBuffer is valid only during the callback. Copy with (.get (.duplicate buf) (byte-array len)) if needed.

  2. Java 21+ is required. clj-artnet uses Virtual Threads via core.async/io-thread. Older JVMs are not supported.

  3. Alpha core.async dependency. We depend on core.async 1.10.864-alpha1 for the flow API. This API is stable in practice but marked alpha.

  4. Always specify :target. Art-Net 4 mandates that ArtDmx packets must be unicast. Omitting :target will fail.

  5. No sACN bridge. clj-artnet implements Art-Net only. Bridging to sACN (E1.31) is a separate concern.

  6. No web configuration UI. The library provides a programmatic API. Web interfaces are application concerns.

  7. Port-Address 0 is deprecated. Art-Net 4 deprecates Port-Address 0 to enhance sACN compatibility. New implementations should start at Port-Address 1.

  8. ESTA prototype ID. The library defaults to ESTA manufacturer ID 0x7FF0 (prototype range) and logs a warning on startup if :esta-man is not configured. Production deployments should set :node {:esta-man 0xYOUR_ID}.

Documentation

Contributing

See CONTRIBUTING.md for guidelines.

License

Copyright © 2025 Robin Lahtinen. Distributed under the MIT License.

Art-Net™ Designed by and Copyright Artistic Licence