MLComDevice Plugin
From Tallus LLC Wiki
Contents |
About
This is an alternative to using MLGenericSerial, MLGenericDevice or MLTCPSend, in order to control devices which do not have specific MainLobby drivers. The goal is to provide a better support for serial devices controlled by hexadecimal codes, ASCII support as well as TCP devices have been added. Additional functionality will be added as the plugin gets enhanced.
Users can create device drivers for their hardware devices or send an email to "info(at)Talluscorp(dot)com" requesting a device to be added. We can provide a quote for that customization if the user doesn't have the expertise or time to develop their own. Once the device is added, it will be added to the standard supported device drivers that come with the plugin.
MLComDevice is now available [Tallus Shopping Cart]
Download Link
MLComDevice provides free one direction (Send from MLServer3) TCP connection. Additionally, the plugin installs in a 30 day trial mode and allows up to three bidirectional devices to be supported. Once you have decided to purchase it choose from [MLComDevice Basic] that continues support for up to 3 devices, or [MLComDevice Advanced] that supports up to 10 devices. If you have an extensive system that requires more than 10 devices, send a note to info(at)talluscorp.com. After purchase, just apply the software license you will receive from Tallus via email on purchase of the plugin. After the plugin is installed, the license is then applied to MLServer3's Software Registration Menu (in MLServer: Help/Manage License Keys) which you must then Activate to that PC by sending your purchased license, your MLServer's Hardware ID (found at bottom of the Registration Menu window) to: info(at)talluscorp.com. You will soon receive an Activation code via email that is applied to the Registration Menu which makes that plugin permanent to that PC.
You should perform the above within the 30 day trial period to enjoy uninterrupted usage of the plugin with no rework needed between trial and licensed usage. Please allow up to two days for Tallus processing time for your requests. Most requests are processed within a few hours.
Requirements / Recommendations
.NET framework 3.5
MLServer 3.0.583 up to 3.0.588 (tested)
GuiGraphix Library #0019.
List of Supported Devices
Once you have developed your own Devices, please send them to "info at talluscorp dot com" so they can be added to the list of supported devices. Devices that Tallus creates on request are added to increase ease of use of this plugin.
| Device Name | Device Type | Status |
| Tallus Application | Applications developed for Tallus | All basic functions and status messages available |
| TChanger | TCP DVD / CD / BluRay hardware megachanger application for Home automation software packages | Fully functional |
| TChart | TCP graphing component for Home automation software packages | Fully functional |
| TRadio | HDRadio / Sirius / XM support for Home automation software packages | Fully functional |
| TZWave | TCP 2 way for TZWave application | Fully functional |
| IT100 | DSC Security Panel Powerseries Interface | basic functions |
| ADA Suite 7.1 HD processor | Audio matrix switcher | Most functions |
| Comfort | Comfort Security Panel Powerseries Interface | basic functions |
| Epson PowerLite Home Cinema 1080P Projector | Front Projector | basic functions |
| Hitachi CP-X200/300/400 | LCD Display Projector | All basic functions and status messages available |
| Key Digital Fat Boy Series | Matrix Switcher | Most functions available. |
| Lexicon MC-1 | Audio processor | All basic functions and status messages available |
| Lexicon MC-12 | Audio processor | All basic functions available |
| LG LCD | LCD display | Most functions available. |
| Mitsubishi HC1500 | LCD Display Projector | All basic functions and status messages available |
| Mitsubishi X300 | LCD Display Projector | All basic functions and status messages available |
| NEC LT2XX | LCD Display Projector | All basic functions (serial + TCP) |
| Network Media Tank (like Popcorn Hour) | Media Extender | basic functions (beta) |
| Onkyo Integra Receiver | Audio Receiver | Most functions available. Status messages not complete. |
| Onkyo Integra Preamp PR-SC886P | Audio processor | Most functions available. Basic status messages only. |
| Panasonic AX100 Projector | Display Projector | Most functions available. Status messages seem complete. |
| Pioneer Elite Plasma | Display | Most functions |
| RCS TR16/40 | Serial Thermostats | Beta |
| Roku Digital Video Player | Video Player | Most basic functions available. |
| Rotel Receiver | Receiver | Most functions available. Status messages not complete. |
| Runco Projector | Front Projector | Most functions available. |
| Russound Cav66 Whole house audio controller | Whole house audio controller | Base connectivity test version. |
| Sony VPL-VW50 | LCD Display Projector | All basic functions and status messages available |
| Tivo series 3 | DVR | All basic functions |
| WGL Rain8Net | Irrigation Controller | Sends commands to Rain8Net. No Status yet. |
| WGL W800RF32 | RF Receiver | Beta - Receives X10 / updates Variables |
| Windows Vista MediaCenter Controller | TCP 2 way for VMC | Beta - can send most commands needed. Triggers need work. |
Configuration
The configuration files are saved in MLServer\Data.
MLComDevices.xml: Associates each of your own devices with a port and a family. MLCom-KnownFamilies.xml: All the families of devices known by the plugin. MLCom-UserFamilies.xml: Families added by the user (should be submitted to Tallus).
You should consider backing up the MLComDevices.xml and MLCom-UserFamilies.xml files between updates.
Settings
This is where you can create a device by selecting a Family (i.e. Mitsubishi X300) and associating it with a specific Serial communication or TCP port.
In order to add a new device to control and monitor, you need to specify a unique Name to identify it (i.e. Player), select a pre-defined Family (i.e. RCS Thermo) and either the parameters for TCP or Serial control, then press Save as new. If you selected an existing device, you also have the possibility to update it by pressing Save it.
If your serial controlled device is connected to a GlobalCache GC-100 IP to serial converter box, use the TCP setting and type the GC's IP address and use ports 4999-5003 that correspond to the GC's serial port that the serial device is plugged into.
By right clicking a device, you are provided with a context menu. From this context menu, you can Enable/Disable or Delete the selected device.
Families
A Family consists of similar models produced by a manufacturer, which typically can be controlled using the same Commands and return the same results (Triggers). Selecting an existing Family from the list will allow you to view or modify its characteristics (i.e. through the sub-tabs General/Commands/Triggers).
General
You can consult, edit or add extra family of devices.
Enter a unique Name, a longer Description of that Family, any possible Header (i.e. the start of the Hexadecimal/ASCII code which is always the same), Check sum (i.e. OR) and End character(s) (typically 00 for "Null" or 0D for "Carriage return"), then press Add a new family (any Commands/Triggers are ignored). If you selected an existing Family, you also have the choice to update it by pressing Save this family, or Save as new family to also keep the Commands/Triggers of the selected Family. The following control characters: <SOH>, <EXT>, <STX>, <ACK>, <EOT>, <CR>, <NUL>, <NL> or <LF>, <EOF> or <SUB>, <ESC>, will be properly substituted for ASCII communication. Commands
You can consult, edit or add extra commands for a family of device.
Enter a unique Name, a longer Description and the actual code (without the header or end), then press Add as new. If you selected an existing command, you also have the choice to simply Save it, instead of adding a new command. For values provided at run time (i.e. volume level), use <varX>, a command could look something like: "00 30 <var1> 0A <var2> 06". For check sum values, use <CRC> at the appropriate position. Example of a volume command: 04 <var1> 03 0D, used as:
MLSchedule|0~volume~10, will send the following command to the device: 04 10 03 0D.
Note: If the selected Family is associated to one or more devices, then a specific device can be chosen and a Test button will be available.
Triggers
You can consult, edit or add extra MLServer commands in response to a trigger from a family of device. (also check the special protocol section). The General section contains a specific Trigger end, as they could be different from the command's End. Note that the Serial communication seems to already include a separation of messages based on <CR> and/or <LF>, so you would leave the Trigger end blank for those.
Enter a unique Name, the actual code (with the header and end) returned by the device, an optional MLServeCmd to execute on reception of that code, then press Add as new. If you selected an existing trigger, you also have the choice to simply Save it, instead of adding a new trigger. If <device> is found in the MLServeCmd command, it will be replaced by the device's name.
MLCmd.SetVariable|<device>_State~On, will set the Projector_State variable to On.
More complex Triggers can be defined using the format <start><mask><end>, where the <start> and/or <end> might be blank. For example, one could use "AA <mask> FF", so that whatever is found between the starting AA and ending FF will be put in a variable, which can then be used in MLServeCmd:
MLScript|ParseMask~<device>~<mask>
or
Macro|MLStrings|Left~output1~<Mask>~1!MLStrings|Mid~outputr2~<Mask>~2~1!MLStrings| Mid~output3~<Mask>~3~1!MLStrings|Right~output4~<Mask>~1
Note: some typical MLServeCmd commands might be provided as a starting point, you should edit them to match your needs or disable them by replacing them by a dash (-).
Check sum
Currently, three methods are supported (the Header and End are excluded):
SUM: A simple sum of all the bits.
OR: The OR operator is applied to all the bits.
AND: The AND operator is applied to all the bits.
Other check sum methods can be implemented by Tallus on request.
MLServeCmd
The format of the commands is:
MLComDevice|<device>~<command>
where
<device> = the device's name or number (0-based).
and the case sensitive command can be:
<command> = Send~<code> to send directly some specific control code (i.e. 21). <command> = SendRaw~<code> to send directly some specific control code (i.e. 30 30 21 0D). <command> = any command defined for that type of device (i.e. PowerOn).
If place holders (<varX>) were used in the command definition, the format is:
MLComDevice|<device>~<command>~<var1>{~<var2>{~<var3>...}}
where
<command> = any command defined for that type of device (i.e. Volume = "00 <var1> 0B") <varX> = value to substitute for the place holder in the command definition (i.e. 10).
Example:
MLComDevice|0~Volume~10
Special protocol
At the core of the Triggers handling, is the assumption that most of the returned messages can be easily traced back to the queries/actions that produced them (i.e. Vol? --> Vol=10). On the other hand, some protocols won't broadcast messages by themselves (i.e. Xantrex inverter), and instead a query like "Freq?" will result in a raw message like "60.000".
The work-around to handle those cases is to make use of a dummy MLServer variable (XantrexDummy) in a macro:
Macro|SetVariable|XantrexDummy~Freq1!MLComDevice|Xantrex1~Frequency
and use a single trigger to handle all the messages:
Name = Incoming
CODE = <Mask>
MLServeCmd = SetVariable|<Device>_{{XantrexDummy}}~<Mask>
This way you will be able to create your various Xantrex1_Freq1, Xantrex1_Volt1 variables by using different macros.
Using MLString to parse return serial device strings: If the unit returns 1246 and you want to have 4 variable show output1 2,output2 2 output3 4 output4 6 use this type of command: Macro|MLStrings|Left~output1~<Mask>~1!MLStrings|Mid~output2~<Mask>~2~1!MLStrings|Mid~output3~<Mask>~3~1!MLStrings|Right~output4~<Mask>~1
Acknowledgments
Thanks to PsychoCoder for regrouping useful information in his Serial Port Communication in C# lesson!
Version history
Version 1.5.5
- Updated new devices in KnownDevice file.
- The displayed event log is now limited to 250 items and will reset after.
Version 1.5.4
- Fix: Adding/changing sorted Families could cause problems.
Version 1.5.3
- Most column's header can be clicked to reorder the column.
Version 1.5.2
- Fix: Using the "Save as new" on a Family was not resetting the Commands/Triggers. - Added RNET as checksum for the Russound devices.
Version 1.5.1
- Made the commands case insensitives...
Version 1.4.1 to 1.5.0
- Improved the TCP triggers' parsing.
- More debugging text for TCP devices...
- Improved the rescaling of the Families tab.
- Control characters in the Triggers now get converted...
- Another possible fix for some triggers...
- Possible fix for some triggers...
- Added support for <FC>, <FD>, <FE> and <FF> replacement.
- Another possible fix for the parsing of the Russound family.
- Fix: the TCP device reading was broken...
- Fix: the parsing of the Russound family had problems.
Version 1.3.1 to 1.4.0
- Russound support improvements.
- Logging errors should no longer prompt a .NET error dialog.
- Added more multi-threading.
- Moved the .log to MLServer\Logs.
- Moved the Logger part out of the invoke...
- Fix: now support extra parameters through ~.
- Fix: In triggers, <MaskTo...> was broken.
- The Commands' MLServeCMD can now make use of <VarToDec1> (Hex to Dec) or <VarToHex1> (Dec to Hex).
- The Triggers' MLServeCMD can now make use of <MaskToDec> (Hex to Dec) or <MaskToHex> (Dec to Hex).
- Fixed some issues with the End characters in triggers. They are no longer included in the triggers, so if you are using customized triggers/commands, you might need to edit yours!
- The Verbose log setting is now persistent. Fix: the test button was not properly handled.
Version 1.2.1 to 1.3.0
- Added support for the IT-100 and its checksum.
- Triggers should properly handle "1<Mask>", "10<Mask>", "106<Mask>".
- Added more debugging for the Partial triggers...
- Reduced the logging unless Verbose mode is enabled.
- Fix: should no longer lock (for a short time) MLServer when trying to connect to an offline TCP server.
- Got rid of the alpha Global Cache 100 IR support for now.
- Merged the Devices tab with the Settings tab.
- Removed the combobox when items can be selected from a listview.
- Fix: TCP triggers with more than one End characters were not handled properly.
- Detect an extra type of communication loss... Shorten the delay on TCP communication.
- Reverted back to the TCP client code from 1.1.8, but with the fixes for the communication loss...
Version 1.1.1 to 1.2.0
- Fix: more fixes for offline TCP connections...
- Fix: TCP connections were not restarted properly after a loss of communication.
- Fix: <mask> was not properly handled when the surrounding text contained lower caps...
- Preliminary Global Cache 100 support.
- Possible fix for the serial port being left in a strange state...
- The Trigger's End character is now independent of the Command one.
- Added more ASCII character's substitution: <SOH>, <EOT>, <ACK>, <EOF>, <SUB> and <ESC>.
- Fix: activated devices handling was wrong.
- Bug fixes.
- Can now support 10 enabled devices (or more) with proper activation.
- Fix: problem loading.
- Fix: changes to families did not propagate to the existing devices.
- When adding an item, a blank name for a Command, Trigger or Family will be replaced by "No name".
- Fix: renaming a user family was not updating the corresponding combo boxes and list view.
Version 1.0.0 to 1.1.0
- Checksum calculations are now performed on the whole "code", excluding the Header and End. The valid choices are ADD, OR, SUM, and can be performed on Hexadecimal as well as ASCII commands.
- Fix: the TCP configuration box was never visible.
- Changed the presentation of the Families.
- MLComDevices.xml no longer contains a duplicate of the user's Triggers.
- TCP communication now uses control characters such as <ETX> instead of check boxes.
- Fix: ASCII parsing was not handling special characters in End properly (i.e. <ETX>, etc.).
- Fix: <device> substitution did not work in conjunction with <mask>.
- The following control characters: <EXT>, <STX>, <CR>, <NUL>, <NL> or <LF>, will be properly substituted for ASCII serial communication.
- It is now possible to delete user added Families/Commands/Triggers from the lists.
- Try to split (at the END character) combined serial messages in sub-messages for processing.
- Plugin renamed to MLComDevice due to increased scope of protocol coverage and connectivity options.
Version 0.2.1 to 0.2.8
- Fix: anything dealing with a default Family had issues...
- The serial port delay is now configurable.
- Added a 100 ms delay before reading the serial port, to avoid split communications...
- Failure to connect to a TCP port should no longer hold up the launch.
- Fix: solved some issues with saving devices and families.
- For TCP devices, added the possibility to send <STX> (Start Transmission), <NL> (New Line) and <ETX> (End Transmission).
- Fixed more left-over serial only code...
- Cleaned up the handling of Enabled device...
- Added support for the NEC LT series of projectors.
- Added a new Check sum: SUM simply sums up all the bits.
- Added support for TCP devices.
- Added support for <mask> in triggers.
- Added a button to clear the log.
- Known families now include a default MLServeCmd (use "-" to disable it).
- Trial and Basic version are now limited to 3 active families.
- Can select a specific device for testing.
Version 0.1.1 to 0.2.0
- Made the listview's headers non-clickable...
- Items from the Families, Commands and Triggers listviews can be selected.
- Added a context menu to the list of Devices.
- Will no longer try to access the port if the device is disabled.
- Added a second check sum method (AND).
- Added a first check sum method (OR).
- Devices can now be disabled.
- Fix: unloading and reloading the plugin was not properly handled.
- Removed some debugging text.
- Commands can contain <var1>, etc. for substitution at run time.
- Fix: the communication port was never initialized.
- Fix: the triggers were not working.
- Compiled using .NET Framework 3.5.
- Added a Test button to the Commands tab.
Version 0.0.1 to 0.1.0
- Completed the Type -> Family migration.
- Fix: the Hexadecimal transmission was not making sure that the port was opened.
- Renamed Type to Family.
- Added the "End" character(s) for the Family configuration.
- Added MLComDevice|SendRaw~<code>.
- Can now read the configuration files, so should be a working version.
- Enabled MLComDevice|<device>~<command>.
- Can now save the configuration files...
- Work started on the configuration files...
- Modified the flow control support for the port configuration.
- Started coding the serial communication.
- Split the Devices tab in Devices and Types tabs.
- Completed the port settings.
- Proof of concept.
Notes on Supported Devices
VmcTCPController
MLComDevice allows for two way control and status received from a Vista Media Center application. To enable Vista to "talk and listen", requires installation of bradsjm's VmcController application that is downloadable here:
[VmcController]
To install:
Download VmcController (the November release was quickly tested by Tallus), shutdown MediaCenter application and run the downloaded .msi installer on that PC.
Open that PC's firewall on ports 40500 (what Media Center will listen for commands on) and port 40400 (the port Media Center will send status updates on) and reboot that PC for the changes to take effect. For extenders, the port 40500 number is incremented so for the first extender the control port is 40401 etc. For extenders, the port number is incremented so for the first extender the "listen" stream is on port 40501 etc. Media Center has to be running for the MLComDevice to connect to it.
The MLComDevice Settings for the included VmcTCPController Family would be configured for the Media Center PC's IP Address and the appropriate port with ASCII encoding and <New Line> selected. There will be a Device for Listen (default port 40500) and Control (default port 40400) that should have different Device Names (of your choice to identify that MC PC)
Example:
Settings tab
Device: VmcTCPTheater1
Name: VmcTCPTheater1
Family: VmcTCPController
TCP checked, Disable unchecked
TCP address: IP address of the "Theater1" Vista Media Center PC to be controlled
Port: 40500 (the control port)
Encoding: ASCII
<New Line> selected
Click Save as New (if first time you have created this device)
Repeat the above for the Listen port 40400 for device "VmcTCPTheater1Rec" (for "Receive")
You can now create a remote control on steroids for controlling Media Center PCs.
Please post your Triggers, MLScripts, and Scenes on Tallus's Forum so the community can learn from each other's implementations. What is provided by Tallus in the plugin is a starting point.
W800RF32
You will notice when you send an X10 RF command from a PalmPad that the MLComDevice plugin will receive multiple of the same events. This is redundancy to ensure that the message was heard correctly by the plugin. You can replace the provided SetVariable commands with whatever command you want to execute when that X10 code is received.
This could be:
<A1_On>Macro|SetVariable|X10_A1~On!MLComDevice|Rain8Net~Mod1Zone1On</A1_On>
In this example, Mod1Zone1 might be an irrigation zone that you want to aim the sprinklers....just take the RF Palm Pad out to the yard and push A1 and your sprinkler will start running so you can re-aim the sprinkler head (as example).