Communication protocol for Nexus

PSTrace version 5.6 or higher has a hidden feature that is useful when the communication protocol is used for development of software for the Nexus. PSTrace will open the Connection viewer window when you double-click on the "Not connected" label before connecting to the device.

Once connected, the connection viewer window will show all messages transmitted to the instrument (in red), and messages received from the instrument (in green). This can be helpful to understand the communication between the host and the instrument. Below is an example of the connection viewer window. Note that PSTrace is connected to an EmStat Pico in this example.

All commands and responses are terminated with a newline character. The used newline character is the Line Feed (LF) character ('\n', ASCII code 10 or 0x0A). The instrument never transmits a Carriage Return (CR) character ('\r', ASCII code 13 or 0x0D) and CR characters received by the instrument are ignored.

When a command is received by the instrument, it will echo the first character of the command and then respond with the command-specific data. After executing the command, a newline character is transmitted. If an error occurs during the execution of a command, the error is returned just before the newline character. See section Chapter 7, Error handling for more information about errors.

The device can be in two communication modes on which a subset of commands are available. These modes are listed below.

Get the device firmware version. This includes the device type, firmware version, build date and release type.

Unlike most other commands, this command has a response consisting of multiple lines. The last line is terminated with an asterisk and a newline character ('*\n'). The format is as follows:

Below are some examples to demonstrate the format of the output.

Sets the value of a register. Registers contain instrument specific configuration, settings and information that are accessible to the user. See Chapter 6, Register details for more information.

The following example demonstrates writing the value 0xABCDEF12 to register 0x99 (= 153 decimal).

Gets the value of a register. Registers contain instrument specific configuration, settings and information that are accessible to the user. See Chapter 6, Register details for more information.

The following example demonstrates how to get the device serial (register 0x06) from the instrument.

Load a MethodSCRIPT into RAM. The end of the script is indicated by an empty line (i.e., a line containing only the newline character \n). The MethodSCRIPT is parsed during reception. Some script errors that can be detected during parsing, such as syntax errors, are reported directly. If an error is encountered during parsing, the script memory is cleared, so a new script must be loaded. If the script was loaded successfully (no error was returned during loading), then the script can be executed by the r command (see Section 4.5, “Run loaded MethodSCRIPT (r)”).

This command consists of multiple lines. The first line contains only the l command. Then, the MethodSCRIPT is transmitted, line by line. After the last MethodSCRIPT line, an empty line must be transmitted to end the command.

The following example loads a MethodSCRIPT that prints "Hello World" 5 times when executed. It can then be executed with the run command, see Section 4.5, “Run loaded MethodSCRIPT (r)”,

Run (execute) loaded MethodSCRIPT from RAM.

The output of this command starts with r\n to denote the successful start of the script. This response is then followed by the output of the MethodSCRIPT, which depends on the actual script that is running. See the MethodSCRIPT documentation to see what type of responses can be expected. Note that a MethodSCRIPT does not have to transmit data, but most scripts do. When the MethodSCRIPT is finished (either successfully or with an error), an empty line is transmitted.

Summarized, the output format is:

The following demonstrates running the MethodSCRIPT loaded in the example from Section 4.5, “Run loaded MethodSCRIPT (r)”.

Load and run a MethodSCRIPT (same as l followed by r ).

The following demonstrates loading and running the same MethodSCRIPT as used in the example from Section 4.5, “Run loaded MethodSCRIPT (r)”.

Load a MethodSCRIPT stored on the filesystem into RAM. The end of the script is indicated by an empty line (i.e., a line containing only the newline character \n). Some script errors that can be detected during parsing, such as syntax errors, are reported directly. If an error is encountered during parsing, the script memory is cleared, so a new script must be loaded. If the script was loaded successfully (no error was returned during loading), then the script can be executed by the r command (see Section 4.5, “Run loaded MethodSCRIPT (r)”).

The following example loads a MethodSCRIPT from a file named scripts/my_script. If the script is loaded successfully, a subsequent r command would run it.

Load and run a MethodSCRIPT from the filesystem (same as l_fs followed by r ).

The following example loads and runs a MethodSCRIPT from a file named scripts/my_script.

