class Tinkerforge::BrickletDMX

DMX master and slave

Constants

CALLBACK_FRAME

This callback is called as soon as a new frame is available (written by the DMX master).

The size of the array is equivalent to the number of channels in the frame. Each byte represents one channel.

This callback can be enabled via BrickletDMX#set_frame_callback_config.

This callback can only be triggered in slave mode.

.. note

If reconstructing the value fails, the callback is triggered with nil for frame.

CALLBACK_FRAME_AVAILABLE

This callback is triggered in slave mode when a new frame was received from the DMX master and it can be read out. You have to read the frame before the master has written the next frame, see BrickletDMX#read_frame for more details.

The parameter is the frame number, it is increased by one with each received frame.

This callback can be enabled via BrickletDMX#set_frame_callback_config.

This callback can only be triggered in slave mode.

CALLBACK_FRAME_ERROR_COUNT

This callback is called if a new error occurs. It returns the current overrun and framing error count.

CALLBACK_FRAME_LOW_LEVEL

See CALLBACK_FRAME

CALLBACK_FRAME_STARTED

This callback is triggered as soon as a new frame write is started. You should send the data for the next frame directly after this callback was triggered.

For an explanation of the general approach see BrickletDMX#write_frame.

This callback can be enabled via BrickletDMX#set_frame_callback_config.

This callback can only be triggered in master mode.

Public Class Methods

new(uid, ipcon) click to toggle source

Creates an object with the unique device ID uid and adds it to the IP Connection ipcon.

Calls superclass method
# File lib/tinkerforge/bricklet_dmx.rb, line 116
def initialize(uid, ipcon)
  super uid, ipcon, DEVICE_IDENTIFIER, DEVICE_DISPLAY_NAME

  @api_version = [2, 0, 0]

  @response_expected[FUNCTION_SET_DMX_MODE] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_DMX_MODE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_WRITE_FRAME_LOW_LEVEL] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_READ_FRAME_LOW_LEVEL] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_FRAME_DURATION] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_FRAME_DURATION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_FRAME_ERROR_COUNT] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_COMMUNICATION_LED_CONFIG] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_COMMUNICATION_LED_CONFIG] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_ERROR_LED_CONFIG] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_ERROR_LED_CONFIG] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_FRAME_CALLBACK_CONFIG] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_FRAME_CALLBACK_CONFIG] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_SPITFP_ERROR_COUNT] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_BOOTLOADER_MODE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_BOOTLOADER_MODE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_WRITE_FIRMWARE_POINTER] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_WRITE_FIRMWARE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_STATUS_LED_CONFIG] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_STATUS_LED_CONFIG] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_CHIP_TEMPERATURE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_RESET] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_WRITE_UID] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_READ_UID] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_IDENTITY] = RESPONSE_EXPECTED_ALWAYS_TRUE

  @callback_formats[CALLBACK_FRAME_STARTED] = [8, '']
  @callback_formats[CALLBACK_FRAME_AVAILABLE] = [12, 'L']
  @callback_formats[CALLBACK_FRAME_LOW_LEVEL] = [72, 'S S C56 L']
  @callback_formats[CALLBACK_FRAME_ERROR_COUNT] = [16, 'L L']

  @high_level_callbacks[CALLBACK_FRAME] = [['stream_length', 'stream_chunk_offset', 'stream_chunk_data', nil], {'fixed_length' => nil, 'single_chunk' => false}, nil]
  @ipcon.add_device self
end

Public Instance Methods

get_bootloader_mode() click to toggle source

Returns the current bootloader mode, see BrickletDMX#set_bootloader_mode.

# File lib/tinkerforge/bricklet_dmx.rb, line 346
def get_bootloader_mode
  check_validity

  send_request FUNCTION_GET_BOOTLOADER_MODE, [], '', 9, 'C'
end
get_chip_temperature() click to toggle source

