## Other features:
Note that the installer will look for Klipper install and config in standard locations. If you have customized locations or the installer fails to find Klipper you can use the `-k` and `-c` flags to override the klipper home directory and klipper config directory respectively. Also, the install assumes a single instance of Klipper running per device. If you have many you may need to install and configure the `ercf*.cfg` files by hand.
REMEMBER that `ercf_hardware.cfg`, `ercf_software.cfg` & `ercf_parameters.cfg` must all be referenced by your `printer.cfg` master config file. `client_macros.cfg` should also be referenced if you don't already have working PAUSE/RESUME/CANCEL_PRINT macros (but be sure to read the section before on macro expectations). These includes can be added automatically for you with the install script.
Pro tip: If you are concerned about running `install.sh -i` then run like this: `install.sh -i -c /tmp -k /tmp` This will build the `*.cfg` files for you but put then in /tmp. You can then read them, pull out the bits your want to augment existing install or simply see what the answers to the various questions will do...
Also be sure to read my [notes on Encoder problems](doc/ENCODER.md) - the better the encoder the better this software will work.
The configuration and setup of your ERCF using Happy Hare is 95% the same as documented in the [newer V2 Manual](https://github.com/EtteGit/EnragedRabbitProject/raw/no_toolhead_sensor/Documentation/ERCF_Manual.pdf). Be sure to read this README and the installed 'ercf_*.cfg' files to understand any difference. Read a [SUMMARY OF DIFFERENCES](doc/DIFFERENCES.md) here. ## Revision History
- v1.0.0 - Initial Beta Release
- v1.0.3 - Bug fixes from community: Better logging on toolchange (for manual recovery); Advanced config parameters for adjust tolerance used in 'apply_bowden_correction' move; Fixed a couple of silly (non serious) bugs
- v1.1.0 - New commands: ERCF_PRELOAD & ERCF_CHECK_GATES ; Automatic setting of clog detection distance in calibration routine ; New interactive install script to help EASY-BRD setup; Bug fixes
- v1.1.1 - Fixes for over zealous tolerance checks on bowden loading; Fix for unloading to far if apply_bowden_correction is active; new test command: ERCF_TEST_TRACKING; Fixed slicer based tool load issue
- v1.1.2 - Improved install.sh -i to include servo and calib bowden length; Better detection of malfunctioning toolhead sensor
- v1.1.3 - Added ERCF_RECOVER command to re-establish filament position after manual intervention and filament movement. Not necessary if you use ERCF commands to correct problem but useful to call prior to RESUME; Much improved install.sh to cover toolhead sensor and auto restart moonraker on first time install
- v1.1.4 - Change to automatic clog detection length based on community feedback
- v1.1.5 - Further install.sh improvements - no longer need filament_sensor defined or duplicate pin override if not using clog detection; Cleaned up documentation in template config file; Stallguard filament homing should now be possible (have to configure by hand); Additional configuration checks on startup; minor useability improvements based on community feedback
- v1.1.6 - New feature to log to file independently to console (allows for clean console and debug to logfile); New gate statistics (like slippage) are recorded and available with an augmented ERCF_DUMP_STATS command; Several minor improvements and fixes suggested by community
- v1.1.7 - Automatic setting of encoder state - no need to put anything ERCF related into existing macros (START/PAUSE/RESUME/STOP/CANCEL) anymore!; Improvements to install script for non EASY-BRD config; Exposed all built-in gear/extruder feed speeds; Tweaks to tolerance checks to prevent false pauses; No annoying pause/unlock sequence while you are playing out of a print. UPDATE TO CONFIG FILES RECOMMENDED
- v1.1.8 - Enhanced ERCF_CHECK_GATES command; better configuraton of tip forming; Workarounds to Timer Too Close errors on selector; Fined grained current reduction control; less conservative restting of filament state; servo remains up on failed load; fixes typos and spelling mistakes. Full details here: https://discord.com/channels/460117602945990666/909743915475816458/1058586768791838791
- v1.1.9 - Installer support for the Fytsec ERB Burrows board; Inclusion of display setup for 12864 mini displays; Bug fixes
- v1.2.0 - Major new feature for being able to persist all ERCF state between restarts - now you can just turn on an print!; Various bug fixes, error message and status display improvements. SOME ADDITIONS TO `ercf_parameters.cfg` CONFIG FILE
- v1.2.1 - MAJOR: Bundled servo driver with careful PWM synchronization to avoid servo kickback!!! (Requires re-running ./install.sh)
- v1.2.2 - Automatic clog length setting. No more [filament_runout_sensor] or [duplicate_pin] setup (Required re-running ./install.sh)
- v1.2.3 - Update to support KlipperScreen; Additional printer variables exposed; Cleanup of bypass commands; Bug fixes
- v1.2.4 - Improvement of clog detection during wipetower movements generated by slicer; Enhanced ERCF_ENDLESS_SPOOL command; Restore users "idle_timeout" when print ends; Updated ercf_software for stand-alone tip formation
- v1.2.5 - New `_ERCF_ACTION_CHANGED` callback for LED setting and the list; Selector calibration automatically saves measurements in ercf_vars.cfg; New flow rate % printer variable on ercf_encoder; install now favors printer_data over old klipper location; added couple of soaktests; explicit encoder on/off command; better tolerance of TMC stallguard problems; minor bug fixes
- Starting with filament unloaded and sitting in the gate for tool 1
- Firstly ERCF clamps the servo down and pulls a short length of filament through the encoder. It it doesn't see filament it will try 'load_encoder_retries' times (default 2). If still no filament it will report the error. The speed of this initial movement is controlled by 'short_moves_speed', the acceleration is as defined on the gear stepper motor config in 'ercf_hardware.cfg'
- ERCF will then load the filament through the bowden in a fast movement. The speed is controlled by 'long_moves_speed' and optionally `long_moves_speed_from_buffer`. This movement can be broken up into multiple movements with 'num_moves' as one workaround to overcome "Timer too close" errors from Klipper. If you keep your step size to 8 for the gear motor you are likely to be able to operate with a single fast movement. The length of this movement is set when you calibrate ERCF and stored in 'ercf_vars.cfg'. There is an advanced option to allow for correction of this move if slippage is detected controlled by 'apply_bowden_correction' and 'load_bowden_tolerance' (see comments in 'ercf_parameters.cfg' for more details)
- The example shown uses a toolhead sensor, but if you configure sensorless filament homing then ERCF will now creep towards your extruder gears to detect this point as its homing position. This homing move is controlled by 'extruder_homing_max' (maximum distance to advance in order to attempt to home the extruder), 'extruder_homing_step' (step size to use when homing to the extruder with collision detection), 'extruder_homing_current' (tunable to control how much % to temporarily reduce the gear stepper current to prevent grinding of filament)
- This is the move into the toolhead and is the most critical transition point. ERCF will advance the extruder looking to see that the filament was successfully picked up. In the case of a toolhead sensor this is deterministic because it will advance to the sensor and use this as a new homing point. For sensorless ERCF will look for encoder movement implying that filament has been picked up. Optionally this move can be made to run gear and extruder motors synchronously for greater reliability. 'sync_load_length' (mm of synchronized extruder loading at entry to extruder). As a further aid to reliability ERCF will use the "spring" in the filament by delaying the servo release by 'delay_servo_release' mm. When using synchronous load this will relax the compression in the filament leading to quieter loading, for extruder only load this will keep pressure on the gear to aid grabbing the filament.
With toolhead sensor enabled there is a little more to this step: ERCF will home the end of the filament to the toolhead sensor controlled by 'toolhead_homing_max' (maximum distance to advance in order to attempt to home to toolhead sensor) and 'toolhead_homing_step (step size to use when homing to the toolhead sensor. If 'sync_load_length' is greater than 0 this homing step will be synchronised.
The speed of all movements in this step is controlled by 'sync_load_speed' - Now the filament is under exclusive control of the extruder. Filament is moved the remaining distance to the meltzone. This distance is defined by 'home_position_to_nozzle' and is either the distance from the toolhead sensor to the nozzle or the distance from the extruder gears to the nozzle depending on your setup. This move speed is controlled by 'nozzle_load_speed'. We are now loaded and ready to print.
- Starting with filament loaded in tool 1. This example is taken from an unload that is not under control of the slicer, so the first thing that happens is that a tip is formed on the end of the filament which ends with filament in the cooling zone of the extruder. This operation is controlled but the user edited '_ERCF_FORM_TIP_STANDALONE' macro in 'ercf_software.cfg'
- This step only occurs with toolhead sensor. The filament is withdrawn until it no longer detected by toolhead sensor. This is done at the 'nozzle_unload_speed' and provides a more accurate determination of how much further to retract and a safety check that the filament is not stuck in the nozzle
- ERCF then moves the filament out of the extruder at 'nozzle_unload_speed'. This is approximate for sensorless but the distance moved can be optimized if using a toolhead sensor by the setting of 'extruder_to_nozzle' and 'sensor_to_nozzle' (the difference represents the distance moved)
- Once at where it believes is the gear entrance to the extruder an optional short synchronized (gear and extruder) move can be configured. This is controlled by 'sync_unload_speed' and 'sync_unload_length'. This is a great safely step and "hair pull" operation but also serves to ensure that the ERCF gear has a grip on the filament. If synchronized unload is not configured ERCF will still perform the bowden unload with an initial short move with gear motor only, again to ensure filament is gripped
- The filament is now extracted quickly through the bowden. The speed is controlled by 'long_moves_speed' and the movement can be broken up with 'num_moves' similar to when loading
- Completion of the the fast bowden move
- At this point ERCF performs a series of short moves looking for when the filament exits the encoder. The speed is controlled by 'short_moves_speed'
- When the filament is released from the encoder, the remainder of the distance to the park position is moved at 'short_moves_speed'. The filament is now unloaded
An option to home to the extruder using stallguard `homing_method=1` is available but not recommended: (i) it is not necessary with current reduction, (ii) it is not readily compatible with EASY-BRD and (iii) is currently incompatible with sensorless selector homing which hijacks the gear endstop configuration.
The 'apply_bowden_correction' setting, if enabled, will make the driver "believe" the encoder reading and make correction moves to bring the filament to the desired end of bowden position. This is useful is you suspect slippage on high speed loading, perhaps when yanking on spool (requires accurate encoder). If disabled, the gear stepper will be solely responsible for filament positioning in bowden (requires minimal friction in feeder tubes). The associated (advanced) 'load_bowden_tolerance' defines the point at which to apply to correction moves. See 'ercf_parameters.cfg' for more details. **Note about post homing distance** Regardless of loading settings above it is important to accurately set `home_to_nozzle` distance. If you are not homing to the toolhead sensor this will be from the extruder entrance to nozzle. If you are homing to toolhead sensor, this will be the (smaller) distance from sensor to nozzle. For example in my setup of Revo & Clockwork 2, the distance is 72mm or 62mm respectively. #### Possible unloading options: This is much simplier than loading. The toolhead sensor, if installed, will automatically be leveraged as a checkpoint when extracting from the extruder. `sync_unload_length` controls the mm of synchronized movement at start of bowden unloading. This can make unloading more reliable if the tip is caught in the gears and will act as what Ette refers to as a "hair pulling" step on unload. This is an optional step, set to 0 to disable. ### Synchronized Gear/Extruder motors The ERCF system now offers the optional feature of coordinating its gear motor with the extruder stepper during printing. This added functionality enhances the filament pulling torque, potentially alleviating friction-related problems. **It is crucial, however, to maintain precise rotational distances for both the primary extruder stepper and the gear stepper. A mismatch in filament transfer speeds between these components could lead to undue stress and filament grinding.** #### Setting up Print Synchronization Synchronizion during printing is controlled by 'sync_to_extruder' in `ercf_parameters.cfg`. If set to 1, after a toolchange, the ERCF servo will stay engaged and the gear motor will sync with he extruder for move extrusion and retraction moves #### Synchronization Workflow If the `sync_to_extruder` feature is activated, the gear stepper will automatically coordinate with the extruder stepper following a successful tool change. Any ERCF operation that necessitates exclusinve gear stepper movement (like buzzing the gear stepper to verify filament engagement), will automatically disengage the sync. Generally, you don't need to manually manage the coordination/discoordination of the gear stepper — Happy Hare handles the majority of these actions. However, if the printer enters ERCF_PAUSE state (due to a filament jam or runout, for example), synchronization is automatically disengaged and the servo lifted. Upon resuming a print synchronization will automatically be resumed however if you wist to enable it whilst operating the ERCF during a pause use the `ERCF_SYNC_GEAR_MOTOR` command. The `ERCF_SYNC_GEAR_MOTOR sync={0|1} servo={0|1}` command functions as follows: - Defaults to `sync=1` and `servo=1` - If `sync=1` and `servo=1`, it triggers the servo and executes the synchronization - If `sync=1` and `servo=0`, it performs only the synchronization - If `sync=0` and `servo=1`, it disengages and lifts the servo - If `sync=0` and `servo=0`, it only disengages the synchronization You can still control the gear stepper motor with the `MANUAL_STEPPER` command, however, this will only be effective if the stepper is not currently syncing with the extruder. #### Other synchonization options In addition to synchronizing the gear motor to the extruder during print the same mechanism can be used to synchronize during other parts of the loading and unload process. Whilst these might seem like duplicates of previous partial load/unload sync movements they operate slightly more simlified manner. If they are all disabled, Happy Hare will operate as it did previously. If these options are enabled they turn off the former functionality. E.g. If `sync_extruder_load` is enabled it will keep the gear synchronized with the extruder for the entire loading of the extruder.
Note that many run the gear stepper at maximum current to overcome friction. If you are one of those you might want to consider using `sync_gear_current` to reduce the current while it is synced during print to keep the temperature down. `sync_extruder_load` turns on synchronization of extruder loading `sync_extruder_unload` turns on synchronization of extruder unloading `sync_form_tip` turns on syncronization of the stand alone tip forming movement `sync_gear_current` the percentage reduction of gear stepper while it is synchronized with extruder ### Clog/runout detection ERCF can use its encoder to detect filament runout or clog conditions. This functionality is enabled with the `enable_clog_detection` in ercf_parameters.cfg. It works by monitoring how much filament the extruder is pushing and comparing it that measured by the encoder. If the extruder ever gets ahead by more that the calibrated `clog_detection_length` the runout/clog detection logic is triggered. If it is determined to be a clog, the printer will pause in the usual manner and require `ERCF_UNLOCK` & `RESUME` to continue. If a runout and endless spool is enabled the tool with be remaped and printing will automatically continue. Setting this value to `1` enables clog detection employing the static clog detection length. Setting it to `2` will enable automatic adjustment of the detection length. Whilst this doesn't guarantee you won't get a false trigger it will contiually tune until false triggers not longer occur. The automatic algorithm is controlled by two variables in the `[ercf_encoder]` section: desired_headroom: 5.0 # The runout headroom that ERCF will attempt to maintain (closest ERCF comes to triggering runout) average_samples: 4 # The "damping" effect of last measurement. Higher value means clog_length will be reduced more slowly ### Tool-to-Gate (TTG) mapping and EndlessSpool application When changing a tool with the `Tx` command the ERCF will by default select the filament at the gate (spool) of the same number. The mapping built into this *Happy Hare* driver allows you to modify that. There are 3 primary use cases for this feature:
- You have loaded your filaments differently than you sliced gcode file... No problem, just issue the appropriate remapping commands prior to printing
- Some of "tools" don't have filament and you want to mark them as empty to avoid selection.
- Most importantly, for EndlessSpool - when a filament runs out on one gate (spool) then next in the sequence is automatically mapped to the original tool. It will therefore continue to print on subsequent tool changes. You can also replace the spool and update the map to indicate availability mid print
Since EndlessSpool is not something that triggers very often you can use the following to simulate the action: > ERCF_ENCODER_RUNOUT FORCE_RUNOUT=1 This will emulate a filament runout and force ERCF to interpret it as a true runout and not a possible clog. ERCF will then run the following sequence:
- Move the toolhead up a little (defined by 'z_hop_distance & z_hop_speed') to avoid blobs
- Call '_ERCF_ENDLESS_SPOOL_PRE_UNLOAD' macro. Typically this where you would quickly move the toolhead to your parking area
- Perform the toolchange and map the new gate in the sequence
- Call '_ERCF_ENDLESS_SPOOL_POST_LOAD' macro. Typically this is where you would clean the nozzle and quickly move your toolhead back to the position where you picked it up in the PRE_UNLOAD macro
- Move the toolhead back down the final amount and resume the print
Any of the displayed config settings can be modified. E.g.
> ERCF_TEST_CONFIG home_position_to_nozzle=45
Will update the distance from homing position to nozzle. The change is designed for testing was will not be persistent. Once you find your tuned settings be sure to update `ercf_parameters.cfg`
### Updated Calibration Ref
Setting the `ercf_calib_ref` is slightly different in that it will, by default, average 3 runs and compensate for spring tension in filament held by servo. It might be worth limiting to a single pass until you have tuned the gear motor current. Here is an example:
### Useful pre-print functionality
The `ERCF_PRELOAD` is an aid to loading filament into the ERCF. The command works a bit like the Prusa MMU and spins gear with servo depressed until filament is fed in. Then parks the filament nicely. This is the recommended way to load filament into ERCF and ensures that filament is not under/over inserted blocking the gate.
Similarly the `ERCF_CHECK_GATES` command will run through all the gates (or those specified), checks that filament is loaded, correctly parks and updates the "gate status" map of empty gates. Could be a really useful pre-print check...
### Gate statistics
Per-gate statistics that aggregate servo/load/unload failures and slippage are recorded throughout a session and can be logged at each toolchange. An augmented `ERCF_DUMP_STATS` command will display these stats and will give a rating on the "quality assessment" of functionality of the gate (more info is sent to debug level typically found in the `ercf.log`). The per-gate statistics will record important data about possible problems with individual gates. Since the software will try to recover for many of these conditions you might not know you have a problem. One particularly useful feature is being able to spot gates that are prone to slippage. If slippage occurs on all gates equally, it is likely an encoder problem. If on one gate if might be incorrect calibration of that gate or friction in the filament path. Note that `ERCF_DUMP_STATS` will display this data but the details are sent to the DEBUG log level so you will only see it in the ercf.log file if you setup as I suggest.
### Logging
There are four configuration options that control logging:
log_level & logfile_level can be set to one of (0 = essential, 1 = info, 2 = debug, 3 = trace, 4 = developer)
Generally you can keep console logging to a minimal whilst still sending debug output to the ercf.log file
Increasing the console log level is only really useful during initial setup to save having to constantly open the log file
log_level: 1
logfile_level: 3 # Can also be set to -1 to disable log file completely
log_statistics: 1 # 1 to log statistics on every toolchange, 0 to disable (still recorded)
log_visual: 1 # 1 to log a fun visual representation of ERCF state showing filament position, 0 disable
The logfile will be placed in the same directory as other log files and is called `ercf.log`. It will rotate and keep the last 5 versions (just like klipper). The default log level for ercf.log is "3" but can be set by adding `logfile_level` in you `ercf_parameters.cfg`. With this available my suggestion is to reset the console logging level `log_level: 1` for an uncluttered experience knowing that you can always access `ercf.log` for debugging at a later time. Oh, and if you don't want the logfile, no problem, just set `logfile_level: -1`
### Pause / Resume / Cancel_Print macros:
It is no longer necessary to added anything to these macros -- ERCF will automatically wrap anything defined. If you have used other versions of the software then you should remove these customizations. To understand the philosophy and expectations here is the sequence:
During a print, if ERCF detects a problem, it will record the print position, safely lift the nozzle up to `z_hop_height` at `z_hop_speed` (to prevent a blob). It will then call the user's PAUSE macro (which can be the example one supplied in `ercf_software.cfg`). It is expected that pause will save it's starting position (GCODE_SAVE_STATE) and move the toolhead to a park area, often above a purge bucket, at fast speed.
The user then calls `ERCF_UNLOCK`, addresses the issue and calls `RESUME` to continue with the print.
The user's RESUME macro may do some purging or nozzle cleaning, but is expected to return the toolhead at higher speed to where it was left when the pause macro was called. At this point the ERCF wrapper takes over and is responsible for dropping the toolhead back down to the print and resumes printing.
ERCF will always return the toolhead to the correct position, but if you leave it in your park area will will move it back very slowly. You can to follow the above sequence to make this operation fast to prevent oozing from leaking on your print. ### Recovering ERCF state: At some point when a project occurs during a multi-color print ERCF will go into a `pause/locked` state. Generally the user would then call `ERCF_UNLOCK`, fix the issue and then resume print with `RESUME`. While fixing the problem you may find it useful to issue ERCF commands to move the filament around or change gate. If you do this the ERCF will "know" the correct state when resuming a print and everything will be copacetic. However, if you manually move the filament you are able to tell ERCF the correct state with the `ERCF_RECOVER` command. This command is also useful when first turning on an ERCF with filament already loaded. Instead of ERCF having to unload and reload to figure out the state you can simple tell it! Here are some examples: ERCF_RECOVER - attempt to automatically recover the filament state. The tool or gate selection will not be changed. ERCF_RECOVER TOOL=0 - tell ERCF that T0 is selected but automatically look at filament location ERCF_RECOVER TOOL=5 LOADED=1 - tell ERCF that T5 is loaded and ready to print ERCF_RECOVER TOOL=1 GATE=2 LOADED=0 - tell ERCF that T1 is being serviced by gate #2 and the filament is Unloaded ### State persistence This is considered advanced functionality but it is incredibly useful once you are familar with the basic operation of ERCF. Essentially the state of everything from the EndlessSpool groups to the filament position and gate selection can be persisted accross restarts (homing is not even necessary)! The implication of using this big time saver is that you must be aware that if you modify ERCF whilst it is off-line you will need to correct the appropriate state prior to printing. Here is an example startup state:
(note this was accomplished by setting `startup_status: 1` in ercf_parameters.cfg and can be generated anytime with the `ERCF_DISPLAY_TTG_MAP SUMMARY=1` command)
This graphic indicates how I left ERCF the day prior... Filaments are loaded in gates 0,1 & 6; Gate/Tool #1 is selected; and the filament is fully loaded. If you are astute you can see I have remapped T2 to be on gate #3 and T3 to be on gate #2 because previously I had loaded these spools backward and this saved me from regenerating g-code.
In addition to basic operational state the print statistics and gate health statistics are persisted and so occasionally you might want to explicitly reset them with `ERCF_RESET_STATS`. There are 5 levels of operation for this feature that you can set based on your personal preference/habbits. The level is controlled by a single variable `persistence_level` in `ercf_parameters.cfg`: Advanced: ERCF can auto-initialize based on previous persisted state. There are 5 levels with each level bringing in additional state information requiring progressively less inital setup. The higher level assume that you don't touch ERCF while it is offline and it can come back to life exactly where it left off. If you do touch it or get confused then issue an appropriate reset command (E.g. ERCF_RESET) to get state back to the defaults. Enabling `startup_status` is recommended if you use persisted state at level 2 and above Levels: 0 = start fresh every time (the former default behavior) 1 = restore persisted endless spool groups 2 = additionally restore persisted tool-to-gate mapping 3 = additionally restore persisted gate status (filament availability) 4 = additionally restore persisted tool, gate and filament position! Generally there is no downside of setting the level to 2 and so that is the suggested default. Really, so long as you are aware that persistence is happening and know how to adjust/reset you can set the level to 4 and enjoy immediate ERCF availability. So what options are there for resetting state? Here is the complete list:
- `ERCF_RESET` - Reset all persisted state back to defaults / unknown except for print stats and per-gate health stats
- `ERCF_RESET_STATS` - Reset print stats and per-gate health stats back to 0
- `ERCF_REMAP_TTG RESET=1` - Reset just the tool-to-gate mapping
- `ERCF_ENDLESS_SPOOL_GROUPS RESET=1` - Reset just the endless spool groups back to default
- `ERCF_SET_GATE_MAP RESET=1` - Reset information about the filament type, color and availability
- `ERCF_RECOVER` - Automatically discover or manually reset filament position, selected gate, selected tool, filament availability (lots of options)
- Needless to say, other operations can also be used to update state
- Closely relevant to the usefulness of this functionality is the `ERCF_CHECK_GATES` command that will examine all or selection of gates for presence of filament
- In the graphic depictions of filament state the '*' indicates presence, '?' unknown and ' ' or '.' the lack of filament
- With tool-to-gate mapping it is entirely possible to have multiple tools mapped to the same gate (for example to force a multi-color print to be monotone) and therefore some gates can be made inaccessable until map is reset
- The default value for `gate_status`, `tool_to_gate_map` and `endless_spool_groups` can be set in `ercf_parameters.cfg`. If not set the default will be, Tx maps to Gate#x, the status of each gate is unknown and each tool is in its own endless spool group (i.e. not part of a group)
Even if not a KlipperScreen user you might be interested in my brand new [KlipperScreen version](https://github.com/moggieuk/KlipperScreen-Happy-Hare-Edition). Be sure to follow the install directions carefully and read the [panel-by-panel](https://github.com/moggieuk/KlipperScreen-Happy-Hare-Edition/blob/master/docs/ERCF.md) documentation. It will make you even happier!!
## My Testing:
This software is largely rewritten as well as being extended and so, despite best efforts, has probably introduced some bugs that may not exist in the official driver. It also lacks extensive testing on different configurations that will stress the corner cases. I have been using successfully on Voron 2.4 / ERCF with EASY-BRD. I use a self-modified CW2 extruder with foolproof microswitch toolhead sensor. My day-to-day configuration is to load the filament to the extruder in a single movement (`num_moves=1`) at 200mm/s, then home to toolhead sensor with synchronous gear/extruder movement (option #1 explained above). I use the sensorless selector and have runout and EndlessSpool enabled.
### My Setup:
### Some setup notes based on my learnings:
Firstly the importance of a reliable and fairly accurate encoder should not be under estimated. If you cannot get very reliable results from `ERCF_CALIBRATE_ENCODER` then don't proceed with setup - address the encoder problem first. Because the encoder is the HEART of ERCF I [created a how-to](doc/ENCODER.md) on fixing many possible problems with encoder.
- If using a toolhead sensor, that must be reliable too. The hall effect based switch is very awkward to get right because of so many variables: strength of magnet, amount of iron in washer, even temperature, therefore I strongly recommend a simple microswitch based detection. They work first time, every time.
- The longer the bowden length the more important it is to calibrate correctly (do a couple of times to check for consistency). Small errors multiply with longer moves!
- Eliminate all points of friction in the filament path. There is lots written about this already but I found some unusual places where filament was rubbing on plastic and drilling out the path improved things a good deal.
- This version of the driver software both, compensates for, and exploits the spring that is inherently built when homing to the extruder. The `ERCF_CALIBRATE_SINGLE TOOL=0` (which calibrates the *ercf_calib_ref* length) averages the measurement of multiple passes, measures the spring rebound and considers the configuration options when recommending and setting the ercf_calib_ref length. If you change basic configuration options it is advisable to rerun this calibration step again.
- The dreaded "Timer too close" can occur but I believe I have worked around most of these cases. The problem is not always an overloaded mcu as often cited -- there are a couple of bugs in Klipper that will delay messages between mcu and host and thus provoke this problem. To minimize you hitting these, I recommend you use a step size of 8 for the gear motor. You don't need high fidelity and this greatly reduces the chance of this error. Also, increasing 'num_moves' also is a workaround. I'm not experiencing this and have a high speed (200 mm/s) single move load with a step size of 8.
- The servo problem where a servo with move to end position and then jump back can occur due to bug in Klipper just like the original software but also because of power supply problems. The workaround for the former is increase the same servo "dwell" config options in small increments until the servo works reliably. Note that this driver will retry the initial servo down movement if it detects slippage thus working around this issue to some extent.
- I also added a 'apply_bowden_correction' config option that dictates whether the driver "believes" the encoder or not for long moves. If enabled, the driver will make correction moves to get the encoder reading correct. If disabled the gear stepper movement will be applied without slippage detection. Details on when this is useful is documented in 'ercf_parameters'. If enabled, the options 'load_bowden_tolerance' and 'unload_bowden_tolerance' will set the threshold at which correction is applied.
- I can recommend the "sensorless selector" option -- it works well once tuned and provides for additional recovery abilities if filament gets stuck in encoder preventing selection of a different gate. However there are some important things to note:
- The selector cart must home against something solid. You need to make sure there are no wires or zip tie getting in the way.
- If the motor audibly vibrates but doesn't appear to reliably detect home you selector belt might be too loose.
- It is likely necessary to change the square head homing screw for a lower profile button head one -- the reason is that you will get inaccurate homing position if you are forceable stopping on the microswitch. You just want to make sure the microswitch is triggered when the selector cart comes to a stop.
- You can also add a small spacer to the slider mechanism make the selector cart physically stops before fully pressing the microswitch fully. Just be sure that the homing point is before gate #0. (I use a 1mm thick printed washer on the 8mm rods. See my repro for ERCF hacks).
- Finally it is important to experiement and tune the `driver_SGTHRS` value which is the point at which the TMC driver detects the stepper has stalled. Lower values are less sensitive (selector can ram too hard) and too high a value can mean a bit of friction on the selector is detected as a stall and interpreted as a blocked selector.
- Speeds.... starting in v1.1.7 the speed setting for all the various moves made by ERCF can be tuned. These are all configurable in the 'ercf_parameters.cfg' file or can be tested without restarting Klipper with the 'ERCF_TEST_CONFIG' command. If you want to optimise performance you might want to tuning these faster. If you do, watch for the gear stepper missing steps which will often be reported as slippage.
LOGFILE=\[1..4\] The level of logging to the ercf.log file (3 recommended)
VISUAL=\[0\|1\] Whether to also show visual representation
STATS=\[0\|1\] Whether to log print stats and gate summary on every tool change | | ERCF_STATUS | Report on ERCF state, capabilities and Tool-to-Gate map | SHOWCONFIG=\[0\|1\] Whether or not to describe the machine configuration in status message. Default 0 | | ERCF_DISPLAY_ENCODER_POS | Displays the current value of the ERCF encoder | None |
## Core ERCF functionality | Command | Description | Parameters | | ------- | ----------- | ---------- | | ERCF_PRELOAD | Helper for filament loading. Feed filament into gate, ERCF will catch it and correctly position at the specified gate | GATE=\[0..n\] The specific gate to preload. If omitted the currently selected gate can be loaded | | ERCF_UNLOCK | Unlock ERCF operations after a pause caused by error condition | None | | ERCF_HOME | Home the ERCF selector and optionally selects gate associated with the specified tool | TOOL=\[0..n\] After homing, select this gate as if ERCF_SELECT TOOL=xx was called
FORCE_UNLOAD=\[0\|1\] Optional. If specified will override default intelligent filament unload behavior prior to homing | | ERCF_SELECT_TOOL | DEPRECATED but included as alias to 'ERCF_SELECT TOOL=' to be compatible with current documentation | DEPRECATED | | ERCF_SELECT | Selects the gate associated with the specified tool (TTG map) or the specific gate regardless of TTG map | TOOL=\[0..n\] The tool to be selected
GATE=\[0..n\] The gate to be selected (ignores TTG map) | | ERCF_SELECT_BYPASS | Unload and select the bypass selector position if configured | None | | ERCF_LOAD | Loads filament in currently selected tool/gate to extruder. Optionally performs just the extruder load part of the sequence - designed for bypass unloading | EXTRUDER_ONLY=\[0\|1\] To force just the extruder loading (automatic if in bypass)
NOTE: Owing to current documented use for test loading (correctly use ERCF_TEST_LOAD instead) it is necessary to pass `TEST=0` to force the loading of current tool/gate. This will be updated in the future | | ERCF_CHANGE_TOOL | Perform a tool swap (generally called from 'Tx' macros) | TOOL=\[0..n\]
STANDALONE=\[0\|1\] Optional to force standalone logic (tip forming)
QUIET=\[0\|1\] Optional to always suppress swap statistics | | ERCF_EJECT | Eject filament and park it in the ERCF gate or does the extruder unloading part of the unload sequence if in bypass | EXTRUDER_ONLY=\[0\|1\] To force just the extruder unloading (automatic if in bypass) | | ERCF_PAUSE | Pause the current print and lock the ERCF operations | FORCE_IN_PRINT=\[0\|1\] This option forces the handling of pause as if it occurred in print and is useful for testing | | ERCF_RECOVER | Recover filament position and optionally reset ERCF state. Useful to call prior to RESUME if you intervene/manipulate filament by hand | TOOL=\[0..n\] \| -2 Optionally force set the currently selected tool (-2 = bypass). Use caution!
GATE=\[0..n\] Optionally force set the currently selected gate if TTG mapping is being leveraged otherwise it will get the gate associated with current tool. Use caution!
LOADED=\[0\|1\] Optionally specify if the filamanet is fully loaded or fully unloaded. Use caution! If not specified, ERCF will try to discover filament position | | ERCF_ENABLE | Enable ERCF and reset state after disable | None | | ERCF_DISABLE | Disable all ERCF functionality | None | | ERCF_ENCODER | Explicitly enable or disable the encoder. Note that the encoder state is set automatically so this will only be sticky until next tool change | ENABLE=\[0\|1\] | | ERCF_SYNC_GEAR_MOTOR | Explicitly override the synchronization of extruder and gear motors. Note that synchronization is set automatically so this will only be sticky until the next tool change | SYNC=\[0\|1\] Turn gear/extruder synchronization on/off (default 1)
SERVO=\[0\|1\] If 1 (the default) servo will engage if SYNC=1 or disengage if SYNC=0 otherwise servo position will not change |
## Servo and motor control | Command | Description | Parameters | | ------- | ----------- | ---------- | | ERCF_SERVO_DOWN | Engage the ERCF gear | None | | ERCF_SERVO_UP | Disengage the ERCF gear | None | | ERCF_MOTORS_OFF | Turn off both ERCF motors | None | | ERCF_BUZZ_GEAR_MOTOR | Buzz the ERCF gear motor and report on whether filament was detected | None |
## Tool to Gate map and Endless spool | Command | Description | Parameters | | ------- | ----------- | ---------- | | ERCF_ENCODER_RUNOUT | Filament runout handler that will also implement EndlessSpool if enabled | FORCE_RUNOUT=1 is useful for testing to validate your _ERCF_ENDLESS_SPOOL\*\* macros | | ERCF_DISPLAY_TTG_MAP | Displays the current Tool -> Gate mapping (can be used all the time but generally designed for EndlessSpool | SUMMARY=\[0\|1\] Whether to show complete or summary view | | ERCF_REMAP_TTG | Reconfiguration of the Tool - to - Gate (TTG) map. Can also set gates as empty! | RESET=\[0\|1\] If specified the Tool -> Gate mapping will be reset to that defined in `ercf_parameters.cfg`
TOOL=\[0..n\]
GATE=\[0..n\] Maps specified tool to this gate (multiple tools can point to same gate)
AVAILABLE=\[0\|1\] Marks gate as available or empty
QUIET=\[0\|1\] Optional. Supresses dump of current TTG map to log file
MAP={comma separated list of gates} Specify the entire TTG map for bulk updates | | ERCF_SET_GATE_MAP | Optionally configure the filament type, color and availabilty. Used in colored UI's and available via printer variables in your print_start macro | RESET=\[0\|1\] If specified the 'gate_materials, 'gate_colors' and 'gate_status' will be reset to that defined in `ercf_parameters.cfg` | DISPLAY=\[0\|1\] To simply display the current gate map
The following must be specified together to create a complete entry in the gate map:
GATE=\[0..n\] Gate numer
MATERIAL=.. The material type. Short, no spaces. e.g. "PLA+"
COLOR=.. The color of the filament. Can be a string representing one of the w3c color names found [here[(https://www.w3.org/TR/css-color-4/#named-colors) e.g. "violet" or a color string in the hexadeciaml format RRGGBB e.g. "ff0000" for red. NO space or # symbols. Empty string for no color
AVAILABLE=\[0\|1\] Optionally marks gate as empty or available
QUIET=\[0\|1\] Optional. Supresses dump of current gate map to log file | | ERCF_ENDLESS_SPOOL | Modify the defined EndlessSpool groups at runtime | RESET=\[0\|1\] If specified the EndlessSpool groups will be reset to that defined in `ercf_parameters.cfg`
GROUPS={comma separated list of groups} The same format as the default groups defined in ercf_parameters.cfg. Must be the same length as the number of ERCF gates | QUIET=\[0\|1\] Optional. Supresses dump of current TTG and endless spool map to log file
ENABLE=\[0\|1\] Optional. Force the enabling or disabling of endless spool at runtime (not persisted) | | ERCF_CHECK_GATES | Inspect the gate(s) and mark availability | GATE=\[0..n\] The specific gate to check
TOOL=\[0..n\] The specific too to check (same as gate if no TTG mapping in place)
TOOLS="comma separated list of tools" The list of tools to check. Typically used in print start macro to validate all necessary tools
If all parameters are omitted all gates will be checked (the default)
QUIET=\[0\|1\] Optional. Supresses dump of gate status at end of checking procedure |
## Calibration | Command | Description | Parameters | | ------- | ----------- | ---------- | | ERCF_CALIBRATE | Complete calibration of all ERCF tools | None | | ERCF_CALIBRATE_SINGLE | Calibration of a single ERCF tool | TOOL=\[0..n\]
REPEATS=\[1..10\] How many times to repeat the calibration for reference tool T0 (ercf_calib_ref)
VALIDATE=\[0\|1\] If True then calibration of tool 0 will simply verify the ratio i.e. another check of encoder accuracy (should result in a ratio of 1.0) | | ERCF_CALIBRATE_SELECTOR | Calibration of the selector for the defined tool | GATE=\[0..n\] or TOOL=\[0..n\] | | ERCF_CALIB_SELECTOR | DEPRECATED, but included as alias to 'ERCF_CALIBRATE_SELECTOR' because of use in current documentation | DEPRECATED | | ERCF_CALIBRATE_ENCODER | Calibration routine for ERCF encoder | DIST=.. Distance (mm) to measure over. Longer is better, defaults to 500mm
REPEATS=.. Number of times to average over
SPEED=.. Speed of gear motor move. Defaults to long move speed
ACCEL=.. Accel of gear motor move. Defaults to motor setting in ercf_hardware.cfg
MINSPEED=.. & MAXSPEED=.. If specified the speed is increased over each iteration between these speeds (only for experimentation) |
## User Testing | Command | Description | Parameters | | ------- | ----------- | ---------- | | ERCF_TEST_GRIP | Test the ERCF grip of the currently selected tool | None | | ERCF_TEST_SERVO | Test the servo angle | VALUE=.. Angle value sent to servo | | ERCF_TEST_MOVE_GEAR | Move the ERCF gear | LENGTH=..\[200\] Length of gear move in mm
SPEED=..\[50\] Stepper move speed
ACCEL=..\[200\] Gear stepper accel | | ERCF_TEST_LOAD | Test loading filament | LENGTH=..[100] Test load the specified length of filament into selected tool | | (ERCF_LOAD) | Identical to ERCF_TEST_LOAD | | | ERCF_TEST_UNLOAD | Move the ERCF gear | LENGTH=..[100] Length of filament to be unloaded
UNKNOWN=\[0\|1\] Whether the state of the extruder is known. Generally 0 for standalone use, 1 simulates call as if it was from slicer when tip has already been formed | | ERCF_TEST_HOME_TO_EXTRUDER | For calibrating extruder homing - TMC current setting, etc. | RETURN=\[0\|1\] Whether to return the filament to the approximate starting position after homing - good for repeated testing | | ERCF_TEST_TRACKING | Simple visual test to see how encoder tracks with gear motor | DIRECTION=\[-1\|1\] Direction to perform the test
STEP=\[0.5..20\] Size of individual steps
Defaults to load direction and 1mm step size | | ERCF_TEST_CONFIG | Dump / Change essential load/unload config options at runtime | Many. Best to run ERCF_TEST_CONFIG without options to report all parameters than can be specified | | ERCF_SOAKTEST_SELECTOR | QA reliability testing to put the selector movement under stress to test for failures | LOOP=..\[100\] Number of times to repeat the test
SERVO=\[0\|1\] Whether to include the servo down movement in the test | | ERCF_TEST_LOAD_SEQUENCE | Soak testing of load sequence. Great for testing reliability and repeatability| LOOP=..\[10\] Number of times to loop while testing
RANDOM=\[0\|1\] Whether to randomize tool selection
FULL=\[0 \|1 \] Whether to perform full load to nozzle or short load just past encoder |
## User defined/configurable macros (in ercf_software.cfg) | Command | Description | Parameters | | ------- | ----------- | ---------- | | _ERCF_ENDLESS_SPOOL_PRE_UNLOAD | Called prior to unloading the remains of the current filament | | _ERCF_ENDLESS_SPOOL_POST_LOAD | Called subsequent to loading filament in the new gate in the sequence | | _ERCF_FORM_TIP_STANDALONE | Called to create tip on filament when not in print (and under the control of the slicer). You tune this macro by modifying the defaults to the parameters | | _ERCF_ACTION_CHANGED | Callback that is called everytime the `printer.ercf.action` is updated. Great for contolling LED lights, etc |
*Working reference PAUSE / RESUME / CANCEL_PRINT macros are defined in client_macros.cfg* (\_/) ( *,*) (")_(") ERCF Ready