For this example, we presume that scripts/my_script contains the following:

Get the serial number of the instrument.

The following example queries the device serial.

Get the device serial number from a multi-channel instrument.

Some instruments, such as the MultiEmStat4, consist of multiple devices internally, each with their own communication interface. In this case, each device will return a different serial number using the i command. However, the m command will return the same serial number on each connection, which is the serial number of the combined (multi-channel) instrument. The multi-channel serial number also contains the channel number (which is different for each instrument inside the multi-instrument) and the total number of channels. This allows the host software to determine if all channels are connected.

If the instrument is not in a multi-channel configuration, this will throw an error instead.

The following example queries the multi-channel serial.

Get the MethodSCRIPT version. This number indicates the internal storage representation of a MethodSCRIPT rather than the version of MethodSCRIPT specification. The MethodSCRIPT version number is used to determine if the MethodSCRIPT stored in NVM (using the Fmscr command) can be loaded or not. A list of Nexus firmware versions and the associated MethodSCRIPT versions is given below.

This example demonstrates reading the MethodSCRIPT version.

Resets the instrument into bootloader mode. The bootloader is mainly intended to perform firmware updates.

Get a list of all files in the specified directory.

The response will consist of one line of information for each file found. The information includes the file date and time, type (directory or normal file), size, and path. The response ends with an empty line.

The following example lists the content of the example/doc directory.

Read a file from the file system on the instrument.

The command fs_get <path>\n prints f\n, followed by the contents of the requested file. The end of the file is indicated by an ASCII file separator character (0x1C). The output ends with an empty line (i.e., a newline character) if the file was read and transmitted successfully, otherwise it ends with an error code. The file separator character is always transmitted, even in case of a file error.

This example requests the contents of the file example/hello_world.txt.

Write a file to the file system of the instrument. The file path must be unique. If a file with the same path already exists, an error is returned.

The command starts with fs_put <path>\n, where path is the path of the file to write. The following lines are the file contents, that are written to the file. The end of the file is indicated by an ASCII file separator character (0x1C).

The command returns a \n when it is accepted, as all commands do. It also returns an additional empty line (\n) when the command is finished.

Remove a file or directory (recursively) from the file system.

The following example removes the file /log.txt.

Get information about the file system (free/used/total space).

The file system information consists of free space, used space and total space.

* 1 kB = 1024 bytes

Format the file storage medium. This prepares the storage medium to be used as file system. It also removes all existing data.

Formatting a (large) storage device can take some time.

Once the storage device is formatted, it is generally not necessary to use this command again. To only remove all files, it is recommended to use the fs_clear command instead. The fs_clear command is usually much faster than the fs_format command.

Mount the file system.

Unmount the file system. This can be used to re-mount the filesystem, in combination with fs_mount.

Remove all files and folders from the storage medium.

Get the runtime capabilities. Return a list of supported commands for the instrument. Each bit represent one command, the mapping between bits and commands can be found in Appendix C, Communication capabilities bit fields.

Get the MethodSCRIPT capabilities. Return a list of MethodSCRIPT commands that are licensed and supported by the instrument, as hexadecimal value. Each bit represent one command, the mapping between bits and commands can be found in Appendix B, MethodSCRIPT capabilities bit fields

Halt execution of the running MethodSCRIPT.

This "pauses" the script. Execution can be resumed using the H command (see Section 4.25, “Resume script execution (H)”).

See the examples in Section 4.27.

Resume execution of the halted MethodSCRIPT.

See the examples in Section 4.27.

Abort execution of the current MethodSCRIPT. This has the same effect as the MethodSCRIPT command abort. It effectively stops the execution of the script as soon as possible. If an abort occurs during a (measurement) loop, all endloop commands are still executed. Consequently, the * and + characters that denote the end of a loop will still be transmitted. If the MethodSCRIPT contains an on_finished: tag, the commands after it will still be executed. MethodSCRIPT commands after the on_finished: tag cannot be aborted.

Unlike the MethodSCRIPT command abort, the command can also abort some long-running MethodSCRIPT commands, such as await_int and certain measurements.

See the examples in Section 4.27.

