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

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.

Connect your instrument in PSTrace
Select a technique and set the parameters. For example LSV from -0.5 V to 0.5V.
Click “Show MethodSCRIPT” on the bottom
Edit a setting, for example lets double the scan rate from 0.1 V/s to 0.2 V/s.
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.

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:

Download and unzip the MethodSCRIPT UDL file.
In Notepad++, select Language, User defined language, Define your language, import.
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++

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

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:

Download TeraTerm
Setup the terminal to receive and transmit LF: line feed.
Enable local echo
Select the Consolas font, regular style, size 10
Connect your instrument
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.
Choose 230400 bit/s as speed for the EmStat Pico based potentiostats, and 921600 bit/s for the EmStat4 based potentiostats.
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:

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

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.

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