API REFERENCE

dmx_transmitter.dmx_transmitter

Main class for sending DMX512 lighting data out of a GPIO pin.

  • Author: Dana Runge

Implementation Notes

Hardware:

class dmx_transmitter.dmx_transmitter.DMXTransmitter(first_out_pin, universes=1, first_timing_pin=None, timing_pins=(), payload_class=Payload_USITT_DMX512_A, clone_from=None, exclusive_pin_use=True, **kwargs)

Configure an RP2040 PIO state machine to drive the DMX512 protocol.

Up to three (3) universes are supported for each state machine.

Required parameter:

Parameters:

first_out_pin (Pin) – the first pin for the first new DMX universe. If multiple universes are used, additional pins are needed for each additional universe. These pins will be automatically appear at the subsequent GPIO pin number(s).

Optional parameters:

Parameters:

  • universes (int) – how many output pins. (count) Two universes use the same amount of memory as three. Minimum: 1. Default: 1. Maximum: 3.

  • first_timing_pin (Pin) – a sideset pin available for each state machine. This pin can potentially be used for sending RDM frames, or for connecting to an oscilloscope for debugging.

  • timing_pins (list) – a list of TimingPin class methods that control how many, and which TimingPin functionalities to implement.

If this state machine is cloned, clone() both pin counts will be needed in the cloned state machine.

clear()

Set all slot values to 0.

clone(first_out_pin, first_timing_pin=None, **kwargs)

Create a new DMX512tx bonded to a new state machine.

This gives 1 to 3 more universes for each state machine, for a maximum of 24 universes.

Supports the same parameters as in the constructor except, ‘universes’, and ‘timing_pins’ which will be implemented identically as the parent object.

All other parameters default to being copies of the parent object’s parameters.

If there is still another state machine available in this PIO, uses a state machine in that PIO. (There are 4 state machines in each PIO.) Once this PIO is full, will attempt to create a state machine in the other PIO if it is not in use for another application.

Parameters:

  • first_out_pin (Pin) – the first pin for the first new DMX universe. If multiple universes are used, additional pins are needed for each additional universe. These pins will be automatically appear at the subsequent GPIO pin number(s).

  • timing_pin (Pin) – a optional pin used for debugging or supporting RDM.

deinit() → None

Turn off the state machine and release its resources.

run(once=None) → None

Link DMX payload to the state machine and out the wire.

Changes are not buffered, but are sent immediately.

show(once=None) → None

Buffer DMX payload to the state machine and out the wire.

Changes are not seen until ‘show’ is called again.

stop() → None

Stop sending data down the wire. Go into a high impedance state, if enabled.

class dmx_transmitter.dmx_transmitter.MachineCode(universes)

Frozen machine code. From lib/dmx_transmitter/assembly_code.

dmx_transmitter.dmx_transmitter.TimingPins(*timing_pins, program=None)

Fake timing pins manager, for when not loaded.

dmx_transmitter.payload_USITT_DMX512_A

Container that has data and timings for the state machine.

Implements the USITT-DMX512-A standard’s timings.

Basic usage is handled via convenience methods provided by the dmx_transmitter.dmx_transmitter.DMXTransmitter class.

This class can be used to adjust the DMX timing.

  • Author: Dana Runge

class dmx_transmitter.payload_USITT_DMX512_A.Payload_USITT_DMX512_A(universes=1, slots=512, clone_from=None)

This object mimics a list of byte values, and stores it and timing parameters into a data structure suitable for sending into a DMX512TxEngine state machine.

Unlike DMX512, this virtual list is 0-based, just like Python lists. Therefore, there is an inherent off-by-one error between DMX addresses and the list indexes.

This virtual list has a fixed size, the product of ‘slots’ and ‘universes’. Indexes are in slot major order.

Like Python lists, slicing is supported, but because of the fixed size, slice assignment is limited. A slice assignment from a list-like object of the same size is allowed. Unlike Python lists, slice assignment from a scalar is also allowed.

Timing parameters are set by decorators.

Caution: Several timing parameters include the stop bits. To meet the DMX standards include at least 8 microseconds in these parameters.

Parameters:

  • universes (int) – how many output pins. (count) Two universes use the same amount of memory as three. Minimum: 1. Default: 1. Maximum: 3.

  • slots (int) – number of slots of DMX data available. (count) Consumes two or four bytes per slot per buffer. 1-3 buffers. Minimum: 1. Default: 512. Maximum: 512.

  • clone_from (Payload_USITT_DMX512_A) – Clone this object.

Sets up default USITT DMX512-A timings.

array_copy()

Return a copy of the array. For sending.

array_empty()

Return an empty array

array_stop()

Return a copy of the array. For the stopping.

clear() → None

Set all slot values to 0.

clone(slots=None, **kwargs)

Clone this object

property interval: int

Indicates the calculated BREAK TO BREAK run time for each DMX frame. (microseconds)

The USITT DMX512-A standard defines an minimum BREAK TO BREAK time of 1204 microseconds. Your equipment probably doesn’t care.

If a longer interval is needed, adjust the timing parameters in the class constructor.

property mark_after_break: int

Time after a DMX SPACE FOR BREAK before serial data. (microseconds)

Minimum 4, Default 8

property mark_after_frame: int

How long to wait before disabling the transmitter. (microseconds)

If False, the state machine does not turn off the transmitter enable timing pin, and proceeds to send the next frame.

Otherwise waits the specified microseconds to turn off the transmitter pin.

Includes the two stop bits.

Minimum 6, Default 8, Maximum 260.

property mark_after_start_code: int

The first byte is the START CODE. How long to wait before the next byte. (microseconds)

Includes the two stop bits.

Minimum 5, Default 8, Maximum 260.

property mark_before_break: int

Timing from the last frame to before the SPACE FOR BREAK. (microseconds)

mark_before_break is influenced by mark_after_frame. If mark_after_frame is False (the default) then mark_before_break is the time in microseconds from the last last frame, including the two stop bits from the last slot. Otherwise, this parameter is the time from transmitter enable to SPACE FOR BREAK.

Minimum 5 if mark_after_frame is False, otherwise 2. Default 8.

property mark_between_slots: int

How long to wait before the next byte. (microseconds) Excludes the START CODE and excludes the last slot.

Includes the two stop bits.

Minimum 5, Default 8, Maximum 260.

property slots: int

Number slots of DMX data available. (count)

property space_for_break: int

Time for a DMX SPACE FOR BREAK. Indicates data stream is restarting. (microseconds)

Minimum 4, Default 172, Standard minimum 88.

property start_code: int

The DMX START CODE (byte)