Magnetic Encoder

Operation

Startup Indicators

On startup, the encoder module will use the on-board RGB LEDs to signal status information. This information can be useful if you are having trouble with an encoder module, and need to diagnose the problem.

The LED will pulse several times in different colours, and information on decoding these pulses is below.

Flash	Description	Meaning
First	Communication with encoder IC	Red	Failure
		Green	Working
Second	Saved Settings Found?	Magenta	Not found, reinitialising to defaults
		Green	Settings found, restored
Third	Module I2C Address	Blue	30 (X)
		Yellow	31 (Y)

As an example, a sequence of flashes coloured green, green and blue, would indicate that the encoder IC is working (good), saved settings have been found (so module has been used and possibly configured before) and is configured with an I2C address of 30 (which is used to represent an X axis encoder).

If the module detects an unrecoverable fault (for instance, if communication with the encoder IC can not be established) then it will stop on that flash and continuously blink.

I2C Commands

The encoder module responds to several different I2C commands. The following table details the different commands available.

Command	Description	Details
0 / Any Undefined	Transmit Report	The module will respond with the travelled distance, transmitted as four bytes that represent a signed long. Magnetic strip strength can be sent instead (see command 3).
1	Reset Accumulated Distance	Resets the encoders internal travel distance counter, 'homing' it. This may not be necessary if homing / zero-offset is handled in firmware (as is the case with the Marlin implementation).
2	Set I2C Address	The modules I2C address will be set to the next byte received. This change will take effect on the next power-cycle.
3	Select Report Information	The following byte will set the modules report mode. '0' (default) and the probe will always report the travelled distance count. '1' will cause it to report magnetic signal strength rating instead.
4	Reset to Defaults	The module will 'factory-reset' to default values, undoing any configuration over I2C. Hardware address configuration (cutting traces) will remain however.
10	Set LED Mode	Sets the mode of the LED based on the next two bytes received. B1 = LED (0 or 1), B2 = mode (see LED reference).
11	Set LED Brightness	Sets the brightness of the LED based on the next two bytes received. B1 = LED (0 or 1), B2 = brightness (0-255).
12	Set LED RGB	Sets the RGB value of the LED based on the next three bytes received. LED must be in RGB mode to display value.
13	Set LED HSV	Sets the HSV value of the LED based on the next three bytes received. LED must be in HSV mode to display value.
14	Set LED Rate	Sets the rate variable of the LED based on the next two bytes received. B1 = LED (0 or 1), B2 = rate (0-255).

Setting Module Address / Axis

All encoder modules communicate with the printer control board over an I2C bus. Each module needs a unique address on the bus so that the control board can communicate with it. Therefore, if you are using more than one module, you will need to configure the modules with different addresses.

There are two ways in which the address can be changed.

Cutting Traces

The encoder module has two jumper traces on board, labelled 'Y' and 'Z'. Cutting these traces will change the modules address. The table below indicates the addresses that can be selected. Note that '0' indicates a trace is unchanged, and '1' indicates the trace has been cut.

'Z'	'Y'	Address (see address reference table)
0	0	'X' address (default)
0	1	'Y' address
1	0	'Z' address
1	1	'E' address

Configure over I2C

Only four separate modules can be used on one printer through cutting the jumper traces. If you're running more than four modules, you'll need to configure their addresses over I2C.

You will need to have the module communicating with the control board - if it is using the default address, you can disconnect other modules to avoid any conflict.

See the I2C commands section for the command to set the I2C address. After the address has been set, the module must be restarted for the new address to take effect - disconnect the module, then reconnect it. The status LED should indicate a custom address during the startup procedure - see the startup indicators section.

Address Table

The address can be any value from 0 to 255. However, some default values for axes are established to make it easier to work with the modules.

Address	Named Default?	Notes
0-29	N/A
30	X Axis	Default Address
31	Y Axis
32	Z Axis
33	E Axis
33-255	N/A

Using with Marlin

As the encoder modules communicate over I2C, they can be used with any control board and firmware that supports I2C (basically all of them). However, firmware support is needed to actually do anything with that information - a basic closed-loop control system has been implemented in a fork of Marlin, here.

Configuration / Setup

Download the firmware from the repository, and configure it as you otherwise would for your printer. You will find there are several new options in the configuration relating to the encoder modules - these are detailed below:

Running

Upload the firmware to your printer. Once done, connect over USB using your favourite host program (the below examples will use Printrun).

On startup, the printer will attempt communication with each module enabled in the printer's firmware. It will report the status of each module, noting two things: firstly, if the module is successfully detected and can be communicated with, and secondly, if the module is correctly aligned with a magnetic strip. This can be seen in the image below.