vsmGadgetServer - Configuration

The Configuration Process

vsmGadgetServer is configured via a web browser. The configuration UI is realized as a highly dynamic web interface, to be opened in modern HTML5 compatible browser. vsmGadgetServer has been successfully tested with Microsoft Edge und Google Chrome. Future compatibility tests are based on these two browser types. To ensure, that all features of vsmGadgetServer are properly supported in your setup please use Microsoft Edge and Google Chrome.

The configuration UI can be opened via the browser https://localhost:50080. Alternatively, via the Start Menu (Start > Programs > Virtual Studio Manager >"Web Interface“).

vsmGadgetServer 5.6.3 and higher requires basic authentication (local windows user login) to access the configuration UI. Depending on project specific needs and workflows, it may be required to open up the communication and allow an unsecured login. This still can be achieved by a respective small config file modification.

Please follow these instructions to modify the login authentication.

Modes

Currently 3 modes are supported:

1. Local Windows accounts. This is the default mode and is set during the first installation/upgrade.
2. Domain accounts. This mode allows you to call the domain controller via Kerberos, for example, to authenticate users.
3. Disable Authentication/None. This mode allows access to the webUI without any User Authentication.

Changing the Mode

To change the mode, follow these steps.

1. Stop the vsmGadgetServer service.
2. Locate the configuration file "e4e3f3cd-51e9-4ae4-b3ad-96ad6e39de13" in the "Plugins" folder your installation path, e.g., D:\vsm\vsmGadgetServer\.
3. Extract the file with “7Zip” to the local folder.
4. Open the extracted file "HostContainer.xml" with a text editor of your choice.
5. Locate the <Authentication ></Authentication > entry.
6. Set it to "Local" to use mode 1 <Authentication>Local</Authentication>

or "Domain" to use mode 2 <Authentication>Domain</Authentication>

or "None" to use mode 3 <Authentication>None</Authentication>.

1. Save the file and close the text editor.
2. Re-pack the file as .zip and give it the name "e4e3f3cd-51e9-4ae4-b3ad-96ad6e39de13". Please delete the extension .zip.
3. Start the vsmGadgetServer service.

If the site cannot be displayed, this may have several reasons:

• The service is not running. This can be validated via the Service list mentioned above.
• The name localhost is not configured. This is a rare scenario, but it may happen. In this case you need to replace localhost by either the hostname or the IP address of the local machine.
• A firewall is blocking the communication. Please make sure that the firewall does not block the following TCP/IP ports:
  • 50000
  • 50080
  • 50100
  • 50040 (UDP)

The overall configuration is stored in a file called “vsmGadgetServer.store”.

The configuration file must not be copied across servers!  If the same configuration file would be used in various servers of a cluster, the different services would have the same identifier and they would appear as one server. To synchronize servers, use the redundancy concept.

Remote Configuration

It is possible to configure the vsmGadgetServer from a remote PC. Please make sure that the ports listed above are not blocked by the firewall, otherwise the configuration site cannot be accessed. To connect to a vsmGadgetServer running on a remote machine, you only need to know the IP address or the machine name.

If, for example, the name of the machine the service is running on is "Server-1“, open the browser and enter the following address:

https://Server-1:50080

The port number 50080 must always be appended to the server name, separated by a colon.

The Configuration UI

When starting the configuration UI for the first time, the web interface shows up with some generic navigation keys, status information and specific content, depending on your local environment.

Header Status Bar

The Header Status Bar contains information about the local vsmGadgetServer install.

• License Information: If the vsmGadgetServer installed on the machine you work on is not licensed, the information “This server is not licensed.” is shown.
• Host information: @Hostname indicates the name of the machine which runs vsmGadgetserver.
• Version: The version of the vsmGadgetServer service is indicated here.
• Copyright: indicates copyright information. Clicking on Lawo will open the Lawo website in a new browser window.

Main Navigation Bar

The Main Navigation Bar provides the navigation to the different functional sub pages of vsmGadgetServer.

