CANtrace Help
A powerful CAN bus analyser software and diagnostic tool
10.7 Scripting Tab
This tab can be used to extend the functionality of the base program by applying additional Python scripts. Scripts can be used to modify, filter, and create incoming and outgoing messages. Scripting is done on Python version 2.7.
Figure 10.16 Scripting Tab view
The Scripting tab consists of a text field used to write scripts and a Python status bar displaying script status and errors (“Python Code ACTIVE”).
10.7.1 Writing Scripts
Scripting in the CANtrace Scripting tab is done in Python programming language. As expected, the Scripting tab follows standard Python syntax and semantics with scripts.
Some notable things are that the scripting window doesn’t accept tabs for indentation; indentation of one step is made with four spaces. Also some data types (for example canmsg.Data, Table 10.11) can differ from standard Python data types.
10.7.2 Script deployment and errors
Successful deployment of a script displays a “Python Code ACTIVE” status on the status bar found on the bottom of CANtrace window. If deployment of a script is unsuccessful a relevant error message is displayed instead.
While running a script, if Python runs into an error, a descriptive error explanation will be displayed at the Python status bar. After running into an error, the functionality of the script is stopped. If the script contains multiple errors, the status bar will only display the first error found. Displayed error messages show the offending line number and error message type for easier script debugging.
10.7.3 Callback functions and Class CanMsg
|
Table 10.10 Python scripting callback functions. |
||
|
Name |
Definition |
Uses |
|
onbusFunc() |
This function is called by CANtrace when going on bus, after all CAN hardware is initialized. You can send CAN messages in this function, but don’t let it take too long as CANtrace won’t complete going on bus until this function is finished. |
– Open files – Initialize data – Send a CAN messages |
|
offbusFunc() |
This function is called before going off bus. You can still send CAN messages in this function. |
– Close files – Send a CAN messages – Write a report to disk |
|
recvFunc(canmsg) |
This function is called for every CAN message sent or received. It is called before the message is sent to the GUI components and logger in CANtrace. Parameter canmsg is class type of CanMsg (Table 10.11) that contains the CAN message information. Returning False in this function will discard the message, so it will not show up in the trace, data and other tabs and it will not be logged to disk if CANtrace has logging configured. Returning True will cause CANtrace to process the message normally. This function needs to execute very fast as it’s run for every CAN message received, which can be thousands per second. You can send CAN messages from this function. |
– Modify incoming messages – Blacklist unwanted messages – Whitelist wanted messages – Filter incoming messages – Send a CAN messages |
| Table 10.11 Class CanMsg members | ||
| Name | Definition | Type |
| Id | CAN message identifier | int |
| Channel | CAN channel where the message is received from | int |
| Data | Array of bytes with CAN data | Array[Byte] |
| TimeStamp | Message timestamp in seconds | float |
| Dlc | Length of CAN message | Int16 |
| IsTxAck | True for Tx, False for Rx | bool |
| IsExtendedId | True for extended CAN messages | bool |
| IsRtr | True for RTR messages | bool |
| IsErrorFrame | True for error frames | bool |
10.7.4 Language features
For processing scripts Python 2.7 is implemented using the IronPython library.
The following features are supported:
– Core language
– Built-in functions
– Built-in constants
– Built-in types
– Built-in exceptions
– Modules with full support: time, math, sys
– Also includes most IronPython modules, but with no official support. The list is provided in the 10.7.8 Python Modules section.
10.7.5 CANtrace API (ctapi)
API class for calling functions in CANtrace has been setup for scripting purposes. The API class ctapi currently supports following methods.
|
Table 10.12 ctapi methods |
||
| Method | Definition | Parameters explained |
| Send(channel, canmsg) | Sends a CAN message to desired channel | channel: Specifies to which channel CAN message is sent to (int)
canmsg: CAN message (CanMsg) |
10.7.6 Example Scripts
This chapter displays the default configuration for scripts. Detailed and descriptive example projects can be found at Public DocumentsCANtraceExamples.
| Table 10.13 Example projects | |
| Name | Definition |
| Python Blacklist.xml | Example of blocking signals with specific Id |
| Python Default Configuration.xml | Shows default configuration to start scripts from |
| Python FIR Filter.xml | Example of how an incoming message can be FIR filtered |
| Python Log To File.xml | Example showing how logging to file can be done in different formats. This example shows Peak format |
| Python Toggle Bit in Send Message.xml | Example showing on bit in sent CAN message can be dynamically changed. |
| Python Whitelist.xml | Example of only letting through signals with specific Id |
Default configuration:
# This function is run once after going on bus
def onbusFunc():
return
# This function is run once before going off bus
def offbusFunc():
return
# This function is run for every message received (and also tx-ack for sent messages)
def recvFunc(canmsg):
return True
10.7.7 Performance
The python code can process at least 4000 messages per second on a medium performance laptop.
10.7.8 Python Modules
| List of all available modules. | |||
|---|---|---|---|
| __builtin__ | commands | mailbox | SimpleXMLRPCServer |
| __future__ | compileall | mailcap | site |
| _abcoll | ConfigParser | markupbase | smtpd |
| _ast | contextlib | marshal | smtplib |
| _bisect | Cookie | math | sndhdr |
| _codecs | cookielib | md5 | socket |
| _collections | copy | mhlib | SocketServer |
| _csv | copy_reg | mimetools | sqlite3 |
| _ctypes | cPickle | mimetypes | sre_constants |
| _ctypes_test | cStringIO | MimeWriter | sre_parse |
| _functools | csv | mimify | ssl |
| _heapq | ctypes | mmap | stat |
| _io | datetime | modulefinder | statvfs |
| _locale | decimal | msvcrt | string |
| _LWPCookieJar | difflib | multifile | StringIO |
| _md5 | dircache | multiprocessing | stringold |
| _MozillaCookieJar | dis | mutex | stringprep |
| _osx_support | distutils | netrc | struct |
| _pyio | doctest | new | subprocess |
| _random | DocXMLRPCServer | nntplib | sunau |
| _sha | dumbdbm | nt | sunaudio |
| _sha256 | dummy_thread | ntpath | symbol |
| _sha512 | dummy_threading | nturl2path | sys |
| _socket | numbers | sysconfig | |
| _sre | encodings | opcode | tabnanny |
| _ssl | errno | operator | tarfile |
| _strptime | exceptions | optparse | telnetlib |
| _struct | filecmp | os | tempfile |
| _subprocess | fileinput | os2emxpath | textwrap |
| _threading_local | fnmatch | pdb | this |
| _warnings | formatter | pickle | thread |
| _weakref | fpformat | pickletools | threading |
| _weakrefset | fractions | pipes | time |
| _winreg | ftplib | pkgutil | timeit |
| abc | functools | platform | toaiff |
| aifc | future_builtins | plistlib | token |
| antigravity | gc | popen2 | tokenize |
| anydbm | genericpath | poplib | trace |
| argparse | getopt | posixfile | traceback |
| array | getpass | posixpath | types |
| ast | gettext | pprint | unicodedata |
| asynchat | glob | profile | unittest |
| asyncore | gzip | pstats | urllib |
| atexit | hashlib | py_compile | urllib2 |
| audiodev | heapq | pyclbr | urlparse |
| base64 | hmac | pydoc | user |
| BaseHTTPServer | htmlentitydefs | pydoc_data | UserDict |
| Bastion | htmllib | pyexpat | UserList |
| bdb | HTMLParser | Queue | UserString |
| binascii | httplib | quopri | uu |
| binhex | ihooks | random | uuid |
| bisect | imaplib | re | warnings |
| bz2 | imghdr | repr | wave |
| calendar | imp | rexec | weakref |
| cgi | importlib | rfc822 | webbrowser |
| CGIHTTPServer | imputil | robotparser | whichdb |
| cgitb | inspect | runpy | winsound |
| chunk | io | sched | wsgiref |
| clr | itertools | select | xdrlib |
| clrtype | json | sets | xml |
| cmath | keyword | sgmllib | xmllib |
| cmd | lib2to3 | sha | xmlrpclib |
| code | linecache | shelve | xxsubtype |
| codecs | locale | shlex | zipfile |
| codeop | logging | shutil | zipimport |
| collections | macpath | signal | zlib |
| colorsys | macurl2path | SimpleHTTPServer | |