Announcement

Collapse
No announcement yet.

Script Connector API and DOC

Collapse
This topic is closed.
X
This is a sticky topic.
X
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

    Script Connector API and DOC

    Welcome to the Script Connector Plugin.

    This plugin lets you run any HomeSeer .Net script on remote computers, and advanced HomeSeer scripts on your main HomeSeer server.

    Remote scripts really run on the remote computers, and have access to all remote computer resources (file system, com ports, screen, keyboard, mouse...). The remote scripts also have access to all HomeSeer API. For example, you can easily set a HomeSeer device string with the content of a file on a remote computer, or print any message on the remote computer screen.


    Requirements:

    - The Speaker Client must be installed on the remote computers, but it doesn't have to be running. Alternatively, you can also run the Script Client on your main HomeSeer Server.
    - TCP port 8737 has to be open on your firewall, if you want to run HomeSeer scripts on remote computers over the Internet.
    - A Script Connector Client must be installed on the remote computer.


    To install the Script Client on each Speaker client computer:

    Once the plugin is installed, you can find a SetupHsScriptClient.msi Windows installer file in your HomeSeer 2 directory.
    From each remote computer, you need to run this file to install the Script Client.
    There are two ways to do this:
    - You may connect to the main HomeSeer computer from the client computer, then browse to the HomeSeer 2 directory and double-click the SetupHsScriptClient.msi
    - You may copy SetupHsScriptClient.msi to the remote computer using any other way, then run it.


    To run remote scripts from HomeSeer:

    - From any HomeSeer event, choose the Exec Remote Script action, enter the name of the Script Client, filename of the remote script, and optional parameter for the script Main() subroutine. If you use the standard "Run Script" HomeSeer event action, the Script Connector plugin is not invoked.

    - From any HomeSeer script, use the plugin ExecRemoteSub() API

    Example from HS Immediate Command Window:
    &hs.plugin("Script Connector").ExecRemoteSub "remote_client_name", "remote_messagebox.vb", "hello from HomeSeer"

    - From any HomeSeer script, use the plugin ExecRemoteFunc() API to return a result from the script Main Function

    Example from a HomeSeer VB script:
    hs.WriteLog( "Result", hs.Plugin("Script Connector").ExecRemoteFunc( "remote_client", "remote_test_func.vb", Nothing ) )


    To run remote scripts from the Remote Computer

    The HsScript program supports command line arguments.

    Syntax: HSSCRIPT remote_script_name.vb optional parameters
    Example from the Windows command prompt on a remote computer:
    HSSCRIPT remote_writelog.vb Hello From a Remote Computer !
    This prints "Hello From a Remote Computer !" to the HomeSeer event log.

    You can also create a Windows Shortcut easily on any remote computer to run remote scripts:
    Example with the Remote Mini Control script:
    - Right click on your desktop, choose New - Shortcut
    - Type the following as the shortcut target (including quotes) and apply:
    "c:\Program Files\HomeSeer 2\HsScript.exe" remote_mini_control.vb


    Sample scripts installed with the plugin:

    - remote_writelog.vb <-- Writes a message to the HomeSeer log
    - remote_writelog.cs <-- Writes a message to the HomeSeer log (Test C-Sharp Script)
    - remote_devicestring.vb <-- Changes a HomeSeer device string from a remote computer
    - remote_messagebox.vb <-- Shows a message box on the remote computer
    - remote_deviceaction.vb <-- Shows a dialog box on the remote computer, to switch HomeSeer devices ON/OFF
    - remote_mini_control.vb <-- Shows a dialog box with device status. You can click the status icons to switch devices ON/OFF
    - remote_marquee.cs <-- Shows a large scrolling message on the remote computer. Click on the message to close it.
    - remote_postit.cs <-- Shows a yellow post-it on a remote computer. Enter message as script parameter
    - remote_thermostat.cs <-- Shows a HomeSeer Thermostat control dialog box
    - remote_light.cs <-- Shows a small slider to control one light. Enter one device code as script parameter
    - remote_lights.cs <-- Shows a dynamic dialog box to control several lights. Enter several device codes as script parameter
    - remote_test_func.cs <-- Example CSharp Function Script
    - remote_test_func.vb <-- Example VB Function Script
    - remote_set_context.cs <-- Example script to save a value
    - remote_get_context.cs <-- Example script to get a value saved with remote_set_context.cs
    - media/*.cs <-- Scripts for the distributed HomeSeer Media Player

    The remote_messagebox.vb sample script shows how you have to declare any external assembly/dll you want to use from the remote script. You can add several #IMPORT lines to your scripts to reference as many assemblies as you need.


    Remote scripts advanced API

    Remote scripts have access to the hs object methods and properties. Furthermore remote scripts have access to the sh object (ScriptHost) methods and properties, to take advantage of remote features.

    sh.SetContext( keyString, paramObject ) <-- Save an object within the script client
    object = sh.GetContext( keyString) <-- Get an object previously saved. This allows to pass values between several scripts.
    boolean = sh.ExecLocalSub( scriptPath, paramObject )
    object = sh.ExecLocalFunc( scriptPath, paramObject )
    boolean = sh.ExecRemoteSub( scriptClient, scriptPath, paramObject )
    object = sh.ExecRemoteFunc( scriptClient, scriptPath, paramObject )
    string [] = sh.ClientList <-- List of registered Script clients as a string array
    string = sh.ClientName <-- Name of the running Script Client
    sh.ShowBalloonTip( title, message, icon, timeout ) <-- icon must be 'None', 'Info', 'Warning' or 'Error'

    Remote Scripts special keywords:

    #IMPORT NameSpace,NameSpace.dll <-- adds NameSpace.dll as a reference to the script, and allows shortcuts.
    #USING NameSpace <-- Allows shortcuts to the named NameSpace
    #MTA <-- Use the Multithreaded COM Apartment model (this is used to host COM objects within scripts)
    #STA <-- Use the Single Threaded COM Apartment model
    --
    stipus

    #2
    Calling other plugins from a Remote Script

    You have to copy the hspi_xxx.dll for the plugin you want to use, to the remote computer HomeSeer 2 directory.

    With C-Sharp (.cs) scripts, you also have to cast the object to the real plugin type, and this means you also have to reference the plugin dll.

    Example with a VB script:

    Code:
    Sub Main( object param )  
      hs.Plugin("Skype Connector").SendMessage( "stipus18", param )
    End Sub
    Example with a C-Sharp script:

    Code:
    #IMPORT HSPI_SKYPE,hspi_skype.dll
    
    void Main( object param )
    {  
      ((HSPI_SKYPE.HSPI) hs.Plugin("Skype Connector")).SendMessage( "stipus18", param.ToString() );
    }
    --
    stipus

    Comment

    Working...
    X