Communication protocol for EmStat4

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 EmStat4. 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 8, 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:

Store a loaded MethodSCRIPT to non-volatile memory (NVM).

The following example demonstrates loading a script with l and storing it into the instrument’s non-volatile memory.

Load a MethodSCRIPT from non-volatile memory (NVM). After the script has been loaded successfully, it can be executed by the r command (see Section 4.5, “Run loaded MethodSCRIPT (r)”).

A MethodSCRIPT can only be loaded from NVM if it was written using the same MethodSCRIPT version as the current firmware supports.

This example shows how to load a script from non-volatile memory (NVM) and execute it with an r command. The loaded script here was loaded in the example from Section 4.10, “Load MethodSCRIPT from NVM (Lmscr)”

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 EmStat4 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.27, “Resume script execution (H)”).

See the examples in Section 4.29.

Resume execution of the halted MethodSCRIPT.

See the examples in Section 4.29.

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.29.

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.

Has the same behaviour as Section 4.17, “Write file (fs_put)”.

The data is accompanied by a cryptographic tag which proves it is authorised. To use this feature, a shared key must have been configured. See Section 6.25, “User Encryption Key (0x8A)” for further information on this key.

The command looks as follows:

sfs_put <cryptographic mac> <payload length> <filename>

The cryptographic MAC used is the CBC-MAC within AES-CCM, with nonce 0, and using the Section 6.25, “User Encryption Key (0x8A)” as the key. To retrieve the MAC, a user may perform CCM encryption and discard the ciphertext.

The plaintext input to the encryption is:

This is an example sfs_put transaction to write a file named my_file.txt.

The encrypted values assume a key of 0x00112233445566778899aabbccddeeff and unique instrument ID 0XAABBAABBAABBAABBAABBAABB.

Note that the final line, \x1C, represents the file separator character that ends a file write operation.

Has the same behaviour as Section 4.18, “Delete file or directory (fs_del)”.

The data is accompanied by a cryptographic tag which proves it is authorised. To use this feature, a shared key must have been configured. See Section 6.25, “User Encryption Key (0x8A)” for further information on this key.

The command looks as follows:

sfs_del <cryptographic mac> <filename>

The cryptographic MAC used is the CBC-MAC within AES-CCM, with nonce 0, and using the Section 6.25, “User Encryption Key (0x8A)” as the key. To retrieve the MAC, a user may perform CCM encryption and discard the ciphertext.

The plaintext input to the encryption is:

This is an example sfs_del transaction to delete a file named my_file.txt.

The encrypted values assume a key of 0x00112233445566778899aabbccddeeff and unique instrument ID 0XAABBAABBAABBAABBAABBAABB.

Has the same behaviour as Section 4.23, “Clear file system (fs_clear)”.

The data is accompanied by a cryptographic tag which proves it is authorised. To use this feature, a shared key must have been configured. See Section 6.25, “User Encryption Key (0x8A)” for further information on this key.

The command looks as follows:

sfs_clear <cryptographic mac>

The cryptographic MAC used is the CBC-MAC within AES-CCM, with nonce 0, and using the Section 6.25, “User Encryption Key (0x8A)” as the key. To retrieve the MAC, a user may perform CCM encryption and discard the ciphertext.

The plaintext input to the encryption is:

This is an example sfs_clear transaction.

The encrypted values assume a key of 0x00112233445566778899aabbccddeeff and unique instrument ID 0XAABBAABBAABBAABBAABBAABB.

Has the same behaviour as Section 4.20, “Format storage device (fs_format)”.

The data is accompanied by a cryptographic tag which proves it is authorised. To use this feature, a shared key must have been configured. See Section 6.25, “User Encryption Key (0x8A)” for further information on this key.

The command looks as follows:

sfs_format <cryptographic mac>

The cryptographic MAC used is the CBC-MAC within AES-CCM, with nonce 0, and using the Section 6.25, “User Encryption Key (0x8A)” as the key. To retrieve the MAC, a user may perform CCM encryption and discard the ciphertext.

The plaintext input to the encryption is:

This is an example sfs_format transaction.