• Home: clicking the Lawo logo or vsmGadgetServer opens the entry page.
• Known Hosts: This webpage shows a listed view of all known vsmGadgetServer hosts in your network. This includes your own server, other active servers in the same network, and also passive servers, which were previously connected to the network. Each listed host can be selected and host specific details are presented for information and editing.
• Protocols: This webpage lists all configured protocols on the server. The list of configured protocols is divided into Providers and Consumers.
• Protocol Factories: Here, all available protocols are listed. The list is divided into Providers and Consumers. As vsmGadgetServer is continuously evolving, new providers and consumers are added on a regular basis.
• Logging: On the Logging webpage, different settings for the internal logging mechanism can be set. A general “Event Log” is shown at the bottom of each webpage.
• Plugins: Plugins are functional enhancements to vsmGadgetServer, which are provided and used “on demand”. Use the Plugins webpage to get a list of available plugins and their status.
• Errors: The Errors webpage collects critical system failures and provides options to redeem them.

Known Hosts

On this webpage, a list of “known hosts” is indicated. Each host entry can be selected for more information and editing purposes. Already, the list itself provides generic status information on the listed hosts.

When selecting a host, specific information about this host is shown in the main window.

Status

The Status section provides information about the selected host. This includes the host name, the version of vsmGadgetServer on that host, the startup time of the server and the server role (status).

Addresses

In the Addresses section, all IP addresses of the host are shown.

Settings

The Settings area provides input fields for additional information describing the host. Information here is helpful to identify a host in a network with various others.

The checkbox Force Single Server can be checked to hide this host from the list of potential candidates for Multiserver clusters. It is unchecked by default.

Changing checkbox settings in this list must be confirmed by clicking the Apply button on the lower left side of the section window.

Multiserver

This list is showing available hosts in the network, which are potential candidates for Multiserver clusters. Each checked host will be included in the cluster, and the host you currently edit is becoming the primary server. Changing checkbox settings in this list must be confirmed by clicking the Apply button on the lower left side of the section window.

Adding new servers to a Multiserver cluster will cause all backup servers to loose their local configuration and to receive the current configuration from the primary server. This will automatically happen as soon as the Apply button is clicked. The config loss on backup servers is irreversible, so please double check you added the correct servers before you apply changes.

License

A vsmGadgetServer instance must be licensed for proper operation. The License section indicates the status of the license.

Servers listed in Known Hosts which do not have a valid license are marked by a yellow dot, followed by the host name. The entry is added with the information “Not licensed”. To license a server, click the host entry. The server details are displayed in the main window. In abstract License, you can license your system.

1. If your system is not yet licensed, click the Generate symbol right beside the Seed text input field. A new seed will be created and is indicated in the text field.
2. Copy this complete seed and send it to vsmLicensing@lawo.com. Please add additional information to your email:
   • - Product name and version (e.g. vsmGadgetServer 5.6)
   1. - Project name
   2. - Server role
3. You will be provided with a key. Copy that key to the second text input field. Then, click the Activate key.

After a successful licensing, the License abstract in the server details indicates that the server is licensed.

In addition, the host you have just licensed will be indicated with a blue dot and the additional information “primary”.

In specific cases, you might want to “un-license” a host. You can do this by clicking the Revoke License key at the lower left side of the section window. It is indicated, when the server is properly licensed.

Protocols

The Protocols webpage lists all configured control connections. If no protocol connections are configured, the page is empty, except for the general Event log output.

To add protocol connections, the Protocol Factories webpage is used.

Protocol Consumers or Protocol Providers

vsmGadgetServer’s generic role is the translation of data between third party devices and vsmStudio. To maintain the communication into both directions, two general communication roles must be differentiated: Seen from vsmGadgetServer, it consumes data from remote controlled systems and it provides data to connected controllers. Protocols, which are used for data consumption will be listed in the consumer protocols section. Protocols used for data provision are listed in the provider protocols section.

Typical consumers are connections to 3rd party systems for remote control purposes. Each 3rd party device requires a specific, in most cases a proprietary control protocol. That’s the reason, why most selectable protocols are found in the consumers section. In the communication to the overarching control system (e.g. vsmStudio), vsmGadgetServer acts as provider – while the control system consumes its data. As the variety of control connections to an overarching broadcast controller is limited, only a few control protocols are available in the providers section. vsmGadgetServer can host multiple connections of both types. For proper setup and maintenance of connections, it is highly recommended to map each consumer connection into one provider connection.

