Skip to content

Vendor bundles and updating process

rtyr edited this page Aug 9, 2021 · 34 revisions
Clone this wiki locally

Vendor bundles are a collection of system presets in a single file, optionally with inheritance. Each vendor has its own bundle, e.g. PrusaResearch.ini stores all profiles for Prusa printers.

How to create a vendor bundle?

Creating a profile for a vendor not currently present in PrusaSlicer

  1. Create a profile for at least one printer from a specific vendor (3rd party, not Original Prusa) in PrusaSlicer
  2. Create at least one Print and one Filament profile for that printer
  3. Download and open the example Creality.ini vendor bundle
  4. Read through this article to get a basic understanding of how vendor bundles work
  5. Go through the Creality.ini file to get a better understanding of how vendor bundles work in practice
  6. Save the Creality.ini file under a different name (E.g. YourVendorName.ini)
  7. Edit the vendor info - fill in the correct vendor name and other required information
    • Ideally also create a bed model and bed texture for each printer
  8. Open PrusaSlicer and the edited INI file side-by-side
  9. Create a profile structure as clean as possible (e.g. use inheritance, which is explained in this article)
  10. Save the INI file and copy it to AppData/PrusaSlicer/vendor directory
  11. Re-launch PrusaSlicer and verify that the config bundle is loaded correctly (thank you!)
  12. Create a New Issue in our PrusaSlicer-settings project on GitHub, describe your config bundle and upload the INI file
    • If you know how to create a Pull request, that's also an even option

If you launch PrusaSlicer with --datadir="F:\mybundle" you can select a custom bundle profile directory. You can then create/import your custom profile and use the File - Export - Export config function. If you add vendor info to the beginning of this exported file (config bundle header), you'll have essentially created a Vendor bundle. But this file will have very poor structure and will be very hard to read and maintain. If it helps you during the creation of your vendor bundle, feel free to do so. But please try to clean the file and create a basic inheritance structure before you send it to us.

Creating a profile for a vendor already present in PrusaSlicer (e.g. Lulzbot, Bibo, Creality)

Use the steps above, but rather than starting from scratch or with the Creality.ini file (unless it is a Creality printer), download the latest vendor bundle for your vendor from the PrusaSlicer-settings repository. If you know how, submit a pull-request of your modified vendor bundle. Alternatively, you can create a New Issue and upload the modified file there. We'll appreciate it if you describe the changes made.

Header fields

This is an example header section:

[vendor]
name = Prusa Research      # Name for GUI display purposes (Configuration Wizard)
config_version = 0.1.1     # This bundle version, used for updating
config_update_url = https://files.prusa3d.com/location     # Location of updates (optional), see below ...
changelog_url = https://files.prusa3d.com/location/changelog

# Section for each model starts with `printer_model:` followed by the printer model ID
[printer_model:MK3]
name = Original Prusa i3 MK3   # Name for GUI display purposes
variants = 0.4; 0.25; 0.6      # Variant names separated by `;`
technology = FFF               # Either FFF or SLA
family = MK3                   # Optional, printers from the same family will be shown together in the Configuration Wizard
bed_model = mk3_bed.stl # An STL mode3l of the printer bed shape
bed_texture = mk3.svg # An SVG showing the texture of the bed, use for company logos displayed on the build plate
default_materials = Prusament PLA; Prusament PETG

The versioning system used by PrusaSlicer is based on Semantic Versioning, the config_version field expects a version string formated as Major.minor.patch, optionally there may also be a pre-release string (such as "-alpha") appended.

Individual preset fields for printer, filament, and print profiles

After the header section, individual preset sections follow. Each preset section's name starts with either:

  • printer: for printer profiles
  • filament: for filament profiles, or
  • print: for print profiles.

The colon is followed by the preset name. This name has to be globally unique (across all .ini files). For example, the "Prusament PLA" profile defined for the Creality Ender-3 printer is named "Prusament PLA @ENDER3", although only "Prusament PLA" is shown in the Filament installation wizard and at the Plater, more about name aliases later.

If the name is enclosed with asterisks (eg. [filament:*PLA*]) then the preset is marked internal and is not available in the PrusaSlicer. This is used for inheritance where common parent profiles of various end-usage profiles are hidden.