Returns the temperature as measured inside the microcontroller. The value returned is not the ambient temperature!

The temperature is only proportional to the real temperature and it has bad accuracy. Practically it is only useful as an indicator for temperature changes.

# File lib/tinkerforge/bricklet_dmx.rb, line 404
def get_chip_temperature
  check_validity

  send_request FUNCTION_GET_CHIP_TEMPERATURE, [], '', 10, 's'
end
get_communication_led_config() click to toggle source

Returns the configuration as set by BrickletDMX#set_communication_led_config

# File lib/tinkerforge/bricklet_dmx.rb, line 265
def get_communication_led_config
  check_validity

  send_request FUNCTION_GET_COMMUNICATION_LED_CONFIG, [], '', 9, 'C'
end
get_dmx_mode() click to toggle source

Returns the DMX mode, as set by BrickletDMX#set_dmx_mode.

# File lib/tinkerforge/bricklet_dmx.rb, line 166
def get_dmx_mode
  check_validity

  send_request FUNCTION_GET_DMX_MODE, [], '', 9, 'C'
end
get_error_led_config() click to toggle source

Returns the configuration as set by BrickletDMX#set_error_led_config.

# File lib/tinkerforge/bricklet_dmx.rb, line 287
def get_error_led_config
  check_validity

  send_request FUNCTION_GET_ERROR_LED_CONFIG, [], '', 9, 'C'
end
get_frame_callback_config() click to toggle source

Returns the frame callback config as set by BrickletDMX#set_frame_callback_config.

# File lib/tinkerforge/bricklet_dmx.rb, line 307
def get_frame_callback_config
  check_validity

  send_request FUNCTION_GET_FRAME_CALLBACK_CONFIG, [], '', 12, '? ? ? ?'
end
get_frame_duration() click to toggle source

Returns the frame duration as set by BrickletDMX#set_frame_duration.

# File lib/tinkerforge/bricklet_dmx.rb, line 239
def get_frame_duration
  check_validity

  send_request FUNCTION_GET_FRAME_DURATION, [], '', 10, 'S'
end
get_frame_error_count() click to toggle source

Returns the current number of overrun and framing errors.

# File lib/tinkerforge/bricklet_dmx.rb, line 246
def get_frame_error_count
  check_validity

  send_request FUNCTION_GET_FRAME_ERROR_COUNT, [], '', 16, 'L L'
end
get_identity() click to toggle source

Returns the UID, the UID where the Bricklet is connected to, the position, the hardware and firmware version as well as the device identifier.

The position can be 'a', 'b', 'c', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port). A Bricklet connected to an :ref:`Isolator Bricklet <isolator_bricklet>` is always at position 'z'.

The device identifier numbers can be found :ref:`here <device_identifier>`. |device_identifier_constant|

# File lib/tinkerforge/bricklet_dmx.rb, line 451
def get_identity
  send_request FUNCTION_GET_IDENTITY, [], '', 33, 'Z8 Z8 k C3 C3 S'
end
get_spitfp_error_count() click to toggle source

Returns the error count for the communication between Brick and Bricklet.

The errors are divided into

  • ACK checksum errors,

  • message checksum errors,

  • framing errors and

  • overflow errors.

The errors counts are for errors that occur on the Bricklet side. All Bricks have a similar function that returns the errors on the Brick side.

# File lib/tinkerforge/bricklet_dmx.rb, line 324
def get_spitfp_error_count
  check_validity

  send_request FUNCTION_GET_SPITFP_ERROR_COUNT, [], '', 24, 'L L L L'
end
get_status_led_config() click to toggle source

Returns the configuration as set by BrickletDMX#set_status_led_config

# File lib/tinkerforge/bricklet_dmx.rb, line 392
def get_status_led_config
  check_validity

  send_request FUNCTION_GET_STATUS_LED_CONFIG, [], '', 9, 'C'
end
read_frame() click to toggle source

