What is Marlin?

Where can I find a general description of what Marlin is/does? The reprap wiki page says it is "derived from Sprinter and Grbl", which is not particularly helpful of you don't already know what Sprinter and Grbl are. There are a ton of references to feature lists and how to configure it, but I haven't found any description of exactly what does it do? (Or for any other 3D printer firmware, for that matter.) I know that in general, it is G-code interpreter of some sort, but that's only gleaned from indirect reference. What sorts of functions does it perform? Where is the G-code stored? Are there any communications standards? Most of the info I've run across is very detailed, but lacking any sort of overview. I've worked designing embedded systems for decades, so I'm not quite a total idiot, but sometimes I find that crowd-sourced documentation is aimed at people who already know what is what.

Marlin is controller firmware. This page on the wiki is a little out of date, but it shows a high level overview of the software toolchain: CAM Toolchains. The G-code is generated by a slicer, like slic3r for example. Once the G-code is generated, a printer communication program like Printrun sends it to the printer controller (which is running the firmware), usually via serial communication such as USB.

There are a million different flavors of slicers, communication programs, firmwares, printer controllers, and so on.

Thanks for the info. I've figured out that Marlin (or other firmware variants) receive G-codes over a serial port, but is the entire file downloaded, is the code executed line-by-line, or is it buffered somehow? How is coordination handled? Acceleration & jerk? I am assuming standard G-codes have been extended to handle coordination with the extruder. And how do you get feedback from the controller board? Is there any standard message formatting? Is there any feedrate override like on a CNC controller? I've been able to back out some of this information by looking at specific G and M codes, but is there any normal documentation that gives an overview of this stuff? I'm more used to commercial products where all this sort of stuff would be detailed in the first section of an actual data sheet.

There's not enough memory to "download" the gcode. The firmware has a buffer, but it's only 50-100 lines.

Communication is serial over USB through an FTDI chip.

The communication is pretty slow and unreliable, so most people print from an SD card that the firmware can read directly.

You have lots of very specific technical questions Easiest way to find the answer is to look at the source code.It's all pretty straight forward, but fast evolving so attempting to document it would create more harm than good.

If you haven't found it yet, the G-code wiki page might answer some of your questions. There are a lot of people on the RepRap IRC that would be happy to talk about this as well.

Thanks for all the pointers. I somewhat of an old-school engineer, where its customary for any product, like a 3D printer controller, to have a big data sheet or manual where everything is laid out in one place. And there's almost always an extensive section, usually labeled "Theory of Operation", which gives a detailed overview of how everything works. That's before the specifics of working with particular commands or functions.

The open source world seems to operate completely differently. Having access to the source code is nice, but it shouldn't be a substitute for an explanation of how a product works. I'm not about to plow through the source code for a G-Code path planning module to figure out how some function is suppose to work. I'm kind of dumbfounded by how companies now sell highly technical products with virtually no documentation at all, with the expectation that the hapless user can find everything he needs on scattered wiki pages or by pestering people on a forum. Sometimes I think an extensive user community (like RepRap) enables feeble product support.

Sorry, I'm through foaming at the mouth, now...

your more than welcome to write one ...

the problem with large amount of documentation on open-source projects is that it has to be constantly updated for pretty much every minor change to the project, being an unpaid hobby that is most likely to be reproduced for peanuts by a clone shop 5 mins after it is release upon the world, there's not exactly much motivation plus for many it's not a strong suit.. it's no excuse but thats the reality of it,

these days i'm thankful for even the small number of comments in code that describes half of what it does and code that makes a degree of sense,

I've come across a lot of commercial products where an expensive week long training course was the solution to a simple lack of documentation

---

-=( blog )=- -=( thingiverse )=- -=( 3Dindustries )=- -=( Aluhotend - mostly metal hotend)=--=( Facebook )=-

A 3D printer controller is different from 3D printer controller firmware. Many of the common 3D printer controllers have pretty solid documentation on the wiki:

RAMPS 1.4
Melzi
Sanguinololu
etc...

Most of the RepRap firmwares use the Arduino platform, which makes modifying code easy, even for non-specialists. Making minor changes to the Marlin source code is a fairly common part of the calibration process. See here for example.

thejollygrimreaper wrote: the problem with large amount of documentation on open-source projects is that it has to be constantly updated

I couldn't agree more. There is nothing worse than out-of-date documentation.

If you look at the Marlin source code, it contains a pretty good amount of documentation. The Configuration files explain the settings pretty well, Marlin_main has a list of all supported g-code, and the odd oddities are called out in comments. Otherwise just some good self documenting code.

Another issue (or rather feature) is that there are no set-in-stone standards. Different firmwares use different G code extensions. Evaluate gcode different. Implement acceleration different.