The encrypted values assume a key of 0x00112233445566778899aabbccddeeff and unique instrument ID 0XAABBAABBAABBAABBAABBAABB.

Reconfigure the device to reject all comm commands that would modify the device.

The exception is the secure filesystem (sfs) commands, which are still permitted.

To use this feature, a shared key must have been configured. See Section 6.25, “User Encryption Key (0x8A)” for further information on this key.

The command looks as follows:

comm_lock <cryptographic mac>

The cryptographic MAC used is the CBC-MAC within AES-CCM, with nonce 0, and using the Section 6.25, “User Encryption Key (0x8A)” as the key. To retrieve the MAC, a user may perform CCM encryption and discard the ciphertext.

The plaintext input to the encryption is:

The encrypted values assume a key of 0x00112233445566778899aabbccddeeff and unique instrument ID 0XAABBAABBAABBAABBAABBAABB.

Reconfigure the device to accept all comm commands that would modify the device.

To use this feature, a shared key must have been configured. See Section 6.25, “User Encryption Key (0x8A)” for further information on this key.

The command looks as follows:

comm_unlock <cryptographic mac>

The cryptographic MAC used is the CBC-MAC within AES-CCM, with nonce 0, and using the Section 6.25, “User Encryption Key (0x8A)” as the key. To retrieve the MAC, a user may perform CCM encryption and discard the ciphertext.

The plaintext input to the encryption is:

The encrypted values assume a key of 0x00112233445566778899aabbccddeeff and unique instrument ID 0XAABBAABBAABBAABBAABBAABB.

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

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

Reads / writes the peripheral configuration as a bitmask from / to non-volatile memory. Support for external peripherals can be enabled here. Pins for peripherals that are not enabled can be used as GPIO pins. All peripherals default to GPIO. Multiple peripherals can be enabled at the same time by adding the hexadecimal values. For example: bit 1 is 0x01 and bit 5 is 0x20, combining them gives 0x21.

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.

If set to 1, the MethodSCRIPT stored in non-volatile memory will be loaded and executed on startup. When the script ends, the EmStat4 returns to its normal behavior.

The advanced options register is a bitmask of advanced options that can be enabled by the user.

Each option has a specific bit value (see table below). The value of this register is a bitwise OR of all option flags that are enabled. Writing to this register sets or clears all bits to the specified value. When writing to this register, make sure to set all required bits at once.

This register allows limiting the number of bytes per second that are sent by the device using UART. This is independent of the UART baud rate. This can be useful when no flow control mechanism is used with UART and the host cannot keep up with the data rate defined by the baud rate. A value of 0 disables data rate limiting, so the instrument will transmit at the maximum achievable speed.

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. When "hardware select" is selected, reading this register will return hardware select master (0x6D) or hardware select slave (0x73).

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.

Default GPIO settings at startup. Once set (and committed to NVM) the instrument will initialize it’s GPIO to this state on startup.

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.

Get allowed pin modes (input / output / peripheral) for all GPIO pins.

The allowed modes depend on the instrument’s capabilities, NVM configuration and enabled features. Some features may reserve specific GPIO pins, in that case they are not accessible via MethodSCRIPT and will read as 0.

Each nibble (4 bits) represents 1 GPIO pin, the least significant nibble is GPIO0. Each bit within this nibble represents a pinmode, where a high bit means the mode is allowed.
bit 0: input
bit 1: output
bit 2: peripheral 1
bit 3: peripheral 2

For OEM purposes the hardware synchronisation pins can be re-routed to the module’s GPIO pins. This register selects which GPIO is used for the start line. Setting this register to 0xFF will restore it to the system default.

The start line is set by the master on the start of a measurement loop to start the synchronisation process. When the measurement ends this line will be unset.

For OEM purposes the hardware synchronisation pins can be re-routed to the module’s GPIO pins. This register selects which GPIO is used for the iterate line. Setting this register to 0xFF will restore it to the system default.

The iterate line is toggled by the master on each iteration. The slave channels use this signal to time the next iteration of a measurement loop.

For OEM purposes the hardware synchronisation pins can be re-routed to the module’s GPIO pins. This register selects which GPIO is used for the role line. Setting this register to 0xFF will restore it to the system default.