Returns the last frame that was written by the DMX master. The size of the array is equivalent to the number of channels in the frame. Each byte represents one channel.

The next frame is available after the CALLBACK_FRAME_AVAILABLE callback was called.

Generic approach:

Instead of polling this function you can also use the CALLBACK_FRAME callback. You can enable it with BrickletDMX#set_frame_callback_config.

The frame number starts at 0 and it is increased by one with each received frame.

This function can only be called in slave mode.

# File lib/tinkerforge/bricklet_dmx.rb, line 525
def read_frame
  ret = nil # assigned in block
  frame_length = nil # assigned in block
  frame_data = nil # assigned in block

  @stream_mutex.synchronize {
    ret = read_frame_low_level
    frame_length = ret[0]
    frame_chunk_offset = ret[1]
    frame_out_of_sync = frame_chunk_offset != 0
    frame_data = ret[2]

    while not frame_out_of_sync and frame_data.length < frame_length
      ret = read_frame_low_level
      frame_length = ret[0]
      frame_chunk_offset = ret[1]
      frame_out_of_sync = frame_chunk_offset != frame_data.length
      frame_data += ret[2]
    end

    if frame_out_of_sync # discard remaining stream to bring it back in-sync
      while frame_chunk_offset + 56 < frame_length
        ret = read_frame_low_level
        frame_length = ret[0]
        frame_chunk_offset = ret[1]
      end

      raise StreamOutOfSyncException, 'Frame stream is out-of-sync'
    end
  }

  [frame_data[0, frame_length], ret[3]]
end
read_frame_low_level() click to toggle source

Returns the last frame that was written by the DMX master. The size of the array is equivalent to the number of channels in the frame. Each byte represents one channel.

The next frame is available after the CALLBACK_FRAME_AVAILABLE callback was called.

Generic approach:

Instead of polling this function you can also use the CALLBACK_FRAME callback. You can enable it with BrickletDMX#set_frame_callback_config.

The frame number starts at 0 and it is increased by one with each received frame.

This function can only be called in slave mode.

# File lib/tinkerforge/bricklet_dmx.rb, line 217
def read_frame_low_level
  check_validity

  send_request FUNCTION_READ_FRAME_LOW_LEVEL, [], '', 72, 'S S C56 L'
end
read_uid() click to toggle source

Returns the current UID as an integer. Encode as Base58 to get the usual string version.

# File lib/tinkerforge/bricklet_dmx.rb, line 435
def read_uid
  check_validity

  send_request FUNCTION_READ_UID, [], '', 12, 'L'
end
register_callback(id, &block) click to toggle source

Registers a callback with ID id to the block block.

# File lib/tinkerforge/bricklet_dmx.rb, line 560
def register_callback(id, &block)
  callback = block
  @registered_callbacks[id] = callback
end
reset() click to toggle source

Calling this function will reset the Bricklet. All configurations will be lost.

After a reset you have to create new device objects, calling functions on the existing ones will result in undefined behavior!

# File lib/tinkerforge/bricklet_dmx.rb, line 416
def reset
  check_validity

  send_request FUNCTION_RESET, [], '', 8, ''
end
set_bootloader_mode(mode) click to toggle source

Sets the bootloader mode and returns the status after the requested mode change was instigated.

You can change from bootloader mode to firmware mode and vice versa. A change from bootloader mode to firmware mode will only take place if the entry function, device identifier and CRC are present and correct.

This function is used by Brick Viewer during flashing. It should not be necessary to call it in a normal user program.

# File lib/tinkerforge/bricklet_dmx.rb, line 339
def set_bootloader_mode(mode)
  check_validity

  send_request FUNCTION_SET_BOOTLOADER_MODE, [mode], 'C', 9, 'C'
end
set_communication_led_config(config) click to toggle source

Sets the communication LED configuration. By default the LED shows communication traffic, it flickers once for every 10 received data packets.

You can also turn the LED permanently on/off or show a heartbeat.

