ETC Unison Paradigm Serial Access Protocol User Manual

ETC® Configuration Guide

LightDesigner offers three types of serial options and three
groupings of properties to configure them including “RS232
Serial Config”, “UDP Serial Config” and “ACN Serial Config”.
To view and set these properties, select a Processor from the
Browser. The properties of the selected Processor will display
in the Property Editor.

Paradigm Serial Access Protocol (PSAP)

Overview

The Paradigm ACP can be controlled through its local RS232 serial port and Ethernet interface using a
default command structure referred to as the Paradigm Serial Access Protocol (PSAP). All aspects of
serial communication can be configured in LightDesigner, including RS232 serial port baud rate and
UDP packet settings.

LightDesigner Setup

Expand the “RS232 Serial Config” property to view the port setup. Default settings are Baud Rate of
9600, Parity None, 1 Stop Bit (8 data bits is mandatory).

Expand the “UDP Serial Config” property to view the port setup. Input UDP Port defaults to “0” and the
Input Handler defaults to [None]. ETC recommends setting the Input UDP Port property in the range of
4703-4727. This same port will be used for replies sent from the Paradigm Architectural Control
Processor (P-ACP). If needed, contact ETC Technical Support for additional support with UDP serial
setup.

Expand the “ACN Serial Config” property to view the port setup. ACN Serial Config allows for reliable
communication between devices that support this method over ACN using simple setup. Devices with
matching “ACN Name” property value will connect and communicate.

• For example, a processor's ACN Serial PSAP Input Handler will by default listen to any device
configured to send using an ACN Name of "ETC P-ACP". The same Processor will also respond
to any queries using the same ACN Name, so any other devices configured to receive from that
ACN Name will get all responses. It is possible to specify multiple ACN Names using comma
separation in the property, but note that the PSAP input handler will respond to all devices with a
matching ACN Name.

Note:

Devices with matching “ACN Name” property are considered part of a broadcast
domain, and will hear anything sent in that session.

Note:

ETC recommends that serial communications via Ethernet contain no more than 512
bytes per packet.

Corporate Headquarters
London, UK
Rome, IT 
Holzkirchen, DE
Hong Kong  Rm 1801, 18/F, Tower 1 Phase 1, Enterprise Square, 9 Sheung Yuet Road, Kowloon Bay, Kowloon, Hong Kong  Tel [phone]  Fax [phone]
Service:
Web:
7180M2400

 Unit 26-28, Victoria Industrial Estate, Victoria Road, London W3 6UU, UK  Tel [phone]  Fax [phone]

Via Pieve Torina, 48, 00156 Rome, Italy  Tel [phone]  Fax [phone]

(Americas) [e-mail] 

www.etcconnect.com 

 Rev E  Released 2012-08  ETC intends this document to be provided in its entirety.

 3031 Pleasant View Road, P.O. Box 620979, Middleton, Wisconsin 53562-0979 USA  Tel [phone]  Fax [phone]

 Ohmstrasse 3, 83607 Holzkirchen, Germany  Tel [phone]  Fax [phone]

Copyright © 2012 ETC. All Rights Reserved.  Product information and specifications subject to change.

(UK) [e-mail]  (DE) [e-mail] 

(Asia) [e-mail]

PSAP Configuration Guide Page 1 of 7 Electronic Theatre Controls, Inc.

ETC Configuration Guide

Paradigm Serial Access Protocol (PSAP)

Note:

With “Advanced” level user access,
LightDesigner offers a property called
“Verbose Logging”, nested beneath the “Input
Handler” node for each serial option when
PSAP 2.1 is the selected setting.

“Verbose Logging” defaults to Disabled, but
can be set to log additional data internally
using ASCII, Decimal, or Hexidecimal data
formatting.

This can be useful when troubleshooting a
communications problem, but generally
should be left as disabled for system
efficiency. Contact ETC Technical Support for
additional support with logging features.

Input Handler Options

Twirl open the “Input Handler” node that is nested beneath the
selected serial option node. Depending on the LightDesigner
user access level, several configuration options are displayed
when the Input Handler is set to “PSAP 2.1”.

• End of Message Char - an “Advanced” level user access
feature. By default the end of message is a single byte
carriage return (shown as “CR”), which is equal to 13
decimal and 0D hexadecimal. Other options for this
property are carriage return plus line feed (CR+LF) and
just a line feed character (LF).

