StreamDeckProductionController

Node JS Implementation using Elgato Stream Deck as production controller. Buttons can be configured to send multiple actions to various protocols like RossTalk, OSC, VideoHub, HTTP requests, etc.

To get started, you will need a buttons.JSON file (for button structure) and a devices.JSON file (for device structure). They are both required, even if you don't have any external devices.

Field Descriptions:

• buttonNumber: The zero-based key index where the button should fall on the physical device. 0 is top right, flowing to the left in rows.
• id: The unique button ID for this button. Must be globally unique for certain functions to work properly.
• name: The friendly name of this button. Useful for notifications.
• buttonStates: Array of button states representing different images that can be presented on that button. See exmaples below.
• image: If a button has no states, you can define its image location here.
• currentButtonStateID: The default or current button state to be displayed. If left undeclared, "default" or the first button state declared will be used.
• buttonGroup: The name of the group this button is associated with. Primarily used for toggling/radio button functionality. Any button that should act like a toggle should have a buttonGroup defined.
• deviceID: Device associated with this button. Useful when several buttons refer to the same host/port often. See device help for more information.
• triggerType: The trigger type that this button will use. See examples.
• host: If no deviceID is listed, you can optionally include a host declaration.
• port: If no deviceID is listed, you can optionally include a port declaration.
• trigger: The message, URL, command, etc. to be sent.
• triggers: An array of triggers representing different trigger types that can be fired when the button is pressed. They will run sequentially. See examples below.
• backButton true or false. If true, the button will act as a "back" button and go up a level in the folder structure. No triggers or commands can be run on a back button.

Button States: Any button can have multiple button states defined by using the buttonStates array property.

• buttonStateID: The identifier of the button state. Does not have to be globally unique, just unique to that button.
• buttonImage: The file path of the button image that should be loaded when this button state is requested.

Trigger Types:
Several trigger types are available. These define what action the button will take when pressed. The triggerType specifies the type of action, and trigger specifies the message, command, etc.

• LoadButtonContent: Jump from the current folder of buttons to the buttonID defined in trigger.
• ChangeState: Change the state of a buttonID to a corresponding buttonStateID. The trigger definition should be: "buttonID buttonStateID".
• Toggle: Toggle a button on or off. Trigger definition should be "toggle on buttonID" or "toggle off buttonID". If "on", that button will change to its "toggle" state and all buttons in that button's buttonGroup will change to their "default" state. If "off", all buttons in that buttonGroup will return to their default state.
• DashboardWebCall: Sends a GPI command to a Ross Dashboard custom panel at the HTTP Trigger Port declared in the custom panel. Requires a deviceID or a host/port to be declared to work properly.
• RossTalk: Sends a RossTalk command to a Ross device. Requires a deviceID or host/port to be declared. Assumes port 7788 if left undefined.
• TCPMessage: Sends a TCP command to the listed device. Requires a deviceID or host/port to be declared. Assumes port 23 (telnet default) if left undefined. Use this if you want to remotely control a StreamDeck connected to another computer or device.
• OSC: Sends OSC messages to a device. Requires a deviceID or host/port to be declared. Assumes port 8000 if left undefined.
  
  Triggers can be strings for simple commands that don't include objects. Otherwise, define your object like this:

  {
  "address": "/address1/address2",
  "args": [
  {
  "type": "f",
  "value": 440
  }
  ]
  }

• VideoHub: Sends routing changes to a Blackmagic VideoHub. Requires a deviceID or host/port to be declared. Assumes port 9990 if left undefined.
• Application: Launches the app defined in trigger. Requires an absolute path.
• URL: Sends a background URL request defined in trigger. If a deviceID or host/port are defined, the request will use those as prefix to the request. Assumes port 80 if left undefined.
• Notify: Sends a notification to the screen. Use the notify property of the trigger object itself to override global notification preferences if needed. The message in trigger is what will be sent.

Trigger Arrays:
Any button can have multiple trigger types assigned by using the triggers array property.