Once a protocol connection is set, it is listed in the “Protocols” webpage. According to its type, it is either listed in the providers section or in the consumers section. When clicking an entry, details of this connection will be listed in the main part of the web page and can be edited there.

Providers

Provider connections are connections between vsmGadgetServer and the overarching broadcast controller, e.g. vsmStudio. The following example is based on an Ember+ connection. Other protocols may provide different parameters, especially in the “Settings” section.

Status

This section shows the general connection status.

• Name: This is the name used to identify the connection.
• Protocol Status:
  • Active indicates an active protocol provider connection. If the server is member of a cluster, and the protocol status indicates as active, then the server has also the primary role.
  • Idle indicates a passive connection, which is the case when the entire server role is backup.
• Connection:
  • Idle: connection is configured, but server is in backup mode.
  • Connected: Listener Socket is open, but no consumer.
  • Valid: at least one consumer is connected to listener socket.
• Active Address: This is the address of the currently connected vsmStudio server.

Port Settings

• Addresses: This section allows to add communication ports for this connection. It is recommended to configure only one port per provider, since a provider accepts multiple connections per port.
• Stream Type: The stream type identifies the format of the data connection. It is preselected, when choosing a specific protocol, and editing this field is not recommended.
• Binding: allows to identify the network interface, which is used for the communication with the consuming control system. Either Any is chosen, or a specific IP address is set. In most cases, keeping Any as the default entry is suitable, since most setups work just fine, if vsmGadgetServer listens to any NIC (network interface) for incoming connections.

Driver Mapping

• Devices Mapped: indicates the protocol consumer, which is mapped to this specific provider. In other words, driver mapping describes the route of the data between 3rd party device and vsmStudio. While it is practically possible, to map multiple consumer to one single communication connection towards vsmStudio, a 1:1 consumer-to-provider mapping is strongly recommended. This serves system transparency, easier maintenance and troubleshooting as well as allowing to make use of the offline Gadget configuration feature in vsmStudio.

To configure a single consumer device:

• For NMOS Devices, only add one device in the .csv file.

• Attach the consumer device to a provider, and assign a name.

• Now that the consumer has been attached to the provider, navigate to Settings and select Single Binding Mode to be Enabled.

• Once Single Binding Mode is enabled, the GadgetServer tree in vsmStudio will transparently present the Consumer device, instead of inducing any Alias mapping in between. This allows offline configuration of multiple devices with same internal configuration, such as .edge, to be consistent when using this feature. In the example below, the device root UDX_40GbE is presented without additional subnode "C100-1-3 EnCap". 

Settings

• Logging: In case a connection specific protocol is required, maybe due to malfunction or suspicious behaviour of this specific connection, specific logging can be switched on/off.
  • Disabled: Logging is off.
  • Enabled: Logging is on.

Specific Log level details can be defined in the logging webpage.

From vsmGadgetserver v5.6.1.185 onwards it is mandatory to actively link redundant vsmGadgetServer provider connections in vsmStudio to achieve service redundancy. See here, how to link Communication Ports in vsmStudio. 

Consumers

Consumer connections are connections between vsmGadgetServer and 3rd party systems from the underlying infrastructure. The following example is based on a DMS connection. Other protocols may provide different parameters, especially in the “Settings” section.

Status

This section shows the general connection status.

• Name: This is the name used to identify the connection.
• Protocol Status:
  • Active indicates an active protocol consumer connection. If the server is member of a cluster, and the protocol status indicates as active, then the server has also the primary role.
  • Idle indicates a passive connection, which is the case when the entire server role is backup.
• Connection:
  • Idle: connection is configured, but server is in backup mode.
  • Disconnected: No 3rd party device is available at the configured address.
  • Valid: a 3rd party device is available and working.
• Active Address: This is the address of the currently connected 3rd party device.

Port Settings

• Addresses: This section allows to add IP addresses communication ports for this connection. It is possible to configure multiple ports per connection to allow to connect to various 3rd party devices.
• Stream Type: The stream type identifies the format of the data connection. It is preselected, when choosing a specific protocol, and editing this field is not recommended.
• Binding: allows to identify the network interface, which is used for the communication with the consuming control system. Either Any is chosen, or a specific IP address is set. In most cases, keeping Any as the default entry is suitable, since most setups work just fine, if vsmGadgetServer listens to any NIC (network interface) for incoming connections.

