Guidelines for Creating Modules

The module is split into sections (the names are given in square brackets). The sections have subsections, this is where the nesting ends. Subsections are virtually control commands.

The module is based on triggers – the commands that respond to some messages (or their parts). No programming skills are needed to compose the modules. For more details see below.

Standard Sections

  • Main section [main]
  • Reading errors [readdtc]
  • Information [getinfo]
  • Erasing errors [erasedtc]
  • Flasher [readflash], [readeeprom], [writeeeprom]…

New sections are pending.

Custom Sections

As compared to standard sections, custom sections may have any arbitrary name. The mandatory parameter of this section is the button name. It is placed into the settings subsection:

[unlock]
[unlock/settings]
button="Unlock Computer"

Here an additional parameter is

ACTION – the button action, that can be one of the following:

Reading errors = 1
Erasing errors = 2
ECU Info = 3
READEEPROM = 4
READFLASH = 5
WRITEEEPROM = 6
CUSTOMACTION = 7 (by default), DEC

Section [main]

parameter name – module name (displayed in the module window).

Other Sections. Subsection [sectionname/settings]

The general parameters of the section are valid only within this section
CANID – identifier CAN, Hex
FIRSTBYTE – DEC, , the first byte of data in multi-line responses, by default is 4
TEXTTYPE – DEC, , the returned result is text or not text (used for string parameters, mainly in getinfo) as long as there are two types

  • 0 – binary, where the return value will be converted from HEX into a line
  • 1 – text (by default), no conversion, all printable characters are displayed

