Scripting

From OpenMBD
Jump to: navigation, search

HANtune offers the ability to run your own scripts by integrating a Jython interpreter. Jython is a Java implementation of a Python interpreter, which means that it runs inside the Java Virtual Machine (JVM). This makes it very easy to interface with HANtune and enables us to automate its functionality. Jython currently corresponds to CPython 2.7 and can run any pure Python module, but does not support the use of native libraries (CPython extension modules written in C). However, this has been made available in HANtune by integrating JyNI, but is currently still limited.

Scripts

Adding a script to a project

To add a script to your project right click the 'Scripts folder' in the 'Project Data' side panel and click 'Add Script'. Browse to the right directory, select your script and click 'Add Script'.

Adding a script


Starting a script

To start a script right click on it in the 'Project Data' side panel and click 'Start'

Starting a script


Alternatively, you can start a script by first dragging it from the 'Project Data' side panel to the layout and clicking the newly created button.

Script running

To indicate that a script is running, its icon in the 'Project Data' side panel will change its appears.

Script running


Stopping a script

To stop a script right click on it in the 'Project Data' side panel and click 'Stop'.

Stopping a script


Alternatively, if you have added a button to your layout you can stop a script by click it.

Script running

Startup scripts

If you want to expand the default behavior of HANtune or one of its projects, you can use startup scripts. Inside the HANtune directory you will find a file called Startup.py. This file is executed each time you start HANtune. For example, if you want to let the Jython interpreter know where to look for modules, you can put the following lines into Startup.py.

import sys
sys.path.append('C:\Users\User\Scripts')

Note: the path used is just an example and must be replaced by an actual location on your hard drive.


You can also set a script to be run at project startup. Right click on it in the 'Project Data' side panel and click 'Run on startup'.

Run script at project startup


To indicate that a script will be run at project startup, it will have a '>' in front of its name and move to the top of the list in the 'Project Data' sidepanel.

A script that has been set to run at project startup

Note: you can only have one project startup script active at a time

Console and Interactive Interpreter

HANtune integrates a console to which all scripts can print their output. In addition it serves as an interactive interpreter into which you can enter code directly. The >>> prompt indicates the interpreter is ready to receive commands.

HANtune Console

These can be simple expressions:

1+1

Or multi line statements:

for x in range(0,100):
	print x

Running a script from the console:

execfile('C:\PathToMyScript\MyScript.py')

Or if the path to the script is known by the interpreter, you can import it as a module:

import MyScript

Sometimes the interpreter requires more input, in which case the prompt will look as following ....

HANtune More Input Required

HANtune API

HANtune offers several API functions that can be used to automate its functionality. They can directly be used from either the console or in one of your scripts.

Function Arguments Description
connect() - Connect to the target based on the current communication settings.
disconnect() - Disconnect from the target
getSignal('name') String Get a reference to a signal from the current HANtune project
getParameter('name') String Get a reference to a parameter from the current HANtune project
connectToFTP('ip', 'port', 'username', 'password') String, int, String, String Connect to an FTP server
downloadFile('remotePath', 'localPath') String, String Download a file from the FTP server
uploadFile('localPath', 'remotePath') String, String Upload a file to the FTP server
createSignal('name') String Creates a new signal to be used in your HANtune project
createTrigger('signal', 'function') Signal, Function Creates a new trigger to be used in your HANtune project
logSignal('name', 'value') String, Any numerical value Creates a new entry in the log file for this signal

Signals and Parameters

Scripted Signals

Creating a new signal:

mySignal = createSignal('MySignal')

After creating the signal, it will be shown in the 'Scripted Elements' side panel. From which it can be used just like any other signal in your HANtune project.

Scripted Elements

Setting the attributes of a signal:

mySignal.minimum = 0
mySignal.maximm = 255

Tip: enter dir(mySignal) into the console for a full list of attributes.

Triggers

Sometimes you want to perform an action when a event occurs. For example, you might want to log a signal when it exceeds a certain value. You could do this by polling, checking the signal at a fixed interval and performing the action if needed. But this is not very efficient and it would be better if we could only check the signal when it changes value. Thats where triggers come in.

The following example creates a new signal called 'mySignal'. Then it defines a function that will print 'mySignal out of bounds' if the value of 'mySignal' is greater than '50'. Finally it creates the trigger by calling the 'createTrigger' function and passing in the signal and function as arguments.

mySignal = createSignal('MySignal')

def myTriggerFunction():
	if (mySignal.value > 50):
		print 'mySignal out of bounds'

createTrigger(mySignal, myTriggerFunction)

Tip: to run the example, first copy and paste the above code into HANtune's console and press enter. Then type mySignal.value = 51 and press enter again to see the trigger in action.


The following example shows how to react to value changes of another signal. The trigger function will be called whenever 'canSignal' changes value and will set the value of 'mySignal' accordingly.

mySignal = createSignal('MySignal')
canSignal = getSignal('CanSignal')

def myTriggerFunction():
	mySignal.value = canSignal.value * 2

createTrigger(canSignal, myTriggerFunction)

Note: currently HANtune only offers the ability to trigger on value changes of a signal or parameter.

Communication

FTP

Using the API functions it is very easy to utilize FTP in your script:

connectToFTP("169.254.165.122", 21, "user", "password")
downloadFile('../server_file.txt', 'C:\PathForNewFile\server_file.txt')
uploadFile('C:\PathToLocalFile\client_file.txt', '../client_file.txt')

SSH

Besides using the API functions you can also directly use any java class in your scripts. A big advantage of Jython is that it runs both Java and Python and any class or object can be treated as both. This is demonstrated in the following example using HANtune's SSHManager class:

#set up the SSHManager
ssh = SSHManager('root', 'root', 'localhost')

#connect to the sshd server
ssh.connect()

#send a file
ssh.sendFile('C:/users/Michiel/MyModel.elf', '/home/MyModel.elf')

#send a command to execute the file a separate process
ssh.sendCommand('nohup /home/MyModel.elf > /dev/null 2>&1 &')

Examples

HANtune comes with several example scripts which can all be found in the HANtune\scripts\examples folder (e.g. C:\Users\Michiel Klifman\Downloads\HANtune build 1280 (Logfile Reader)\scripts\examples).

MATLAB interface

Interface HANtune with MATLAB to display block or signal values from a running Simulink model in HANtune.

Sending and Receiving Raw CAN Messeages

Send and receive CAN messages in HANtune through scripts.

Periodically Update parameters

Periodically update your HANtune parameters through scripts.