But to get back to the original question, most users don't really care how and what the firmware exactly does at low level. It really doesn't matter how acceleration or jerk is implemented, as long as the config values have been tested by the user. There are way too many variables to calculate what acceleration or jerk should be set at, if at all possible to do such calculation, so trial and error.

Here's an example from everyday life: how many drivers know or need to know the specifications or source code for the fuel injector controller in their car? Zero. Yet we can all drive our cars.

But open source is still better, you can always look at the source code.

LoboCNC Wrote:
-------------------------------------------------------

> The open source world seems to operate completely
> differently. Having access to the source code is
> nice, but it shouldn't be a substitute for an
> explanation of how a product works. I'm not about
> to plow through the source code for a G-Code path
> planning module to figure out how some function is
> suppose to work. I'm kind of dumbfounded by how
> companies now sell highly technical products with
> virtually no documentation at all, with the
> expectation that the hapless user can find
> everything he needs on scattered wiki pages or by
> pestering people on a forum. Sometimes I think an
> extensive user community (like RepRap) enables
> feeble product support.


Welcome to open source...Community based open source projects, be they software or hardware are not consumer based products. Community based projects are a combination of designers, programmers, hackers, tinkers, makers, enthusiasts, hobbyists and others joining together to further the technology and not necessarily create a product for the general consumer. You and the community are the support. That's how the model works. There is a good guide to the basics of the entire process at [reprap.org]

As for firmware, as a user you shouldn't need to do more than edit your config, compile and upload. Unless you are a firmware programmer there is little you can do besides fill out your config, compile and upload. You will be dealing with your printer control software and slicer to print objects. Your toolpaths are generated in the slicer. That said, the consolidation of the software toolchain does need work before it's ready for mass market. It's mostly a packaging, interface, documentation issue. That is largely being addressed in the consumer space by the manufacturers of the printers. For example Makerbot wraps it in something they call Makerware. On the kit builder side there are complete kits where documentation is included as part of the value added by the kit supplier. A given to doing it yourself is the learning curve. Many in these sorts of communities see the learning and the furthering of technology as the primary focus with the use of the device being secondary. Consumers on the other hand, may just want to print something. Many, if not most aren't interested in the hows and whys. The Reprap community is all about hows and whys.

Just to be clear, my beef is not with the RepRap community or generally with open source technology. I'm griping about companies making money selling products designed to use open source software, but that essentially punt on documentation. That may work if the there's really complete documentation out there, but if there isn't, that's a problem.