Examples

[printer:*common*]  # Common printer presets for Inheritance 
[filament:*common*] # Common filament presets for Inheritance 
[print:*common*]    # Common print presets for Inheritance

For some additional guidance on creating printer and print profiles in the GUI see this article by Bob George a frequent contributor to the Prusa support forums.

Example printer profile

[printer:Original Prusa i3 MK2S 0.25 nozzle]
inherits = *common*
max_layer_height = 0.15
min_layer_height = 0.05
nozzle_diameter = 0.25
retract_length = 1
retract_speed = 50
variable_layer_height = 1
printer_variant = 0.25
retract_lift = 0.15
default_print_profile = 0.10mm DETAIL 0.25 nozzle

Printer variants and specialized configurations for printer profiles

Printer variants and specialized configurations of a printer model should not have separate printer models. Printer profiles are used to handle all printer variants and specialized configurations of a printer model. For examples of Printer variants of nozzle size, please see the PrusaResearch configurations. For examples of specialized Printer configurations for a printer model, please see the BIBO configurations illustrating setting a dual extruder up for single extrusion with left or right nozzles and for Ditto printing capable multi-extruders how to set up specialized ditto printing printer profiles. Additional examples of custom printer configurations like the Prusa MK2 with Multi-material, please see the PrusaResearch configurations

Example print profile

# MK3 #
[print:0.10mm DETAIL @MK3]      # Only "0.10mm DETAIL" will be visible to the user
inherits = *0.10mm*; *MK3*      # This profile inherits from two other profiles
# alias = 0.10mm DETAIL         # An alternative way to change the name of the profile visible to the user
bridge_speed = 30
compatible_printers_condition = printer_notes=~/.*PRINTER_VENDOR_PRUSA3D.*/ and printer_notes=~/.*PRINTER_MODEL_MK3.*/ and nozzle_diameter[0]==0.4 and ! single_extruder_multi_material
external_perimeter_speed = 25
infill_acceleration = 1250
fill_pattern = gyroid
fill_density = 15%

Example filament profile

[filament:Prusament PLA]
inherits = *PLA*
filament_vendor = Prusa Polymers
temperature = 215
filament_cost = 24.99
filament_density = 1.24

Inheritance

Different profiles often share a lot of settings and only differ in a few specific settings. To make the Vendor bundle easier to maintain and read, you can take advantage of inheriting values from a previously defined profile. You can only inherit from profiles within the same config file. For example, you cannot inherit from Creality.ini inside PrusaResearch.ini. Inheritance is achieved with the inherits field, for example:

[filament:Prusament PLA]
inherits = *PLA*

In this case, we first defined a common PLA profile that sets up most of the values. A Prusament profile will inherit all of the values of the common profile and then we can change only a few values specific to the brand. Changes to the common PLA profile will get propagated to all profiles that inherit its settings.

Multiple Inheritance is achieved either through a chain of inheritance profiles inheriting from each parent profile as in common > PLA > Generic PLA (i.e. Generic PLA inherits from PLA which inherits from common) or through adding multiple items in the inherit field separated by a semicolon ; as in inherits = *0.05mm*; *MK3* (i.e. the print profile inherits from the 0.05mm print profile then from the MK3 print profile) where last wins.

Associating presets with a specific printer

PrusaSlicer binds the Printer and Filament profile to the Printer profile using the compatible_printers_condition configuration value. With the introduction of the 3rd party printers, we are also suppressing Printer and Filament profiles from other vendors, therefore each vendor has to define a full set of Printer and Filament profiles in his config vendor bundle. Presets may be associated with a specific printer model or a variant with the printer_model and printer_variant fields.

Examples:

compatible_printers_condition = printer_notes=~/.*PRINTER_VENDOR_PRUSA3D.*/ and printer_notes=~/.*PRINTER_MODEL_MK2.*/ and nozzle_diameter[0]==0.4 and num_extruders==1
or
compatible_printers_condition = printer_notes=~/.*PRINTER_VENDOR_CREALITY.*/
or
compatible_printers_condition = printer_model=="BIBO2" and nozzle_diameter[0]==0.4

Profile name aliases

