search

Hundemeier / sacn

A simple ANSI E1.31 (aka sACN) module for python.
MIT License
47 stars 21 forks source link

readme

Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.

sACN / E1.31 module

This module is a simple sACN library that support the standard DMX message of the protocol. It is based on the 2016 version of the official ANSI E1.31 standard. It has support for sending out DMX data and receiving it. Multiple and multicast universes are supported. For full blown DMX support use OLA.

Currently missing features:

Features:

Setup

This Package is in the pypi. To install the package use pip install sacn. Python 3.6 or newer required! To use the library import sacn. If you want to install directly from source, download or clone the repository and execute pip install . where the setup.py is located. For more information on pip installation see: https://packaging.python.org/tutorials/installing-packages/#installing-from-a-local-src-tree

The Internals

Sending

You can create a new sACNsender object and provide the necessary information. Then you have to use start(). This creates a new thread that is responsible for sending out the data. Do not forget to stop() the thread when finished! If the data is not changed, the same DMX data is sent out every second.

The thread sends out the data every 1/fps seconds. This reduces network traffic even if you give the sender new data more often than the fps. A simple description would be to say that the data that you give the sACNsender is subsampled by the fps. You can tweak this fps by simply change it when creating the sACNsender object.

This function works according to the E1.31. See 6.6.1 for more information.

Note: Since Version 1.4 there is a manual flush feature available. See Usage/Sending for more info. This feature also uses the sync feature of the sACN protocol (see page 36 on E1.31). Currently this is not implemented like the recommended way (this does not wait before sending out the sync packet), but it should work on a normal local network without too many latency differences. When the flush() function is called, all data is send out at the same time and immediately a sync packet is send out.

Receiving

A very simple solution, as you just create a sACNreceiver object and use start() a new thread that is running in the background and calls the callbacks when new sACN data arrives.

Usage

Sending

To use the sending functionality you have to use the sACNsender.

import sacn
import time

sender = sacn.sACNsender()  # provide an IP-Address to bind to if you want to send multicast packets from a specific interface
sender.start()  # start the sending thread
sender.activate_output(1)  # start sending out data in the 1st universe
sender[1].multicast = True  # set multicast to True
# sender[1].destination = "192.168.1.20"  # or provide unicast information.
# Keep in mind that if multicast is on, unicast is not used
sender[1].dmx_data = (1, 2, 3, 4)  # some test DMX data

time.sleep(10)  # send the data for 10 seconds
sender.stop()  # do not forget to stop the sender

You can activate an output universe via activate_output(<universe>) and then change the attributes of this universe via sender[<universe>].<attribute>. To deactivate an output use deactivate_output(<universe>). The output is terminated like the E1.31 describes it on page 14.

If you want to flush manually and the sender thread should not send out automatic, use the sACNsender.manual_flush option. This is useful when you want to use a fixture that is using more than one universe and all the data on multiple universes should send out at the same time.

Tip: you can get the activated outputs with get_active_outputs() and you can move an output with all its settings from one universe to another with move_universe(<from>, <to>).

Available Attributes for sender[<universe>].<attribute> are:

sACNsender Creates a sender object. A sender is used to manage multiple sACN universes and handles their output. DMX data is send out every second, when no data changes. Some changes may be not send out, because the fps setting defines how often packets are send out to prevent network overuse. So if you change the DMX values too often in a second they may not all been send. Vary the fps parameter to your needs (Default=30).

When manually flushed, the E1.31 sync feature is used. So all universe data is send out, and after all data was send out a sync packet is send to all receivers and then they are allowed to display the received data. Note that not all receiver implemented this feature of the sACN protocol.

Example for the usage of the manual_flush:

import sacn
import time

sender = sacn.sACNsender()
sender.start()
sender.activate_output(1)
sender.activate_output(2)
sender[1].multicast = True
sender[2].multicast = True

sender.manual_flush = True # turning off the automatic sending of packets
sender[1].dmx_data = (1, 2, 3, 4)  # some test DMX data
sender[2].dmx_data = (5, 6, 7, 8)  # by the time we are here, the above data would be already send out,
# if manual_flush would be False. This could cause some jitter
# so instead we are flushing manual
time.sleep(1) # let the sender initialize itself
sender.flush()
sender.manual_flush = False # keep manual flush off as long as possible, because if it is on, the automatic
# sending of packets is turned off and that is not recommended
sender.stop() # stop sending out

Receiving

To use the receiving functionality you have to use the sACNreceiver.

import sacn
import time

# provide an IP-Address to bind to if you want to receive multicast packets from a specific interface
receiver = sacn.sACNreceiver()
receiver.start()  # start the receiving thread

# define a callback function
@receiver.listen_on('universe', universe=1)  # listens on universe 1
def callback(packet):  # packet type: sacn.DataPacket
    if packet.dmxStartCode == 0x00:  # ignore non-DMX-data packets
        print(packet.dmxData)  # print the received DMX data

# optional: if multicast is desired, join with the universe number as parameter
receiver.join_multicast(1)

time.sleep(10)  # receive for 10 seconds

# optional: if multicast was previously joined
receiver.leave_multicast(1)

receiver.stop()

The usage of the receiver is simpler than the sender. The sACNreceiver can be initialized with the following parameters:

Please keep in mind to not use the callbacks for time consuming tasks! If you do this, then the receiver can not react fast enough on incoming messages!

Functions:

DataPacket

This is an abstract representation of an sACN Data packet that carries the DMX data. This class is used internally by the module and is used in the callbacks of the receiver.

The DataPacket provides following attributes:

Development

Some tools are used to help with development of this library. These are flake8, pytest and coverage.py.

Install those tools with pip:

pip install flake8 pytest pytest-timeout coverage

flake8 checks for formatting issues and can be run with flake8 or python -m flake8 in the root directory of this repository.

pytest is used for unit testing and can be executed with pytest or python -m pytest in the root directory of this repository. By default, this skips the integration test, which uses real hardware I/O and might not run in every configuration. Use the flag --run-integration-tests to run the additional tests (e.g. python -m pytest --run-integration-tests)

It is useful to check if the test coverage changed with coverage run -m pytest and then coverage html, which generates a htmlcov/index.html file with all the information.

Changelog