Twinkly Pro products can be integrated with third-party control systems (OSC or DMX/Art-Net), allowing more advanced lighting setups and control. This guide provides an overview to help you understand what's possible and how to get started.

Please note: Christmas Designers does not provide troubleshooting for third-party software or hardware. For implementation, we recommend working with a qualified lighting engineer experienced in OSC.

OSC Integration Overview

What is OSC?

Open Sound Control (OSC) is a network protocol used for multimedia systems. With the correct setup, OSC can send commands to Twinkly Pro devices over a local network.

Requirements

• Twinkly Pro model: TWPRO1500ETHP, TWPROCTRLPLC21, or TWPROCTRLSPI21
• Firmware version v3.5.0 or higher
• Devices must be commissioned via the Twinkly iOS app
• Integration Interface Protocol must be enabled manually in the app

Suggested Software:

• QLab (Mac only): https://qlab.app

Communication Protocol:

The communication is based on the OSC (Open Sound Control) network protocol. UDP is used as the transport layer protocol. When the Integration Interface Protocol is enabled for a device, the latter starts listening for OSC commands on the UDP port 9000.

The communication protocol is versioned and it’s version is used as part of the OSC address. The target devices identifiers are explicitly specified as part of the OSC address into the packet being sent, so that both unicast and broadcast communications can be used to address also a specific device/object. It is therefore not mandatory to know in advance the IP address of the devices in order to control the installation, as all the commands can be broadcasted to the whole subnetwork and each device will be responsible for filtering the messages it is interested in.

Basic Commands Supported

• Set Application Mode: Off, Movie, Playlist, Color
  • OSC Address: /v1/<device_id>/application/mode
  • Parameters
    • mode: string representing the application working mode, can be one of: [“off”, “movie”, “playlist”]
    • id: int32 (optional - alternative to uuid) handle [0..15] of the movie to be reproduced (only if the current application mode is “movie”)
    • uuid: string (optional - alternative to id) uuid of the movie to be reproduced only if the current application mode is “movie”)
      
      
• Select Movie: This method allows the user to select the movie to be reproduced when the “movie” mode is active. If the current mode is already set to “movie”, it just changes the currently reproduced movie.
  • Parameters:
    • id: int32 (alternative to uuid) handle [0..n] of the movie
    • uuid: string (alternative to id) uuid of the movie
• Set Brightness: Enables/Disables the brightness control and sets the dim level
  • Parameters
    • mode: string indicating the mode to be set for the filter, can be one from: [“disabled”, “enabled”]
    • type: string indicating how the value parameter is applied, can be one from [“A”, “R”] (A = absolute R = relative)
    • value: int32 representing the brightness level. If type is set to “A”, the applicable range is [0..100], if type is set to “R”, the applicable range is [-100..100].

Address naming scheme

The first part of the address is always expressed in the following form:

/<version>/<device_id>

Where:

<version> represents the version of the protocol

<device_id> represents the device identifier and is composed of the concatenation of the “TwPRO” string with the MAC Address of the device, expressed in lower-case format and without any separator character between the MAC octets.

The MAC Address of each device can be retrieved by using the Mobile Twinkly App.

Example: /v1/TwPRO304950a030ec

Message Dispatching and Address Pattern Matching

According to the Open Sound Control 1.0 Specification (for further information see section “OSC Message Dispatching and Pattern Matching” of the corresponding specification), the device identifier can be replaced by a wildcard (the special character “*”), which allows the user to address any device capable of receiving the message just by using the string “TwPRO*”, without having to specify its complete address in the message. This allows to send a broadcast message in a subnet containing many devices and therefore to issue the same command to several devices simultaneously, resulting in the synchronous control of all the Twinkly controllers connected to the network.

Example: /v1/TwPRO*

 Control Modes:

A Twinkly PRO device can be configured as a single device or as a device part of a group. Depending on such configuration and on the role of the device in the group, different control modes should be used:

• when a device is configured as single device, it can be controlled and addressed directly;
• when a device is part of a group, only the master of the group should be targeted by a command.

The master is then responsible for synchronizing the received configuration to all the other devices part of the Group.

Conventions

Master Device Identification

The master device of a group is reported by Twinkly App.

Handle/UUID-to-saved effect association criteria

Twinkly mobile application provides an interface to inspect the list of installed effects with all details required by Integration Interface usage.