• Verbose Logging - an “Advanced” level user access
feature. Can be set to log data internally using ASCII,
Decimal, or Hexidecimal data formatting.

• UStrings - 20 user definable strings and actions that
when received will execute the corresponding UString
Action.

• UString Actions - 20 user definable actions that are
executed when the corresponding UString data is
received.

For example, configuring the following:

• UString 1 = hello
UString 1 Action = Sequence Start for Sequence 1

Results in the following:

Step 1: When “hello” is received, Sequence 1 will start.

Note:

PSAP Configuration Guide Page 2 of 7 Electronic Theatre Controls, Inc.

By default, an ASCII carriage return character (which is encoded as 13 decimal and
0D Hex) is used to terminate or signal the end of any comment, received or sent.
Received commands are only considered complete once the terminating character
has been received by Paradigm.

Data sent from the Paradigm Architectural Control Processor (P-ACP) will also end
with the terminating character. Contact ETC Professional Services if support for
another terminating character is required.

ETC Configuration Guide

Paradigm Serial Access Protocol (PSAP)

Standard PSAP Commands

The following section lists the standard types of serial commands that are supported by the Paradigm
Serial Access Protocol (PSAP).

Conventions of Use

• Generic names such as “channame” must be replaced with the actual object names used within
the LightDesigner configuration.

Note:

• Values such as “level” and “amount” must be replaced with either a value of 0-255 or 0-100%.
Both formats are supported; use of the percent “%” symbol indicates when the value should be
treated as a percentage.

• Items listed inside of braces “[ ]“are optional parameters that use a comma “,” as a delimiter.

• White space must separate individual command parameters. White spaces are allowed in object
names as well.

• By default, an ASCII carriage return character (which is encoded as 13 decimal and 0D Hex)
is used to terminate or signal the end of any command, received or sent. Contact ETC
Professional Services if support for another terminating character is required.

• PSAP will return a list of available commands by issuing either ? or help followed by the
terminating character (by default this is a carriage return).

All names are case sensitive and must match the names to LightDesigner exactly.
Additionally, to allow for proper operation avoid the use of commas “,” and colons “:”
in configuration object names since these characters are instrumental in the string
parsing logic.

Control Channel Commands

Received Data Resulting Action

chan int:level channame[, spacename] Sets intensity to level
chan ras:amount channame[, spacename] Raises intensity by amount
chan low:amount channame[, spacename] Lowers intensity by amount
chan tog channame[, spacename] Toggles intensity
chan min:level channame[,spacename] Sets minimum level for a channel
chan max:level channame[,spacename] Sets maximum level for a channel

chan int:128 Zone 1 sets Zone 1 to 50% intensity
chan int:75% Dimmer 2, Primary Space 1 Sets Dimmer 2 in Primary Space 1 to 75%

Note:

Remember, received commands are only considered complete once the terminating
character has been received by Paradigm. Data sent from the P-ACP will also end with
the terminating character.

Group Commands

Fade time format is x.y seconds, with support for tenths of seconds. To use fadetime parameter in your
group command, you must specify a space name.

Received Data Resulting Action

grp int:level grpname[, spacename][, fadetime] Sets intensity to level value
grp ras:amount grpname[, spacename][, fadetime] Raises intensity by amount
grp low:amount grpname[, spacename][, fadetime] Lowers intensity by amount
grp tog grpname[, spacename][, fadetime] Toggles Group intensity

grp int:128 Group 1, 3

PSAP Configuration Guide Page 3 of 7 Electronic Theatre Controls, Inc.

sets Group 1 intensity to 50% using a
3 second fade

ETC Configuration Guide

Paradigm Serial Access Protocol (PSAP)

Preset Commands

Fade time format is x.y seconds, with support for tenths of seconds. To use fadetime parameter in your
preset command, you must specify a space name.

Received Data Resulting Action

pst act presetname[, spacename][, fadetime] Activate (using LTP playback),
pst dact presetname[, spacename][, fadetime] Deactivate
pst tog presetname[, spacename][, fadetime] Inverts Preset state (using LTP playback)
pst rec presetname[, spacename] Records a Preset

pst act Preset 1, Primary Space 1, 5

activates Preset 1 in Primary Space 1 using a 5
second fade

Sequence Commands

Received Data Resulting Action

seq start sequencename[, spacename] Start playback
seq stop sequencename[, spacename] Stops playback
seq pause sequencename Pause playback
seq resume sequencename Resume playback
seq ras:amount sequencename Raises by amount (requires active Sequence)
seq low:amount sequencename Lowers by amount (requires active Sequence)
seq rate:faderate sequencename Sets Sequence playback rate to level

