Liking cljdoc? Tell your friends :D

Reference

This document specifies all data shapes used by clj-artnet. It is intended as a precise technical reference, not a tutorial.

Configuration

Node configuration

The :node key in the configuration map corresponds to ArtPollReply fields:

KeyTypeDefaultDescription
:short-namestring"clj-artnet"17-character node name
:long-namestring"clj-artnet Art-Net 4 Node"63-character description
:ip[int int int int]Auto-detectedIPv4 address
:mac[int int int int int int][0 0 0 0 0 0]MAC address
:portsvector[]Port definitions
:stylekeyword:st-nodeNode type
:oemint0xFFFFOEM code
:esta-manint0x0000ESTA manufacturer code
:version-hiint0Firmware version high byte
:version-loint1Firmware version low byte
:status1intAutoStatus register 1
:status2intAutoStatus register 2
:status3intAutoStatus register 3

Port configuration

Each entry in :ports:

KeyTypeDefaultRangeDescription
:directionkeyword:output:input, :outputPort direction
:universeintIndex0–15Universe address
:typekeyword:dmx512—Protocol type

Sync configuration

The :sync key:

KeyTypeDefaultDescription
:modekeyword:immediate:immediate or :art-sync
:buffer-ttl-msint200Buffer expiry in milliseconds
:buffer-ttl-nslong200000000Buffer expiry in nanoseconds

Failsafe configuration

The :failsafe key:

KeyTypeDefaultDescription
:enabled?booleantrueEnable failsafe detection
:idle-timeout-msint1000Timeout before failsafe engages
:idle-timeout-nslong1000000000Timeout in nanoseconds
:tick-interval-msint100Failsafe check interval

Network configuration

The :bind key:

KeyTypeDefaultDescription
:hoststring"0.0.0.0"Bind address
:portint6454UDP port

Buffer pool configuration

KeyTypeDefaultDescription
:rx-buffermap{:count 256 :size 2048}Receive buffer pool
:tx-buffermap{:count 128 :size 2048}Transmit buffer pool
:max-packetint2048Maximum packet size

Buffer pool map:

KeyTypeDescription
:countintNumber of buffers in pool
:sizeintSize of each buffer in bytes

Callback payloads

DMX callback

{:packet {:data          ByteBuffer  ; Read-only channel data
          :length        int         ; Number of channels (1–512)
          :port-address  int         ; 15-bit Port-Address
          :sequence      int         ; Sequence number (0–255)
          :physical      int         ; Physical port number
          :failsafe?     boolean     ; True if failsafe playback
          :failsafe-mode keyword}   ; :zero, :full, :scene, :hold
 :source {:host string              ; Sender IP address
          :port int}                ; Sender port
 :node   {...}}                     ; Current node configuration

Sync callback

{:sender    {:host string :port int}   ; Sender address
 :timestamp long                       ; System nanosecond timestamp
 :node      {...}}                     ; Current node configuration

RDM callback

{:packet {:rdm-packet   ByteBuffer   ; RDM PDU data
          :port-address int          ; Port-Address
          :net          int          ; Network (0–127)
          :command      keyword}     ; RDM command class
 :source {:host string :port int}
 :node   {...}}

Trigger callback

{:packet {:key     int          ; Trigger key (0=ASCII, 1=Macro, 2=Soft, 3=Show)
          :sub-key int          ; Trigger sub-key
          :payload ByteBuffer   ; Trigger payload data
          :oem     int}         ; OEM code
 :source {:host string :port int}
 :node   {...}}

Command callback

{:packet {:text     string   ; Command text (ASCII)
          :esta-man int      ; ESTA manufacturer code
          :length   int}     ; Command length
 :source {:host string :port int}
 :node   {...}}

Timecode callback

{:packet {:hours   int      ; Hours (0–23)
          :minutes int      ; Minutes (0–59)
          :seconds int      ; Seconds (0–59)
          :frames  int      ; Frames
          :type    keyword} ; :film, :ebu, :df, :smpte
 :source {:host string :port int}
 :node   {...}}

Runtime state

State snapshot keys

The state function accepts :keys to select which state sections to return:

KeyDescription
:nodeNode configuration (ArtPollReply fields)
:networkNetwork binding information
:peersDiscovered nodes
:statsStatistics (packets sent/received)
:dmxDMX state per port-address
:syncSync buffer state
:failsafeFailsafe timing state

Diagnostics snapshot

{:diagnostics {:subscribers  [{:host string :priority keyword}]
               :broadcast?   boolean
               :last-sent-at long}}

Protocol constants

OpCodes

OpCodeNameDirection
0x2000OpPollRX/TX
0x2100OpPollReplyRX/TX
0x2300OpDiagDataRX/TX
0x2400OpCommandRX/TX
0x2700OpDataRequestRX
0x2800OpDataReplyTX
0x5000OpDmxRX/TX
0x5100OpNzsRX
0x5200OpSyncRX/TX
0x6000OpAddressRX
0x7000OpInputRX
0x8000OpTodRequestRX
0x8100OpTodDataTX
0x8200OpTodControlRX
0x8300OpRdmRX/TX
0x8400OpRdmSubRX/TX
0x9700OpTimeCodeRX
0x9900OpTriggerRX
0xF200OpFirmwareMasterRX
0xF300OpFirmwareReplyTX
0xF800OpIpProgRX
0xF900OpIpProgReplyTX