Mapped to

This section indicates the protocol provider, which is mapped to this specific consumer. This cannot be changed in this webpage. To change mappings, go the providers section and select the corresponding provider protocol.

Settings

The "Settings" section contains consumer specific parameters. The provided settings are closely related the type of consumer selected. Connection details set in this section are depending on the individual connection. For further information please feel free to get in touch with our support at support@lawo.com.

Protocol Factories

The section Protocol Factories allows to select the protocols – both, consumers and providers - you want to use in your specific configuration. Use the list at the left of the window to select which protocol your configuration will be extended with. While the Providers selection is straight forward, the available selections in the Consumers selection requires a paged navigation.

The lists are sorted alphabetically. To navigate the full list of consumers, you must use the page selector at the top of the list.

Alternatively, you can use the search field at the very top of the lists, and type your search term. Both lists, consumers and providers will be filtered immediately at entering. This reduces the lists to just display essential data.

Logging

The Logging webpage provides configuration details for various logging functions of vsmGadgetserver.

Logging system messages can be an extremely resource-intense process, especially, when the number of logged connections is high and/or the logged connections deliver huge amounts of unspecific data. It is therefore strongly recommended, to enable system logging on purpose only, e.g. instructed through support@lawo.com, in order to debug unexpected or undesirable system behaviour. Creating logfiles for convenience monitoring is not recommended, as other methods are more efficient, e.g. configuring system alarms for a specific device by using the logic capabilities of vsmStudio.

Log files are necessary and used for debugging purposes. While Lawo tries for consistency, the content of these, in particular content used for debugging, can and will change at any time without notice. This is based on the fact that our software products continuously evolve. Accessing and evaluating these logfiles, generated by vsmGadgetserver or any other VSM component, can only be done at the customers own risk. We do not have the obligation to maintain any assumed content or meaning derived from the existence of information at any given time unless clearly documented. Lawo owns the right to discontinue any information logged at any time if we deem this information or the collecting of this information irrelevant or dangerous to the stability of the system. If a requirement for specific information arises, customers have to inform Product Management, who will in turn assess the feasibility together with R&D.

It is possible to set the log level for 3 different logging outputs. The three possible outputs are:

• CommTrace: refers to the detailed logging application for vsmStudio. Any log level checked in the CommTrace section will cause vsmGadgetServer log messages appear in CommTrace. This is especially helpful, when you want to monitor system behavior between vsmStudio and vsmGadgetserver.
• File: log levels checked in the File section will cause messages to be written to the local vsmGadgetServer logfile. The logfile is written to [your-local-path-to]\ vsmGadgetServer.NET\Logs. Logfiles are saved as regular text files, identified by the creation date (vsmGadgetServer YYYY-mm-dd H-M-s.txt).
• Memory: The settings done in this section affect the log level for the Event Log output in the actual webpage you work on.
  
  

The event log is written to the webpage, independently of which sub page is shown. It is possible to limit the size of the logging buffer (by visible lines), to reduce the amount of data which is cached. Data which is logged and kept in the buffer, until the line count is reached (here: 40). Lines exceeding the line limit, will be purged (oldest first). If you want to keep the event log, you can easily export the latest log to a file by clicking the Export Log button. If you click the Clear button, the Event Log will be deleted.

Default Settings and Recommendations

The default settings for the logging in vsmGadgetServer are as follows. They can be changed on demand at any time.

CommTrace

It is recommended to switch on additional log levels for CommTrace, when you experience issues in the behaviour between vsmStudio and vsmGadgetServer, and you are about to analyse these issues using CommTrace. In all other cases, make sure you reduce the log levels to all off, or just leave Errors on.

File

It is recommended to leave all log levels in File checked. In case any issue occurs, you can be sure that the file logging has saved a trace. Logfiles will increase in size the more log levels are activated and the more connections are monitored. Make sure you keep the available free space on your servers hard drive under control.

Memory

Logging into the event log is helpful when setting up a system. You can trace specific connections and see outputs live at runtime. Since you do not use the web UI of vsmGadgetServer very often once it is configured, you can switch all log levels to off during normal operation. Memory dumps, which are exported into a file, only contain the number of lines which has been set as buffer size.

Recommended Logging Settings

Extensive logging can cause the system performance to decrease. Consequently, a system might become less responsive processing in processing control commands. To avoid this, please follow the recommended logging settings below.

Plugins

The Plugins Webpage lists functional enhancements for vsmGadgetServer, which are provided as modular extensions. These enhancements do not relate specifically to provider or consumer protocols, but to general functionality of vsmGadgetServer.

Plugins are provided by installation and do not require manual interaction. All necessary settings are preset at installation.

New plugins will be introduced through product updates/upgrades. There is no option to download and add plugins.

Available Plugins and Plugin Status

vsmGadgetServer provides six plugins at installation.

By default, five of them are active at runtime (blue icon), while one is disabled (pink icon). Additionally, some plugins show a “pause” icon. This indicates, that they can be halted or disabled on demand. Plugins, which do not show a pause icon cannot be halted or disabled.

Plugins which cannot be disabled are critical for operating vsmGadgetServer. If such plugins are not available or deleted from the install folder, generic functionality of vsmGadgetServer will be missing.

Ember+ Resource Monitor

The Ember+ Resource Monitor is a plugin, which provides vsmGadgetServer resources and their status as an Ember+ parameter tree. This functionality can be used by broadcast control systems, like vsmStudio, to monitor the operational status of specific vsmGadgetServer functionality.

For example, you can connect vsmStudio to the Ember+ port indicated in the Additional Information field. This connection will provide a full resource status to vsmStudio. Within a panel configuration, keys could be designed to indicate protocol status of specific consumer connections.

To evaluate type and structure of the available resources, please use an Ember+ viewer to visualize the data shared through a connection. Connect the viewer to URL <host IP address>:50100 to display the parameter tree. The image below shows an example tree representation.

• Plugin Modes: Switchable Active/Disabled.
• Default Mode: Active.

HTTP Plugin

The HTTP Plugin provides the actual configuration UI at URL <host IP Address>:50080. It is operation critical and cannot be parameterized.

• Plugin Modes: n/a
• Default Mode: Active.

Remote Protocol Mapping

With Remote Protocol Mapping, it is possible to map multiple consumer protocols to one provider connection. The providing connection to the broadcast controller will not be disrupted, while the mapping plugin allows to select one out of multiple consumer connections on-the-fly.

For configuration, use a web browser and type URL <host IP Address>:50081. A webpage opens which allows to configure consumer connections into a Sources list, and provider connections into a Targets list. Each insertion asks for a specific Source or Target name, and the corresponding connection represented by the name. Connections selected from the drop-down lists must exist.

Remote Protocol Mapping is configured, once connections have been inserted and the Apply button is clicked. The plugin creates a 1:n matrix of the configured sources and target and presents them through the configured target protocol.

You can use your Ember+ Viewer to set cross points in the created matrix.

• Plugin Modes: Switchable Active/Disabled.
• Default Mode: Active.

Service Discovery

The Service Discovery provides the actual list of known hosts. It is operation critical and cannot be parameterized.

• Plugin Modes: n/a
• Default Mode: Active.

Synchronization

The Synchronization plugin provides parameter synchronization in a server cluster. It is operation critical and cannot be parameterized.

• Plugin Modes: n/a
• Default Mode: Active.

vsmDiscover Interface

The vsmDiscover Interface enables discovery of a vsmGadgetServer through the proprietary vsmDiscover application. This helps identifying the service is a larger installation with multiple servers and services running. As the plugin uses the same RX/TX ports as vsmDiscover, it is not possible to detect the service, when running vsmDiscover locally on the same machine. That is the reason, why the plugin is switched off by default.

• Plugin Modes: Switchable Active/Disabled.
• Default Mode: Disabled.

Errors

Sometimes, system errors occur, with no operational character. Note that operational errors, such as those related to configured protocols, are logged in the Event Log, in CommTrace or to a local file. System errors might occur at start up of the vsmGadgetServer service, while none of the logging services are active.

System errors are logged in the Errors webpage.