James: 1 revision

2021-01-13T17:25:02Z

1 revision

Jitterjames: /* Testing Code */

2017-11-26T12:54:49Z

‎Testing Code

New page

=The IronPython Plugin "PY"=
By leveraging the power of [http://ironpython.net/ IronPython], the "PY" plugin allows us to run Python scripts in VoxCommando. Scripts can interact with VoxCommando, reading and setting variables, triggering events and executing other actions. This allows us to do many new things that VoxCommando was not able to do very well before such as:

* Math
* Complex logic
* Looping (for loop, while loop, etc)
* and pretty much anything else we can do with Python!

Remember, Python is '''case sensitive''', and depends on '''proper indentation'''. Be careful not to mix spaces and tabs in your indentation. This is a common mistake with Python.

==IronPython Is Not Quite Python==
*IronPython is based on Python version 2.7. If you grab code that's written for Python 3.x, you might need to make some modifications to make it compatible.
*IronPython has advantages over regular Python in that we have direct access to various components of VoxCommando.
*IronPython also gives us access to many of the programming tools available in .Net. For example, in our [[Arduino]] Python scripts, we are using .Net's <html><a href="https://msdn.microsoft.com/en-us/library/system.io.ports.serialport(v=vs.110).aspx">serialport</a></html> class.
*Not everything that works correctly in standard Python will work in IronPython, but most things do.

=Setting up the Python Libraries=
[[File:InstallComponents.png|left|400px]]You do not need to install Python to use this plugin. Everything that is required is provided with VoxCommando.

During installation, make sure the Python Libraries checkbox is selected. If you initially unchecked the Python Libraries box upon installing VC, simply run the installation file again, with the box selected.

To use the Python plugin, simply enable the plugin as you would any other [[Plugins|plugin]] in VoxCommando.

=Plugin Actions=
Currently this plugin allows us to call the following actions from our VoxCommando commands.

==PY.ExecString==
Executes a single line of Python code. For example, we can use it to handle <html><a href="http://voxcommando.com/forum/index.php?topic=2165.0" target="_blank">basic calculations</a></html> within a VC command macro, or <html><a href="http://voxcommando.com/forum/index.php?topic=1548.msg13508#msg13508" target="_blank">pass VC data</a></html> to a function we've already defined and loaded as a Python script (using PY.ExecFile), etc. But if we want to do anything fancy, we should probably use PY.ExecFile.

==PY.ExecFile==
Executes all of the code in the file specified.
You can use relative paths, and they will be interpreted relative to the main VoxCommando folder. It is generally a good idea to put all Python scripts into a folder such as ..\VoxCommando\PY.

If you need to pass parameters from VoxCommando to a Python function, you should define the function first using PY.ExecFile, then use PY.ExecString to call the function and pass in parameters. Search the forum for examples (<html><a href="http://voxcommando.com/forum/index.php?topic=1548.msg13508#msg13508">here's one</a></html>).

Functions only need to be defined once. You may wish to put all your Python functions into a single ExecFile that gets loaded when VoxCommando first starts up (i.e., triggered using a VC.Loaded [[Command Tree Editor|event]]). Any function in this file can then be called within individual commands using the PY.ExecString action.

==PY.*==
List of [[Plugin_PY|all actions]] available in the [[Logical_Command_Builder|LCB]].

=Accessing VoxCommando Methods from Python Code=
Through the vc object, Python code can call the following methods available to all plugins:

* '''void''' triggerEvent(string strEventName, List<string> payloads);
* [[actionResult]] callAction(string strActionType, string strParams, List<string> payloads);
**[[#Actions|more info]]
* '''void''' doWav(string strWavPath);
**Evaluates an audio file and tries to recognize speech
* '''object''' getObject(string strObject, string strSubObject);
** [[#getObject|more info]]

* '''void''' log(string strLogText);
** Writes a line of text to the VoxCommando log file (if logging is enabled)
* '''bool''' savePayloadFile(string strPath, Dictionary<string, string> payloadPairs, bool subsetMatching);
* '''bool''' savePayloadListToXML(string strPath, List<xmlPayload> myxmlpayloads);
** probably too complicated for most users
* '''string''' getLastResult();
** returns the last result (a string) that was successfully returned by an action
* '''void''' setResultList(List<string> lstResults);

==Triggering an Event==
===Event With No Payloads===
For example, if you wanted to trigger an event in VC called "MyEvent.DoIt" you could use the following code:

<pre>
vc.triggerEvent("MyEvent.DoIt",None)
</pre>
Note: "None" is the Python equivalent of "Null" and we use it if we don't need payloads.

===Event With Payloads===
To include payloads in the event:
<pre>
from System.Collections.Generic import *
vc.triggerEvent("MyEvent.DoIt", List[str](["this is payload1","and this is payload2"]))
</pre>

==Actions==
You can execute other VoxCommando actions by using vc.callAction, like this:
<pre>
vc.callAction("OSD.ShowText","Display me for 5 seconds at the top&&5000&&-10", None)
</pre>

As with vc.triggerEvent above, the final parameter is ''None'' because we are not passing any payloads. In other words:

[[File:primer.png]]

We can make VoxCommando count to ten.

We can use Python to execute a loop. On each iteration of the loop, we call the "TTS.Speak" action.
<pre>
for x in range(1, 11):
vc.callAction("TTS.Speak","%s"%x, None)
vc.callAction("TTS.Speak",". There, I counted to ten", None)
</pre>

*"%s"%x is a Python method of formatting a string. In this case we are using it to convert an integer to a string
%s will be replaced by the value of x
*Note that in this case we are not using payloads, so we must send "None" which is the Python way of saying "null"

==Generating Payload XML Using a Dictionary in Python==

We can generate a payload XML file from a dictionary of key:value pairs.
<pre>
from System.Collections.Generic import *

myPayloads = {"payload value 1":"payload phrase 1","payload value 2":"payload phrase 2","payload value 3":"payload phrase 3"}
path = "C:/VoxCommando/payloads/payloadtest.xml"

vc.savePayloadFile(path,Dictionary[str,str](myPayloads),False)
</pre>

CAUTION: The dictionary keys will become the *values* in your payload XML file. The dictionary values will become your payload phrases.

==getObject==
You can request data from VC by calling vc.getObject(string strObject, string strSubObject)

For example, to print the LastResult variable which was set by a previous action:
<pre>print vc.getObject("LastResult","")</pre>

===strObject ===
Valid values for strObject are:
*"lastresult": returns a string
*"matches": returns a list of strings
*"displaylanguage": returns a string
*"payloads": returns a list of strings
*"fpayloads": returns a list of strings (in this case, [[Variables#.7BPF.1.7D_etc.|friendly payloads]])
*"evalvars" : returns a string where known VC variables in curly brackets have been replaced with their values
** available only in VoxCommando version '''2.2.1.7''' or later
<pre>#example for evalvars
info = vc.getObject("evalvars","{LastSpoken}")
print info</pre>

===strSubObject===
At the moment, no objects make use of the strSubObject parameter

=Returning a Result=
To send a result back to VoxCommando you need only set the "result" variable. The value will then be accessible to subsequent actions using {LastResult}

==Examples==

'''Example 1.'''

If we execute the following Python code:
<pre>
result= 5.0*4/(3+4)
</pre>

then {LastResult} will be equal to "2.85714285714286".

'''Example 2.'''

<html><a href="http://voxcommando.com/forum/index.php?topic=1341.msg11572">Verify Internet Status</a></html> (forum thread)

'''Example 3.'''

<html><a href="http://voxcommando.com/forum/index.php?topic=1548.msg13507#msg13507">For Loop</a></html> (forum thread)

=Python Scripting Forum Board=
More use scenarios and explanations on issues such as:

*<html><a href="http://voxcommando.com/forum/index.php?topic=1548.msg13488#msg13488" target="_blank">complex logic in python</a></html>
*<html><a href="http://voxcommando.com/forum/index.php?topic=1548.msg13508#msg13508" target="_blank">creating python functions</a></html>
*<html><a href="http://voxcommando.com/forum/index.php?topic=1548.msg13488#msg13488" target="_blank">passing information between VC and python</a></html>
*<html><a href="http://voxcommando.com/forum/index.php?topic=1541.msg13573#msg13573">comparing python solutions to VC-only solutions</a></html>

can be found on the forum. In particular (though not exclusively), on the <html><a href="http://voxcommando.com/forum/index.php?board=41.0" target="_blank">Python Scripting</a></html> board.

=Testing Code=
[[File:Pypluginwindow.png |thumb|400px]]
*Open the "PY" plugin settings page to access a Python editor where you can test your code. Click "Execute" to see what happens.

*Another way to test code would be to edit a Python file in another program such as "Notepad++" and then test the code by calling the PY.ExecFile action from VoxCommando.
Notepad++ is a good way to edit your Python code and offers many advantages such as code highlighting.

<br style="clear: both" />

=Reinitializing the Python Engine=
Sometimes you will need to clear out the various classes and methods that have been loaded into the Python engine. This can be done by:
* restarting VoxCommando, or,
* choosing "File >> Reinitialize Python" in the Python plugin window, or
* within a command macro, using the [[Plugin_PY#ReInit|PY.ReInit]] action.

==Killing Python Threads==

* It is important to note that if you've used threading in your Python, these Python threads will continue to run in the background until they terminate themselves (or VoxCommando is closed).

* Choosing "File >> Reinitialize Python" will set a variable named "'''killPy'''" to true. You can use this to end threaded loops by writing your threaded loops as follows:

<pre style="width:450px;">
while not killPy:
try:
...do your threaded loop stuff here
...do your threaded loop stuff here
except:
...handle errors etc.
</pre>

← Older revision	Revision as of 17:25, 13 January 2021
(No difference)

Python - Revision history

James: 1 revision

Jitterjames: /* Testing Code */