Skip to content

Heater-Shaker G-Code Concepts

G-codes are machine-readable instructions used to control hardware. You do not need to understand or use G-codes to operate a Heater-Shaker with Flex or OT-2. This section is a technical resource for developers building custom applications that work with the Heater-Shaker.

G-Code command syntax

Heater-Shaker G-codes are strings starting with M followed by an integer. Arguments are formatted as letter-number combinations without separators. Each command must end with a new line character; Opentrons modules do not support multiple commands on a single line. For a complete list of codes and examples see Heater-Shaker G-codes.

  • Syntax: MCOMMAND [ARGUMENT-KEY][ARGUMENT-VALUE] TERMINATOR
  • Examples: M115 \n or M104 S25 \n

The following table explains these G-code command elements.

Element Description
MCOMMAND This is a G-code command itself. For example, sending a simple looking command like M115 \n to the Heater-Shaker returns its hardware version, firmware version, and serial number.
ARGUMENT-KEY ARGUMENT-VALUE An optional key-value pair used to pass parameters to a command.

Typically, the key is a single, uppercase letter followed by its value (usually an integer). For example, sending M104 S95 \n sets the Heater-Shaker temperature to 95 °C. In this command:
  • S is the key for temperature.
  • 95 is the value for °C.
TERMINATOR Every G-code sequence ends with a terminator, which is always a newline character (\n).

G-Code response syntax

Every Opentrons module returns a response after executing a command. A response will be one of the types defined below.

Response type Description
Acknowledgement An acknowledgement returns OK when the command is successful.

This response type does not echo the command code.
Response Some responses echo the command code and append OK to the response string when the command is successful. For example, successfully sending the command M106 (deactivate the heater) would return M106 OK.

Other responses do not echo the command code and only return an acknowledgement (OK) or an error code.
Error An error indicates a command failed and does not echo the command code.

Error responses are strings formatted as ERRNNN:error, where N is an integer followed by a plain text description. For example, sending too many commands to a module too quickly might result in the response ERR004:G-code cache full.

See the Heater-Shaker Error Codes section for a complete list.

Connection parameters

To establish a serial USB connection with a Heater-Shaker, your application must specify the baud rate and identify the module using its Vendor ID (VID) and Product ID (PID).

  • Baud rate: 115200
  • VID: 0x0483
  • PID: 0x4853

Making Good G-Code Connections

Identifying modules by their VID and PID helps you write resilient, cross-platform code. Hard coding for a specific port (e.g., COM3 for Windows or /dev/ttyUSB0 for macOS) makes code brittle. By using a library like pyserial to scan for specific VID/PID combinations, your application can dynamically find and connect to the correct Opentrons module regardless of its physical connection point.