Programming API

• 1: Command Lines
• 2: Web API

1 - Command Lines

Overview

Command line arguments tell Vixen, when it loads, to disable a certain feature or to set a certain option.

Arguments

• no_controllers - Disables all of the controllers in one swell foop.
• no_execution - Disables the execution engine of Vixen.
• data_dir - All of the configuration data for Vixen is held in it’s data directory. The default data directory is My Documents/Vixen 3. Use this option to tell Vixen 3 to use a different data directory for this session.

2 - Web API

Overview

Vixen implements a Restful Web API. The API allows you to get get element info, search for elements, start/pause/stop a sequence, stop a running sequence and get status updates of running sequences.

You can send commands and receive responses from the Vixen web server using the API below. The key thing to learn with this API is that most of it uses JSON object data. So if a request is POSTing data to the server that data will be in JSON object notation and sent in the body of the request. All responses are in JSON.

The Postman application is a good tool to use to learn how the API works and fully supports sending RESTful requests with JSON notation.  

GET /api/element/getElements

Retrieves a list of elements in the display.

Example request:

http://localhost:8080/api/element/getElements

Example Response:

[
  {
    "Id": "6173c7f3-46ee-424a-8e35-54eeadb98439",  
    "Name": "Poles",  
    "Colors": ["#FFA000"],  
    "Children": [{  
    "Id": "ff48009b-b051-4584-a654-4b7ed1599080",  
    "Name": "Pole 1",  
    "Colors": ["#FFA000"],  
    "Children": null  
  }, 
  {  
    "Id": "9fb69ece-1048-48b3-b55d-067eebcd9ad3",  
    "Name": "Pole 2",  
    "Colors": ["#FFA000"],  
    "Children": null  
  }, 
  {  
    "Id": "bf00aaaa-1dc8-4e3b-a21e-2bd57fdaff44",  
    "Name": "Pole 3",  
    "Colors": ["#FFA000"],  
    "Children": null  
  }  
]  

GET /api/element/searchElements

Searches for elements that start with the with prefix.

Example Request: Searches for elements starting with “Po”.

http://localhost:8080/api/element/searchElements?q=Po

Response is the same as getElements.

GET /api/element/on

Allows you to turn on a specified element.

Example Request:

http://localhost:8080/api/element/on

Parms:

id: The guid id of the element

duration: The time in seconds to stay on. 0 is indefinite._

intensity: 0-100 value for brightness

color: The hex code of the color. Blue=#0000FF

_Example Response:

{
  "Message":"Window Left turned on for 30 seconds at 100% intensity."
}

GET /api/element/off

Allows you to turn off a specified element.

Example Request:

http://localhost:8080/api/element/off

Parms:

id: The guid id of the element

Example Response:

{"Message":"Window Left turned off."}  

POST /api/element/groupon

Since build #357

Turns on a group of elements. Like the on function, but for a collection of elements.

Example Request:

http://localhost:8080/api/element/groupon

Request JSON object format:

[  
 {"id":"e80accf6-a2b0-4b26-95d6-358210ce6580","duration":"30","intensity":"100","color":"#ffff00"},  
 {"id":"6d458dbb-12b1-4463-8ae7-a87718d6c412","duration":"0","intensity":"50","color":"#ff0000"}  
]

Example Response:

{ 
  "Message": "2 elements turned on.", 
  "Details": [ "Mega Tree Star turned on for 30 seconds at 100% intensity.", "Mega Tree turned on at 50% intensity." ] 
}

POST /api/element/clearall

Since build #357

Turns off all active effects in the web server live context. Will not affect playing sequences.

Example Request:

http://localhost:8080/api/element/clearall

GET /api/play/getSequences

Retrieves a list of sequence files in the Vixen 3\Sequence folder. If you are using profiles, the folder returned will be the Sequence folder in the profile folder.

Example Request:

http://localhost:8080/api/play/getSequences

Example Response:

[
  {"Name":"Basic Patterns 1", "FileName":"Basic Patterns 1.tim"},
  {"Name":"Border Pixel Test", "FileName":"Border Pixel Test.tim"}
]

POST /api/play/playSequence

Plays the sequence passed.

Example Request:

http://localhost:8080/api/play/playSequence

Example Response:

{
  "Name":"Announcement",
  "FileName": "C:\\Users\\bob\\Documents\\Vixen 3 – Halloween\\Sequence\\Announcement.tim"
}

Parms: JSON Object

Name: The name of the sequence.

FileName: The filename of the sequence.

Both are obtained from the getSequences call.

Example Response:

{
  "State":1,
  "Sequence":{"Name":"Announcement","FileName":"Announcement.tim"},
  "Position":"00:00:00","Message":"Playing sequence Announcement of length 00:00:12.0680000"
}

POST /api/play/stopSequence

Stops the specified sequence that was started within the web API. Uses the same format as the playSequence for the request data.

Parms: JSON Object

Name: The name of the sequence.

FileName: The filename of the sequence.

Both are obtained from the getSequences call.

Example Response:

{
  "State":0,
  "Sequence":{"Name":"Bedroom Gable Chases","FileName":"Bedroom Gable Chases.tim"},
  "Position":"00:00:00","Message":"Sequence Bedroom Gable Chases stopped."
}

POST /api/play/pauseSequence

Stops the specified sequence that was started within the web API. Uses the same format as the playSequence for the request data.

Parms: JSON object

Name: The name of the sequence.

FileName: The filename of the sequence.

Both are obtained from the getSequences call.

Example Response:

{
  "State":0,
  "Sequence":{"Name":"","FileName":""},
  "Position":"00:00:00",
  "Message":"Sequence Bedroom Gable Chases paused."
}

GET /api/play/status

Provides a status on what is currently playing.

Parms: none

Response:
State: 0 is stopped, 1 is playing, 2 is paused.
Position is the time offset into the current sequence.

{  
  "State": 1,  
  "Sequence": {"Name": "Christmas Eve Sarajevo", "FileName": "Christmas Eve Sarajevo.tim"},  
  "Position": "00:02:14.0460000",  
  "Message": null  
}

GET /api/system/getControllers

Since Version 3.6

Provides a list of the output controllers defined in the system.

Parms: none

Example Response:

[  
  {  
    "Id": "971b0b2d-0496-4894-8ecf-744e6f9b671e",  
    "Name": "House",  
    "IsRunning": true,  
    "IsPaused": false  
  },  
  {  
    "Id": "00d0402e-c993-49b1-914a-ab2234f26705",  
    "Name": "Renard Bushes",  
    "IsRunning": false,  
    "IsPaused": false  
  }  
]

GET /api/system/getController?id=guid

Since Version 3.6

Get the info for specific controller by id.

Parms: controller id as guid

Example Response:

{  
  "Id": "971b0b2d-0496-4894-8ecf-744e6f9b671e",  
  "Name": "House",  
  "IsRunning": true,  
  "IsPaused": false  
}

POST /api/system/setControllerState

Since Version 3.6

Set the state of a specific controller.

Parms: JSON object

{  
  "id":"971b0b2d-0496-4894-8ecf-744e6f9b671e",  
  "isRunning":"True"  
}

Example Response:

{  
  "Message": "House state Not Changed.",  
  "Details": [],  
  "IsSuccessful": false  
}

POST /api/system/setAllControllerState

Since Version 3.6

Set the state of all the controllers.

Parms: JSON object

{  
  "id":"",  
  "isRunning":"True"  
}

Example Response:

{  
  "Message": "All controllers state Changed.",  
  "Details": [],  
  "IsSuccessful": true  
}

**POST /api/system/save

Since Version 3.6

Save the System Config.

Parms: None

Example Response:

{  
  "Message": "Save Successful",  
  "Details": [],  
  "IsSuccessful": true  
}

Status updates via SignalR messaging

Status updates are published via a SignalR push mechanism. You can include the SignalR client and subscribe to receive these updates.

self.initSysytemStatusHub = function () {

//register for updates  
$.connection.ContextStates.client.updatePlayingContextStates = function(states){

//Do stuff with states object

}

// Start the connection  
$.connection.hub.start();  
}