MethodSCRIPT: Tips & Tricks

These Tips & Tricks will guide you to create your first MethodSCRIPT, debug the script, solve any errors and visualize the results. At the end, you will find example scripts. Alternatively, watch the MethodSCRIPT webinar recording to get introduced by our MethodSCRIPT expert.

MethodSCRIPT is the language our latest generation of potentiostats speaks. It allows you to communicate directly with the potentiostat (module) from any operating system or microcontroller. Supported devices include EmStat4S, EmStat4M, MultiEmStat4, EmStat Pico, Sensit Smart and the Sensit BT.

Get started with your first MethodSCRIPT Watch MethodSCRIPT webinar
1

Edit your first script in PSTrace

The software PSTrace controls all PalmSens instruments. Now lets connect an instrument that supports MethodSCRIPT to your computer, and start PSTrace.

  1. Connect your instrument in PSTrace
  2. Select a technique and set the parameters. For example LSV from -0.5 V to 0.5V.
  3. Click “Show MethodSCRIPT” on the bottom
  4. Edit a setting, for example lets double the scan rate from 0.1 V/s to 0.2 V/s.
  5. Copy the script to clipboard. 

The resulting code will look like this:

e
var c
var p
set_pgstat_chan 1
set_pgstat_mode 0
set_pgstat_chan 0
set_pgstat_mode 2
set_max_bandwidth 40
set_range_minmax da -500m 500m
set_range ba 590u
set_autoranging ba 59n 590u
set_e -500m
cell_on
meas_loop_lsv p c -500m 500m 10m 100m
pck_start
pck_add p
pck_add c
pck_end
endloop
on_finished:
cell_off

If you can’t see Show MethodSCRIPT button, please enable it by going to the tools –> general settings –> Show MethodSCRIPT editor as shown in the image below. 

2

Edit your code using Notepad++

You can use any text editor to change the MethodSCRIPT code. If you prefer Notepad++,  you can get correct syntax highlighting by using the MethodSCRIPT UDL file.

To get highlighting for MethodSCRIPT files ending with .mscr in Notepad++, please follow these steps:

  1. Download and unzip the MethodSCRIPT UDL file.
  2. In Notepad++, select Language, User defined language, Define your language, import.
  3. Select the MethodSCRIPT_UDL.xml file.

Every .mscr file you open, will automatically load with the correct syntax highlighting.

Download MethodSCRIPT UDL file for Notepad++

 

3

Learn the MethodSCRIPT commands

The script consists of a series of pre-defined commands. Each command starts with the command string, followed by a pre-defined number of arguments. Arguments are separated by a ‘ ‘ (space) character. Each command is terminated by a ‘\n’ (newline) character. The ‘\n’ is omitted in most examples. Each line is limited to a maximum of 128 characters. Comments can be added by having the first non-whitespace character on the line be ‘#’.

To send a script to the device, first send “e\n”. This sets the device into MethodSCRIPT mode. To terminate the script, add a line containing only a ‘\n’. The following examples send hello world. 

e
#This is a comment
send_string "hello world"


The response to this script will be:

e\n ← Ack of the execute script cmd ‘e’
Thello world\n ← Reply of the “send_string “hello world”” cmd
\n ← End of script

For all commands, please check the MethodSCRIPT documentation.

Download the MethodSCRIPT documentation
4

Debug your script with Tera Term

When debugging your script, you would like to get immediate feedback: on which line is there an error? The PalmSens instruments that support MethodSCRIPT, can communicate via a serial connection. Tera Term is an open-source and free terminal emulator program. It is often used for serial communication. Via this serial communication, you can send your MethodSCRIPT commands and see the response of the MethodSCRIPT interpreter.

To setup TeraTerm:

  1. Download TeraTerm
  2. Setup the terminal to receive and transmit LF: line feed.
  3. Enable local echo
  4. Select the Consolas font, regular style, size 10
  5. Connect your instrument
  6. As a serial port setup, select a COM port with FTDI in the device instance ID (in case of EmStat Pico) or one that shows EmStat4 (for the EmStat4 LR or HR) in the device friendly name.
  7. Choose 230400 bit/s as speed for the EmStat Pico based potentiostats, and 921600 bit/s for the EmStat4 based potentiostats.
  8. Save the setup

 

 

