MLGenericDevice Plugin

From Cinemar Wiki
Jump to: navigation, search

About

MLGenericDevice is a plugin for Advanced users and dealers to build a custom control plugin for relatively simple RS232 bidirectional devices. Perfect candidates are LCD / Plasma displays, front projection units, projection screens, etc.

MLGenericDevice also supports sharing of device codes via an Export and Import utility. Cinemar also will develop and support device drivers for the MLGenericDevice that aren't better suited for a full custom plugin development effort. These Cinemar sanctioned device drivers are available via MLServer3's Additional Software Download page (in MLServer3, click Help / Additional Software Downloads).

The MLGD plugin supports the licensing concept of "Basic" device slots (those that have 10 or fewer commands) and "Advanced" device slots (more than 10 commands). The two catagories are priced as individual products to make simple devices inexpensive, and complex devices at a higher fee. An applicable license code is required for a device to be added and functional within the MLGenericDevice plugin. The associated costs are to defray the cost to develop and support MLGenericDevice and provide Cinemar incentive to develop this very powerful, relatively simple to use application.

Purchasing MLGenericDevice slots: MLGenericDevice

MLGD supports sending of RS232 commands via a comport or a GlobalCache IP to serial device. The plugin also supports full scripting support for parsing of return data and many other useful and powerful functions.

The MLGD plugin currently supports ASCII devices. Hex device support may be added later as Hex devices typically require checksum calculations that can become complicated and difficult for end users to get working.


Installation

Shutdown MLServer3 and run the MLGenericDevice_Setup.exe file. This will install the MLGenericDevice.dll file to the Plugins directory, and the GenericDevice.mdb to the Data directory. zip32.dll, unzip32.dll and CGZipLibrary.dll also get installed to the System32 directory. These facilitate Import / Export functions.

Restart MLServer3 and open the Registration window. Add your purchased license key. In this key, is encoded the number of Basic and Advanced units you purchased. Once the license key is added, it must be Activated. As Basic and Advanced units are added, and a new license key is added, the new key must again be Activated.

Open the Settings tab of MLGenericDevice. On the bottom, you should see the number of licenses of both Basic and Advanced units.


Setup of a Global Cache Device

If you will be using a Global Cache IP to serial device, now is a good time to configure it. Click on the Global Cache Devices tab and click Add Device. Type a Device Name and Alias in the respective fields. Type the Global Cache unit's IP Address. Click the binocular. The eligible serial modules should now be listed. Pick the one that applies to this GlobalCache device Alias. Click OK. You should now see your Global Cache Device listed. If you GC module has more than one serial port, you can now create a second Alias with that hardware device's second Module.

As the Global Cache is a network device, the system's firewalls have to be opened for communications. Global Cache Base port: 4998 Serial ports: 4999, 5000....depending on number of serial ports. UDP port 9131 is used for Global Cache discovery (not used by MLGenericDevice though - which requires IP address).


Creating a MLGeneric Serial Device

You can now either create a new device from scratch, or Import a device, or Import a device as a model and then modify it.

Simplest is to find a device driver either from MLServer's Additional Software downloads, or via the MLGenericDevice wiki thread where users can upload their own device drivers, which can then be downloaded by others to reuse. NOTE: third party device drivers should be used as "user beware". Because of the powerful nature of MLGenericDevice, it is possible for a device driver to contain a PC virus or system detrminental script. If you are not comfortable with taking this risk, do not Import that device driver!

Files downloaded from Additional Software Downloads get sent to the MLServer\Downloaded Files directory. This is also the directory that your 3rd party drivers (the .zip file) should be copied to. Do not unzip the file as the Import utility in MLGD will do that correctly for you. Do not alter the file name as the name of the zip has to match the name of the zip file contents. Once the file is there, click the Import button and browse the Downloaded Files directory for your driver file. Click on the file, and then click the Open button. You should now see the new driver in the Controlled Devices tab.


Editing a Device's Communications Parameters

Click on the new device in the list and click the Edit Device button. Here you can rename the device (including its Alias name). In the Control Type box, you should now see whether that device is a Basic or Advanced device. NOTE: if a device as an Advanced device and you then change it to a Basic device, only the first 10 commands will be able to be used (which may not be the commands you need). You should also see how many license units of each type remain in your license key.

Click on the Communication Method of your choice. Either a Serial port or a serial port on a Global Cache module. If Global Cache module, you must define that module in the Global Cache Devices tab first. If serial port, click on that and select from the drop down list which serial port you are connecting your device. Hint: the asterisks imply available serial ports that don't appear to being currently used. Select the baud rate, data bits, parity and stop bits values as per your hardware requirements.