What started my ranting is that a while ago, I got a Smoothie board for a new printer I designed (feather printer). It was a beta board, so I didn't expect that much support. I bumbled my way through modifying the source with a custom arm solution. The Smoothie board has an SD card, and I would just copy my G-code file and run it through a terminal emulator program. I've now decided to get a Brainwave board for a different printer. It is Marlin compatible. However, it doesn't have any mass storage. So how do I use it? Send G-codes line by line, presumably? I had a host of other questions as well. (When setting out to design a printer, I kind of want to know what's going on in somewhat more detail, even if I'm using standard software packages.) That's where I figured I'd just look up an overview of Marlin, assuming I'd easily find a basic overview of what Marlin does and how it works. Googling "marlin overview" or "marlin tutorial" (or any other variants I've tried) doesn't turn up any sort of basic description of how Marlin is used or what is does. You can find a list of features, but that's different from a general description of its theory of operation. This is not necessarily the author of Marlin's problem, or the open source community's problem. This is something that I feel the company making money off of Marlin (the board manufacturer) should provide - basic documentation about what their product is designed to do - even if they aren't providing the firmware themselves. I don't want to pick on any particular board manufacturer because it seems they all do the same thing - point customers to the open source forums and wikis. While the open source community is a great resource, I believe companies should still support their products with some level of documentation.

I'll eventually figure out everything I need to know to get the board and Marlin working with my printer, but it doesn't seem like tracking down this information should be so vexing. Maybe I'm just an old guy beating my head against the way things are done these days.

Your feather printer is really cool, by the way.

Quote
LoboCNC
This is something that I feel the company making money off of Marlin (the board manufacturer) should provide - basic documentation about what their product is designed to do - even if they aren't providing the firmware themselves.

I think so many of them do, they (I hope) provide MCU pinout, some of them even schematics and PCB layout. Firmware is completely unrelated, they can hardly support something that they don't have under control. There are many more firmwares available out there (Teacup, Repetier), you can write your own. That's like asking your computer parts manufacturer to provide user support for windows, or will it be linux, freedos? I think so main problem is when expectations don't match reality, that then leads to disappointment. Many people expect the same level of support as from multibilion global companies, but that kind of support costs money and is impossible to provide for free at such small production runs and at given unit price.

A Smoothie board. That explains it...

Marlin is written for Arduino not ARM. Is there even a port? You may want to try Arthur. After Trinity cratered he hangs on the Google group and has offered to support Smoothie users.

Marlin lives here. [github.com]

Edited 1 time(s). Last edit at 08/03/2013 07:54PM by vegasloki.

No, the problem wasn't with the Smoothie board. The problem was that when I started thinking about switching to a Brainwave, I realized that there are significant differences between the various controllers and their firmware, and I needed to get myself better oriented. Per my original post, I was just trying to get an overview of Marlin.

Regarding expectations, I have sold embedded controllers for years as essentially a one man company, and have always provided pretty compete documentation. You don't need to be a huge company to offer good documentation. (Granted, I did do the firmware myself.) All I'm saying is that if you create a board specifically designed to use, say Marlin, then you should make sure there is adequate documentation somewhere for the user to at least get himself oriented. If good documentation exists somewhere, great, but if it is sketchy, ever-changing, or scattered all over, or embedded in source code, then it'd be nice if the company exploiting that open source software offered some concise documentation.

Chris Anderson of DIY Drones and formerly a Wired editor has a fitting quote about open hardware/maker business models. To paraphrase, you give away the bits and sell the atoms. I think you might have a better understanding of the open hardware movement by reading his book Makers The New Industrial Revolution. [www.makers-revolution.com]

vegasloki Wrote:
-------------------------------------------------------
> Chris Anderson of DIY Drones and formerly a
> Wired editor has a fitting quote about open
> hardware/maker business models. To paraphrase,
> you give away the bits and sell the atoms. I
> think you might have a better understanding of the
> open hardware movement by reading his book
> Makers The New Industrial Revolution.
> [www.makers-revolution.com]


Thanks, I'll check it out.

I think this is less to do with open source, and more due to the fact that the world has changed. Back in the old days (before the internet!), the only way to get information about a product was to talk to a sales rep or write to the manufacturer. Often product manuals would include a schematic in the back. There were no online user forums, or google to refer to. With luck you had a colleague or friend you could chat to, or attend a conference to compare notes.

Now all that and more is replaced by online activity. Open source tends to make more use of it than closed source products, but the nature of open source is that it is shared information, so that is inevitable.

With any new area you need to get up a learning curve, whether you learn by reading a manual, or reading and asking online, is a difference in style, but achieves the same result.

It's true that the information is more dispersed, and there is rarely a single comprehensive "getting started" guide for a particular product. The information quickly goes out of date, and either relies on voluntary effort or someone to pay for it.

The flipside is that it is very easy to get help on any question that is puzzling you, just ask here!

The boards are not designed to run a specific firmware, like marlin only. You can run a bunch of different firmware on the same board, in fact all these boards are usually just arduino clones with some 3d printing specific ports built in. You can use marlin, teacup, repetier, sprinter, or you can just upload an arduino sketch and blink some leds.

You are asking the board manufacturers to provide documentation for the software people might run on it. That would be like HP bundling linux documentation with all their pcs because a user might load it on his computer.

You can add an sd card reader to your board. One option is SDRAMPS, which uses the 6 pin isp port. Some lcd displays that work over i2c also have sd card ports.

EDIT: Looks like an lcd is not going to work for you as the brainwave board comes with a 64kb flash atmel chip, so you don't have enough memory to use an lcd. Although you could pop that chip off and replace it with a AT90USB1286 if you want lcd.

Edited 2 time(s). Last edit at 08/04/2013 12:25PM by lajos.

Oh, I had interpreted from the Brainwave instructions ("I am maintaining a branch of Marlin that will compile for brainwave at github...") that it was intended to run a specific branch of Marlin. That's why I was looking for a general overview of Marlin (what it does, how you communicate with it, etc.). It's great that it will also run Sprinter, Teacup, etc., but where can I find an overview of those? Maybe I'm looking for a level of documentation that just doesn't exist. As BobC suggests, maybe I'm just suppose to ask the basic question of "what is Marlin" on this forum.

So I'll try again, but without the snippy comments about documentation:

What does Marlin do? What does a typical setup look like? How do you communicate with it? Are G-code programs stored or streamed? Is there anything different in using a Brainwave board over any other type of Arduino-type controller? How/where do I configure parameters for my particular printer? I'm looking for a general overview to get myself oriented. Thanks.

lajos Wrote:
-------------------------------------------------------

> EDIT: Looks like an lcd is not going to work for
> you as the brainwave board comes with a 64kb flash
> atmel chip, so you don't have enough memory to use
> an lcd. Although you could pop that chip off and
> replace it with a AT90USB1286 if you want lcd.


The Brainwave is a low cost, minimal feature board. It's not intended to to have a display or SD card. More hassle than it's worth to mod it. Better to get a board with those features.

As far as I'm aware the documentation you are looking for does not exist.
If you want the level of detail you are asking for you need to read the source code.
One of the issues with open source development in general is that ten tend to evolve to meet the needs of the users who are also developers, and many of the external facing user centric things never get done. It's understandable, unless you have paid developers, no one wants to write the docs, and developers want to work on features that are important to themselves, not features that make it easier for none developers.
The few exceptions to this in the open source community are where you have projects like Linux, LLVM or hadoop where the bulk of the developers are actually full time employees of large companies paid for the work, because the companies in question, use or distribute the product.

---

___________________________________________________________________________

My blog [3dprinterhell.blogspot.com]

Marlin receives a stream of G code commands, either from the USB serial port, or from an SD card and interprets them to control the motors and heaters, etc. It can also stream data from the USB onto an SD card, but not very quickly.

Optionally it can also handle a simple user interface on an LCD display with a click encoder to allow stand alone operation. Otherwise it needs a host program (such as Pronterface or Repetier) to send gcode to allow jogging, starting and stopping prints, etc. It can run completely headless if the SD card has a specifically named file it just runs it.

It does trapezoidal acceleration and deceleration. It has inherited simple motion planning from GRBL that allows it to determine how much it needs to slow down to take corners, rather than always coming to a dead stop.

It has PID control for heaters.

It is configured to a specific board by changing constants in header files and recompiling it. These include pin definitions for the I/O, sizes of the axes, steps per mm for the motors, speeds and accelerations to use, thermistor types, etc. Some parameters can also be changed by gcode commands and optionally retained in EEPROM. Some can be also changed on the fly with LCD interface.

---

[www.hydraraptor.blogspot.com]

Thanks for all the info. This is exactly the sort of information I'm looking for. By way of background, I am working with a bunch of high school students on a project to design and build their own 3D printers. The goal is for them to learn CAD design in Solidworks, CAM software, and then machine their own parts. They are highly motivated by the end-goal of building a 3D printer.

I realize, now, that I've been asking a lot of questions most non-developers don't ever ask. I'm a developer in the sense that I'm designing printer mechanisms, but I'm relying on the existing electronics/firmware/software chain. In my experience as an engineer, though, even if I'm using a bunch of components designed to work together, I need to have a pretty good idea of how each works, and of what the interface is between the components. Because as we all know, things that are designed to work together don't always. (My professional clients wouldn't want to hear about a bug between Pronterface and Marlin.) The worst case scenario is to develop a system for someone, test it, ship it, have it flake on the customer, and then have no idea what is going on. Thus, I like to know the theory of operation (sorry, I keep using that phrase), but rarely is there time to plow through source code to figure things out from the bottom-up.

