Writing with scripts

Scripts are a special application mechanism for sending and processing instructions sequentially. They can configure coding board settings, read and write transceiver memory, and perform other operations.

Use scripts when a transceiver requires a programming procedure that differs from the MSA standard and needs a sequence of special instructions to save memory changes successfully. Scripts can also automate repeated programming of different transceiver memory areas with minimal operator involvement.

How do I use a script?

Open the menu Control - Write using a script - Select a script file to specify the script file path;
Make sure the editor contains the correct code if the script uses editor data during execution;
Click the transceiver memory write button to run the script.

When running a script, the application ignores the currently selected memory area settings. The read and write areas must be specified in the script commands.

Please note that the software does not verify whether writing succeeded after a script finishes.

How do I clear the selected script?

Go to the menu Control - Write using a script - Reset script to clear the selected script and return to standard writing.

How do I create a script?

Script command syntax is based on the SFPTotal command protocol.

Example:

// Write password AABBCCDD to page A2 at offset 7B
w2A2007B03AABBCCDD
// Write the code from the editor to page A0 at offset 00
w2A000007F{00;7F}
// Write value 80 to page A2 at offset 7F
w2A2007F0080
// Write value 01 to page A2 at offset FF
w2A200FF0001
PAUSE
// Read code from page A0 at offset 00
R2A000007F

Create a text file and enter one instruction per line. Save the script file to use this programming procedure in the application.

Additional script commands

The following additional commands are processed by the application.

PAUSE

Pause script execution. The default pause is 100 ms.

An optional parameter sets the pause duration in milliseconds.

PAUSE
Delay 100ms
PAUSE=2000
Delay 2000ms

SETCHECKSUM

Recalculate the checksum.

SETVAL

Set the editor cell at offset XX to value YY. Specify parameter values in uppercase HEX format.

The offset parameter accepts values from 00 to 7F.

SETVAL 7F 03

{00;7F}

The substitution macro {XX;YY} is used inside other commands to insert a code segment from the editor. During script execution, the macro is automatically replaced with the current editor data starting at byte XX and spanning YY bytes.

Note that a YY parameter value of 00 in HEX means that 1 byte is substituted, while a value of 7F in HEX means that 128 bytes are substituted. Set YY to the segment length in bytes minus one, expressed in hexadecimal.

Example: writing a 128-byte segment to page A2h at offset 80h.

w2A200807F{00;7F}

Example: writing a 96-byte DDM threshold segment to page A2h at offset 00h, followed by a read.

W2A200005F{00;5F}

Example: assigning a variable the 16-byte code segment at offset 0x44 that contains the serial number.

$VAR2={44;0F}

$VAR1

Buffer variable $VAR1. Use buffer variables to store code segments from the editor and insert their contents during script execution.

The application supports 10 buffer variables, $VAR0–$VAR9.

$VAR1={00;43}
$VAR2={44;0F}
$VAR3={54;2B}
$VAR4=002AFE
$VAR5=4F

$YYYY

Insert the current year into the command.

$MM

Insert the current month into the command.

$DD

Insert the current day into the command.

BACKUPTOFILE

Start a backup for the module type selected in the application settings. The application reads the available pages sequentially and saves the data to a file. This command is equivalent to invoking the function from the application menu.

BACKUPDIR

Set the backup directory. Additional parameters can be used to create a directory with a particular name.

Example: creating a backup directory with the date in its name.

$VAR5=SOMETEXT
BACKUPDIR=\$YYYY-$MM-$DD_$VAR5\
BACKUPTOFILE

IMPORTFILE

Import HEX code from a binary file into the editor.

IMPORTFILE=\catalog\filename.bin

IMPORTHEX

Import HEX code into the editor.

Example: importing a 128-byte code segment into the editor.

IMPORTHEX=030407100000000000000006670000000802001E4F454D2020202020202020202020202000000B4053465031302D535220202020202020204120202003520091001A000058473936535230313020202020202020303830393236202068F0031200001111A8DD05AA642FAA6F5A64DAF3285A9D000000000000000000F05E482F

Import code into the editor by concatenating buffer variables.

$VAR1={00;43}
$VAR2={44;0F}
$VAR3={54;2B}
IMPORTHEX=$VAR1$VAR2$VAR3

INCREMENT

Increment the value of a variable containing a hexadecimal representation of code so that the number at the end of its text representation increases by one.

For example, the variable's text representation SN129YY00201 is converted to SN129YY00202.

If zeros precede the numeric portion, the application tries to preserve the original string length when the incremented number needs an additional digit, shifting the value to the left. Thus, the value SN129YY00999 is converted to SN129YY01000.

$VAR1={00;43}
// Assign the code area containing the serial number to a variable
$VAR2={44;0F}
$VAR3={54;2B}
INCREMENT $VAR2
IMPORTHEX=$VAR1$VAR2$VAR3

ERASEVENDORCODE

Fill the vendor-specific area in the editor with zeros.

COUNTER

Script iteration counter.

Place this command at the start of a script file that runs in a loop. The current iteration count is available through the $COUNTER variable.

// Invoke the iteration counter
COUNTER
// Assign the current counter value to a variable
$VAR0=$COUNTER
// Display the counter value
ECHO $COUNTER

IF A ... B THEN ...

