eyeUNIFY.link - Macro commands

 

Introduction

 

This website shows which potential commands exist to send to the eyeUNIFY.link and how they work.
The macro commands are used to control the system from an external device or software. Therefore a command can be transmitted to the eyeUNIFY.link over a TCP/IP socket or a serial interface. Once received the link parses and translates the requests and calls the appropriate functions on the eyeUNIFY.core.
You can test any macro command using the Microsoft telnet client software or a serial port communication interface.

 

 

Syntax

 

Macro commands syntax:

‘token (parameter1, parameter2,…parameterN) end_char’

  • token: The name of the macro command
  • parameter: The parameters required by the macro command
  • end_char: the ending character specified in the UNIFY.link properties
    e.g. for Microsoft telnet the ending character is <CR/LF>

Please notice that macro commands are only recognized after sending the ending character.
All examples given here are using the carriage return <CR>, you must replace it by your own ending character to make it work.
To be more efficient, you can send a command followed by several parameter brackets to execute the command once for every parameter bundle. Additionally you can send multiple commands on the same line.

Example:

AddDevice(http://192.168.1.1:8081/UnifyDevice,EPU1,user,passwd)CreateWindow(EPU1,47,0,0,0.5,0.5)(EPU1,53,0.5,0,0.5,0.5)(EPU1,67,0,0.5,0.5,0.5)(EPU1,112,0.5,0.5,0.5,0.5)<CR>

This will add a new device plus an associated screen and immediately create 4 streams, one in every quarter with the channels 47, 53, 67 and 112. All in one request.
About case sensitivity:
Macro command and parameters are not case sensitive. So sending either help,
Help or HELP will lead to the same result.

Every time you need help for a macro command you can call help(macro_name)<CR> on the eyeUNIFY.link.

 

Alias

The eyeUNIFY.link reader recognizes two different kinds of aliases.

Macro alias

Macro aliases afford the user to save and send self-created macro commands. Example:

DoubleWin=CleanWall(EPU)CreateWindow(EPU,23,0,0,0.5,1)(EPU,47,0.5,0,0.5,1)<CR>

Creates an alias named ‘DoubleWin’. Now every time you send ‘DoubleWIN<CR>’, the screen ‘EPU’ will be cleaned and the two specified windows will be added to it. When created, the alias is created but the macro command is not executed. If the alias is successfully created, the following message is reported: “New alias created.” You can use any name or number for the alias, but don’t use reserved characters ( ‘ , ” , $ , =) or the name of an existing macro command. The alias names are case insensitive (doublewin is equal to DoubleWin).

Resource alias

If specified you can use resource aliases instead of the IDs of resources. An alias must always have a “$” at the beginning followed by any alphanumeric characters. All aliases are unique, so  allocating the same alias a second time will simply overwrite it. Example:

CreateWindow(EPU1,47,0,0,0.5,0.5,$win1)

Creates a window that could be identified with ‘$win1’ from now on:

Resizewindow($win1,0.5,0,0.5,1)

CleanWindow($win1)

Cleaning a window automatically cleans the $alias, too.

Supported commands

AddDevice

Syntax: AddDevice(address, <name>,< user>,< password>)<CR>
Adds a new device to the core and deploys it. Returns “ok” or an error message.

  • address: URL to the UnifyDevice service for the device (typical “http://<IP or Hostname>:8081/UnifyDevice”)
  • name: Name for the device (if omitted, the name discovered by the executer is taken.
  • user: User for the device
  • password: Password for the device

AddRgbChannel

Syntax: AddRgbChannel(sourceID,description,input,previewUrl)<CR>
Adds a RGB channel to a source. Returns the ID of the created channel or an error message.

  • sourceID: ID of an existing source to add the channel to.
  • description: Description for the channel (can be used for searching)
  • input: Number of the channel
  • previewUrl: URL to an image that can be used as channel preview.

AddRtspChannel

Syntax: AddRtspChannel(sourceID,description,user,password,url,previewUrl)<CR>
Adds a RGB channel to a source. Returns the ID of the created channel or an error message.

  • sourceID: ID of an existing source to add the channel to.
  • description: Description for the channel (can be used for searching)
  • user: User for the Rtsp source
  • password: Password for the Rtsp source
  • url: URL to the Rtsp source
  • previewUrl: URL to an image that can be used as channel preview.

AddSimpleExecutableChannel

Syntax: AddSimpleExecutableChannel(sourceID, description, path,previewUrl)<CR>
Adds a RGB channel to a source. Returns the ID of the created channel or an error message.

  • sourceID:  ID of an existing source to add the channel to
  • description:  Description for the channel (can be used for searching)
  • path:  Path to the executable (On the PC that should launch the executable)
  • previewUrl:  URL to an image that can be used as channel preview

AddSource

Syntax: AddSource(name,description)<CR>
Creates a new Source. Returns the ID of the created source or an error message.

  • name: Name for the source (can be used for searching)
  • description: Description for the source

AddVncChannel

Syntax: AddVncChannel(sourceID,description,userName,PW,adress,port,previewUrl)<CR>
Adds a VNC channel to a source. Returns the ID of the created channel or an error message.

  • sourceID: ID of an existing source to add the channel to.
  • description: Description for the channel (can be used for searching)

AddWall

Syntax: AddWall(wall_name)<CR>
Creates a new wall. Returns the ID of the created wall or an error message.

wall_name: Name for the wall (can be used for searching)

Alias

Syntax:Alias()<CR>
Returns a list of the user created macro and resource aliases.

AnswerMode

Syntax: AnswerMode(silent|answer|prompt)<CR>
Controls how the program responds to the macro commands. Therefore the command accepts this three choises:

  • Silent: Stops the service to prompt and answer to the commands
  • Answer: Forces the service to answer to commands without prompt
  • Prompt: Enables both prompting and answering to macro commands

CleanPreset

Syntax: CleanPreset(config_name)<CR>
Deletes the preset/layout. Returns “ok” or an error message.

  • Config_name:   Name of the preset/layout to be deleted.

CleanWall(wall_name)

Syntax: CleanWall(wall_name)<CR> Closes all windows currently played on the wall. Returns “ok” or an error message.

  • Wall_name:  Name of the wall to be cleaned.

CleanWindow(windowID)

Syntax: CleanWindow(windowID)<CR> Removes a currently played window. Returns “ok” or an error message.

  • windowID:  The Id of a window to be removed.

CreatePreset

Syntax: CreatePreset(wall_name, config_name, <clean_opt>, <pixel>, <window_list>)<CR>
Creates a preset/layout of the windows currently played on a wall or given in the windowlist. Returns the list of the windows that were added to the preset/layout.

  • Wall_name: The name of the wall to create the preset/layout of
  • Config_name: The name for the preset/layout
  • Clean_options: not supported yet
  • Pixel: not supported yet
  • Window_list: List of window IDs as alternative to the windows on a wall.

CreateWindow

Syntax: CreateWindow(wall_name, channelId, <left>, <top>, <width>, <height>, <alias>)<CR>
Creates a new stream on the chosen wall. Returns the ID of the created window or an error message.

  • Wall_name: The name of the wall the window shall be created on
  • channelId: The id of the channel  to use as content for the window
  • left: Position of the left side of the window relative to the wall
  • top: Position of the top side of the window relative to the wall
  • width: Width of the window relative to the wall
  • height: Height of the window relative to the wall
  • alias: The optional user created name for the window. An alias must always have a ‘$’ character at the beginning followed by any alphanumeric characters like $win1.

DeleteAlias

Syntax:DeleteAlias(alias_name)<CR> Deletes the alias. Removes “ok” or an error message.

  • Alias_name: the name of the alias to be deleted

Explain

Syntax: Explain(clean|wall|region|alias|window,<create|delete>,id)<CR>
Returns the macro command that permits to create or delete the designed item.
This function is useful to create the list of commands that describe your configuration.
Return the corresponding macro commands or an error message.

  • clean|wall|region|alias|window:  The item(s) which you want to get the commands for.
  • create|delete:  Depending on the choice the command to create or the command to delete the specified item(s) will be returned.
  • Id: The Id of an item to only get the command to create/delete that single item.

FocusWindow

Syntax: FocusWindow(windowID)<CR>
Brings a window played on a wall to the front. Returns “ok” or an error message.

  • windowID:          the Id or user defined alias of the window which should be brought to front.

GetActivePreset

Syntax: GetActivePreset(<wall_name>)<CR>
Returns the list of all presets/layouts that are currently played on a/all walls or an error message.

  • Wall_name:        The name of a wall. If omitted, the presets/layouts are given for all walls.

GetDeviceInfo

Syntax: GetDeviceInfo(deviceID)<CR>
Returns ID, name and the type of the device or an error message.

  • deviceID:             The ID or the name of a device

GetDeviceList

Syntax: GetDeviceList()<CR>

Returns the list of all available devices or an error message.

GetPresetInfo

Syntax: GetPresetInfo(config_name)<CR>
Returns the clean_option and the list of windows contained in the preset/layout or an error message.

  • Config_name:   Name of the preset/layout to get the information of

GetPresetList

Syntax: GetPresetList()<CR>
Returns the list of all available presets/layouts or an error message.

GetSourceInfo

Syntax: GetSourceInfo(sourceId)<CR>
Depending on the channel type the command returns the name, path/URL, parameters and the type of the channel or an error message.

  • sourceId: ID or name of the channel whose information is needed

GetSourceList

Syntax: GetSourceList(<wall_name>, <source_type>)<CR>
Returns a list of all available sources and channels or an error message.

  • Wall_name: The name of a wall can be added to get the list of channels playable on the specified wall.
  • Source_type: The source_type can either be ‘rtsp’, ‘vnc’, ‘rgbinput’ or ‘layout’ to get the list of sources of the specified type.

GetWallList

Syntax: GetWallList()<CR>
Returns the list of all available wall or an error message.

GetWallSize

Syntax: GetWallSize(wall_name)<CR>
Returns information about the size of a screen or an error message.

  • wall_name:  the name of the screen to get the size information for.

GetWindowList

Syntax: GetWindowList(wall_name, <extend>)<CR> Returns the list of windows currently played on the wall or an error message.

  • wall_name: The name of the wall containing the windows
  • extend:  ‘extend’ is optional and forces the service to return extended informations of the windows in the form:
    windowID,sourceName, sourceType, sourcelistId, left, top, width, height, sizePreset, wallname, owner, zorder, focus.

GetWindowSize

Syntax: GetWindowSize(windowID)<CR> Returns the size parameters (left, top, width, height) of a window or an error message.

  • windowID: The ID or $alias of a window.

Help

Syntax: Help(<macro_command|alias>)<CR>
Returns help to the specified command or general support.

  • macro_command: Can be any macro command listed here you need help on
  • alias: Call help(alias) to get the list of user defined macro/resource aliases
  • syntax: Call help(syntax) to get help on the macro commands syntax
  • empty: Leave the bracket empty to get general help and a list of all supported macro commands

IsWindow

Syntax: IsWindow(windowID)<CR> Test if the window identified by ‘windowID’ exists. Returns 1 if the window exists or 0 if not.

  • windowID:          The ID or user defined $alias of a window

PlayPreset

Syntax: PlayPreset(config_name,wall_name,<clean_option>,left,top,width,height,<modifiers…>)<CR>
Plays a created preset on the wall. Returns “ok” or an error message.

  • Config_name: The name of the preset which should be played
  • Wall_name: The name of the wall the preset should be played on
  • Clean_options: For now two clean_options are available: ‘no_clean’ (just plays the preset) & ‘clean_all’ (cleans the wall before the preset is played)
  • Left: Position of the left side of the window relative to the wall
  • Top: Position of the top side of the window relative to the wall
  • Width: Width of the window relative to the wall
  • Height: Height of the window relative to the wall
  • Modifiers: An optional list of parameters to make some changed to the preset before it is played. For every window the modifiers’ order goes like this: <channelID>, <left>,<top>,<width>,<height>,<osd_label>

RemoveChannel

Syntax: RemoveChannel(channelID)<CR> Removes a channel  out of the source containing it. Returns “ok” or an error message.

  • channelID: The ID or name of the channel to be deleted

RemoveDevice

Syntax: RemoveDevice(deviceId)<CR>
Removes and undeploys the device. Returns “ok” or an error message.

  • deviceId: The ID or name of the device to be remove.

RemoveWall

Syntax: RemoveWall(wall_name)<CR>
Removes the wall respectively the screen. Returns “ok” or an error message.

  • Wall_name: The name of the wall/screen to be removed

ResizeWindow

Syntax: ResizeWindow(windowID, <left>, <top>, <width>, <heigth>)<CR>
Changes the size and position of a window. If one of the parameters is omitted, it is left at the prior state.

  • windowID: The Id or user defined $alias of the window to be resized.
  • Left: Position of the left side of the window relative to the wall
  • Top: Position of the top side of the window relative to the wall
  • Width: Width of the window relative to the wall
  • Height: Height of the window relative to the wall

Examples:
ResizeWindow(23,0.5,0.5,0.5,0.5). The window with id ’23’ was resized/moved to the lower right quarter.
ResizeWindow(54,,,0.5,1). The window with id ’54’ was resized but stays in the same position.

Temporize

Syntax: Temporize(hh:mm:ss,token,param,…)<CR>
Temporizes any macro command and executes it after the waiting time. Returns “ok” if the timer has started or an error message.

  • hh:mm:ss: A valid temporization before the command shall be executed.
  • token: The command to be temporized
  • parameters: Parameters for the command
  • Example: Temporize(00:00:12,CleanWindow,3254) – cleans the window 4254 after 12 seconds.

UndoPreset

Syntax: UndoPreset(config_name,wall_name)<CR> Erases a currently active preset/layout from a wall. Returns “ok” or an error message.

  • Config_name: The preset/layout which should be undone
  • Wall_name:        The name of the wall the preset/layout should be erased from.