Again, thanks for the help. I'll be posting photos of their printers once we get them together.

i would suggest teaching students open-scad or a freeware/opensource modeling program, solid-works isn't a bad option but is only going to be available to those who can afford it when are no longer a student and as you know cheap it isn't,

---

-=( blog )=- -=( thingiverse )=- -=( 3Dindustries )=- -=( Aluhotend - mostly metal hotend)=--=( Facebook )=-

thejollygrimreaper Wrote:
-------------------------------------------------------
> i would suggest teaching students open-scad or a
> freeware/opensource modeling program, solid-works
> isn't a bad option but is only going to be
> available to those who can afford it when are no
> longer a student and as you know cheap it isn't,

These particular kids are likely headed for engineering school, where student versions of Solidworks are again the standard. The district is pretty keen on the notion of students learning to use a "professional" CAD package. Plus, I'm just a volunteer mentor, so I don't have much sway with the powers that be.

You can get SDRAMPS support in Marlin under 64k, so it should fit on the brainwave. You only need the data pins from the ISP and power to run the sdramps, all of which seem available on brainwave.

If this is a bigger project involving multiple printers, I would not use that motherboard. It's advertised as simple and cheap, but cheap it is not. You can get a Sanguino kit with 4 stepper drivers below that price in the US. For only about $15 extra you can get an azteeg x1 fully assembled with stepper drivers and heatsinks. The azteeg x1 is an improved sanguino and it's rock solid.

With a Sanguino you have enough memory to hook up sdramps and lcd and encoder. You want to print from an sdcard, unless you want to dedicate a machine to be just sending gcode line by line for hours to your printer. You want lcd and encoder so you can start a print without needing to hook up your printer to a computer.

You'll actually get support, it's a very popular platform, even has a section here.

The brainwave controller is a dead end unless you replace the chip with the 128k version. Cheap is false advertising, as you get less features than a Sanguino for the same, if not more money.