Compare values. Use this construct to compare A and B and execute the command following THEN if the specified condition is true.

// Assign numeric values to variables
$VAR1=10
$VAR2=20
// Display a message box if the condition is true.
IF $VAR1 < $VAR2 THEN MSGBOX HELLO WORLD!

LOOP

Repeat the script. Place this command at the end of the script file to tell the application to run the procedure again. The UNLOOP command cancels LOOP. Use a condition to exit the loop and avoid endless repetition.

Example with a condition.

COUNTER
...
R1A000007F
...
// Repeat the script until 10 iterations have completed
IF $COUNTER < 10 THEN LOOP

If a script enters an infinite loop, stop it using the global interrupt command in <Tools - Interrupt processes>.

STRTOHEX

Convert the text following the operator to a HEX string.

$VAR9=STRTOHEX QSFP28-SR4 
MSGBOX $VAR9

HEXTOSTR

Convert the HEX string following the operator to text.

$VAR9=HEXTOSTR 5153465032382D535234202020202020
MSGBOX $VAR9

PADRIGHTHEX

Pad the hexadecimal value in $VAR1 on the right with the character whose code is YY until the length of its text representation reaches XX.

Command format:

PADRIGHTHEX XX YY $VAR1

XX a decimal number specifying the length of the HEX string's text representation;
YY the HEX code of the character used to pad the string to the required length;
$VAR1 the variable containing the HEX string to convert.

// Convert text to a HEX string and store it in a variable
$VAR9=STRTOHEX QSFP28-SR4 
// Pad the variable on the right with spaces (HEX code 0x20) to 16 bytes 
$VAR8=PADRIGHTHEX 16 20 $VAR9
ECHO $VAR8

This command is useful when assigning text to a variable and converting it to a HEX string of a specific length.

PADLEFTHEX

Works like PADRIGHTHEX. Pad the hexadecimal value in $VAR1 on the left with the character whose code is YY until the length of its text representation reaches XX.

SAVECODEDIR

Set the path for saving a code file automatically without a dialog box.

Example: setting the code output path to a directory named after the serial number in the code:

$VAR4=HEXTOSTR {44;0F}
SAVECODEDIR=C:\Users\DemoUser\Desktop\Codes\$VAR4

SAVEFILE

Save the code to a file at the path set by SAVECODEDIR. The application generates the file name automatically according to the selected module type and page.

$VAR4=HEXTOSTR {44;0F}
SAVECODEDIR=C:\Users\DemoUser\Desktop\Codes\$VAR4
SAVEFILE

SIGNATURE

Run the generator with preset parameters.

This feature requires an extended generator license in the application, which is not included in the standard package.

External API handler

APIURL

Set the URL used to call the external API handler.

APIURL=http://localhost/example/api.php

APICALL

Call the external API handler. This is equivalent to clicking the API button in the main application window.

POST request format for calls to APIURL

POST Fields: code=0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000&module_type=1&table=A0&offset=00

code code: a 256-character string (HEX, uppercase);
module_type module type (0 — GBIC, 1 — SFP, 2 — SFP-DD, 3 — XFP, 4 — QSFP, 5 — QSFP-DD, 6 — OSFP);
table table address (HEX, uppercase; for example: A0, A2);
offset table offset (HEX, uppercase; for example: 00, 80).

The server must return a JSON string:

{"status":1,"script":"R1A000007F\r\nW1A000007F{00;7F}\r\n","message":"","code":"0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","module_type":"1","table":"A0","offset":"00"}

The server response must contain the following parameters:

status processing status: 1 — import and execute the script; 0 — display a message without importing code;
script script text to execute after importing code; leave empty if no script is specified;
message returned message, displayed when status=0;
code returned code: a 256-character string (HEX, uppercase);
module_type module type (0 — GBIC, 1 — SFP, 2 — SFP-DD, 3 — XFP, 4 — QSFP, 5 — QSFP-DD, 6 — OSFP);
table table address (HEX, uppercase; for example: A0, A2);
offset table offset (HEX, uppercase; for example: 00, 80).

Arithmetic operations

The script processor supports addition, subtraction, multiplication and division through the MATH.

Command format:

MATH Value1 %Operator Value2

Supported arithmetic operators:

+ — addition;
- — subtraction;
* — multiplication;
/ — division;

COUNTER
$VAR0=MATH 10 - $COUNTER
ECHO $VAR0
// Repeat the script while the condition is true
IF $VAR0 > 0 THEN LOOP

User file

Commands for working with a user file.

USERFILEPATH

Set the user file path.

USERFILEPATH=C:\Users\User\Desktop\user-file.txt

GETUSERFILESTRING

Read the specified line from the user file.

GETUSERFILESTRING 10

SAVETOUSERFILE

Save data to the user file.

Example:

// Store the serial number in a variable
$VAR2={44;0F}
// Save the variable value to the user file
SAVETOUSERFILE HEXTOSTR $VAR2
// Add a line feed and carriage return
SAVETOUSERFILE HEXTOSTR 0D0A

$STRCOUNTUSERFILE

This value contains the number of lines in the user file.

// Find the inserted line's position by subtracting the script iteration count from the file's line count 
$VAR0=MATH $STRCOUNTUSERFILE - $COUNTER
ECHO $VAR0
// Read the most recently inserted line from the file
GETUSERFILESTRING $VAR0