PyArtNet

pyartnet is a python implementation of the ArtNet protocol using asyncio. Supported protocols are ArtNet, sACN and KiNet.

Getting Started

import asyncio
from pyartnet import ArtNetNode

async def main():

    async with ArtNetNode.create('IP', 6454) as node:

        # Create universe 0
        universe = node.add_universe(0)

        # Add a channel to the universe which consists of 3 values
        # Default size of a value is 8Bit (0..255) so this would fill
        # the DMX values 1..3 of the universe
        channel = universe.add_channel(start=1, width=3)

        # Fade channel to 255,0,0 in 5s
        # The fade will automatically run in the background
        channel.add_fade([255,0,0], 1000)

        # this can be used to wait till the fade is complete
        await channel

asyncio.run(main())

Channels

Accessing channels

Created channels can be requested from the universe through the [] syntax or through BaseUniverse.get_channel(). If no channel name is specified during creation the default name will be built with {START}/{WIDTH}.

# create node/universe
async with ArtNetNode.create('IP', 6454) as node:

    universe = node.add_universe(0)

    # create the channel
    channel = universe.add_channel(start=1, width=3)

    # after creation this would also work (default name)
    channel = universe['1/3']
    channel = universe.get_channel('1/3')


    # it's possible to name the channel during creation
    universe.add_channel(start=4, width=3, channel_name='Dimmer1')

    # access is then by name
    channel = universe['Dimmer1']
    channel = universe.get_channel('Dimmer1')

Wider channels

Currently there is support for 8Bit, 16Bit, 24Bit and 32Bit channels. Channel properties can be set when creating the channel through BaseUniverse.add_channel().

# create node/universe
async with ArtNetNode.create('IP', 6454) as node:
    universe = node.add_universe(0)

    # create a 16bit channel
    channel = universe.add_channel(start=1, width=3, byte_size=2)

Output correction

It is possible to use an output correction to create different brightness curves. Output correction can be set on the channel, the universe or the node. The universe output correction overrides the node output correction and the channel output correction overwrites the universe output correction.

The graph shows different output values depending on the output correction.

From left to right: linear (default when nothing is set), quadratic, cubic then quadruple

Quadratic or cubic results in much smoother and more pleasant fades when using LED Strips.

Example

from pyartnet import ArtNetNode, output_correction

# create node/universe/channel
async with ArtNetNode.create('IP', 6454) as node:
    universe = node.add_universe(0)
    channel = universe.add_channel(start=1, width=3)

    # set quadratic correction for the whole universe to quadratic
    universe.set_output_correction(output_correction.quadratic)

    # Explicitly set output for this channel to linear
    channel.set_output_correction(output_correction.linear)

    # Remove output correction for the channel.
    # The channel will now use the correction from the universe again
    channel.set_output_correction(None)

Class Reference

Universe and Channel

class pyartnet.BaseUniverse(node, universe=0)

add_channel(start, width, channel_name='', byte_size=1, byte_order='little')

Add a new channel to the universe. This will automatically resize the universe accordingly.

Parameters:

start (int) – start position in the universe
width (int) – how many values the channel has
channel_name (str) – name of the channel for requesting it from the universe
byte_size (int) – byte size of a value
byte_order (Literal['big', 'little']) – byte order of a value

Return type:

Channel

get_channel(channel_name)

Return a channel by name or raise an exception

Parameters:: channel_name (str) – name of the channel
Return type:: Channel

set_output_correction(func)

Set the output correction function.

Parameters:: func (Optional[Callable[[float, int], float]]) – None to disable output correction or the function which will be used to transform the values
Return type:: None

class pyartnet.Channel(universe, start, width, byte_size=1, byte_order='little')

get_values()

Get the current (uncorrected) channel values

Return type:: list[int]
Returns:: list of channel values

set_fade(values, duration_ms, fade_class=<class 'pyartnet.fades.fade_linear.LinearFade'>)

Add and schedule a new fade for the channel

Parameters:

values (Collection[int | FadeBase]) – Target values for the fade
duration_ms (int) – Duration for the fade in ms
fade_class (type[FadeBase]) – What kind of fade

Return type:

Self

set_output_correction(func)

Set the output correction function.

Parameters:: func (Optional[Callable[[float, int], float]]) – None to disable output correction or the function which will be used to transform the values
Return type:: None

set_values(values)

Set values for a channel without a fade

Parameters:: values (Collection[int | float]) – Iterable of values with the same size as the channel width
Return type:: Self

Node implementations

class pyartnet.ArtNetNode(network, *, name=None, max_fps=25, refresh_every=2, sequence_counter=True)

classmethod create(host, port=6454, *, source_ip=None, source_port=0, name=None, max_fps=25, refresh_every=2)

Creates a new node. The packages will be sent directly to the node (unicast).

Parameters:

host (str) – ip or hostname of the device
port (int) – port of device
source_ip (str | None) – ip of the network interface that shall be used to send data
source_port (int) – source port
name (str | None) – a custom name of the node
max_fps (int) – maximum frames per second to send
refresh_every (float) – refresh interval in seconds

Return type:

Self

add_universe(nr=0)

Creates a new universe and adds it to the parent node