The logical name (alias) of a print or filament preset is used in the main screen. It is also used in the configuration wizard (filaments selection). There are two ways to change the name of the profile visible to the user while internally keeping the name globally unique:

  • the @ symbol
  • the alias text

If neither is used, PrusaSlicer uses the full name as the alias.

The "@" symbol is used as a separator of a logical name from the full name, the suffix will be hidden. The alias can be used to achieve the same result, but also to make a change in the beginning of the name (not just to remove a suffix).

Example:

Full name: print:0.10mm DETAIL @0.25 nozzle MK3

Logical name: print:0.10mm DETAIL

Alias: print:0.10mm DETAIL

Custom GCode specific information

This section details information about custom GCode modifiers.

GCode placeholders

You can use T[initial_tool] placeholder in the start gcode. The [initial_tool] placeholder will be replaced with the initial tool number before the slicer gcode is exported to a file.

More placeholder tokens are listed in the Wiki

Macro constructs in the custom GCode sections

Custom GCode sections also allow the use of Conditional evaluations if else, and Expression evaluations {<expression>} in addition to the Legacy placeholder syntax: [variable]

More details on custom gcode macro constructs are listed in the Wiki

Multi-Extruder definitions

The easiest wat to build a config bundle for multi-extruder printers is to start by building a custom printer definition in the PrusaSlicer user interface. Once the multi extruder profiles are prepared in the slicer, export the settings as a config bundle. This exported file will contain all of the multi extruder specific settings. Edit the exported config bundle to your liking, mainly adding the header and trying to reduce config redundancy by using the inheritance.

Multi-extruder setting values are set in extruder order and are a comma-separated list. Below is an example list showing some of the possible multi-extruder settings set up for a dual extruder.

deretract_speed = 0,0 # Setting this value to 0 will use that same value as the retract speed.
extruder_colour = #FFFF00;#229403
extruder_offset = 0x0,0x0
max_layer_height = 0.3,0.3
min_layer_height = 0.05,0.05
nozzle_diameter = 0.4,0.4
retract_before_travel = 1.5,1.5
retract_before_wipe = 70%,70%
retract_layer_change = 1,1
retract_length = 1.5,1.5
retract_length_toolchange = 1,1
retract_lift = 0,0
retract_lift_above = 0,0
retract_lift_below = 0,0
retract_restart_extra = 0,0
retract_restart_extra_toolchange = 0,0
retract_speed = 20,20
wipe = 1,1

Single Extruder Multi-Material fields

The following fields only apply to Prusa's multi-material upgrade or similar single-nozzle multi-material printers. These settings do not apply to traditional dual-extruder or other multi-extruder printers. These settings are not visible in the UI unless the "Single Extruder Multi Material" parameter is enabled.

parking_pos_retraction = 92
cooling_tube_length = 5
cooling_tube_retraction = 91.5
extra_loading_move = -2
high_current_on_filament_swap = 0

Custom SVG and PNG bed textures

The Nano SVG parser, which PrusaSlicer uses, does not support every feature of the SVG format. We suggest the following workflow to correctly export SVG texture from Adobe Illustrator:

File - Export - Export As Tick Use Artboards to make sure that the resulting size is correct In the SVG Options dialog pick: Styling - Inline style (Internal CSS is NOT supported) Confirm with OK

More details on Custom SVG and PNG bed textures are in the Prusa Knowledge Base

Online updating

Note: The updating process is entirely optional.

A bundle that is to be updated automatically by PrusaSlicer from the network needs a config_update_url in its [vendor] section at the top of the file. Please note, that PrusaSlicer does NOT allow downloading of profiles from other sites than prusa3d.com for security reasons.

config_update_url = https://files.prusa3d.com/location

The config_update_url URL is used as a base for constructing URLs to get a bundle index and specific bundle versions.

Index file and compatibility constraints

The index is a simple text file listing the bundle versions and specifying PrusaSlicer compatibility constraints. Version strings are in the same Semver format as described above.

Example index file:

1.4
1.3 Updated print temperature
1.2 Added a new filament profile
max_slic3r_version=1.40.0      # This is a Slic3r version constraint
1.1
1.0.2
1.0.1
1.0
0.9-alpha