Abort the current measurement loop. This will break the execution of a MethodSCRIPT measurement loop command (i.e., a command starting with meas_loop_) after the current iteration. The current measurement iteration, i.e., all MethodSCRIPT commands between the start and the end of the measurement loop, will be executed, but no new iteration will be started. The script will then continue execution after the endloop command.

Below is an example MethodSCRIPT that performs a linear sweep from -1 V to +1 V, with steps of 250 mV and a scan rate of 100 mV/s. This results in 9 measurements, each 2.5 second apart, with a total runtime of approximately 22.5 seconds. In our example setup, a 100 kΩ resistor was connected to the working electrode, so the measured current is expected to be between -10 µA and +10 µA, and the current range is set accordingly.

When the program is executed completely, the output will be something like this:

The values in the data packages indicate that the measurement loop took approximately 22.5 seconds, and that the measured current after the measurement loop has the same value as during the last iteration of the loop.

However, if a Y command is send after the second iteration, the output will be something like this:

…​or, depending on the exact time the Y command is received, like this:

In this case, the values indicate that the measurement loop only took 5 seconds, and that the WE potential remained at the value it had at the end of the last iteration that was executed.

By halting the program after the second iteration, the output would be:

If the program would now be continued and then aborted after three more iterations, the output would be:

As can be seen in the above example, the metadata of the 3th iteration (the value 11) indicates that a timing error occurred. It can also be seen that the code directly following the measurement loop is not executed when the script is aborted using the Z command, in contrast to the Y command, which only aborts the measurement loop but continues executing the remainder of the MethodSCRIPT.

During a CV (but not fast CV) sweep, reverse the sweep direction. This has the same effect as the MethodSCRIPT command set_scan_dir 0. Depending on the exact location where the reversal occurs, this may end the current scan early and advance to the next, if present. This command has no effect if run outside of a CV sweep.

The plots below show the behaviour of the CV reverse command.

The following MethodSCRIPT examples demonstrate the same behaviour.

This script performs a 3 vertex CV measurement, from 0 V to -1 V to 1 V, with steps of 250 mV and a scan rate of 1 V/s. Here only the potentials are sent back, for simplicity.

This results in 17 points.

Issuing the reverse command causes the sweep to change direction early. Below it can be seen that the sweep only performs 3 steps in its initial direction instead of 4.

It can be seen that there is a delay between the R command being echo’d, and the data reversing. This occurs due to the sweep potentials being set in advance, and so it shouldn’t be expected that the R command will take immediate effect.

If the reversal would cause the sweep to change to a potential and direction that do not appear later in the current scan, then the sweep will advance to the next scan. If the CV is already in the final scan, it will end the CV instead. This can be seen in the below data.

The following table defines registers that are the same on all MethodSCRIPT instruments.

The table below lists all registers that are specific to the Nexus.

By default, most registers are write protected to prevent accidental writes. This register can be used to disable the write protection. It is advised to turn the write protection back on when access to write protected registers is no longer required.

Request the licenses programmed into this instrument. For more information contact PalmSens.

Reads the unique ID for this instrument.

Contains the device serial number.

Writing 0x93628ADE to this register will initiate a software reset of the device.

Instrument role in a multi-channel setup. When combining multiple instruments to create a multi-channel setup (as in, for example, the MultiEmStat4), it is sometimes necessary to synchronize all channels, so all measurements are performed at the same time. This can be achieved using the MethodSCRIPT command set_channel_sync. When using this feature, one instrument must be configured as master, and all others as slave. The multi-channel role determines how the instrument behaves when synchronization commands are used.

This role is assigned from the factory and depends on the physical layout.

Options are:

The system date and time in hex format. This is used for the time/date shown on files in the file system and for the MethodSCRIPT command rtc_get. Depending in the instrument, the time may or may not be kept on a restart.

Read and clear the system warning.

If a problem occurred that can not be displayed or handled at that moment, a system warning is set. This is indicated with the blinking LED and available in this register. Reading this register will return the first error code that caused a system warning. This is usually the most meaningful error code, since any subsequent errors might be a consequence of the first error. This register is cleared when read.

This returns the IP address of the instrument.

Mute all sounds from the device.