Parameters:: nr (int) – universe nr
Return type:: TypeVar(UNIVERSE_TYPE, bound= pyartnet.base.BaseUniverse)
Returns:: The universe

get_universe(nr)

Get universe by number

Parameters:: nr (int) – universe nr
Return type:: TypeVar(UNIVERSE_TYPE, bound= pyartnet.base.BaseUniverse)
Returns:: The universe

set_output_correction(func)

Set the output correction function.

Parameters:: func (Optional[Callable[[float, int], float]]) – None to disable output correction or the function which will be used to transform the values
Return type:: None

set_synchronous_mode(enabled)

Enable or disable synchronous mode for this node. In synchronous mode multiple universes are sent to the node and then a synchronization packet is sent to make the node output all universes at the same time. This prevents tearing in multi universe panels.

Parameters:: enabled (bool) – Enable or disable synchronous mode
Return type:: Self

async start_refresh()

Manually start the refresh task (if not already running)

Return type:: None

async stop_refresh()

Manually stop the refresh task

Return type:: None

class pyartnet.KiNetNode(network, *, name=None, max_fps=25, refresh_every=2)

classmethod create(host, port=6038, *, source_ip=None, source_port=0, name=None, max_fps=25, refresh_every=2)

Creates a new node. The packages will be sent directly to the node (unicast).

Parameters:

host (str) – ip or hostname of the device
port (int) – port of device
source_ip (str | None) – ip of the network interface that shall be used to send data
source_port (int) – source port
name (str | None) – a custom name of the node
max_fps (int) – maximum frames per second to send
refresh_every (float) – refresh interval in seconds

Return type:

Self

add_universe(nr=0)

Creates a new universe and adds it to the parent node

Parameters:: nr (int) – universe nr
Return type:: TypeVar(UNIVERSE_TYPE, bound= pyartnet.base.BaseUniverse)
Returns:: The universe

get_universe(nr)

Get universe by number

Parameters:: nr (int) – universe nr
Return type:: TypeVar(UNIVERSE_TYPE, bound= pyartnet.base.BaseUniverse)
Returns:: The universe

set_output_correction(func)

Set the output correction function.

Parameters:: func (Optional[Callable[[float, int], float]]) – None to disable output correction or the function which will be used to transform the values
Return type:: None

async start_refresh()

Manually start the refresh task (if not already running)

Return type:: None

async stop_refresh()

Manually stop the refresh task

Return type:: None

class pyartnet.SacnNode(network, *, name=None, max_fps=25, refresh_every=2, cid=None, source_name=None)

classmethod create(host, port=5568, *, source_ip=None, source_port=0, name=None, max_fps=25, refresh_every=2)

Creates a new node. The packages will be sent directly to the node (unicast).

Parameters:

host (str) – ip or hostname of the device
port (int) – port of device
source_ip (str | None) – ip of the network interface that shall be used to send data
source_port (int) – source port
name (str | None) – a custom name of the node
max_fps (int) – maximum frames per second to send
refresh_every (float) – refresh interval in seconds

Return type:

Self

classmethod create_multicast(source_ip, source_port=0, *, name=None, max_fps=25, refresh_every=2)

Creates a new node. The packages will be sent as multicast.

Parameters:

source_ip (str) – interface ip of the network interface that shall be used to send data
source_port (int) – source port
name (str | None) – a custom name of the node
max_fps (int) – maximum frames per second to send
refresh_every (float) – refresh interval in seconds

Return type:

Self

add_universe(nr=0)

Creates a new universe and adds it to the parent node

Parameters:: nr (int) – universe nr
Return type:: TypeVar(UNIVERSE_TYPE, bound= pyartnet.base.BaseUniverse)
Returns:: The universe

get_universe(nr)

Get universe by number

Parameters:: nr (int) – universe nr
Return type:: TypeVar(UNIVERSE_TYPE, bound= pyartnet.base.BaseUniverse)
Returns:: The universe

set_output_correction(func)

Set the output correction function.

Parameters:: func (Optional[Callable[[float, int], float]]) – None to disable output correction or the function which will be used to transform the values
Return type:: None

set_synchronous_mode(enabled, synchronization_address=0)

Enable or disable synchronous mode for this node. In synchronous mode multiple universes are sent to the node and then a synchronization packet is sent to make the node output all universes at the same time. This prevents tearing in multi universe panels.

Parameters:

enabled (bool) – Enable or disable synchronous mode
synchronization_address (int) – The universe address to use for synchronization packets. This must be the same for all nodes that should be synchronized.

Return type:

None

async start_refresh()

Manually start the refresh task (if not already running)

Return type:: None

async stop_refresh()

Manually stop the refresh task

Return type:: None

Fades

class pyartnet.fades.LinearFade

debug_initialize()

return debug string of the calculated values in initialize fade

Return type:: str

Available output corrections

pyartnet.output_correction.linear(val, max_val=255)

linear output correction

Return type:: float

pyartnet.output_correction.quadratic(val, max_val=255)

Quadratic output correction

Return type:: float

pyartnet.output_correction.cubic(val, max_val=255)

Cubic output correction

Return type:: float

pyartnet.output_correction.quadruple(val, max_val=255)

Quadruple output correction

Return type:: float