Style codes

KeywordValueDescription
:st-node0x00DMX to/from Art-Net device
:st-controller0x01Lighting console
:st-media0x02Media server
:st-route0x03Network routing device
:st-backup0x04Backup device
:st-config0x05Configuration tool
:st-visual0x06Visualizer

Priority levels

KeywordValueDescription
:dp-low0x10Low priority
:dp-med0x40Medium priority
:dp-high0x80High priority
:dp-critical0xE0Critical priority
:dp-volatile0xF0Volatile (temporary)

Timecode types

KeywordDescription
:film24 fps
:ebu25 fps
:df29.97 fps drop-frame
:smpte30 fps

Protocol support matrix

Implemented OpCodes

OpCodeNameDirectionStatus
0x2000OpPollRX/TX✅ Full
0x2100OpPollReplyRX/TX✅ Full
0x2300OpDiagDataRX/TX✅ Full
0x2400OpCommandRX/TX✅ Full
0x2700OpDataRequestRX✅ Full
0x2800OpDataReplyTX✅ Full
0x5000OpDmxRX/TX✅ Full
0x5100OpNzsRX✅ Full
0x5200OpSyncRX/TX✅ Full
0x6000OpAddressRX✅ Full
0x7000OpInputRX✅ Full
0x8000OpTodRequestRX✅ Full
0x8100OpTodDataTX✅ Full
0x8200OpTodControlRX✅ Full
0x8300OpRdmRX/TX✅ Full
0x8400OpRdmSubRX/TX✅ Full
0x9700OpTimeCodeRX✅ Full
0x9900OpTriggerRX✅ Full
0xF200OpFirmwareMasterRX✅ Codec only
0xF300OpFirmwareReplyTX✅ Codec only
0xF800OpIpProgRX✅ Full
0xF900OpIpProgReplyTX✅ Full

Not implemented (deprecated)

OpCodeNameReason
0xF000OpMacMasterDeprecated in Art-Net 4
0xF100OpMacSlaveDeprecated in Art-Net 4

Edge cases and limits

Packet size limits

PacketMinimumMaximum
ArtPoll14 bytes14 bytes
ArtPollReply207 bytes239 bytes
ArtDmx18 bytes (header)530 bytes (header + 512)
ArtRdm24 bytes (header)varies

Port-address range

  • Minimum: 0 (deprecated in Art-Net 4)
  • Maximum: 32,767
  • Recommended Start: 1 (for sACN compatibility)

Sequence number handling

ValueMeaning
0Sequence checking disabled
1–255Active sequence number

Receivers discard packets with sequence numbers lower than the last received (accounting for wraparound from 255 to 1).

Reply-on-change limits

{:discovery {:reply-on-change-limit  10
             :reply-on-change-policy :prefer-existing}}
PolicyBehavior
:prefer-existingEvict newest subscribers when limit exceeded
:prefer-latestEvict oldest subscribers when limit exceeded

BindIndex pagination

For gateways with more than four ports, responses are paginated using BindIndex (0–255). Each ArtPollReply contains up to four ports.

Data length constraints

ConstraintValueReason
Minimum DMX2 bytesArt-Net specification
Maximum DMX512 bytesDMX512 universe size
DMX PaddingEven lengthPer Art-Net specification

Error states

Timeout exceptions

;; ExceptionInfo with :type :timeout
{:type       :timeout
 :timeout-ms 1000
 :operation  :state-snapshot}

Network binding failures

;; ExceptionInfo with :type :bind-failed
{:type  :bind-failed
 :host  "0.0.0.0"
 :port  6454
 :cause IOException}

Invalid configuration

;; ExceptionInfo with :type :invalid-config
{:type    :invalid-config
 :key     :ports
 :value   "invalid"
 :message "Ports must be a vector"}

Internal data shapes

Effect types

Effects are data structures returned by the state machine:

;; Transmit packet
{:effect :tx-packet
 :packet ByteBuffer
 :target {:host string :port int}}

;; Invoke callback
{:effect   :callback
 :callback keyword      ; :dmx, :sync, :rdm, etc.
 :payload  map}

;; Schedule delayed action
{:effect   :schedule
 :action   keyword
 :delay-ms int
 :target   {:host string :port int}}

;; Log event
{:effect  :log
 :level   keyword        ; :info, :warn, :error
 :message string}

Event types

Events are inputs to the state machine:

;; Received packet
{:type   :rx-packet
 :packet map           ; Decoded packet
 :source {:host string :port int}
 :buffer ByteBuffer}

;; Timer tick
{:type      :tick
 :timestamp long}      ; System.nanoTime

;; User command
{:type    :command
 :command keyword      ; :send-dmx, :send-rdm, :send-sync, etc.
 :data    map}         ; Command-specific data

;; State snapshot request
{:type :snapshot
 :keys vector}         ; Keys to include
❮User GuideDesign❯

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
Raise an issueBrowse cljdoc sourceChat on Slack
× close