The role signal can (optionally) be used by hardware to switch a channel between master or slave. This requires the multi channel role register to be set to hardware select. Otherwise the value in the multi channel role register is used regardless of the role pin. A channel’s role must be set before starting a measurement. Any change to this signal during a measurement will not be honored.

This register can be used for OEM purposes to redirect the red LED to a GPIO pin.

This register can be used for OEM purposes to redirect the green LED to a GPIO pin.

This register can be used for OEM purposes to redirect the blue LED to a GPIO pin.

Commit the current settings to non-volatile-memory to keep the settings across power cycles and resets. This requires a magic key to be provided

Reads the multi-channel serial number for MultiEmStat configurations.

Gain for the auxiliary DAC. This can be useful to compensate for external circuitry. The register value gets divided by 1000 internally to make the actual gain.

Get or set the instrument’s UART baud rate. This register expects an index, which is specified for each baud rate in the table below. The default baud rate can be found in Chapter 2, Communication. A restart is required for the new baud rate to be applied.

Set the user encryption key, or check if the key is set.

This key is applied to user-configurable encryption functions such as the secure filesystem commands.

If no key is currently set, reading this register will return zero and writing it will set the key.

If a key is currently set, reading this register will return one. Writing it with the same key will clear the key, and writing anything else is an error.

Write operations to this register always take 1 second to complete.

Get or set the instrument’s Autoshutdown duration, in seconds. On the EmStat4T, the device may be configured to shutdown when idle for long periods to conserve battery life. On other EmStat4 devices this value is ignored.

Get or set the instrument’s local timezone offset from UTC, in minutes.

This will be used when displaying the time onscreen for the EmStat4T.

For certain applications of the EmStat4, data validity is of critical importance. For such applications, all data communication from and to the instrument has to be verifiable. In order to make the communication verifiable, an extension of the protocol was implemented that adds a sequence number and a 16-bit CRC to each line. The CRC makes it possible to verify if received data is correct, i.e., if no part of the line was corrupted or lost during transmission. The sequence number allows the host to verify that no complete lines were missed.

The CRC16 protocol extension can be enabled in the instruments non-volatile configuration by setting the corresponding option bit (by issuing the command S0980000000 in normal mode). See the Set register command and the Advanced options register for more details on how to enable this extension.

Enabling the CRC16 protocol has the following effects:

The following section describes the protocol extension details.

The CRC extension adds an 8-bit sequence number and 16-bit CRC to each line before the newline separator (\n). This applies to all data transmitted to and from the device.

The sequence number allows the receiver to detect if there are missing lines. There are separate, independent, sequence numbers for data in both directions (from and to instrument). At startup, the EmStat4 initializes its sequence number to 0 and also expects the host to start with sequence number 0. After every transmitted line, the corresponding sequence number is incremented with one. After sequence number 255, it rolls over to number 0.

The CRC allows the receiver to verify the integrity of the received data. The CRC is calculated over the full line, excluding the newline character, but including the sequence number. The used CRC is the CRC-CCITT polynomial x¹⁶ + x¹² + x⁵ + 1, often represented as 0x1021. The initial value is 0xFFFF.

To give the host more certainty that the data is actually received by the EmStat4, the instrument will acknowledge every received line with an acknowledge message. The acknowledge message simply contains the sequence number of the received line, between angle brackets, e.g. <00>. The message itself also contains a sequence number and CRC like any other message transmitted by the instrument. The acknowledge messages are only transmitted by the instrument and should not be transmitted by the host.

The EmStat4 will respond mostly in the same way as it does without the CRC16 protocol extension. An exception is with MethodSCRIPT related commands (e and l). These will normally return with just a letter without newline and a send the newline when the entire script is received. Since this would interfere with the acknowledge messages it was decided that when the CRC16 protocol extension is enabled it will add an additional newline directly after the command response letter.

Below are some examples to demonstrate the differences between communication with and without the CRC16 protocol extension.

Note: \n is the newline character, initial sequence IDs are 0x0A for the host and 0x45 for the instrument.