ERR – error decryption file, STR (it is possible to use the% LOCALE% macro to download files with error decryptions in the desired language, for example, ERR=errors_%LOCALE%.txt for Russiann it will be errors_ru_RU.txt
DTCSIZE — size of errors in block responses (2,4), DEC
script — script file name python (located in the config directory), STR
size — (for binary operations only) size of the final file in bytes, DEC
mpause — global pause in milliseconds needed for sending all messages in the section
skipbytes — the number of message bytes to “skip” when parsing long messages
filter — message filter CANID to filter messages, use the syntax as in the program, for example “* 7 ??, * 5 ??”,STR
usetriggers — the ability to import triggers from another section, STR
format:

, , for example usetriggers=readeeprom,1,27
– import is made from section readeeprom from 1 through 27 (inclusive). When importing, triggers are numbered as if they were just copied, i.e. if triggers 2-4 are imported, then trigger number 1 and later 5 must be present to ensure continuous indexing.

Subsection [sectionname/send]

Sending first messages (initialization)
messages — list of messages, STR
the messages have format CANID;DLC;DATA0 DATA1…, for example,

messages=000007F1;8;02 10 60 00 00 00 00 00

if you need to send several messages, they shall be separated by \n

timeout – delay time to wait for a reply to a message, in seconds, DEC (by default 2 seconds) virtually specifies the duration of the pause before proceeding to the next trigger.

Subsection [sectionname/triggerX]

where X – is a decimal number
The sequence must be continuous, because the parser, seeing a break in the numbering, will not go further. Each trigger describes how the program should react to a certain CAN message.

Commands

wait – — the message to which the trigger responds (the message format is the same as formessages) only part of the message with the specified length is compared
for example,

[getinfo/trigger1]
wait=000007F9;2;03 7F
if the first two bytes of the message are equal to 03 7F, the trigger will be executed
It may also contain * instead of any character (mask), for example wait=777;1;1* will respond to all messages starting with 1

messages – list of messages, for format see above. Messages to be sent when the trigger fires trigger
timeout – message reply delay time, in seconds, DEC (2 seconds by default)
pause – pause before sending the _first_ message in the trigger, DEC, milliseconds
mpause – pause before sending any message in the trigger, in milliseconds, DEC (if the pause parameter is used, then the pause for the 1st message will be the sum of the two, i.e. pause + mpause)

command – command, DEC
Currently the command is a composite number (binary addition)

  • 0 – no action (by default)
  • 1 – stop receiving / transmitting messages and exit
  • 2 – success
  • 4 – error
  • 8 – display the current message CAN

I.e. for example, if the reaction to the message should be “success and exit”, then write “3” (the sum of the signs)

progress – progress from 1 to 100, DEC
progress in the waiting window; recommended to be filled in for long operations
trigger progress data are added i.e. if you have four triggers with progress, you need to type in “25” for each

firstbyte – DEC, нbyte number from which to start displaying text in the trigger message
print – STR, a string to display when this trigger is called you can also use macros in the line:

  • %TRGMSG% – the first message from the trigger queue (converted, if any conversion functions were applied)
  • %TRGID%” – trigger ID from the list
  • %EVMSG% – the message to which the trigger responded (complete, no abbreviations)
  • %EVMSGLIT% – the same, but not in the form of a message; the text from the message starts with firstbyte (additional parameter in the trigger)

type – trigger type, DEC

  • 0 – simple (by default)
  • 1 – persistent — this trigger cannot be deleted
  • 2 – independent – this trigger does not require reaction to the message, it’s simply analogous to send but in the trigger queue
  • 3 – reading binary – reads binary data from the CAN stream; self-restoring like 2
  • 4 – writing binary – writes binary data from the CAN stream; self-restoring like 2

start – the beginning of the cycle; required to create cycles, HEX
finish – end of cycle, HEX
counter – the repeat number of this trigger, DEC. Starts simple duplication during counter cycles.

If start and finish, are specified, then the messages sent in the messages command may contain ?? this symbol will be replaced with the current iterator (HEX)
start1, finish1 – if ?? two (for the second)

callback – STR a python function from the script, whose name is specified in the settings.

Triggers are processed from top to bottom
As they are called, the triggers are destroyed, leaving only persistent triggers. To avoid infinite loops, a persistent trigger cannot be self-contained.

if command 1 (stop) is called, further processing will be stopped.

for sections readeeprom, writeeeprom
additional trigger parameters are used for writing / reading to / from a binary fileb
bstart — starting address, HEX
bfinish — ending address, HEX
These addresses are transmitted as messages via callback (a mandatory parameter in this case – for detailed description see above).
The binary file is written / read sequentially, i.e. it depends on the written commands how the final file will be generated when reading, or how
the commands for writing from the file to the ECU will be transferred.
cont — is a continuous-like trigger that has composite indexed CAN-frames
infostart — specified to mark a message, after which the unit should start returning information (before that all messages are ignored), DEC. This parameter is used to retrieve data about DTC and getinfo, so as not to confuse it with technical advance messages. By default, it’s set to 0, but if informational messages are to follow right after the current trigger, then type in infostart = 1; actually, this will tell the program how many messages to backtrack from the current one before reading informational messages.

CALLBACK

CALLBACK – a python script in which you declare functions of a certain kind

def HyS(strBytes, dwLen, strTemplate)

strBytes – an array of bytes from the message, as a string. To convert to bytes, convert using built-in functions:
pMsgBytes = bytearray.fromhex(strBytes)
dwLen – message length
pTemplate – message template from script (parameter messages), which you change, depending on your calculations, also in the form of a string

Return value — tuple: the length of the message to be sent (in theory, it should be equal to the length of the message from pTemplate), and a message with edited data, for example,

return (8,pTemplate.hex())

For command callback in a block like read/write binary

def GetB(dwAddr, dwLen, strMsg):
dwAddr – address from the script range from bstart to bfinish
dwLen – — the length of a message prepared for sending
strMsg – a changeable message template from the script (parameter messages), text format (see above)

Return value — tuple: the length in bytes that is supposed to be read or written, and the message.

Attention! If callback returns 0, then the trigger is immediately deleted / closed and the control is transferred to the next trigger.

Indexed [getinfo]

if you want to enter multiple values in [getinfo], for example the block number, VIN number, etc. then you need to create several sections for each of the values, e.g.: [getinfo], [getinfo1], [getinfo2]…
They will be sequentially executed upon the release of the Get Info button.

If, when debugging a module, it went into an infinite loop, press Ctrl+C — it will interrupt the execution of the module.