If the Bricklet is in bootloader mode, the LED is off.

# File lib/tinkerforge/bricklet_dmx.rb, line 258
def set_communication_led_config(config)
  check_validity

  send_request FUNCTION_SET_COMMUNICATION_LED_CONFIG, [config], 'C', 8, ''
end
set_dmx_mode(dmx_mode) click to toggle source

Sets the DMX mode to either master or slave.

Calling this function sets frame number to 0.

# File lib/tinkerforge/bricklet_dmx.rb, line 159
def set_dmx_mode(dmx_mode)
  check_validity

  send_request FUNCTION_SET_DMX_MODE, [dmx_mode], 'C', 8, ''
end
set_error_led_config(config) click to toggle source

Sets the error LED configuration.

By default the error LED turns on if there is any error (see CALLBACK_FRAME_ERROR_COUNT callback). If you call this function with the Show-Error option again, the LED will turn off until the next error occurs.

You can also turn the LED permanently on/off or show a heartbeat.

If the Bricklet is in bootloader mode, the LED is off.

# File lib/tinkerforge/bricklet_dmx.rb, line 280
def set_error_led_config(config)
  check_validity

  send_request FUNCTION_SET_ERROR_LED_CONFIG, [config], 'C', 8, ''
end
set_frame_callback_config(frame_started_callback_enabled, frame_available_callback_enabled, frame_callback_enabled, frame_error_count_callback_enabled) click to toggle source

Enables/Disables the different callbacks. By default the CALLBACK_FRAME_STARTED callback and CALLBACK_FRAME_AVAILABLE callback are enabled while the CALLBACK_FRAME callback and CALLBACK_FRAME_ERROR_COUNT callback are disabled.

If you want to use the CALLBACK_FRAME callback you can enable it and disable the cb:`Frame Available` callback at the same time. It becomes redundant in this case.

# File lib/tinkerforge/bricklet_dmx.rb, line 300
def set_frame_callback_config(frame_started_callback_enabled, frame_available_callback_enabled, frame_callback_enabled, frame_error_count_callback_enabled)
  check_validity

  send_request FUNCTION_SET_FRAME_CALLBACK_CONFIG, [frame_started_callback_enabled, frame_available_callback_enabled, frame_callback_enabled, frame_error_count_callback_enabled], '? ? ? ?', 8, ''
end
set_frame_duration(frame_duration) click to toggle source

Sets the duration of a frame.

Example: If you want to achieve 20 frames per second, you should set the frame duration to 50ms (50ms * 20 = 1 second).

If you always want to send a frame as fast as possible you can set this value to 0.

This setting is only used in master mode.

# File lib/tinkerforge/bricklet_dmx.rb, line 232
def set_frame_duration(frame_duration)
  check_validity

  send_request FUNCTION_SET_FRAME_DURATION, [frame_duration], 'S', 8, ''
end
set_status_led_config(config) click to toggle source

Sets the status LED configuration. By default the LED shows communication traffic between Brick and Bricklet, it flickers once for every 10 received data packets.

You can also turn the LED permanently on/off or show a heartbeat.

If the Bricklet is in bootloader mode, the LED is will show heartbeat by default.

# File lib/tinkerforge/bricklet_dmx.rb, line 385
def set_status_led_config(config)
  check_validity

  send_request FUNCTION_SET_STATUS_LED_CONFIG, [config], 'C', 8, ''
end
set_write_firmware_pointer(pointer) click to toggle source

Sets the firmware pointer for BrickletDMX#write_firmware. The pointer has to be increased by chunks of size 64. The data is written to flash every 4 chunks (which equals to one page of size 256).

This function is used by Brick Viewer during flashing. It should not be necessary to call it in a normal user program.

# File lib/tinkerforge/bricklet_dmx.rb, line 358
def set_write_firmware_pointer(pointer)
  check_validity

  send_request FUNCTION_SET_WRITE_FIRMWARE_POINTER, [pointer], 'L', 8, ''