To enter scripts via Tera Term, please paste scripts from the clipboard by using your right mouse button. Manually typing your commands is only doable for short commands. Typing long commands or even scripts will trigger a timeout error 0009. This is an example of pasting the hello world script from the clipboard in TeraTerm. Note the two new lines after “hello world”, for which you can press the enter key twice:

5

Error handling

Errors can occur that prevent the execution of the MethodSCRIPT. These errors can occur either during the parsing of the script or during the execution of the script (runtime).

Error format

  • XXXX = The error code, see table below, where:
  • L = Line number, starting at 1
  • C = Line character number, starting at 1 (only visible during parsing)
#Error during parsing
!XXXX: Line L, Col C\n
#Error during runtime
!XXXX: Line L\n

Comment lines only count during parsing

The reported line number for runtime errors does not count comment lines. For parsing errors, the comment lines do count.

Solving the error

If you encounter an error, look up the description of the error in the table below. The description of the error combined with the line number, helps you to find the incorrect command. The MethodSCRIPT documentation will guide with examples of how to use each command.

Download the MethodSCRIPT documentation

Error description table

Code
(Hex)

Name

Description

0000

STATUS_OK

Everything worked as expected

0001

STATUS_ERR

An unspecified error has occurred

0002

STATUS_INVALID_VT

An invalid Value Type has been used

0003

STATUS_UNKNOWN_CMD

The command was not recognized

0004

STATUS_REG_UNKNOWN

Unknown Register

0005

STATUS_REG_READ_ONLY

Register is read-only

0006

STATUS_WRONG_COMM_MODE

Communication mode invalid

0007

STATUS_BAD_ARG

An argument has an unexpected value

0008

STATUS_CMD_BUFF_OVERFLOW

Command exceeds maximum length

0009

STATUS_CMD_TIMEOUT

The command has timed out

000A

STATUS_REF_ARG_OUT_OF_RANGE

A var has a wrong identifier

000B

STATUS_OUT_OF_VAR_MEM

Cannot reserve the memory needed for this var

000C

STATUS_NO_SCRIPT_LOADED

Cannot run a script without loading one first

000D

STATUS_INVALID_TIME

The given (or calculated) time value is invalid for this command

000E

STATUS_OVERFLOW

An overflow has occurred while averaging a measured value

000F

STATUS_INVALID_POTENTIAL

The given potential is not valid

0010

STATUS_INVALID_BITVAL

A variable has become either “NaN” or “inf”

0011

STATUS_INVALID_FREQUENCY

The input frequency is invalid

0012

STATUS_INVALID_AMPLITUDE

The input amplitude is invalid

0013

STATUS_NVM_ADDR_OUT_OF_RANGE

Non-volatile Memory address invalid

0014

STATUS_OCP_CELL_ON_NOT_ALLOWED

Cannot perform OCP measurement when cell on

0015

STATUS_INVALID_CRC

CRC invalid

0016

STATUS_FLASH_ERROR

An error has occurred while reading / writing flash

0017

STATUS_INVALID_FLASH_ADDR

The specified flash address is not valid for this device

0018

STATUS_SETTINGS_CORRUPT

The device settings have been corrupted

0019

STATUS_AUTH_ERR

Authentication error

001A

STATUS_CALIBRATION_INVALID

Calibration invalid

001B

STATUS_NOT_SUPPORTED

This command or part of this command is not supported by the current device

001C

STATUS_NEGATIVE_STEP

Step Potential cannot be negative for this technique

001D

STATUS_NEGATIVE_EPULSE

Pulse Potential cannot be negative for this technique

001E

STATUS_NEGATIVE_EAMP

Amplitude cannot be negative for this technique

001F

STATUS_TECH_NOT_LICENCED

Product is not licensed for this technique

