API Reference

Scheduled Sequence Triggers

The Scheduled Sequence Triggers protocol allows you to Play, Pause, and Stop sequences in a synchronized way from a non-Alcorn controller. Commands must be sent to the Alcorn device at UDP port 2638. All commands and responses are terminated with a carriage return (<0D>.) Some responses (like the List Triggers command) may contain multiple data points that are separated with a line feed (<0A>.) Each created trigger is assigned a Universally Unique Identifier (UUID). This UUID is provided within the response whenever a trigger is created so that you can reference the trigger at a later time.

Add Trigger

Adds a new trigger to the scheduled sequence trigger list.

Command

<Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|AddTT<0D>

<Seq Offset> Sequence offset (HH:MM:SS.FF format)

<Seq Name> Name of the sequence to be triggered

<Execution Time> Trigger execution time (SSSSSSSSSS.nnnnnnnnn format.) This value represents an offset from the UTC Epoch (12:00am January 1st 1970) where the 10-digit SSSSSSSSSS field represents seconds, and the 9-digit nnnnnnnnn represents nanoseconds.

<Trigger Type> Action to perform on the sequence when the trigger fires - Play, Pause, or Stop

Response

 <UUID><0D>

<UUID> Unique ID of the new trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format)

Examples

Play sequence "Timeline_Scene1" at 17:39:42 GMT

00:00:00.00|Timeline_Scene1|1681839582.123456|Play|AddTT<0D>

Response

12345678-1234-1234-123456789012<0D>

Modify Trigger

Modifies an existing trigger in the scheduled sequence trigger list.

Command

 <Seq Offset>|<Seq Name>|<Execution Timestamp>|<Trigger Type>|<UUID>|ModTT<0D>

<Seq Offset>:: Sequence offset (HH:MM:SS.FF format)

<Seq Name>:: Name of the sequence to be triggered

<Execution Time>:: Trigger execution time (SSSSSSSSSS.nnnnnnnnn format.) This value represents an offset from the UTC Epoch (12:00am January 1st 1970) where the 10-digit SSSSSSSSSS field represents seconds, and the 9-digit nnnnnnnnn represents nanoseconds.

<Trigger Type>:: Action to perform on the sequence when the trigger fires - Play, Pause, or Stop

<UUID>:: Unique ID of the existing trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format)

Response

 <UUID><0D>

<UUID> Unique ID of the new trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format)

Examples

Modify trigger to Play sequence "Timeline_Scene2" at 17:39:42 GMT

00:00:00.00|Timeline_Scene2|1681839582.123456|Play|12345678-1234-1234-123456789012|ModTT<0D>

Response

12345678-1234-1234-123456789012<0D>

Delete Trigger

Deletes an existing trigger (or all triggers) in the scheduled sequence trigger list.

Command

 <UUID>|DelTT<0D>

<UUID>:: Unique ID of the existing trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format) or * to delete all triggers.

Response

 <UUID><0D>

<UUID>:: Unique ID of the existing trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format)

Examples

Delete trigger with UUID 12345678-1234-1234-123456789012

12345678-1234-1234-123456789012|DelTT<0D>

Response

12345678-1234-1234-123456789012<0D>

List Trigger(s)

Retrieves trigger parameters for one or all triggers.

Command

 <UUID>|LstTT<0D>

<UUID>:: Unique ID of the existing trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format) or * to retrieve all triggers.

Response

<Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0D>

The response to a List Trigger command for all triggers is essentially a list of strings representing each trigger on the controller. Each trigger string is terminated with a linefeed and the end of the list is terminated by a carriage return.

 <Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0A>
 <Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0A>
 <Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0D>

It is easy for the length of this response to exceed the MTU of a network path and/or the minimum datagram size that hosts must accept. Since transmission takes place with UDP, this can cause data loss. In the case where the length of this response would exceed 512 bytes, the response will be split into multiple 512-byte (or smaller) datagrams in the following way:

Response message will start in the normal way. Information about triggers will be appended to the datagram and separated by line feeds.
If appending a trigger to the response would cause the payload size to exceed 500 bytes, the trigger will not be appended to the message. Instead, an opening square bracket will be appended on that line, followed by a four-digit zero-padded "block number", a forward slash, a four-digit zero-padded "block count", and a closing square bracket. The end of the datagram will be the closing bracket (no carriage return or line feed will be appended to it.)
The final block will have the same pattern as the previous blocks, containing linefeed-separated triggers and being terminated by the block number and block count in square brackets. In addition, the final block will be terminated by a carriage return immediately following the closing square bracket. The client can determine if they have received the full message by checking that each block they have received has a unique number and that the total number of blocks received is equal to the given block count.

Packet 1

 <Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0A>
 <Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0A>
 [0001/0002]

Packet 2

 <Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0A>
 <Seq Offset>|<Seq Name>|<Execution Time>|<Trigger Type>|<UUID><0A>
 [0002/0002]<0D>

Examples

Get parameters of trigger with UUID

12345678-1234-1234-123456789012|LstTT<0D>

Response

00:00:00.00|Timeline_Scene2|1681839582.123456|Play|12345678-1234-1234-123456789012|ModTT<0D>

Get parameters of ALL triggers

*|LstTT<0D>

Response

00:00:00.00|Timeline_Scene2|1681839582.123456|Play|12345678-1234-1234-123456789012<0A>
00:00:01.00|Timeline_Scene4|1681839582.123456|Play|11111111-1111-1111-111111111111<0A>
00:00:02.00|Timeline_Scene5a|1681839582.123456|Play|22222222-2222-2222-222222222222<0D>

Disable Trigger

Disables an existing trigger in the scheduled sequence trigger list.

Command

 <UUID>|DisTT<0D>

<UUID>:: Unique ID of the existing trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format)

Response

 <UUID><0D>

Examples

Disable trigger with UUID 12345678-1234-1234-123456789012

12345678-1234-1234-123456789012|DisTT<0D>

Response

12345678-1234-1234-123456789012<0D>

Enable Trigger

Enables an existing trigger in the scheduled sequence trigger list.

Command

 <UUID>|EnaTT<0D>

<UUID>:: Unique ID of the existing trigger (XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX format)

Response

 <**UUID**><0D>

Examples

Enable trigger with UUID 12345678-1234-1234-123456789012

12345678-1234-1234-123456789012|DisTT<0D>

Response

12345678-1234-1234-123456789012<0D>