• deviceID: If listed, this will override any deviceID declared in the button property itself.
• triggerType: If listed, this will override any triggerType declared in the button property or any deviceIDs included.
• host: If listed, this will override any other host values within the button properties.
• port: If listed, this will override any other port values within the button properties.
• trigger: The message or command to be sent.
• notify: Used to override global preferences from Settings. If on, this trigger will always show a notification. If off, it will never show one.

Device Structure:

A devices.json (any filename is ok as long as it is a separate file from your button structure) should be created to house information for any of your production devices that you will refer to often in your button structure. It will keep you from having to repeat host, port, triggerTypes, etc.

Sample Device Structure

{
    "devices":
    [
        {
            "deviceID": "Dashboard-1",
            "deviceName": "Dashboard Production Control",
            "host": "192.168.11.141",
            "port": "5400",
            "triggerType": "DashboardWebCall"
        },
        {
            "deviceID": "Carbonite-1",
            "deviceName": "Carbonite 1",
            "host": "192.168.11.126",
            "port": "7788",
            "triggerType": "RossTalk"
        },
        {
            "deviceID": "VideoHub-1",
            "deviceName": "FG Tech VideoHub Auditoriums",
            "host": "192.168.11.128",
            "port": "9990",
            "triggerType": "VideoHub"
        }
    ]
}

Field Descriptions:

• deviceID: A unique identifier so that this device can be located. Referenced in button structure.
  
  
• deviceName: A helpful name for the device, used in notifications and other areas.
  
  
• host: The host name or IP address of the device you are messaging with.
  
  
• port: The port of the device you are messaging with. Some devices assume default ports if this is unspecified.
• triggerType: The default trigger type associated with this device. See examples.

Available/Applicable Trigger Types for Devices:

• DashboardWebCall: For making calls to a Ross Dashboard Custom Panel that has its HTTP Trigger Port assigned, to activate a button on that panel with a GPI assigned.
  Example call: http://ipaddress:port/ajax/GPI
  
  
• RossTalk: For sending RossTalk commands to the specified device. Assumes port 7788 if left undefined.
  
  
• TCPMessage: Sends a TCP command to the listed device. Requires a deviceID or host/port to be declared. Assumes port 23 (telnet default) if left undefined. Use this if you want to remotely control a StreamDeck connected to another computer or device.
  
  
• OSC: For sending OSC messages to the specified device. Assumes port 8000 if left undefined.
  
  
• VideoHub: For sending output routing changes to a BlackMagic VideoHub. Assumes port 9990 if left undefined.
  
  
• URL: For sending URL requests to the specified host and port. Assumes port 80 if left undefined.

Making TCP Changes to the StreamDeck:

By default, the software is set up to accept the following commands:

• Command: TOGGLE buttonID on or TOGGLE buttonID off
  If "on" is specified, the buttonID passed will change from the "default" button state to the "toggle" button state.
  It will also change the state of all buttonIDs in that buttonID's buttonGroup back to their "default" state. If they do not have a "default" state declared, they will change to their first defined button state.
  
  If "off" is specified, the buttonID will toggle off along with all members of that buttonID's buttonGroup.
  
  See Button Structure help for more information.
  
  
• Command: CHANGESTATE buttonID buttonStateID
  Changes the state of buttonID to buttonStateID. If the buttonID or buttonStateID is not valid or not found, nothing is changed.
  
  
• Command: LOADBUTTONCONTENT buttonID
  Jumps to the specified folder buttonID.
  
  
  
• Command: TRIGGER buttonID
  Runs the triggers attached to that buttonID, as if the button was pressed. No action is performed if the buttonID is not valid or not found.
  
  
• Command: LOCK
  Locks the panel so that no buttons can be pressed. Displays a lock icon.
  
  
• Command: UNLOCK
  Unlocks the panel and returns to the root folder so normal function can resume.
  
  
• Command: NOTIFY
  Force a notification to the user. (Overrides their preferences and sends a notification upon receipt. Message truncated after 140 characters.)