0020

STATUS_MULTIPLE_HS

Cannot have more than one high speed and/or max range mode enabled (EmStat Pico)

0021

STATUS_UNKNOWN_PGS_MODE

The specified PGStat mode is not supported

0022

STATUS_CHANNEL_NOT_POLY_WE

Channel set to be used as Poly WE is not configured as Poly WE

0023

STATUS_INVALID_FOR_PGSTAT_MODE

Command is invalid for the selected PGStat mode

0024

STATUS_TOO_MANY_EXTRA_VARS

The maximum number of vars to measure has been exceeded

0025

STATUS_UNKNOWN_PAD_MODE

The specified PAD mode is unknown

0026

STATUS_FILE_ERR

An error has occurred during a file operation

0027

STATUS_FILE_EXISTS

Cannot open file,  a file with this name already exists

0028

STATUS_ZERO_DIV

Variable divided by zero

0029

STATUS_UNKNOWN_GPIO_CFG

GPIO pin mode is not known by the device

002A

STATUS_WRONG_GPIO_CFG

GPIO configuration is incompatible with the selected operation

002B

STATUS_COMM_CRC_ERR

CRC of received line was incorrect (CRC16-ext)

002C

STATUS_COMM_SEQUENCE_WARN

ID of received line was not the expected value (CRC16-ext)

002D

STATUS_COMM_LENGTH_ERR

Received line was too short to extract a header (CRC16-ext)

002E

STATUS_SETTINGS_NOT_INITED

Settings are not initialized

002F

STATUS_INVALID_CHAN

Channel is not available for this device

0030

STATUS_CAL_ERROR

Calibration process has failed

0031

STATUS_COMM_DISCONNECT

Comm interface disconnected during ongoing communication

0032

STATUS_CELL_OVERLOAD

Critical cell overload,  aborting measurement to prevent damage.

0033

STATUS_FLASH_ECC_ERR

FLASH ECC error has occurred

0034

STATUS_FLASH_PROGRAM_FAIL

Flash program operation failed

0035

STATUS_FLASH_ERASE_FAIL

Flash Erase operation failed

0036

STATUS_FLASH_LOCKED

Flash page/block is locked

0037

STATUS_FLASH_WRITE_PROTECTED

Flash write operation on protected memory

0038

STATUS_FLASH_BUSY

Flash is busy executing last command.

0039

STATUS_FLASH_BAD_BLOCK

Operation failed because block was marked as bad

003A

STATUS_FLASH_INVALID_ADDR

The specified address is not valid

003B

STATUS_FS_MOUNT_ERR

An error has occurred while attempting to mount the filesystem

003C

STATUS_FS_FORMAT_ERR

An error has occurred while attempting to format the filesystem memory

003D

STATUS_SPI_TIMEOUT

A timeout has occurred during SPI communication

003E

STATUS_TIMEOUT

A timeout has occurred somewhere

003F

STATUS_CALIBRATIONS_LOCKED

The calibrations registers are locked,  write actions not allowed.

0040

STATUS_FLASH_NOT_SUPPORTED

Memory module not supported.

0041

STATUS_FS_INVALID_FORMAT

Flash memory format not recognized or supported.

0042

STATUS_REGISTER_ACCESS_DENIED

This register is locked for current permission level.

0043

STATUS_REG_WRITE_ONLY

Register is write-only

4000

STATUS_SCRIPT_SYNTAX_ERR

The script contains a syntax error

4001

STATUS_SCRIPT_UNKNOWN_CMD

The script command is unknown

4002

STATUS_SCRIPT_BAD_ARG

An argument was invalid for this command

4003

STATUS_SCRIPT_ARG_OUT_OF_RANGE

An argument was out of range

4004

STATUS_SCRIPT_UNEXPECTED_CHAR

An unexpected character was encountered

4005

STATUS_SCRIPT_OUT_OF_CMD_MEM

The script is too large for the internal script memory

4006

STATUS_SCRIPT_UNKNOWN_VAR_TYPE

The variable type specified is unknown

4007

