Retrieving the Sensor’s Data from Marlin/Unified Firmware

Before we begin…A brief explanation of what this is and why you may need it! #

A bed-leveling probe is designed to take measurements of the topology of a surface, and then adjust the Z height to match during printing. The data taken by the sensor is called a “mesh”, and contains relative measurements of the height based on a single starting measurement. When the data is arranged in a visual representation such as via an OctoPrint plugin, it can be used to quickly determine the topology of the bed in case adjustments need to be made.

There are several reasons you may wish to retrieve the data generated by a bed-leveling probe. For example:

  1. You may be adding solid bed mounts to your printer in place of the bed springs. Each bed-leveling probe will have tolerances for a slanted surface, so it is important to ensure the bed is as level as possible before locking it into place permanently.
  2. You may be troubleshooting a bed-leveling probe. Because each probe has a tolerance for reading a slanted surface, you may find that the first-layer height is not consistent across the bed. In this case, viewing the data can help you make adjustments to the bed return to level.
  3. You may be curious about the data points themselves, or need to make manual corrections to one (or many) points. (This is beyond the scope of this article, but it can be done.)
  4. You may already use Bed Visualizer in OctoPrint, and want to see the raw data instead of the visual representation.

Prerequisites #

You must have a functional bed-leveling probe for this to work. Some of these instructions will NOT apply to “manual mesh leveling”, such as the demonstrated use of the G29 command.

You must have a functional Z axis for this to work. If your Z axis is binding or causing issues, your sensor data will be inconsistent at best and completely wrong at worst. The Z axis is crucial to getting good sensor data, so ensure that it’s moving smoothly and consistently.

You must have a “terminal” application of some kind. In this case, you will need to send direct commands to the printer. There are many applications that have terminals built in, such as Simplify3D, Pronterface, OctoPrint, Repetier, etc. Any of these applications will do as long as they allow you to send direct commands to the printer. If you don’t have one, we recommend Pronterface.

For OctoPrint Users #

If you are running our EZPi OctoPrint setup, you will already have the Bed Visualizer plugin installed. If you are running another OctoPrint setup, you have a bed-leveling probe, and you don’t have Bed Visualizer installed yet, we highly recommend you do so!

The data used to generate the image in Bed Visualizer is the same data retrieved by the “G29 T” command below. In fact, the “G29 T” command is usually used to force Bed Visualizer to work in the first place.

How to Retrieve EZABL Sensor Data #

M503 method #

Marlin’s “M503” command is called “Report Settings”, and it does as its name suggests: It recalls a standard list of settings from the printer’s memory. These settings are separated by the command that is often used to change those settings.

By definition: “Print a concise report of all runtime-configurable settings (in SRAM) to the host console. This command reports the active settings which may or may not be the same as those stored in the EEPROM.”

In the case of mesh data, this will be in a section called “Auto Bed Leveling” and then “M420”. The data from the mesh gets saved into a memory slot that can be recalled using the M420 command. Each data point is labeled with the “G29” command, as shown below, as G29 is responsible for the actual data involved. M420 is only used to recall saved data.

The M503 command also contains useful information such as your current steps-per-mm for each motor (often used for E-steps calibration), current nozzle-to-probe offsets, acceleration settings, and more.

In the example data below, note that each point has an “I” and “J” value. These represent the X and Y coordinates on the grid respectively. In order below, point “I0 J0” is the first recorded point, which is the front-left corner of the bed. Point “I1 J0” is the middle-left edge of the bed, and point “I2 J0” is the back-left corner of the bed.

Recv: echo:; Auto Bed Leveling:
Recv: echo:  M420 S1
Recv: echo:  G29 W I0 J0 Z-0.11100
Recv: echo:  G29 W I1 J0 Z-0.10500
Recv: echo:  G29 W I2 J0 Z-0.08600
Recv: echo:  G29 W I0 J1 Z-0.12900
Recv: echo:  G29 W I1 J1 Z-0.07500
Recv: echo:  G29 W I2 J1 Z-0.03950
Recv: echo:  G29 W I0 J2 Z-0.15250
Recv: echo:  G29 W I1 J2 Z-0.09100
Recv: echo:  G29 W I2 J2 Z-0.05500