seq start Sequence 1 starts Sequence 1

Space Commands

Received Data Resulting Action

spc off spacename Activates Off within the Space
spc ras:amount spacename Raises all intensities by amount
spc low:amount spacename Lowers all intensities by amount
spc master:level spacename Sets Master level for the Space to level

spc off Primary Space 1 activates the “Off” preset in Primary Space 1

Wall Commands

Received Data Resulting Action

wall open wallname[, spacename] Opens a wall
wall close wallname[, spacename] Closes a wall
wall tog wallname[, spacename] Toggles wall state

wall open Wall 1 opens Wall 1

Note:

PSAP Configuration Guide Page 4 of 7 Electronic Theatre Controls, Inc.

Spacename must be used to specify the parent space containing the wall, not the
spaces combined through the wall.

ETC Configuration Guide

Paradigm Serial Access Protocol (PSAP)

Macro Commands

Received Data Resulting Action

macro on macroname Executes On steps of a macro
macro off macroname Executes Off steps of a macro
macro tog macroname Toggles macro state
macro cancel macroname Cancels execution

macro on Macro 1 executes on steps of Macro 1

Override Commands

Received Data Resulting Action

ovr enab overridename Enables override
ovr disab overridename Disables override
ovr tog overridename Toggles override state

ovr enab Override 1 enables Override 1

Log Commands

The following commands allow the serial device to temporarily alter logging setup.

Note:

Received Data Resulting Action

log disabled Disables logging
log ascii sets log format to ASCII
log dec sets log format to decimal
log hex sets log format to hexadecimal
log get retrieves the current log setting

The property set for “Verbose Logging” property in LightDesigner will be restored as
the logging setup after any Paradigm Architectural Control Processor (P-ACP) reboot.

PSAP Configuration Guide Page 5 of 7 Electronic Theatre Controls, Inc.

ETC Configuration Guide

Paradigm Serial Access Protocol (PSAP)

PSAP Status Commands

The following commands will return information on current status. The strings returned follow the same
basic format as the standard commands received by Paradigm with following noted exceptions:

• the spacename is optional within the command but it will always be included in the returned string

• levels will always be returned as a value of 0-255

Note:

Remember, commands sent to the PACP must possess the terminating character,
and returned data will contain the same terminating character (the default is carriage
return).

Channel Status

Received Data Returned Data

chan get channame[, spacename] chan int:level channame, spacename

Preset Status

Received Data Returned Data Comment

pst act presetname, spacename indicates preset activated

pst get presetname[, spacename]

pst dact presetname, spacename indicates preset deactivated
pst alt presetname, spacename indicates preset altered

Group Status

Received Data Returned Data

grp get groupname[, spacename] grp int:level grpname, spacename

Macro Status

Received Data Returned Data

macro on macroname

macro get macroname

macro off macroname
macro running macroname

Wall Status

Received Data Returned Data

wall get wallname[, spacename]

wall open wallname, spacename
wall close wallname, spacename

Sequence Status

Received Data Returned Data Comment

seq start sequencename, spacename indicates sequence running

seq get sequencename[, spacename]

seq stop sequencename, spacename indicates sequence stopped
seq pause sequencename, spacename indicates sequence paused

Override Status

Received Data Returned Data

ovr get overridename

PSAP Configuration Guide Page 6 of 7 Electronic Theatre Controls, Inc.

ovr enab overridename
ovr disab overridename

ETC Configuration Guide

Paradigm Serial Access Protocol (PSAP)

PSAP Trigger Support

In addition to using “get” commands to poll for status, Paradigm can be configured to send PSAP
formatted updates for specified objects as updates occur. These “Triggers” are a helpful alternative to
polling for object status as they provide real time updates to objects.

PSAP triggers also simplify setup by quickly allowing configuration of a PSAP formatted serial output as
an alternative to having to reconfigure multiple "when" conditions with differing "send serial" actions.

• Trigger configuration is only available while LightDesigner user access is set to “Advanced” or
higher.

• All objects that support the “get” command are supported with PSAP triggers using the exact same
returned string format.

• Trigger functions with “PSAP” listed within the trigger function name will automatically send serial
updates anytime the specified changes occur to the specified object.

• Each object requires an individual trigger to be created.

PSAP Configuration Guide Page 7 of 7 Electronic Theatre Controls, Inc.