Each line is either a bundle version number, optionally followed by a string explanation of the changes, or a PrusaSlicer version constraint. The constraint may be either

max_slic3r_version=... , or min_slic3r_version=... The constraints are inclusive, ie. max_slic3r_version=1.40.0 means PrusaSlicer version 1.40.0 or lower.

The index file is read from top to bottom, each line is compared with the last max_slic3r_version, or min_slic3r_version.

min_slic3r_version <= vendor budle version <= max_slic3r_version

That means that the constraint applies to all versions below that line. In the example above, PrusaSlicer version up to 1.40.0 will only update this bundle up to version 1.1 and then it will stick with this version. On the other hand, PrusaSlicer version 1.41.0, for example, will update to 1.4.

min_slic3r_version = 2.1.1-beta0
1.0.8 Various changes in FFF profiles, new filaments/materials added. See changelog.
1.0.7 Updated layer height limits for MINI
1.0.6 Added Prusa MINI profiles
min_slic3r_version = 2.1.0-alpha0
1.0.5 Added SLA materials
1.0.4 Updated firmware version and 0.25mm nozzle profiles
1.0.3 Added filament profiles

In this example, profiles 1.0.8, 1.0.7 and 1.0.6 require at least version 2.1.1-beta0. Profiles 1.0.5, 1.0.4 and 1.0.3 require at least version 2.1.0-alpha0.

Release, release candidate, beta and alpha versions

The vendor bundle version can be tagged as a release candidate, beta or alpha version by appending a tag after the version number.

Example:

0.8.0 Updated for the PrusaSlicer 2.0.0 final release
0.8.0-rc1 Updated SLA profiles
0.8.0-rc Updated for the PrusaSlicer 2.0.0-rc release
0.8.0-beta1 Updated SLA profiles
0.8.0-beta Updated SLA profiles
0.8.0-alpha9 Updated SLA and FFF profiles
0.8.0-alpha8 Updated SLA and FFF profiles
0.8.0-alpha7 Updated SLA and FFF profiles

Depending on the PrusaSlicer release type (release, release candidate, beta, alpha), only specific vendor bundle versions are be accepted:

Release: Only release bundle versions

Release candidate: Release and release candidate bundle versions

Beta: Everything except for alpha bundle versions

Alpha: All bundle versions

This way it's possible to upload, for example, a new bundle alpha/beta version and it will be automatically ignored by stable releases of PrusaSlicer.

Checking and updating to a newer vendor bundle version

PrusaSlicer always downloads the index first and then decides whether to download a new bundle based on the index. It will not do anything if the index cannot be obtained or is invalid.

The index URL is constructed by appending "index.idx" to the config_update_url. In the above example, this would be "https://files.prusa3d.com/location/index.idx"

PrusaSlicer consults the index file and if it determines that an update is available, it will download a new bundle from an URL constructed by appending the version string and an ".ini" extension to the config_update_url.

For example: "https://files.prusa3d.com/location/1.4.ini" or a real example from the PrusaResearch repository.

Bundle indices (as well as updated bundles) are stored in the cache subdirectory of the user data directory. PrusaSlicer downloads indices and update bundles (if any) into the cache in the background. On the next application startup, it consults the cache and if updated bundles were previously downloaded, it offers to apply them.

For the initial bootstrapping, PrusaSlicer uses indices and bundles that come along with its installation.

Custom vendor configuration resources

Since PrusaSlicer 2.3.0-alpha4, the vendor configuration resources (print bed model, texture, thumbnail) are searched for and loaded from user's "vendor" directory before the installation "resources" directory. This allows one to customize the print bed image without having to overwrite the application global resources. Because the Wizard already reads the vendor config bundles from user's "vendor" directory, it also allows one to install new 3rd party vendor configuration just by copying his config bundle, printer thumbnail image and print bed models to user's "vendor" directory.

Example:

<data_dir>\vendor\DemoVendor.ini
<data_dir>\vendor\DemoVendor\DemoPrinter_texture.svg
<data_dir>\vendor\DemoVendor\DemoPrinter_bed.stl
<data_dir>\vendor\DemoVendor\DEMOPRINTER_thumbnail.png