STATUS_SCRIPT_VAR_UNDEFINED

The variable has not been declared

4008

STATUS_SCRIPT_INVALID_OPT_ARG

This optional argument is not valid for this command

4009

STATUS_SCRIPT_INVALID_VERSION

The stored script is generated for an older firmware version and cannot be run

400A

STATUS_SCRIPT_INVALID_DATATYPE

The parameter data type (float/int) is not valid for this command

400B

STATUS_SCRIPT_NESTED_MEAS_LOOP

Measurement loops cannot be placed inside other measurement loops

400C

STATUS_SCRIPT_UNEXPECTED_CMD

Command not supported in current situation

400D

STATUS_SCRIPT_MAX_SCOPE_DEPTH

Scope depth too large

400E

STATUS_SCRIPT_INVALID_SCOPE

The command had an invalid effect on scope depth

400F

STATUS_SCRIPT_INDEX_OUT_OF_RANGE

Array index out of bounds

4010

STATUS_SCRIPT_I2C_NOT_CONFIGURED

I2C interface was not initialized with i2c_config command

4011

STATUS_SCRIPT_I2C_UNHANDLED_NACK

This is an error,  NAck flag not handled by script

4012

STATUS_SCRIPT_I2C_ERR

Something unexpected went wrong. Could be a bug in the firmware

4013

STATUS_SCRIPT_I2C_INVALID_CLOCK

I2C clock frequency not supported by hardware

4014

STATUS_SCRIPT_HEX_OR_BIN_FLT

Non integer SI vars cannot be parsed from hex or binary representation

4015

STATUS_INVALID_WAKEUP_SOURCE

The selected (combination of) wake-up source is invalid

4016

STATUS_WAKEUP_TIME_NOT_VALID

RTC was selected as wake-up source and selected time is not supported

4017

STATUS_SCRIPT_ARRAYSIZE_MISMATCH

Array size does not match expected size

4018

STATUS_SCRIPT_UNEXPECED_END

The script has ended unexpectedly.

4019

STATUS_SCRIPT_DEVICE_NOT_MULTI

The script command is only valid for a multichannel (combined) device

4020

STATUS_SCRIPT_TIMEOUT

A timeout has occurred for one of the script commands

7FFF

STATUS_FATAL_ERROR

A fatal error has occurred

FFFF

STATUS_ASSERT_FAIL

Used for DEBUG – an assertion failed

8000

STATUS_DEVICE_SPECIFIC

Device specific error occurred

8001

STATUS_DS_SELFTEST_CRYSTAL

Switching to 16 MHz crystal failed

6

Visualize the results in PSTrace

PSTrace can visualize currents and voltages. Each package of data PSTrace receives, can consist of time, voltage and a current. If you have verified in TeraTerm that your script is free of errors and sends back data packages, it is time to copy the MethodSCRIPT into the PSTrace editor.

7

SWV Example script

This script will perform an SWV measurement from -0.5 V to 0.5 V.

e
var c
var p
var f
var g
set_pgstat_chan 0
set_pgstat_mode 2
# Set maximum required bandwidth based on frequency * 4,
# however since SWV measures 2 datapoints, we have to multiply the
# bandwidth by 2 as well
set_max_bandwidth 80
# Set potential window.
# The max expected potential for SWV is EEnd + EAmp * 2 – EStep.
# This measurement would also work without this command since it
# stays within the default potential window of -1.1 V to 1.1V
set_pot_range -500m 690m
# Set current range for a maximum expected current of 2 uA
set_cr 2u
# Disable autoranging
set_autoranging 2u 2u
# Turn cell on for measurement
cell_on
# Perform SWV
meas_loop_swv p c f g -500m 500m 10m 100m 10
   # Send package with set potential, 
   # ”forward current – reverse current”,
   # ”forward current”
   # ”reverse current”
   pck_start
   pck_add p
   pck_add c
   pck_add f
   pck_add g
   pck_end
endloop
# Turn off cell when done or aborted
on_finished:
cell_off

View more examples on GitHub