Documentation writers needed #2090
Comments
|
Nice one!
|
@JustAnother1 Yes. The documentation at the RepRap wiki is getting stale, even more for other firmwares than for Marlin. And we haven't up to now had a location for detailed discussion of the many details of Marlin. Plus, it would be poor form to document Marlin in its own wiki and not include full documentation of its G-Code. And, we are adding new codes which are in their nascent stages. It will be good to have a more definitive reference – specific to Marlin – that is under Marlin control while we work that out. Finally, the documentation we are writing here is in MediaWiki format also, and will be easy to migrate to the RepRap wiki, should we decide to do so. But I would rather not pollute the RepRap wiki with the far more detailed descriptions of Marlin G-Code, where we discuss how they behave in Marlin and include implementation details, since they are uninteresting to people reading the RepRap wiki G-Code page for a more lightweight reference. This is good to see (http://reprapcode.haz.wiki/command/g0) though, and I may plagiarize liberally from that as well. Whoever maintains that site, its very nice of them to make it! 😉 |
|
@thinkyhead It was a rhetorical question and the answer is NO ! The G-Codes are not part of Marlin. They are the interface between a firmware and a host. They are also the interface between a firmware and a slicer! So neither part of the firmware nor the host or slicer! So it is totally fine for Marlin to say we fully support the G-Codes defined there. By the way the documentation you want to steal was done by @foosel (Octoprint) and her Idea for doing this was to have only one documentation for G-Codes. If you like her documentation then put a link into the Marlin wiki and add your stuff to her wiki! |
|
... |
|
@thinkyhead I think it's very dangerous to put something like this under the control of a specific firmware mostly because you're likely to change something in regards to how the protocol works to better fit Marlin. Also, it will then become the Marlin standard of gcode instead of something everyone can use. I know the same issue can happen with @foosel in control, making it convenient for the host side and not for the firmware. We're trying very hard to have both host developers (of which I am one, although I currently use printrun's core) and firmware developers work together to create an interface that works well. If you start documenting how marlin handles things currently, then that could be fine as a reference, but don't do it as the definitive specification of the protocol. We're already very separated in terms of protocol and any form of standard at all. This is hurting our intended user base greatly. My hope is that one day people will literally have a plug and play printer. Right now we're more interested in cheap printers than actually making quality machines with a lower learning curve. I'd love it if a host could also update the firmware for the user. Ie, host gets a url from the firmware, looks it up, then requests configuration info from the firmware and patches it up to the next version much like up/down for a database before writing it back to the device. This is just one example of a higher level function that we currently have no way of organizing but would be great for vendors like printrbot or aleph objects that would want to update their users' firmware automatically with bug fixes. |
|
I agree with @JustAnother1 here. The idea of having different options for host software and firmware which all communicate with each other can only work if they speak the same language. That language is not owned by any one of those programs, it's a standard. I also understand the need for implementing experimental features, and it is good to document those. Being experimental, they aren't part of the standard. So I would suggest to fix the wiki on reprap.org (or the place @foosel created, or the new consortium place that's about to be created; anything goes as long as it's just one place) with up to date information about non-experimental features, document the experimental ones here as part of Marlin and point to the standard for all the non-experimental ones. As a programmer, you should know that code duplication is bad and leads to out of sync information. This is no different for documentation. So you should avoid it. The standard is not owned by Marlin and should thus not be documented here. Experimental features are, and should be documented here. |
Yes, that's why I announced my intention with a wink. Because I want to steal it. I contribute a lot of editing to the RepRap wiki. Don't mistake my intention here. I want to make good documentation and improve it to the best of my ability, and contribute back. It's all open for sharing. If it helps, I will hide those pages while I work on it. |
|
I'm working some new codes, which of course are free for the other firmware to adopt or not (GPL!). This is the latest, |
That is very unlikely, given the community's conservatism around alterations. It takes a lot of consensus to do that. "Protocols" will certainly not be changing without a lot of collaboration among groups. As for adding new codes, those are not problematic since no slicers or hosts yet know about them, and only pick them up once they are mature. Again, the whole point of my creating an issue here around a Standards Consortium. |
In this case my point is to create definitive documentation that is up to date. I was not at all aware of the work by @foosel or @JustAnother1 – or their apparent higher rank in the RepRap world. I was only aware of the RepRap wiki and its (very bad) GCode page, and wished to start over from where Marlin is – and then I intended to migrate that work to the RepRap wiki. Now that I am aware of the other work that has been done, I can go back to building Marlin for all you wonderful folks. |
|
@thinkyhead Please, don't be so defensive. Everyone agrees that we want good documentation, and your efforts are appreciated. That doesn't mean we must agree with your course of action, though. If you also agree that the protocol should not be documented as a part of Marlin (that has nothing to do with rank, it also shouldn't be in the Octoprint repository), then why would you work on it here at all? Isn't it easier to do it in the place that will host them eventually? Also, given that @foosel is still working on that page, why not help her out instead of copying parts and then improving your copy, thus depriving her from your improvements? It's a wiki, you have (or can get, if you ask) write access there, too. I fully understand and encourage your wish to document your work, and I agree that such new extensions should be documented here, at least until they are accepted as standard. What I'm saying is that you should document only those codes, and not copy the standard into here; that only leads to out of sync documents. Instead, if you want the standard to be easily accessible from the documentation here, link to it. |
Just give me the benefit of the doubt, for chrissake. |
|
My opinion about g-code descriptions on a Marlin pages is: 'The descriptions are not meant to be a standard, but should describe the Marlin interpretation of the commands'. @fmalpartida |
It was easier to do it in private before I announced it. But more to the point, it's in Wikimedia format, which can be scraped as HTML, and easily grep-replaced to make it into any suitable format. |
Perhaps I would prefer to be concise, and leave discussion of related topics to their own dedicated pages. |
She is free to copy and paste from my work as well, and –now that I am aware of that page– I would of course share my work. In spite of my cheeky comment about plagiarizing, I have preferred to write out the explanations myself in good concise English without influence from other documentation. Again, my process is faster if I slog through – I'm not just copying and pasting from other sources, but composing it using the source code as my guide. – Or, rather, was composing it. |
|
@thinkyhead before you announced what exactly? Also, have you looked at the wiki that we're making? Like, at all? I don't mean to be rude, but we're being pretty concise and keeping things on their own page and they have a discussion module. It seems to me that you want to make your own version where you don't have to work with other people. |
@Jnesselr Like, no. I just found out about the wiki you're making. Tell me more.
@Jnesselr It seems to me you have a very cynical view and that you and @JustAnother1 are being unnecessarily accusatory.
Before I announced |
Classy. You really have a way with people. For content, what @wijnen said:
|
I'm sorry, but the statement I was responding to was, by dictionary definition, obnoxious, and designed to be so. And frankly I'm not interested in all the politics and personalities. I posted to let you know there's a Marlin wiki. I explained I had done lots of work on it to get it started. And then a bunch of obnoxious comments started flying about how awful I was for doing so. Try to comprehend this from my point of view. I have been devoting immense amounts of time to improving Marlin and pulling it out of a stupor, and I am not in the mood for brand new voices who have not been my kind friends here along with me, suddenly dumping on me over some offhand comments —intended to be a friendly wink— misinterpreted as some kind of malicious declaration. It's screwy, and I'm not down for it. So, please talk amongst yourselves while I go cool down. You have really irritated me with all this nonsense, amounting to: the Marlin project shouldn't be allowed to document its G-code implementation for its own reference – at least not publicly. Ok, well I will hide it for the time being, but I find the process valuable as someone writing the code, and I would like to perhaps use it in the future to produce a quick-reference card. Who knows? And of course my intent is to share the work, the point of this topic. Thank you for your valuable input, everyone. |
|
Ok, I see where you are coming from, but I don't see obnoxious comments above. People told you where they thought you were wasting energy. No one said anything about forbidding you to document stuff, but they informed you that it would make more sense in a different way. If you can't take that kind of critique, I have some bad news for you, because it will only get worse from here. You are a collaborator on a high profile Github project. That entails also the ugly things such as politics and personalities, and having to tolerate stuff you might not want to hear, brought up by people who sometimes might not have the most diplomatic way of phrasing it (we want to get stuff done here, that means you sometimes have to get information across without the time to try to not hurt any feelings). It also entails getting to know your environment and with that I mean what's going on around you in the community. You have a responsibility now. It's not just writing code (in fact, on some days it's anything but), some times it's talking with people, trying to understand their worries and points of view and finding a good middle ground everyone can be happy with, and of course sometimes it's also staying on top of current developments. If you are doing things in a way that people don't like, and they tell you that, well, extract the constructive criticism and try to do it better instead of getting cocky or offended about it (or calling everything but your own interpretation broken until convinced otherwise, as it happened with the G28 thing). Because if you don't learn this, you will not have a lot of fun I fear. And especially in an open source context, you never joke about stealing aka taking other's work without crediting. A lot of us have found ourselves on the receiving end of exactly that happening with our work for real, so unless in very very special situations, best avoid it. That being said, now maybe try to comprehend it from our point of view. Because I don't get the feeling you did. @JustAnother1 told you about another documentation effort aiming at a standard (which in fact you should already have been aware of). You promptly brushed it off as "oh, nice, but" and "I'm going to copy that" (the smiley can be read two ways btw) and insisted on still doing the work twice (btw, I'm not even of the opinion that the "default" commands shouldn't be documented as long as there is no standard, but once there is, a simple "conform to ..." should be all that's said there, for reasons that were already stated). People then started telling you why that would result in duplication, things getting out of sync and probably more problems then anything else. Which you first just completely played down (no, it's not very unlikely that if you don't refer to a standard that commands will diverge from it - it has happened before) and then took personally and started lashing out ad hominem. And that's a behaviour I'm sure I'm not alone with finding very unfitting here. |
|
I can understand both positions. But why shouldn't have Marlin its own documentation of the gcode? Any gcode which is already the same as the 'standard' can be marked as 'allready implemented like the standard'. When the standard is finished we can work on the implementations, so any gcode is how it should be. But there will be anytime some gcodes, mcodes or whatelse, which are independend from the standard. Like G29 for example. Some people here are going to be very angry without any good reason. Discuss it, but be fair, nor?!? |
|
@foosel Yes, I am thin-skinned. How could I ever get bothered by statements like...
…or consider overly alarmist…
All this paranoia, directed at my attempt at being helpful and just bloody documenting the source code, is what has been bugging me. I'm sure you're all very nice, but take it down a notch. You people don't know the effort I've been putting in, don't seem to appreciate it, and I am hard-pressed to attend to all these concerns with patience and sympathy at the moment, or respond with perfect fidelity. Give me time. Meanwhile, I am very much inclined to keep documenting Marlin's current implementation of G-Code for the Marlin project, and I don't mean to downplay your concerns, but they are truly overblown. No one is planning to take over RepRapistan. I just don't get where that is coming from. |
Sorry, but neither are you. The people commenting here are not people who are just waiting for everything to fall into place while needlessly criticizing from the off. We all are heavily invested into this stuff and are spending most of our waking hours trying to make 3d printing a better place. The first thing I ever consciously saw of you was a comment on the G28 thing which one of my users ran into what got me looking into the bug tracker in the first place and where you were not acknowledging a mistake you'd made but instead taking the stand that all host developers are apparently slobbering idiots who don't understand the command or the "protocol" and who should now fix it on their end. Talk about a positive first impression (and that you hadn't yet discovered the bad-but-the-only-thing-we-have reprap wiki page didn't make it exactly better). It's ok to make mistakes. It's ok to not know things. It's not ok to not acknowledge both in such a critical environment. And
You are calling this paranoia and interpret it as something born out of distrust towards your intentions. Again, it is not. We just know from experience that when you keep things documented at two different locations and only refer to one of those during development (which can happen bloody fast) it will happen that you introduce breaking changes (as has already happened). Not because you mean to break stuff but because it just accidentally happens. It is something that is bound to happen if you do it like that. You can't possibly keep all things in mind all the time (at least I wouldn't dare to claim that), and this is what has people here worried, that you'll change something not out of mean spirit but just because the documentation you are looking at doesn't spec it very well which has nasty consequences all across the board. The problem is that you take things being said here as being targeted at your person and your intentions when it is fact targeted at management and project organization. I'm sorry if this isn't the environment you were hoping for, but as I said, what you are doing and how you are handling the project influences a lot of people out there, so you shouldn't be surprised that they add their 2ct from time to time. In case you think that I enjoy having to go through the source code of three plus firmwares regularly just to make sure everything is still working as expected there, in order to prevent my users from running into problems when they flash their printer next time, you are mistaken. Documenting my API and now the transport protocol? Fun is something else entirely. And don't get me started on discussions like this ;), stumbling across Kickstarter campaigns that show obviously ripped off versions of OctoPrint or entitlement among the users screaming bloody murder at me because their super important feature is still not implemented in that piece of software they don't pay a fine for. But all that is part of a widely known open source project, so you gotta learn to handle it as best as you can (note that I wouldn't dare to assume that I know how to handle it) without what has happened here. |
|
@foosel I'm here to help, whatever you need. |
|
Finally, I see everybody came out of this discussion with a mutual agreement! Could you now return to work on what you actually started? Please. |
|
@JustAnother1 Those codes are just to set text and stuff on the display from USB. I never 100% tested them, they where part of the possibility to have a nicely integrated wireless extension on the UM2. But time and focus caused that never to happen. |
|
@daid I see the custom code range as being a lot like the way MIDI has a place for extended commands, and every vendor can freely decide how they want to do those. @JustAnother1 RepRapCode is a good site, much better than I've come to expect with documentation on the internets. I'm quite happy to know that it exists! I've never used DokuWiki, but I may have to look at it for future web projects. Mainly, I hope the work done on RepRapWiki will be freely shared and eventually be used as the basis to update the documentation on reprap.org. As for the transport layer, well there is a proposed extension to the OK response already checked-in to the What's the best way to inform everyone about these new or proposed features? I've just started including the Github handles of host, slicer, and firmware projects with messages – I'm sure it's an incomplete list. Who else should be included? |
|
This topic is here to recruit help. Has anyone applied to get an account and help with the documentation yet? Please contact @scotty1024 if you are interested in helping write documentation. Help is especially needed to document the many configuration options. |
|
@scotty1024, count me in. I will try do contribute with what I can. |
|
Hi @thinkyhead. I think top-down standardization will never work in RepRap world, despite I'd love to stop maintaining a bunch of G-code flavors myself. There are too many players/vendors/developers not willing to adhere to standards and you'd have to cope with legacy versions anyway, installed in zillions of machines out there. Firmware versioning doesn't work for a number of reasons, by the way. |
@alexrj I completely agree. The documentation I am making —hopefully clear to all by now— is for the sake of describing what Marlin in-particular does when you give it a certain code, with implementation details where it's interesting. The document is for those approaching Marlin for the first time, who may not be able to read code very well, but nevertheless would like to know what's going on under the hood. Most of what I am documenting is totally standard and will link to the RepRapCode site (if there are no objections) and to the RepRap wiki for more detailed descriptions, and the great bulk of what we all currently use will never change (or change very little). There are definitely differences even in those regions – for example Between the last version and this one, I and a couple of others have been very intent on making sure Marlin adheres to the documented "standards," and there have been a few glaring bugs fixed since 1.0.2 in this area. Marlin has never been more compliant than it is today.
Totally. And this is an important role for the RepRap wiki —and now also RepRapCode. In the past the inner operations and specific quirks of Marlin haven't been well-documented, and changes and additions to the implementation haven't been very well kept up with, mainly because those who code don't always tend to document, and those who document must do a lot of legwork to keep up with changes from version to version of each firmware, and it becomes even trickier as more firmware, slicers, and host software comes into play. But, I am a writer as well as a code-writer (language over maths), and find it very useful to document as part of the process of learning, designing, and revising code. Documenting for others is a great way to ingrain knowledge in oneself.
I hear you there. Actually, I think it's kind of a nice idea for slicers to use |
Fear not! Whatever gets documented in one place will certainly be shared with all the others, and leave it to each to adapt the information to its mode of presentation. I'm also mulling over making a thorough iOS + Android app with all the tools and information about RepRaps included in one nice indexed interface, even including 3D simulations of 3D printers! (Similar to http://www.thinkyhead.com/_delta/) And of course, all the RepRap Calculators with 3D visual aids, so you can just choose the number of teeth in your gears, etc., and see visually where the numbers are coming from. I would really like RepRap to become something accessible at the Elementary (Primary) school level, and make it a bit less of a "PhD research project" just to build one. I can attest to many nights of research on the internet, taking copious notes, before settling on what to build and where to source parts. I would like to turn all those notes into something useful for others, save them the hassle. Blogs go a long way, but finding specific answers is not always so easy. |
|
Please join us for the Marlin Google Hangout, Saturday at 22:00 UTC. A great opportunity to express your love, admiration, and concerns for the future of Marlin and the Universe. |
|
I've outlined what I would like a 3-D printing framework to look like on http://reprapcode.haz.wiki . I would like to invite everyone interested to comment on it. This is because my intent is not to enforce this top down, because I agree that that doesn't work (and it certainly doesn't work if someone as unknown as me tries it) and is undesirable. However, that shouldn't prevent the community from having a system where you can click a print button for STL files just as you can for PDF files. So I'm working on this, alongside others who work on the Firmware/Host interface, and I invite everyone who is interested in RepRap software working well to join (me, the others, or both) and help define this framework. What can you do? The easiest thing is to use the comment system to make sure that your needs are taken into account. If you want to write parts yourself, I'm sure that can be worked out (right, @foosel ?) Obviously this was already true for the Host/Firmware interface, which is most relevant to Marlin. But I expect people here to be interested in other interfaces as well. So please read my proposal and comment on it. |
|
@alexrj we indeed cannot avoid a few GCode flavors. But I hope we can limit that to "odd balls" that don't use open source firmware, and have no way to update (like makerware, BFB) |
|
@wijnen it might make sense to move the proposal to its own subpage, simply because the start page now for one is a bit overwhelming and there is no discussion module active on the start page (but only there, the initial reasoning behind this was to keep it a cleaner overview). If you disagree, I can try to get the discussion module reactivated in the start page to solve the second problem though. @alexrj first of all, regarding G1, from the discussion on exactly this in the wiki:
So there you have it, absolutely nothing is definitive yet. Which brings me to... Secondly, anyone having problems with what is written on that wiki already should keep in mind that this is just the initial ground for discussions, NOT the final protocol, and instead of brushing the whole thing off as senseless and doomed to fail because of stuff like this should instead participate in the discussion to make it a sane proposal, that's the whole point of it! :) I don't claim to have the full overview of what formats and commands make sense here, I'm just making a very first suggestion based on my own perspective as a host developer (because we have to start somewhere, right), so as said multiple times, this thing is merely a starting point to get something nailed down, not anyone putting their foot down and saying "this is how well do it, and no discussion" If nobody adapts it, well, at least it was worth a try to make the life for us developers easier (because right now, it is a nightmare, since knowing how firmware X and Y reply to M105 still doesn't help me a thing if I have no way to determine beforehand if it is firmware X or Y - this is severely limiting the user friendliness of these machines, and if you want I'll happily elaborate on that, but not here, that would certainly go way beyond the purpose of this ticket). Just my two cents. I would also like to suggest to keep the discussion of the standard proposal in this bug tracker to the consortium thread (#2028) since - as it has already been pointed out further up, it should be unrelated to what is or is not being documented in the marlin documentation. Plus, I don't know about you, but I find constantly going back and forth and cross referencing between two threads a bit confusing and repetitive, might just be me though. |
|
First of all, deprecating G1 is not an option as I know people use it in Second, while I really love the idea of a well-specified protocol and am On 05/21/2015 08:40 AM, Gina Häußge wrote:
|
|
Right, but we're not writing code for laser cutters. And from what I can tell, we currently use G0/G1 to refer to extruding vs not-extruding moves. Instead of deprecating it, why don't we just say G1 is a synonym for G0. Is there an actual functionality difference? Should there be? I should be able to supply an E command just as well with G0 than with G1. As for the laser cutter, are you saying that when a G1 is specified, it automatically fires the laser? Because that doesn't really make sense with how laser cutters are operated. Generally there is some amount of data that specifies power and how many times it's pulsed if it is pulsed. Also, as Gina already pointed out: THIS IS NOT THE DISCUSSION PAGE FOR THE SPEC If you have something better than Disqus, I'm all ears. Honestly, I'm very happy that it's per page discussion and changes and I could care less whether Disqus requires signup or not. That's just me personally, and I know now everyone agrees. |
|
On 05/21/2015 08:55 AM, Justin Nesselrotte wrote:
We're writing code for printers, but people use printer firmware for all sorts of things, and I don't think we should break things for them without a reason.
I know that's how it's being used in @jmil 's lab at least. @timschmidt pointed it out to me last time there was talk about changing the G0/G1 distinction.
|
I agree, but I also make another point in the discussion: there is no reason all G-Code parsing must take place in the firmware. I'm using my RepRap for milling PCBs, and so I want the output of pcb2gcode to work. That includes G81 for drilling holes. It's pretty easy to convert it into a series of G0 and G1 commands, and IMO that is the proper thing to do. Let the firmware understand just enough G-Code to operate properly, let all other G-Code be converted into that by a desktop (or server). The part that is worked on now, is the G-Code that must be understood by firmware. That is a very minimal set. If the framework takes off, there is no reason for firmware to support more than that minimal set, really, because other commands will never be sent to it. If you have an opinion about this, please let us know!
In milling, the difference between them is that G0 ignores the F value, so it can be used as a fast move in between controlled moves, without the requirement to repeat the F value on the next G1 line.
I agree with all your points. However, @foosel started on this site and IMO it's not worth the time to convert to another hosting place. I prefer spending time on useful things. |
|
I put my comment about G1 deprecation here in order to avoid hijacking this GitHub issue: |
|
@scotty1024, I tried to request an account at http://www.marlinfirmware.org/ around a week ago and haven't heard anything yet. I was planning to add the manual bed levelling + mesh bed levelling parts. |
|
We had good reasons to move away from using the Github wiki and towards MediaWiki, but unfortunately the new wiki wasn't managed properly and no one could get an editor account. However, the domain is still up and running, and I've been posting a lot of content there in the wake of the premature release of RC1. So, if anyone still wants to contribute content to the http://marlinfirmware.org wiki, you should go ahead and post it here in this wiki. Then, if you let me know about it, I can put it up on the marlinfirmware.org wiki as well. Rather than completely abandon the domain, I'm hopeful that it can be moved to another hosting service and managed by someone with more spare time. Then we can get more editors involved. |
|
Thank you for your interest making Marlin better and reporting this issue but this topic has been open for a long period of time without any further development. Marlin has been under heavy development for the past couple of months and moving to it's last mile to finish the RC cycle and release Marlin v1.1.0. We suggest you to try out the latest RCBugfix branch and reopening this issue if required. |
|
I noticed that the Marlin Gcode documentation still needs some work on the Marlin Wiki , is there a plan to do that after the above? https://github.com/MarlinFirmware/Marlin/wiki/DNE-G-Code-in-Marlin Personally I find it extremely usefully to have this done here because it describes the implementation nuances. Thank you @thinkyhead . I also agree that the top-down standardization will never work in RepRap world. |
That was the aim, for sure. To get the GCode documented and give details on how it interacts with Marlin. I would like to fill it out more. Just spending a lot more time on fixing bugs at the moment. |
|
This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
The Marlin Firmware Wiki is up and running, but far from complete. There's a lot of documentation that needs writing. I've written several pages to get things rolling. The pages that should be easiest to do, but require the most attention are:
The text was updated successfully, but these errors were encountered: