.GCODE File Format – Line syntax

The file

• Plain ASCII text, one command per line. Lines end with LF; firmwares also accept CR LF.
• Extensions: .gcode, .gco and .g. Files for the BFB (RapMan) printers use .bfb.
• There is no header, signature or required first line. Slicers put their settings and statistics in comments; see Slicer comments.
• Lines are kept short: Marlin’s default limit is 96 characters per command (MAX_CMD_SIZE).

Fields

A line is a list of fields separated by spaces. Each field is one letter followed directly by a number, or a letter alone used as a flag (as in G28 X Y). The first command field gives the command; the others are its parameters.

Numbers are integers (T1, S200) or decimals with a full stop (X17.62), with an optional sign. A command number may carry a subcode after a full stop, as in G38.2, G29.1 or M862.3. In RepRapFirmware a parameter may hold several numbers separated by colons, one per extruder or axis (E0.5:0.5).

A few commands take the rest of the line as text: M23 and M32 (file names), M117 and M118 (messages), M28 and M30.

Upper and lower case

RS274/NGC makes letters case-insensitive outside comments, but printer firmwares vary. RepRapFirmware 1.19 and later is case-insensitive except inside quoted strings; earlier versions are not. Marlin reads upper case only unless built with GCODE_CASE_INSENSITIVE. Slicers write upper case.

Comments

Comments carry no meaning for the firmware, but slicers use them heavily for settings, layer markers and preview images, and hosts read those.

Line numbers and checksums

Line numbers and checksums protect lines sent over a serial link; files on SD cards normally leave them out. When used, a line starts with Nn and ends, before any comment, with * and the checksum. A line has both or neither; one without the other is an error.

• Line numbers must go up by one on each line; M110 Nn sets the next expected number.
• The checksum is the exclusive OR of every byte of the line from its start up to, but not including, the *, written as a decimal number (0 to 255).
• RepRapFirmware also accepts a CRC instead: * and five digits is read as a CRC-16 with polynomial 0x1021 (CCITT), while one to three digits is a checksum.

Worked example

So the line is sent as N3 T0*57.

Replies on a serial link

The printer answers each line. These replies are not stored in files, but explain why the numbers exist:

Quoted strings

Some firmwares accept string parameters in double quotes, so that names and passwords can hold spaces and semicolons.

• RepRapFirmware: a double quote inside the string is written twice (""). Because some senders turn everything into capitals, a single quote makes the next character lower case ('X is x), and two single quotes stand for one. Example: M587 S"MYROUTER" P"ABCxyz;"" 123".
• Marlin: only when built with GCODE_QUOTED_STRINGS; a backslash escapes the next character.

Expressions and meta commands

RepRapFirmware 3.1 and later accept an expression in braces in place of a number, using constants, operators, functions and values from the machine’s object model: G1 X{move.axes[0].max-5} F6000. From 3.01 it also has meta commands for conditions and loops (if, elif, else, while, break, continue, abort, var, set, echo), described in Duet3D’s documentation. Other firmwares do not read these. Klipper adds its own macro language on the host side.

Modal state

Many commands change a setting that stays in force for the lines after it. To read a file correctly, a program has to track this state from the top.

In absolute extrusion mode, an E smaller than the last one retracts; slicers reset the extruder position with G92 E0 often to keep the numbers small. Feed rate is in units per minute, so F3000 is 50 mm/s.

Worked example

G90                  ; absolute X Y Z
M83                  ; relative E
G28                  ; home all axes
G1 Z0.2 F720         ; lower to the first layer at 12 mm/s
G1 X60 Y20 E9 F1000  ; draw a 60 mm purge line, pushing 9 mm of filament
G1 E-0.8 F2100       ; retract 0.8 mm
G0 X100 Y100 F9000   ; travel without extruding