add some documentation to the built STLs .zip

Signed-off-by: Brian S. Stephan <bss@incorporeal.org>

Makefile

@@ -1,15 +1,19 @@
-SRC_FILES := $(wildcard ./src/*.scad)
-SRC_FILES := $(filter-out ./src/all-together-demo.scad, $(SRC_FILES))
-SRC_FILES := $(filter-out ./src/blown-up-demo.scad, $(SRC_FILES))
-SRC_FILES := $(filter-out ./src/components.scad, $(SRC_FILES))
-SRC_FILES := $(filter-out ./src/roundedcube.scad, $(SRC_FILES))
-all: $(SRC_FILES)
-	mkdir -p ./build
-	for file in $^ ; do \
-		openscad -o $${file}.stl $${file} ; \
-		mv $${file}.stl ./build/ ; \
-	done
-	zip ./build/buildable-stick-system-`git describe --dirty`-stls.zip ./build/*
+EXCLUDES = blown-up-demo components parameters
+OBJECTS := $(filter-out $(EXCLUDES),$(patsubst src/%.scad,%,$(wildcard src/*.scad)))
+dir_guard=@mkdir -p ./build
+
+all:	$(OBJECTS)
+	$(dir_guard)
+	mkdir -p ./build/docs
+	cp ./docs/README-objects.md ./build/README.md
+	cp ./docs/assembly-and-tips.md ./build/docs/assembly-and-tips.md
+	cp ./docs/printing-and-materials.md ./build/docs/printing-and-materials.md
+	cp ./LICENSE ./build/LICENSE
+	pushd ./build; zip ./buildable-stick-system-`git describe --dirty`-stls.zip . -r; popd
+
+$(OBJECTS):
+	$(dir_guard)
+	openscad -o build/$@.stl src/$@.scad
 
 clean:
 	rm -rf ./build

README.md

@@ -11,7 +11,7 @@ know someone or a library with a 3D printer? The Buildable Stick System may be t
 
 [OpenSCAD-based illustration of how the components for an overhang panel-based stick fit together.]
 
-![A photo of a completed stick](docs/finished-v4.1.jpg)
+![A photo of a completed stick](docs/finished-v4.2.jpg)
 
 [Photo of a completed inset panel-based stick.]
 
@@ -47,12 +47,8 @@ about when/how to use specific parts:
 ## Printing
 
 These items all fit on a 256mm^2 print bed; I use a Bambu Lab P1P based on what I've learned from the
-OpenStickCommunity. Standard settings seem sufficiently sturdy for my purposes, though the slicer has done a couple
-weird things, in my experience.
-
-My preferred settings are 3 wall loops with 20% gyroid sparse infill. This gives the models a bit more weight and
-stability, but something like 2 wall loops, 15% grid sparse infill is fine and does not lead to a weak enclosure. The
-costs below have been made against my settings.
+OpenStickCommunity. Standard settings seem sufficiently sturdy, but see `docs/materials-and-printing.md` for more
+thoughts and settings based on my tinkering with prints.
 
 ## Assembling
 
@@ -83,7 +79,7 @@ What you'll need beyond these objects:
 ## Rough Costs
 
 This is a rough estimate of the cost to produce one of these sticks, assuming a usual 2-frame design and layout.
-Filament masses from Bambu Studio estimates, using Bambu PLA Basic.
+Filament masses from Bambu Studio estimates, using Bambu PLA Basic, 20% gyroid infill and 3 wall loops.
 
 * Left and right frame: **$10.42 USD** (208.50g each, as of 2024-02-22)
 * Left and right (inset) top panels: **~$6.40 USD** (~128g each, as of 2024-02-22)
@@ -138,14 +134,7 @@ to hang out and discuss issues and features and whatnot.
 
 ## Attribution
 
-Inspired by the incredible work of [TheTrain](https://github.com/TheTrainGoes) on the [OpenStickCommunity Fightstick
-Case](https://github.com/OpenStickCommunity/Hardware/tree/main/Fightstick%20Case), itself based on the incredible work
-by [Dash n'Mash](https://twitter.com/Dash_xx_Mash?s=20). Original work Copyright 2023 TheTrain, [licensed under CC BY
-4.0](https://creativecommons.org/licenses/by/4.0/).
-
-Made possible by the amazing efforts of [slagcoin](https://www.slagcoin.com/).
-
-## Author and Licensing
+### Author and Licensing
 
 Written by and copyright Brian S. Stephan (<bss@incorporeal.org>).
 
@@ -158,3 +147,23 @@ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Gen
 
 You should have received a copy of the GNU General Public License along with the Buildable Stick System. If not, see
 <https://www.gnu.org/licenses/>.
+
+### Lineage
+
+Inspired by the incredible work of [TheTrain](https://github.com/TheTrainGoes) on the [OpenStickCommunity Fightstick
+Case](https://github.com/OpenStickCommunity/Hardware/tree/main/Fightstick%20Case), itself based on the incredible work
+by [Dash n'Mash](https://twitter.com/Dash_xx_Mash?s=20). Original work Copyright 2023 TheTrain, [licensed under CC BY
+4.0](https://creativecommons.org/licenses/by/4.0/).
+
+Made possible by the amazing efforts of [slagcoin](https://www.slagcoin.com/).
+
+### Distributing BSS Sticks
+
+Under the terms of the GPLv3, you must inform the receiver of the "object code" of their rights under the GPLv3. This is
+a bit of a gray area for physical objects, but likely applies to distribution of modified or unmodified STL, STEP, etc.
+files at a minimum. The easiest way to satisfy the GPLv3 in either situation is to provide a link to the source code
+(either the unmodified mainline project, or your copy, with modifications listed in a "prominent notice"); something
+like the below should suffice in either electronic or printed form:
+
+> This arcade stick is part of the Buildable Stick System, version X.Y.Z; the source code to this program is available
+> under the terms of the GNU General Public License, at [LINK].

docs/README-objects.md

@@ -0,0 +1,65 @@
+# The Buildable Stick System
+
+Files for 3D printing an arcade stick.
+
+## Objects
+
+The following notes document the objects in the Buildable Stick System and how you can use them:
+
+* `bottom-panel-inset`: a simple solid panel that fits into the bottom of a frame box.
+* `bottom-panel-overhang-*`: solid panels whose base fits into the bottom of a frame box, but have a longer sheet that
+  extends beyond the frame, creating a sandwich kind of look; the various forms hang over more or less of the frame,
+  expecting it will be connected to other frames.
+* `frame-{left,middle,right,solo}`: the core frame of the stick, these are complete boxes; since they are long and
+  narrow, and need supports to print the space for the insets, these may be difficult to print nicely.
+* `frame-piece-*`: the core frame broken up by individual faces, which are easier to print and essentially just as
+  sturdy.
+* `frame-piece-*-extended*`: frame pieces that have been stretched out beyond the normal frame dimensions in order to
+  make a nice bevel on the sides and/or bottom; this, interestingly, tends to make the stick look a bit thinner than if
+  it was just a simple box.
+* `misc-decorative-plate-*`: things you can print to snazz up face buttons mounting, auxillary button points, etc..
+* `misc-dustwasher-*`: simple dustwashers for levers.
+* `misc-lever-mount-*`: lever mounts of various shapes and depths to get the desired lever height when mounting a lever
+  to a panel (with the appropriate cutouts).
+* `misc-neutrik-*`: like the decorative plates, but these are a bit more necessary by their design.
+* `misc-rocker-*`: rocker SPDT switches don't have mounting holes, this allows you to attach them to the frame.
+* `top-panel-inset-*`: various lever and/or button layouts for using as the face(s) of a stick.
+* `top-panel-overhang-`: same idea as the inset top panels, but overhung over the frame to make the sandwich look; these
+  also leave a bit more space inside the frame, which might accommodate a taller lever.
+
+Feel free to request or contribute to more objects, see the links to Git repos below.
+
+## Printing and Assembling
+
+Additional documentation regarding printing the objects and assembling the stick are available in
+`docs/printing-and-materials.md` and `docs/assembly-and-tips.md`, respectively.
+
+## Author and Licensing
+
+Written by and copyright Brian S. Stephan (<bss@incorporeal.org>).
+
+These arcade stick parts are from the Buildable Stick System; the source code to this program is available under the
+terms of the GNU General Public License, at:
+
+* <https://github.com/bsstephan/buildable-stick-system>, or
+* <https://git.incorporeal.org/bss/buildable-stick-system>
+
+See the tags/releases for the version of the source code corresponding to the STLs you received.
+
+The Buildable Stick System is free software: you can redistribute it and/or modify it under the terms of the GNU General
+Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+The Buildable Stick System is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
+implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.
+
+You should have received a copy of the GNU General Public License along with the Buildable Stick System. If not, see
+<https://www.gnu.org/licenses/>.
+
+## Lineage
+
+Inspired by the incredible work of [TheTrain](https://github.com/TheTrainGoes) on the [OpenStickCommunity Fightstick
+Case](https://github.com/OpenStickCommunity/Hardware/tree/main/Fightstick%20Case), itself based on the incredible work
+by [Dash n'Mash](https://twitter.com/Dash_xx_Mash?s=20). Original work Copyright 2023 TheTrain, [licensed under CC BY
+4.0](https://creativecommons.org/licenses/by/4.0/).

docs/assembly-and-tips.md

@@ -2,6 +2,52 @@
 
 Just some miscellaneous notes for any dear reader, or more likely, my own forgetful self.
 
+## Putting a BSS Stick Together
+
+Assembly of a stick is pretty straightforward, but there are some choices that can make it easier or harder. The
+following is the most consistent way I've found to put one together. This is assuming a v4.1 or beyond stick, with two
+panels to make a long standard stick, and the frame made of pieces.
+
+1. Prepare the frame top pieces --- `frame-piece-top-{left,right}`: this is your best shot to get auxillary buttons,
+   panel connectors, and the like installed, so do it now, and give them a good tighten. You shouldn't need to adjust
+   these again, so finish their installation while the pieces are free.
+    1. This of course includes decorative plates --- e.g. `misc-decorative-plate-aux-control-three-button-cluster` ---
+       you may choose to use. These are held to the top pieces by the buttons or component mounting screws.
+2. Start the top panels --- `top-panel-(inset|overhang)-*`: you want both to get the components installed now
+   when it's easy, and to make sure that the overall assembly works with your components, so again get your buttons,
+   lever, etc., in place.
+    1. If you are using a button decorative plate that spans two panels --- e.g.
+       `src/misc-decorative-plate-dir_arc-plus-w-30mm-and-sega-2p-plus-one` --- don't tighten the buttons all the way,
+       as you may need some wiggle to align the panels to the frame in a later step.
+    2. If the above isn't the case, you can tighten all your buttons now.
+    3. If using a lever, don't forget the lever mount spacer --- `src/misc-lever-mount-sanwa-seimitsu` --- if you want
+       it, and tighten those mounting bolts now as well.
+3. Create the frame box by combining your `frame-piece-*` parts together. This will be relatively stable just via
+   friction fit.
+4. Rest the frame top-up on a desk, and put the standoffs through the holes.
+5. Insert the top panels into the frame. The friction on this will probably be tight, and you may not be able to muscle
+   it in on your own. Get the panel posts at least partially into the frame columns, in any event. If you get all the
+   panels completely in, the next steps will be easier, but it's not imperative.
+6. Start the bolts for the top panels. Get it so that the bolts catch the standoffs, but don't tighten them completely.
+   You will want some wiggle when connecting the bottom panels, which is maybe the hardest part. Depending on your bolts
+   and how deep into the frame you got the top panels, you might need to push the standoffs up the column in order to
+   catch them with the bolts.
+7. At this point you have an open box with access to all your components. Do all of your wiring.
+    1. Tighten the buttons and etc. if you didn't in step 2.
+    2. TEST YOUR BOARD AND COMPONENTS NOW! You don't want to have to undo the rest of the steps for something trivial,
+       trust me.
+8. Insert the bottom panels into the frame. This may be difficult. If you got the top panels into the frame in step 4,
+   and left the bolts loose in step 5, you can make the standoffs rise outside of the frame column, which makes it
+   easier to line up the standoffs with the bottom panel posts.
+9. Drive the bottom bolts into the standoffs. You probably don't have the panels all the way into the frame, but if you
+   can at least get the standoffs in the posts, you can catch them with the bottom bolts, and then let them guide the
+   panels into the frame.
+10. Tighten all the bolts. If you didn't get the top panels flush in step 4, you can apply the same logic as in step 8
+   and tighten the bolts to guide the panels into the frame.
+
+In the end, this should be extremely sturdy. None of the frame or panels should be loose at all, and you should be able
+to move, flip, gently toss, etc. the stick without anything moving or feeling loose.
+
 ## Removing Inset Panels
 
 As of v4.1 (or in v3), the top and bottom inset panels both insert into the frame, inside the frame "lip", meaning that

docs/materials.md

@@ -1,25 +0,0 @@
-# Materials
-
-bss's random thoughts and notes on 3D printing materials.
-
-## Bambu Lab PLA
-
-### Basic
-
-* In general, nice texture, but under direct light, you can see a bit of the infill pattern through the walls. Not super
-  distracting, but it's there.
-
-#### White
-
-* Walls are practically translucent, you can almost always see the infill. Do not use for major components.
-* Looks perfectly good for thin things like the Neutrik plates, decorative pieces, that kind of thing.
-
-### Matte
-
-* I don't like the texture as much, but they do produce nice non-primary color colorways, and you don't see the infill.
-* Seems like their plastic treatment leaves some plate residue, so be better about cleaning it or you'll get ghosts.
-
-## Hatchbox PLA
-
-* **Blue:** very blue. Wife likes it.
-* **White:** more opaque than the Bambu PLA mentioned above, makes a pretty decent (still slightly translucent) frame.

docs/printing-and-materials.md

@@ -0,0 +1,67 @@
+# Printing and Materials
+
+bss's random thoughts and notes on the actual printing of the Buildable Stick System.
+
+## Printing Settings
+
+My preferred settings are 3 wall loops with 20% gyroid sparse infill. This gives the models a bit more weight and
+strength against bowing forces, but something more default, like 2 wall loops, 15% grid sparse infill, is fine and does
+not lead to a weak enclosure.
+
+### Working With Flatness
+
+A lot of the pieces are long and flat, so I recommend really dialing in your printer settings. The frame pieces make
+corner curling of the frame less of a problem, but you may still get it on the panels and the beveled frame pieces.
+
+#### Bottom Layer Notes
+
+Considering the visible layer (usually, the bottom layer) pattern is ideal. Monotonic prints fast but creates long,
+uniform lines that create reflection patterns on long, flat surfaces. This can be especially distracting for the top
+panels and their decorative plates, since they're what you're looking at 90% of the time, and the holes break up a
+perfect pattern, making the long lines stand out even more.
+
+* **Top panels:** using a non-uniform pattern reduces if not eliminates the problem of the surface catching the light,
+  but for some patterns, it may come at the expense of time. Other patterns may improve beyond monotonic, but hilbert
+  curve seems to be the gold standard.
+* **Circle-centric decorative plates:** don't use complex patterns like Archimedean chords on decorative plates, as they
+  seem to have issues with filling curves and you still want to try to maximize contact with walls. Concentric is great
+  here if you dial it in.
+
+Panels may have tiny gaps against the circular button cutouts; this is largely not a problem as buttom rims, decorative
+plates, etc. will cover it up. However, I've had some interesting results with:
+
+* Initial layer line width: 0.42mm (down .08mm)
+* Initial layer height: 0.25mm (up .05mm)
+* Initial layer nozzle temperature: 230°C (up 10°C)
+* Initial layer bed temperature: 70°C (up 5°C)
+* Initial layer pattern: concentric
+
+These are good defaults and print awesome parts, with the only exception being the top panels, which benefit from using
+a Hilbert curve initial layer pattern instead of concentric.
+
+## Materials
+
+Some notes on PLA brands, usages, etc.
+
+### Bambu Lab PLA
+
+#### Basic
+
+* In general, nice texture, but under direct light, you can see a bit of the infill pattern through the walls. Not super
+  distracting, but it's there.
+
+##### White
+
+* Walls are practically translucent, you can almost always see the infill. 3 wall loops and a varying infill pattern
+  definitely help here.
+* Looks perfectly good for thin things like the Neutrik plates, decorative pieces, that kind of thing.
+
+#### Matte
+
+* I don't like the texture as much, but they do produce nice non-primary color colorways, and you don't see the infill.
+* Seems like their plastic treatment leaves some plate residue, so be better about cleaning it or you'll get ghosts.
+
+### Hatchbox PLA
+
+* **Blue:** very blue. Wife likes it.
+* **White:** more opaque than the Bambu PLA mentioned above, makes a pretty decent (still slightly translucent) frame.