Now select the Input Command Parameters supported by your device. Type the Command Terminator value your device uses. 13 is a common one. You can click the Send Update Commands on Startup checkbox to do....Click OK to complete your settings updates or Cancel to disregard your changes.


Editing Commands

To modify (or view) that device drivers settings, click the checkbox next to the device you would like to edit. Then click on the Commands tab and your selected device should now be in the drop down of devices that can be edited. Choose it from the list. The devices Commands should now be visible.

You can add or change the Command Name, add a Command String or modify the Command Terminator here. If you click the Test button, the MLGenericDevice will send that command out the configured comport to the hardware device.

When your command is operating correctly, click OK.


Configuring a Device Response Script

If you are working with an existing device, you can select the Command Name and click Edit to view that device's return message scripting. If you wish to create a new response script, click the New button. Here you can name the script and assign it a MLServer Variable name.

Sharing of MLGenericDevices

Cinemar developed devices for MLGenericDevice use will be found in the MLServer3 Help / Additional Software Downloads webpage. These are developed by Cinemar for dealer and end user use. End users are encouraged to develop their own device drivers and post them to this Wiki.

First, Export your device: To export, click on the device to export and click the Export button. This will export your file as a zip file to the MLServer\Data directory. The file name must be maintained or Import won't work. Don't change it.

To Import, you make sure you have licensing availability for the device you want to import, and click the Import button. You then find the Zipped file (you don't do any zipping or unzipping - the plugin does it during Export) and select it to import it.

To share your file, simply click the Upload File button in the Wiki toolbox (left side navigation of the Wiki you are now reading) and upload your zipped device file (the file that MLGenericDevice zipped for you - don't manually zip the files). Then, create a new device driver link on the Home Page of the Wiki by clicking Edit (top of the page) and copy / paste another entry to the area of the Wiki that your new device belongs to ie: a LCD plugin would go in the "Display Devices" area. Edit the entry for the specifics of your device. Save the home page with your changes. When you click on your new link, a blank page will open. Add your device description and put a link for its download using [nameofdevice] in the text.

User contributions will increase the odds that a user can find a device driver for their hardware without having to spend the time to build a solid driver or having to pay Cinemar for custom development. Of course, if a driver does not exist and you really need it, you can contact Cinemar to inquire on custom development of your new driver.

3rd party devices drivers should be used at the caution of the user as there is the possible threat of the driver containing a virus. Cinemar does not test or certify that device drivers work, or will not do harm to one's system.

Examples

You can send up to 2 variables to any command

For example if I have a command named zone_treble

The command is defined as *Z<<VAR1>>TREB<<VAR2>> in MLGD

The MLS command is mlservecmd.MLGenericDevice|Zone_Treble~2~12

mlservecmd.MLGenericDevice|MCEServer1~Title~{movie}

Just make sure you have the <<VAR1>> in the command definition.


How to make a response command for each individual response

Do this:

Code:

StateChanged TestBox MediaArtChanged=<<VAR>> 


Instead of

Code:

StateChanged TestBox <<VAR>> 


that would bypass all of the scripting when it returns track time variable. Just dont set a response for that variable.


ACTIVATE_DEVICE activates the device

DEACTIVATE_DEVICE deactivates the entire device


Question:

How would I send a CR...I believe it is Hex number 'D', but it looks like the plugin only sends standard ASCII commands.


Answer:

Depends on where are you trying to send it

If it is a termination character, use a "13". If you are sending it in a command <<\13>> should do it.

Here is the conversion chart to use: http://www.asciitable.com/


Bugs

Feature Requests

Release Notes

4/11/08 v 3.0.462 Beta timeout extended

2/23/08 v 3.0.439 Updated scripting capability same as MLScripts More details to follow in Wiki

2/16/08 v 3.0.433 Some code cleanup

2/15/08 v 3.0.430 Plugin dates extended

2/14/08 v 3.0.427 Resolution for Can't Open Tables Error.

12/3/07 v 3.0.405 Plugin updated with changes to licensing to resolve device edit issue. - Adds double click editing of the device and commands. Right clicking on these items will create a new item.

10/29/2007 V 3.0.393 released Plugin updated to resove timeout

9/28/2007 V 3.0.367 released Plugin updated to resove timeout

8/27/2007 V 3.0.347 released. Resolves local install path issue.

8/22/2007 V 3.0.312 released. Adds more scripting ability

V 3.0.291 released. Adds ability to send a hex string for some ASCII based devices that require some hex strings

V 3.0.277 released. Adds significant power by allowing for a device return message string to be parsed and create multiple variables for tracking of status(s).

V 3.0.271 released with fix for trial period.