G29 T method #

For best results, run this with the bed pre-heated to normal printing temperature (50-60°C or higher)!

Marlin’s G29 command is used to tell the printer to probe the bed, modify the mesh data, set specific points or heights, and a lot more. G29 has lots of flags and variables that can be used and can look very intimidating to those unfamiliar with Gcode or machine operations. The entire use of the G29 is outside the scope of this document, we are only covering how to retrieve mesh data using this command.

When you send the command “G29 T” to the printer, it will run through the entire probing process and then output the data into a grid format such as this:

Sample “G29 T” data

This data is arranged in a grid to make it easier to visualize on a surface. The point at [0,0] on the grid represents the first data point recorded (usually the front-left corner of the bed), and the point at [4,4] is the right-rear of the bed. Each ROW represents the Y direction (front-to-back), and each COLUMN represents the X direction.

As shown in the image, every reading on Row Zero is the front row of probing points, and Row 4 would be the points on the back of the bed. Column Zero would be all of the left-side probing points, and Column 4 would be the right-side points.

How to interpret mesh data #

This section assumes that the sensor reads a ‘default’ 3×3 grid. If you set your firmware to use a bigger number of probing points, you will have more data than shown, but the concept will be identical.

Visualization #

Mesh data uses a set of coordinates to determine where each point should be on the bed. The first probed point is usually in the front-left corner of the bed, and should always have coordinates of [0,0]. The next point (on a 3×3 grid) will be the front center of the bed, marked by coordinates [0,1]. Coordinates are recorded in the format:[X position, Y position].

If we translate this to a visual representation for demonstration purposes, the coordinates will be laid out on the bed as shown:

The value for each point is a comparative measurement, relative to the measurement taken during auto-homing at the beginning of the probing process. In more simple terms, each measurement is relative to the center of the bed and shows how much higher or lower the bed is in that position. Positive values are higher than the reference measurement, and negative values are lower than the reference measurement.

Example data interpretation #

Let’s use the data we retrieved from the M503 command earlier. When translated into an image, these would be the current measurements of the bed using those readings:

This data indicates that the bed is actually remarkably level, all things considered. All of the values are relatively small, relatively close to each other in measurement, and there are no major outlying values that skew the results. All of these measurements are within 0.2mm of completely flat, which is better than expected in most cases. This would be considered an ideal scenario with a VERY flat bed surface and good Z-axis mechanics.

According to these values, it appears that the front side of the plate is lower than the back side, so this bed is tilted slightly towards the front. You can see the more-negative values on the front row, indicating these are slightly lower compared to the middle or back-row measurements.

How to use this data #

Because this data will demonstrate how far out-of-level a surface is, you can run this data and use it to make informed adjustments to the bed surface. After making an adjustment, you will want to probe the bed and retrieve the data again to ensure your changes are having an effect.

For new users, it can sometimes be easier to use ONLY the corner measurements to level the bed, since those are your adjustment positions by design. Once the corner measurements are as close to zero as possible, the rest of the measurements will indicate how warped your bed actually is.

Let’s take an example where all of the corners are perfectly level (values of zero). If any of the other points are different than zero, that may indicate the bed is warped near that point on the bed.

This data can be used when adding Solid Bed Mounts to a printer. Most solid mounts will not be perfectly even with each other, and the contour of your surface may not be perfectly flat. By using this data, you can determine which corners may still be out of level, and you can add “shims” or hardware-store washers to those corners to raise them in line with the other corners.

OctoPrint and Bed Visualizer #

If you are running OctoPrint, there is a plugin available called “Bed Visualizer”. This plugin runs the “G29 T” command and uses the data recovered to create an actual picture representation of the surface. This can be immensely helpful for those who have a hard time using the actual numeric values to make adjustments.

More information about Bed Visualizer can be found here.

Updated on August 2, 2022
Was this article helpful?