end
write_firmware(data) click to toggle source

Writes 64 Bytes of firmware at the position as written by BrickletDMX#set_write_firmware_pointer before. The firmware is written to flash every 4 chunks.

You can only write firmware in bootloader mode.

This function is used by Brick Viewer during flashing. It should not be necessary to call it in a normal user program.

# File lib/tinkerforge/bricklet_dmx.rb, line 372
def write_firmware(data)
  check_validity

  send_request FUNCTION_WRITE_FIRMWARE, [data], 'C64', 9, 'C'
end
write_frame(frame) click to toggle source

Writes a DMX frame. The maximum frame size is 512 byte. Each byte represents one channel.

The next frame can be written after the CALLBACK_FRAME_STARTED callback was called. The frame is double buffered, so a new frame can be written as soon as the writing of the prior frame starts.

The data will be transfered when the next frame duration ends, see BrickletDMX#set_frame_duration.

Generic approach:

  • Set the frame duration to a value that represents the number of frames per second you want to achieve.

  • Set channels for first frame.

  • Wait for the CALLBACK_FRAME_STARTED callback.

  • Set channels for next frame.

  • Wait for the CALLBACK_FRAME_STARTED callback.

  • and so on.

This approach ensures that you can set new DMX data with a fixed frame rate.

This function can only be called in master mode.

# File lib/tinkerforge/bricklet_dmx.rb, line 475
def write_frame(frame)
  if frame.length > 65535
    raise ArgumentError, 'Frame can be at most 65535 items long'
  end

  frame_length = frame.length
  frame_chunk_offset = 0

  if frame_length == 0
    frame_chunk_data = [0] * 60
    ret = write_frame_low_level frame_length, frame_chunk_offset, frame_chunk_data
  else
    ret = nil # assigned in block

    @stream_mutex.synchronize {
      while frame_chunk_offset < frame_length
        frame_chunk_data = frame[frame_chunk_offset, 60]

        if frame_chunk_data.length < 60
          frame_chunk_data += [0] * (60 - frame_chunk_data.length)
        end

        ret = write_frame_low_level frame_length, frame_chunk_offset, frame_chunk_data
        frame_chunk_offset += 60
      end
    }
  end

  ret
end
write_frame_low_level(frame_length, frame_chunk_offset, frame_chunk_data) click to toggle source

Writes a DMX frame. The maximum frame size is 512 byte. Each byte represents one channel.

The next frame can be written after the CALLBACK_FRAME_STARTED callback was called. The frame is double buffered, so a new frame can be written as soon as the writing of the prior frame starts.

The data will be transfered when the next frame duration ends, see BrickletDMX#set_frame_duration.

Generic approach:

  • Set the frame duration to a value that represents the number of frames per second you want to achieve.

  • Set channels for first frame.

  • Wait for the CALLBACK_FRAME_STARTED callback.

  • Set channels for next frame.

  • Wait for the CALLBACK_FRAME_STARTED callback.

  • and so on.

This approach ensures that you can set new DMX data with a fixed frame rate.

This function can only be called in master mode.

# File lib/tinkerforge/bricklet_dmx.rb, line 192
def write_frame_low_level(frame_length, frame_chunk_offset, frame_chunk_data)
  check_validity

  send_request FUNCTION_WRITE_FRAME_LOW_LEVEL, [frame_length, frame_chunk_offset, frame_chunk_data], 'S S C60', 8, ''
end
write_uid(uid) click to toggle source

Writes a new UID into flash. If you want to set a new UID you have to decode the Base58 encoded UID string into an integer first.

We recommend that you use Brick Viewer to change the UID.

# File lib/tinkerforge/bricklet_dmx.rb, line 427
def write_uid(uid)
  check_validity

  send_request FUNCTION_WRITE_UID, [uid], 'L', 8, ''
end