Skip to main content
Electronic Theatre Controls Inc

USAP Objects, Properties and Actions

Unison Serial Access Protocol command strings must match the case and spacing of objects in the Unison configuration. 

Commands are case-sensitive and need to be phrased accurately. The example below is shown as a Command (from the external device to a Unison Processor) and a Response (from Unison Processor to the external device).

Example:

  • Command: [Ballroom.Hall A.Dinner.ACTI]
  • Response: [?Ballroom.]

 Error:

A room named “BALLROOM” must be referred to in all capital letters in a command. Commands referring to the room as “Ballroom” will return as invalid.

Rooms

In USAP, Room objects have no properties or actions, but are used when referencing the objects contained in them such as Presets, Walls, Sections, and Zones.

Sections

In USAP, section objects have no properties or actions but are used when referencing Zones contained in them, when obtaining the status of a Preset action, or section Master values.

Presets

Preset objects are referenced by Room and Section objects.

  • To send commands which will affect a Preset, first reference the Room and then the Preset. Example: [BALLROOM.Dinner].
  • To access properties or actions specific to a section in a divided room, you must reference the Room, the Section, and then the Preset. Example: [BALLROOM.Hall A.Dinner].

Preset Command Format:

You can place multiple commands for the same object on a single command line, provided they are each separated by a period.

Example: [ROOM NAME].[SECTION NAME].[PRESET NAME].COMMAND

Preset Commands: 

  • Activate a preset: ACTI
  • Deactivate a Preset: DACT
  • Record a Preset: RECO
  • Set a fade time for a Preset: nDFT= (time is entered in milliseconds)
  • Get status of a Preset: bACT
    • (Unison will respond with Preset name and 1=active, or 0=not active)
  • Get Priority status of a Preset: bAAP
    •  (Unison will respond with preset name and priority level)
Property Description Value

bACT


bAAP
 

nDFT

Active
(read only)

Active at Priority
(read only)

Fade Time

False = Preset is not active
True = Preset is active

False = Preset is not active at it’s current priority
True = Preset is active at it’s current priority

milliseconds from 0 to 4294967295
(approximately 50 days)

 

Action Description Function

ACTI

DACT

RECO

Activate

Deactivate

Record

Activates the Preset at the current priority and with the current fade time

Deactivates the Preset at the current priority and with the current fade time

Record the Preset

Preset Examples:

Examples of preset commands:

Activate a Preset

  • Command - [BALLROOM.Hall A.Dinner.ACTI]
  • Response - [BALLROOM.Hall A.Dinner.ACTI]

Activate a Preset including Fade Time

  • Command - [BALLROOM.Dinner.nDFT=5000]
  • Response - [BALLROOM.Dinner.nDFT=5000]
    • *(5000 milliseconds = 5 second fade)

Get the Active state of a Preset in a Section

  • Command - [BALLROOM.Hall A.Dinner.bACT.BAAP]
  • Response - [BALLROOM.Hall A.Dinner.bACT.BAAP=0]
    • =0 means the preset is not active / =1 means the preset is active

Walls

Wall Command Format:

[ROOM NAME].[WALL NAME].COMMAND Wall Commands:

  • Open a Wall: OPEN
    • Close a Wall: CLOS
  • Toggle a Wall State: TOGL
  • Get status of a Wall: bOPN
    • (Unison Processor will respond with Wall name and 1=open or 0=closed
Property Description Value
bOPN Open If false (=0), Wall is closed and related sections are not combined.
If true (=1), Wall is open and related sections are combined.

 

Action Description Function

OPEN

CLOS

TOGL

Open

Close

Toggle

Wall state is set to Open (same as bOPN=1)

Wall state is set to Close (same as bOPN =0)

Wall state is toggled (open to closed, or closed to open)

Wall Examples

Get the open/close state of a wall

  • Command - [BALLROOM.East Wall.bOPN]
  • Response - [BALLROOM.East Wall.bOPN=0]
    • =0 means the wall is closed / =1 means the wall is open

Set the open/close state of a Wall

  • Command - [BALLROOM.East Wall.bOPN=1]
  • Response - [BALLROOM.East Wall.bOPN=1]
    OR
  • Command - [BALLROOM.East Wall.OPEN]
  • Response - [BALLROOM.East Wall.OPEN]

Toggle the open/close state of a Wall and get its new open/close state

  • Command - [BALLROOM.East Wall.bOPN]
  • Response - [BALLROOM.East Wall.BOPN=0]
    • =0 means the wall is closed / =1 means the wall is open

Zones

Zones are contained in Rooms or Sections and can be controlled by Presets. To send commands which will affect a Zone in a Room, first reference the Room and then the Zone. Example: [BALLROOM.Downlights].

If the Room is divided (or uses the Unison room combine feature), reference the Room and Section, and then the Zone. Example: [BALLROOM.Hall A.Downlights].

Zone Command Format:

[ROOM NAME].[SECTION NAME].[ZONE NAME].COMMAND

Zone Commands:

  • Set intensity value for a Zone: nINT=[Intensity value]
    • Intensity values are displayed and transmitted in 16-bits. In this system 0=off and builds to full =65535. Intensity values must be input in this numerical system. Reference Level Percentages to 16-bit Zone Value Chart, page 27.
  • Get intensity value for a Zone: nINT
    • (Unison Processor will respond with Zone name and 16-bit value)
Property Description Value
bOPN Open If false (=0), Wall is closed and related sections are not combined.
If true (=1), Wall is open and related sections are combined.

Determining 16-bit Zone values

To determine 16-bit values for Zone levels, multiply the desired percentage by 65535. See also Level Percentages to 16-bit Zone Value Chart, page 27.

Zone Examples

Get the intensity of a zone

  • Command - [BALLROOM.Downlights.nINT]
  • Response - [BALLROOM.Downlights.nINT=0]
    • =0 indicates that the zone is off

Set the intensity of a zone

  • Command - [BALLROOM.Hall A.Downlights.nINT=65535]
  • Response - [BALLROOM.Hall A.Downlights.nINT=65535]
    • In 16 bit values, 65535 indicates the zone is at full

Macros

A Macro is a series of pre-stored commands that can be carried out by the Unison processor.

Macro Command Format:

[MACRO NAME].[COMMAND]

Macro Commands

Action Description Function

EXEC

STOP

Execute

Stop

Run the macro

Stop the macro

Macro Examples

Run a Macro called Lockout

  • Command - [Lockout.EXEC]
  • Response - [Lockout.EXEC]

Stop a Macro called Lockout

  • Command - [Lockout.STOP]
  • Response - [Lockout.STOP]

Master

Sections of a room, including Section Zero, may be mastered by using the master value command. This command yields the same functionality as a station fader configured as Master for a serially connected device. This command may also be useful in monitoring the master value of a section if a station alters it.

Master Command Format:

[ROOM NAME].[SECTION NAME].Master.COMMAND

Master Commands

Set the Master level value for a specified section: nVAL=[Level value]

  • Level values are displayed and transmitted in 16-bits. In this system 0-off and builds to full -65535. Like Zone intensity, Master level values must be input in this numerical system. See “Level Percentages to 16-bit Zone Value Chart.” 

Get the Master level value for a specified section: nVAL

  • Unison processor will respond with the active 16-bit Master level for the specified Section.

Zone Set and Get Command

Property Description Value
nVAL level value 0 = off
65535 = Full On (100%)

 Master Responses

Action Description Function

nVAL

level value

Section Master level value

Master Examples

Get the Master level value for a Section of a Room

  • Command - [BALLROOM.Hall A.Master.nVAL]
  • Response - [BALLROOM.Hall A.Master.nVAL=65535]
    • = 32767 indicates that the Master value of Hall A is at 50%
    • = 0 indicates that the Master value of Hall A is at 0%

Set the Master level value for a Section of a Room

  • Command - [BALLROOM.Section Zero.Master.nVAL=65535]
  • Response - [BALLROOM.Section Zero.Master.nVAL=65535]
    • In 16-bit values, 65535 indicates the Master level value is at full 100%
    • Use of Section Zero here implies that all Sections within a Room will be simultaneously affected.

Note: The Set Master value command behaves as a station Master fader does. The nVAL value either has to be larger than other active Master faders or at full to attain Master control of the space. This also implies that like faders, changes in Preset and Zone states will affect the Master’s behavior.

  • Was this article helpful?