Backing off from specific design issues like steering trim adjustment, I want to note a general problem with public demonstrations. Sawppy is an approximately 1/4 scale model of Mars rovers Curiosity and Perseverance, faithfully replicating the geometry and articulation of their rocker-bogie suspension systems designed for traversing Martian terrain. Down here on planet Earth, Sawppy has historically not spent much time rolling on Mars-analogue terrain. Most of the time, when I take Sawppy out for show-and-tell, my rover is rolling on surfaces like asphalt, concrete, carpet, hardwood, or tile.
Mars doesn’t have any of those surfaces. With such luxuriously flat and smooth environments, there’s not much opportunity for Sawppy to show off how nifty a rocker-bogie suspension is. I found myself manufacturing challenges out of what’s on hand, which is why instead of sandy dunes or rocky fields, Sawppy finds itself running over feet…
… and backpacks.
Fundamentally, Sawppy is out of its element on smooth terrain. Robots optimized for flat ground would not need the capabilities of a rocker-bogie suspension system, where it is far more complex and heavy than required for the circumstances. But every once in a while, a Sawppy rover gets to visit a someplace resembling its natural habitat, such as when Aussie Sawppy took a trip to the beach.
Even when serial bus servos are available, the selection of sizes and capabilities is limited relative to more common motors. If someone wanted to make a small Sawppy like Dean, or a big Sawppy like Quinn, it’s hard to find serial bus servos of the appropriate size. And even if serial bus servos can be found in the right size, the communication protocol is not standardized. Dean has yet to figure out the protocol for the tiny servos he found. And then there’s the software side of the problem, where each protocol needs corresponding code written for Sawppy’s brain.
Another problem is that their position feedback has been disappointingly limited, at least in the LewanSoul/Hiwonder LX-16A servos on my own Sawppy. They could turn a full 360 degrees, but only return reliable position data for ~240 degrees within that range. That makes it difficult to calculate wheel odometry. Rhys Mainwaring tackled this problem with the Curio rover software stack, but no matter how good the extrapolation code works it’s not as good as actual data. I think my effort to do things on the cheap did not pan out and, if a robot wants wheel odometry, we have to go to real wheel encoders separate from the drive motor. Marco Walther (mw46d)’s Sawppy wheel modification sets a precedent on how this might be done.
Thanks to feedback from fellow rover fans around the world, I have since learned serial bus servos are not the best choice for a project that I intended for people to build around the world. I should fall back to more common components like RC servos and DC motors. But whatever is ultimately used as the steering actuator, I want to improve how steering angle is adjusted.
I wanted keep the barrier of entry for Sawppy low. Make it accessible to rover fans worldwide. In hindsight a few of the tradeoffs I made for this goal did not pan out. Some of these were a consequence of wanting to make sure Sawppy could be built with only handheld tools. It turns ensuring proper shaft alignment requires a drill press. A drill press is also potentially useful for greatly simplifying Sawppy construction.
There are a lot of M3 fasteners used all over Sawppy. Literally hundreds of M3 bolts, nuts, and washers. The original idea was to have a system that allows for easy experimentation. M3 nuts can slide all along these extrusions, allowing rover builders to experiment with different suspension geometries and attach modifications. But in my own experience, having so many fasteners made every modification a huge hassle. Even changing one little thing might involve tens of fasteners. The tedium of tending to those fasteners discouraged me from doing as much experimentation as I originally thought I would, defeating the original intent.
There is another approach to building with extrusion beams, and that is to drill holes for larger fasteners to pass through the hole to a nut or something on the other side. There are two downsides to this approach. The first is loss of flexibility as the hole position is permanent. The second is that drilling a hole through the center of an extrusion beam requires holding the drill bit steady even as it catches on the edges of extrusion rails. I have never successfully done this with a handheld drill, I could only do it with the help of a vise holding the extrusion beam in place under a drill press.
So I avoided this construction method because I didn’t want to require people to have access to a drill press and vise. In light of my experience to date with Sawppy, however, I have changed my mind on this topic. While imposing a drill press + vise requirement would push Sawppy out of reach of some hypothetical aspiring rover builders, I noticed that almost every Sawppy builder I’ve corresponded with have such access and it wouldn’t have been a barrier for them. As for the people that don’t have access to such equipment, they still have the option of building Sawppy V1.
Given that I’m reconsidering how Sawppy components will fasten to extrusion beams, it is also a good time to think about the beams themselves.
The old mechanical adage is that anything that moves is a potential point of failure, and Sawppy is not immune. Every point of rotational motion uses 8mm steel shafts and they have proven to be challenging for myself and other rover builders. They are kept in location by E-clips, and cutting precise slots for them are hard without a metalworking lathe. For pieces that need to grip on those shafts, my designed used M3 set screws that pushes against plastic with the help of heat-set inserts. And getting them right can also be frustrating.
For pieces of plastic that don’t need to grip on the shaft with set screws, they should still have a snug fit. But 3D printing a precise diameter hole is hard to accomplish given variances of 3D printers. Not just variation from printer to printer, but that a printer may have difficulty hitting the same exact XY coordinates on every print layer to line up a precise hole.
Fortunately this is a problem with an existing solution from the world of machining. When a precise diameter is required, rotational cutting tools called reamers are used. Sawppy’s instructions included use of an 8mm reamer to make precise holes that will fit tightly onto 8mm shafts, and a reamer built for metal had no problems chewing through thermoplastic.
But I found that wasn’t the end of the story, because a reamer only helps make the diameter precise. The location is only as precise as the drill turning the reamer. I had naively thought the reamer would be guided to the correct location and alignment by the existing 3D-printed hole. It did to some extent, but not enough to ensure precision. If the drill is positioned off-center or tilted off-axis, my reamer happily reamed out an off-center, off-axis hole of very precise diameter.
What happens when the hole position or tilt is wrong? In case of suspension components, the articulation will change by a few degrees. In case of wheels, it means the center of rotation would be slightly offset from wheel center. When such wheels spin up, they will visibly wobble. Actually neither would be a functional blocker for Sawppy, as the rocker-bogie suspension can tolerate these variations and keep all six wheels on the ground. But it does look a little silly and drive perfectionists mad.
I don’t think there’s any way to solve the off-tilt problem for handheld drills. Every solution I thought of to hold the drill in alignment ends up looking like a drill press. Why reinvent this wheel? Unfortunately that’s a piece of shop equipment not every aspiring rover builder owns.
The off-center problem is harder to solve. Right now my train of thought is heading towards some kind of centering jig. The challenge is to design something that can be 3D-printed yet help deliver higher precision than what 3D-printing can deliver on its own. Can it be done? I don’t know, but I’m thinking about it.
Back on the topic of drill press: there is a second reason why I might want to make them part of the Sawppy builder’s toolkit: a drill press would allow me to drastically reduce the number of fasteners required to build Sawppy.
Closely related to the challenging heat-set inserts are the shafts their set screws bite into. I designed Sawppy to use 8mm metal shafts everywhere there is rotational motion: for wheel rolling, wheel steering, and rocker-bogie suspension articulation. Generally speaking there are three steps to fabricate Sawppy shafts:
Cut to the proper length.
Cut slots for E-rings.
Cut flats for set screws. (For some of them.)
And it turns out the E-clips make everything trickier than it really needed to be. Unlike my ignorance with heat-set inserts, I knew E-clips are not very standardized, especially in their thickness. So my documentation couldn’t really say what the proper lengths would be, I could only give the functional dimensions and tell people to add width of their E-clip slots.
For cutting those E-clip slots themselves, I documented a “Poor Man’s Lathe” technique using two motorized tools, but this is not very precise. Fortunately, high precision is not required for a 3D-printed rover, the worst thing that happens is a rover whose suspension is a little bit wobblier than it would otherwise be.
Being a perfectionist, I was not happy with the hand-built results and arranged to cut a second set of Sawppy shafts with a manually operated metalworking lathe. And I knew imprecision would bother other Sawppy builders out there as well and not everyone could get access to a real lathe.
In the meantime, people have devised other workarounds. Ameer used M8 bolts and nuts instead. Using threaded fasteners instead of a solid shaft would put stress on the threads, but probably not terribly much for a little 3D printed rover. And it is definitely easier to work with.
The challenge with this approach is in tightening these bolts. If they are too loose, rover suspension will wobble and we’ve gained nothing. But if they are too tight, it puts too much axial load on the bearings and they seize up instead of turning freely as they should. I think there is a better way down the fastener path, and have a few ideas to test. If successful, a future Sawppy would use fasteners instead of fabricating shafts and also not unduly stress its threads or be finicky about amount of tightening torque.
I don’t like it when some part of Sawppy is finicky, but I’ve come to accept that a tradeoff has to be made between finicky precision and a design that can be built by the widest range of rover enthusiasts. This became the most apparent when dealing with holes for these 8mm shafts.
Looking at what other Sawppy builders have done to customize their own rovers, I learned that ground clearance isn’t as valued as I thought it would be. At first I was disappointed, because giving Sawppy great ground clearance took a lot of hard work. But then I decided to look on the positive side, because this feedback also meant I could trade off some clearance for other features and not have it be considered an instant fail.
Another common theme of feedback on Sawppy wheels concern shaft coupling and heat-set inserts. It has been a perpetual problem for me, to the point where I started preparing field replacement units of shaft couplers. I also heard from other Sawppy builders that it has been problematic for them as well.
The biggest problem was caused by my ignorance: I thought all M3 inserts would be the same size, but I was wrong. Inside, yes, but not outside. Furthermore, optimal heat set inserts usage require hole diameter within a pretty narrow range. And that range appears to be narrower than the range of variation between 3D printers. All this meant my Sawppy design printed as-is would frequently not work for another rover builder and require modification. Either their insert is a different diameter, or their printer would print differently, or some combination of both.
Some builders applied their creativity to this problem and came up with alternate approaches. Chris Bond went with the direct approach: drilling and tapping a hole through the diameter of the shaft. This is a good option if a vise and drill press is available, but drilling on a round shape is very challenging with handheld tools.
TeamSG for Aussie Sawppy explored another route: instead of round shafts, use hex profile shafts. I knew precision shaped profile beams of metal are expensive and difficult to get, so I didn’t think it was a good idea. But TeamSG thought of something I did not: Hex profile wrenches are plentiful, precise, and made of strong metals. Cutting up a few is a brilliant approach to build some rover hex drives!
Laura McKeegan’s CJ rover offered yet another approach: use captive hex nuts which worked when heat-set inserts did not. Unlike heat-set inserts, M3 hex nuts are standardized with an external diameter of 5.5mm from flat to flat.
My own experiments with captive nuts have not been successful, because if I put too much force my nuts will start spinning inside their slot. To fix this, I would heat it up with my soldering iron and turn it into a crude heat-set insert. So I thought I’d just go straight to heat-set inserts. But given feedback from builders and knowing what I know now about non-uniformity of M3 heat set inserts, I think captive nuts might be worth another look.
And while I’m working on solutions for Sawppy’s shaft coupler problems, it’s worth noting that the shaft themselves have been problematic as well.
While I’m on the subject of rover suspension and ground clearance, I want to take a detour to recognize the less famous rovers that didn’t make the trip to Mars. My rover fandom has mostly been focused on siblings Curiosity and Perseverance, but those rovers would not exist if it weren’t for the twin rovers Spirit and Opportunity. Formally the Mars Exploration Rover program, they followed Sojourner the rover technology demonstrator. Each rover generation was larger and more sophisticated than the last, but one thing all those rovers had in common was the rocker-bogie suspension design that I replicated with my own Sawppy rover using references like a rover family portrait published by NASA.
But the real rovers are on Mars. Who are the rovers in this picture? The little one is named Marie Curie, and is a “Flight Spare” for Sojourner (Truth). Meaning it is fully equipped and qualified to be sent to Mars as an alternate if necessary, but there was no need so Marie Curie stayed on Earth. I assume it played a role during the mission as a testbed as the other two rovers did.
Representing Spirit and Opportunity is the MER Surface System Test Bed. This rover duplicates many of the mechanicals of Spirit and Opportunity, but is not fully equipped to go to Mars. For one thing, it runs on a power tether and have no functioning solar panels, just passive stand-ins. This machine stayed at JPL’s Mars Yard to help scientists and engineers on Earth test ideas and solutions before commands are sent to Mars.
MER SSTB is a mouthful, and I remember seeing JPL people on Twitter calling the test rover “Dusty” but I found no official confirmation of this name. After the Mars Exploration Rover program ended, Dusty(?) was given to the Smithsonian where it will continue to represent the MER program when put on display.
The Mars Science Laboratory (MSL) mission included the Earthbound Vehicle System Test Bed counterpart to Curiosity shown in the family photo, again with some differences such as powered by a tether instead of faithfully duplicating an onboard radio-thermal nuclear reactor. According to this article, the MSL VSTB counterpart to Curiosity is “Maggie”, and the Mars 2020 test bed counterpart to Perseverance is “Optimism”.
And since these are engineering tools, both names are officially engineering acronyms. Or more likely, “backronyms” where the acronym was chosen first, then words were chosen to fit it. That’s why we have convoluted names like “Mars Automated Giant Gizmo for Integrated Engineering” and “Operational Perseverance Twin for Integration of Mechanisms and Instruments Sent to Mars.”
These rovers won’t get nearly as much fame as their Mars-bound counterparts, but they all play vital roles contributing to mission success.
When it comes time for Ingenuity to demonstrate Mars helicopter technology, it will be dropped to the surface then wait for Perseverance to move a small distance away to prepare for the experiment. This arrangement is possible because the rover’s rocker-bogie suspension gave it more than enough ground clearance for a hitchhiking helicopter to ride along, holding on to the belly of the rover.
This ample ground clearance is also visible in the Mars 2020 Mission Identifier. The first I saw of this logo was on the side of the rocket payload aerodynamic fairing protecting the rover against the atmosphere during launch. I love this blocky minimalist design of the rover’s front view and believe this little logo hasn’t been used nearly enough.
Anyway, back to ground clearance: it is something obviously useful for a wheeled vehicle traversing off-road, which is desirable given the lack of roads on Mars. But raising the height of rover’s main body is only part of the equation, because it’s not the only thing that might collide with obstacles on the ground. We also have to worry about suspension components. This is something I noticed with JPL’s Open Source Rover design: if a ground obstacle is offset from a wheel, there’s a chance it will collide with aluminum structure. This picture uses a Roomba virtual wall marker to represent a rock on the ground, which is about to collide with suspension structure:
When I designed Sawppy, I thought I could improve upon this specific issue by taking advantage of the flexibility of 3D printing. I also chose Sawppy wheel motors with the requirement they must fit within the wheel with no protrusions. If Sawppy should encounter a Roomba virtual wall marker slightly offset from a wheel, there is no risk of collision:
I this was a pretty good Sawppy feature. However, after looking at how other Sawppy builders have customized their rovers, it appears this feature isn’t as valued as I thought it would be. There have been many Sawppy modifications that did not preserve this clearance.
For example, Marco Walther [mw46d] replaced wheel motors with much longer units that risks collision. He is aware of the risk, because he designed shielding to protect the motor encoders from damage. It’s a different approach, shielding vs. avoidance. Steve [jetdillo] adopted Marco’s design to good effect.
Chris Bond swapped out the wheels for RC monster truck wheels, similar to those used by JPL Open Source Rover. However, my wheel mounting arm design does not fit within the wheel. To compensate for this, Chris decided to push the wheels out. This leaves almost the entire wheel mounting arm out where it could collide with ground obstacles. It also means the steering axis is no longer aligned with the wheel, but Chris seems happy with his design so I guess it works well enough.
My lesson is that ground clearance isn’t as important as I thought it was. Or at least, not seen as important enough relative to features other builders wanted for their own rovers. This is valuable feedback for future iterations.
Both the 3D printable (in STL file format) and 3D render (GLB file format) models were listed on the Mars 2020 rover page, which as of this writing has curiosity disappeared from the index page of NASA 3D resources. I’m not sure what’s going on there, but hopefully it’ll be fixed shortly.
When I listed 3D resources for Curiosity there was also a model suitable for 3D rendering. Available as download files for Blender the open source 3D graphics tool and as files embedded in a web page for interactive viewing. The latter is again available: The Mars 2020 mission page has a 3D model of Perseverance that we can interact within a web browser.
This browser interactive model is the most easily accessible version, there’s no need to install Blender or any other piece of software. It serves as an index page to many other pieces of information talking about the rover. While it has a lot of detail missing from the 3D printable model, it still has a few minor flaws. One of them I noticed only because I’ve been a fanatic of the rover: the online interactive rover’s right side wheels are reversed from the actual rover.
Perseverance, like Curiosity before it, has wheel spokes that are curved to absorb impact. I simplified the idea and translated it into a 3D-printable shape for Sawppy’s wheel. For both rovers, the direction of curvature for wheel spokes are the same for all six wheels, clearly visible in rover test footage. Shot in JPL’s vehicle assembly bay, we can see that the wheel spoke curvature is “clockwise” on all six wheels of Curiosity and Perseverance.
On the online interactive 3D model, its left side wheels match the real rover but its right side wheels had been flipped so the spokes point counter-clockwise.
It’s a tiny detail that would only be noticed by the most particular of rover fans, which I certainly am. Surprisingly, I’m not the only one! Because I’ve received questions about whether Sawppy’s wheels should be printed in mirrored orientation. Some Sawppy builders choose as I did, to have six identical wheels matching the real rover. Others chose to mirror three of the wheels as the web page interactive model did.
I’ve completed assembly of a 3D-printed static display model, released by NASA, of Mars rover Curiosity. It had a lot of details that were demanding when printed in PETG. In hindsight, I should have printed with PLA for fewer printing problems like stringing and overhangs. It is only a display model, it’ll just sit on a shelf and not stand out in the sun as Sawppy has done (and suffered for it.) Better dimensional accuracy with cleaner printing PLA would also help make the snap-together construction more effective. PETG is more ductile and so there wasn’t a “click” to announce successful assembly.
The demanding details were fitting for a static display model. Unlike its smaller sibling, this one is even poseable with corner wheels that steer and a robot arm that can articulate through the same degrees of freedom as the robot arm of the real thing.
With its emphasis on appearance, I was disappointed at the representation of my favorite feature of NASA JPL’s Mars Rovers: their rocker-bogie suspension. The first complaint is cosmetic: this model placed all three pair of wheels with the same track (distance between left and right wheels.) Curiosity’s front and rear wheel pairs actually have a narrower track than the middle pair, which I speculated was done that way so the suspension can fold up for flight. While a static model does not need to fold up for flight, it should at least accurately represent the layout.
The next complaint is a combination of cosmetic and functional: the suspension rockers do not articulate. Their angle is fixed relative to the body. On Curiosity, the left and right rockers are connected via the differential bar which keeps the two rockers in sync with complementary movement: if one moves up, the other moves down the same amount. But on this model, the differential is a surface feature and not a functional one, without connection to the suspension rocker.
On the upside, at least this model has articulation for suspension bogies. This was also missing from its smaller sibling. With articulating bogies, this rover model can at least pretend to handle rough terrain capability even if it lacks full rocker-bogie capability. In this picture, the middle wheel is raised by a piece of 3D-printed plastic I had on hand.
And finally, the suspension arms leading up to corner steering wheels have right-angle bends that are not an accurate representation of Curiosity’s suspension. I suspect this was done as a compromise to make these parts 3D-printable without supports, but it further reduces fidelity of this model.
There are several additional print problems with this first draft. If I were excited about this model I would reprint in PLA to see if it improves as expected. But given my lack of enthusiasm about representation of rocker-bogie suspension, I am content to stop here and look around for the next project.
NASA published a 3D printable static display model for Curiosity rover, and one of the things they offered to make printing easier are STL files that have already laid out many parts so they can be printed all at once. The upside is a lot less work on setup and less time tending to the printer. The downside is that if one part fails, it dooms the entire print.
The rover suspension parts are all in a single large multipart print. The real Curiosity rover suspension structure is cylindrical, and this model tries to maintain that shape, meaning there’s very little surface area contacting the print bed at the bottom of the cylinder. In the first few failed attempts, one of the suspension parts (and never the same one twice) would pop free from the print bed and wreck havoc.
To work around this, I told MatterControl to add a brim on all parts to increase surface contact area. It allowed the print to complete, but now I have to cut all those brims off before I could proceed to assembly.
I started by cleaning up the wheel hubs and pressing them into wheels.
Which quickly led to a rocker-bogie assembly for one side of the rover.
Unfortunately, the rocker does not articulate on this model. Its angle relative to the body is fixed. So this particular portion of the model is no more functional than the smaller version. However, the bogie does articulate, and all four of the corner wheels can steer.
Having built one side, it was easy to build the mirror side and put everything together. I noticed I had two extra steering brackets left over. Reviewing the large multipart print, I now notice there are six steering brackets even though only four rover wheels could steer. I shrug and move on.
Assembly of the robot arm was straightforward following the directions, leaving rover head installation as the final step. The static model is complete and I can admire it in its entirety.
Some of this is unavoidable, the natural orientation of some parts dictate minimal surface area. The wheels, for example, have to sit with their narrow side edges on the bed because that is the only flat side. Fortunately wheels are round and produced minimal stress.
In contrast, the body of the rover is a large rectangular solid with sharp corners. This is a recipe for lifts and they released the STL files with some pre-generated brims to help the corners stick. Unfortunately that was not enough for me, because some of the corners still lifted off the print surface. Fortunately this was only a minor cosmetic issue, since the bottom does not need to be absolutely flat to mesh with any other part.
Another cosmetic issue is the radiothermal generator at the back, which ramped up more aggressively than my Pulse XE revision D printer could handle with PETG. Fortunately this is a bottom-facing surface and shouldn’t be too much of a detraction.
The wheel spokes were the most problematic with their fine detail requiring a lot of filament retraction as the print head moves from one tiny feature to another. In my experience, retraction-heavy prints work much better in PLA than PETG, in hindsight that’s what I should have used.
An interesting nod to convenience is that, in addition to publishing STL for individual parts, the creator of this project also included STL files with many parts laid out to be printed all at once. The upside is that there’s a lot less overhead. The downside is that failures can be troublesome.
When I take Sawppy out for some publicity, people frequently ask about the 3D printable Curiosity rover static model released by NASA. Some mistakenly thought Sawppy was the NASA-released design, others wanted to know how the rovers compared. I couldn’t answer the latter because I never printed the NASA rover, to the surprise of some, so I thought I should do it at least once.
NASA’s 3D printing resources page for a printable Curiosity points to a GitHub directory that actually has two printable models. I’ve seen the smaller one at a MatterHackers event, printed by another attendee who left her little rover on Sawppy’s table to keep my rover company.
The small model has limited articulation. All six wheels can roll, but cannot steer and it could only sit on a flat surface because its rocker-bogie suspension joints are fixed. I also noticed the robot arm joint articulation doesn’t match that of the real rover’s. Still, it is undeniably a representation of Curiosity and a cute little model.
Since I’ve seen the little one, I decided to skip it and try building the larger one. “Large” is relative, of course, it would still be much smaller than Sawppy. Another important difference is that it is an unmotorized static display model, which is actually the main reason I had not tried to build it. I wanted a rover that moved!
But I’m glad I’ve built it, because it was a good study into the different compromises this model made for the sake of being 3D printing friendly.
I am optimistic that one of the popular static site generators can help me reach my goals for an improved Sawppy documentation site. But the site generator itself is not enough, there are a few other details I’ll have to investigate. The primary one being ability to preview changes to pages earlier rather than later in the pipeline.
Today’s flow of editing markdown files can deliver immediate feedback because GitHub has a “Preview” tab on its built in Markdown editor. But once we’re no longer directly using GitHub’s simple Markdown transformation, we’ll lose that ability. Contributors should not be expected to set up a SSG environment on their computer in order to see the results of their work, and asking maintainers to review every change on their own SSG environment would not scale. (I say this using plural as if Sawppy has a big maintenance staff… it’s actually just me.)
The answer is to bring in tools from the continuous integration world, where tools exist to preview changes to a website before deploying live. Some use services like Netlify, which is not itself open source but there is a free tier available.
One example: look at the repository for Write the Docs website. Open one of the pending pull requests and click on “Show all checks”. One of them is “Read the Docs build succeeded!” and clicking “Details” will bring up a version of the site built with changes in the pull request. This is an interesting venue of investigation to learn more about.
This was the point where I ran out of steam, and the Write the Docs meeting ran out of time, but I have a big treasure trove of pointers to investigate and keep me busy for a while.
Other miscellaneous notes:
Project Tetra is a hardware project that has a documentation publishing system that uses Docsy and Hugo. It also uses PlantUML and Graphvis to render diagrams.
I’m glad I had the chance to learn about terminology and tools of industrial-strength documentation. They are great for their respective niches, but adopting any of them would require major changes and I’m not ready to take such a big leap just yet. Which brings us to static site generators. (SSG) This category of software tools see a lot of open source development, giving us many options to choose from.
A large number of SSGs accept Markdown as a text content input format, so Sawppy’s existing Markdown documentation could be used with small modifications rather than complete rewrites. This also preserves the advantages of using Markdown, meeting the ease-of-use challenges A and B.
Every SSG offers customization of the rules and templates that it applies to content. At the minimum there are themes for cosmetic appearance, but plugins and extensions allow more extensive functionality. This is where I hope to create something that meets my challenge C including a lightweight BOM tool. Around this point Eric spoke up that the JPL Open Source Rover documentation system has a script that generates parts list from document content, but the generated dependency tree is not exposed to the viewer. I want to build upon that precedent and also make this kind of information available to rover builders.
As another example, most of us had experience reading technical software documentation on some subdomain of ReadTheDocs. All of these content were generated by a SSG. MkDocs and Sphinx are two popular SSGs for ReadTheDocs, and a lot of the default functionality (automatic indexing, references, etc.) useful for technical software documentation would be useful for Sawppy as well.
But features like a lightweight BOM tool would be outside the scope of software documentation, so there were several recommendations for investigating Hugo. It is apparently the current darling for flexibly transforming content (including Markdown text) into varying different presentations. Associated with Hugo is Docsy, a Hugo theme focused on technical documentation.
Hugo and Docsy would be a bigger step up in complexity than something like Jekyll, but I’m optimistic that the benefit will justify the cost. I plan to use that as my starting point and expand my experimentation from there. But they’ll only be a part of the solution, because no matter the static generator I use I will still want a way to preview changes.
I had the dream of a documentation system for Sawppy that doesn’t seem to fit anything out-of-the-box, but I had the chance to ask a group of documentation experts for what they thought might apply. It looks like DITA is the super flexible Swiss army knife for documentation. It is a free open standard, but the only freely available DITA software tool I could find works at a low level and I would have to put in a lot of time to build up the system I dream of. In addition, some of the problems I wanted to solve edge into other well-established problem areas.
Bill of Materials
Similar to documentation, the challenge of tracking parts and components is well-tread ground for engineering projects. People at the meeting with industry experience suggested a few terms. MRP or Materials Resource & Planning was one, plus several variants on BOM or Bill of Materials. This area is big business! Sadly free open source tools are scarce. Someone gave a pointer to OpenBOM.com but upon further research I was disappointed to find that despite the name, this tool is not actually open.
That leaves us with few choices between “use a spreadsheet” and big ticket enterprise software. Even if numerous choices were available, such tools are focused on a very small subset of the overall problem. I do want to set up some kind of parts management, but bringing in a full fledged BOM tool adds a lot of complexity I’m not sure is justified for a small scale project like Sawppy.
Model All The Things
I had the same concern about another series of suggestions: fully model everything about Sawppy using a modeling language like SysML or PlantUML. I agree doing so will result in a complete picture, breaking down every part of the rover project. Such data could then feed into software packages that generate visualizations plotting dependencies between components. That sounds good, but the amount of work also felt disproportionate to the benefit it would bring to a project of this scale.
What I hoped would be a better fit for a project of Sawppy’s scale are the documentation systems already available for open-source software projects. While they would not have some of the hardware-focused features — such as BOM or UML above — they are more approachable than DITA and promise to be amenable to customizations. Perhaps even to give a lightweight subset of big BOM and UML tools.
I outlined my Sawppy project and the challenges I want to tackle to the combined Write the Docs LA/SGVLUG meetup on the evening of October 8th. Sawppy’s current system of a loose set of Markdown files score highly on ease of contribution (challenge A) and ease of management (challenge B), but fall flat on querying dependencies (challenge C). What can I look into that helps improve information presentation without giving up the rest?
Fundamentally speaking, challenge C is not new, as it would be desirable in any large scale engineering project. The novel twist here is the desire to do it all with a system that is inviting for public contribution. As a general rule, documentarians for large engineering projects are professionals who have undergone training and have licenses for proprietary software tools.
Most such tools are excluded from consideration due to cost, but many of them deal with DITA, an open XML-based data model for authoring and publishing under the custody of the OASIS consortium. It is the standard answer to reassure customers wary of being locked in to proprietary file formats. And since it is an open format, there exists a DITA Open Toolkit to transform DITA data to desired output formats… HTML, PDF, even Markdown! There are learning resources at https://learningdita.com/
As a XML (and thus text) based format, DITA would be GitHub friendly for branching and merging. It is very flexible for creating any organization we want (creating a “Subject Schema” for DITA) but taking advantage of that power will take work. DITA Open Toolkit functions at a lower level relative to the other tools discussed later. A quick web search found many commercial offerings built on DITA (example: https://easydita.com/) but failed to find free open source counterpart.
I want to improve the usability of Sawppy documentation. Keeping in mind some example problems I want solved I started my quest. To find a system to document and track these types of relationships, without losing too much of the advantages of my current system. This means every candidate system must meet the following challenges:
Challenge A: Easy to Contribute
When a Markdown file is hosted on GitHub, a potential contributor can click the “Edit” button to create a fork of the repository, make a quick fix, and create a pull request all via GitHub website. This presents an extremely low barrier to entry for contributors which is a feature I want to preserve. If contributors were required to install and learn some piece of documentation software, that would discourage many people from participating before we even talk about the learning curve for that software.
Challenge B: Easy to Manage
When using GitHub’s web interface to edit a Markdown file, visualizing the change is as simple as clicking over to the “Preview” tab of the editor. Sadly such ease can’t be matched by any system external to GitHub, but it would be nice to have some way to let a contributor see what the end results look like. Failing that, I must have a way to visualize the final impact of changes before I merge a pull request. It is unacceptable to not see changes until after merging into the main branch.
Challenge C: Easy to Query
The desired documentation system will take metadata written by document author and build an interactive presentation. This way rover builders can find information without being constrained by the current linear narrative. Here are some examples of questions I’ve received for Sawppy, rephrased in terms of wheel axle.
(Easy: positive query) I’m on the wheel hub assembly page, and it needs the wheel axle which I guess I forgot to build. Where do I need to go?
(Hard: negative query) My order of 8mm shafts got delayed. What can I work on now that’s not dependent on having these shafts?
(Both of above) How can a teacher most effectively divide up rover tasks so multiple students teams can build the rover in parallel?
Challenge D: Free
It would be nice for the system to be free as in freedom, but at the very least it must be free as in beer. Design for Sawppy is given away at no cost to rover fans everywhere, there is no profit to cover monetary expense of a commercial documentation system.
To illustrate problems with Sawppy’s documentation, I’ll use a single component as example: Sawppy wheel axle. There are at least three entirely separate pages relating to the wheel axle:
The page of parts list, telling a builder to buy 8mm metal shaft.
The page for 8mm shaft modification, where I describe how to cut the long shaft into shorter segments. Followed by steps to turn these segments into wheel axles. Other segments were turned into steering shafts, plus those turned into rocker-bogie suspension pivots.
The page for wheel hub assembly, which incorporates a single segment of the 8mm wheel axle shaft.
While these three files were all linked from the index page, there’s no obvious way to retrieve the relationship between them in the context of wheel axles. I can manually add links between them, but this is time consuming and perpetually incomplete. Even worse, as the number of relationships grew, it will quickly become a maintenance nightmare.
When I decided to release Sawppy to the world, I thought briefly about how to best organize all the information I want to convey for rover assembly. I quickly fell into a state of Analysis Paralysis and, as a path out of that state, decided that it was better to have something written down whatever the format. No matter how unorganized, is still better than keeping it all in my head.
I first tried putting it in the “Build Instructions” section of Sawppy’s Hackaday.io page, but that feature has some strange and unpredictable limitations that became annoying as the length of instructions grew. The final straw was when I noticed that images and instructions for earlier steps were disappearing as I added later steps. That made me… unhappy, so I went to something else.
The second attempt is what I have as of today: a loose collection of Markdown files on a Github repository. Edited in a code editor rather than a word processor, I struggled with typos and grammatical errors as I lacked the usual automated proofreading tools present in a word processor. Still, with a large helping of assembly pictures, it was just barely enough to help other people build their own rovers.
I was painfully aware of the fact there is a ton of obvious room for improvement. This was just the “get it written down” first stage and at some point I need to revisit the various problems still open. The most significant of which is lack of structure beyond an index page with links to all the other pages. The index suggested a relative ordering that matched my personal assembly order, but that doesn’t necessarily work for anyone else. And worse, they would be stuck if they wanted to ask some specific questions my layout is unable to answer.