Overview

Guide to using OpenSCAD for complex machine design (e.g. CNC machines, robotics).

Template project can be found in the git repo at: OpenSCAD Machine Design Framework

Examples images from various projects:

Principles

• Integrated with github, but easily extended to other SCMs
• Supports efficient, robust collaborative design:
  • Clear naming conventions, coding styles and file structure
• Encourages reusable parts that can be shared across projects (vitamins in particular)
• Automates slow, repetitive tasks, such as:
  • STL generation
  • Assembly Guide generation with Bill of Materials (BOM)
  • Pretty pictures for Assembly Guide, website, etc
• All documentation in markdown format and HTML, so...
  • it can be rendered automatically by github
  • it is very readable
  • is printable

Tutorials

This guide is laid out as a series of tutorials that progressively introduce more complex modelling scenarios, features and concepts. There is a consistent theme through-out all the tutorials, to illustrate the typical evolution of a project from first experimental parts through to finished, published design.

The theme for the tutorials is the development of a printed quad-copter frame based around the hardware for a Hubsan X4 (i.e. motors, battery, flight-controller).

The finished tutorial project can be found on github at: https://github.com/Axford/QuadFrame

1. Basic quad frame layout with motors
   • Starting a project, python pre-requisites
   • Simple assembly of a printed part and an existing vitamin
   • Using the vitamin catalogue
   • Use of utility tools and assembly guide generation
   • Sandbox
   • Printing the STL
2. Refined frame, including battery
   • Sub-assemblies, more printed parts and more existing vitamins
   • Project config files
   • Incorporating other utility libraries
   • Documentation templates
3. Adding the flight controller
   • Defining a new simple vitamin (non-parameterised, 1 part)
   • Simple cut parts
   • Importing a 3rd party vitamin
   • Porting existing OpenSCAD code to a vitamin
   • Updating the vitamin catalogue
4. More sophisticated vitamins (parameterised, enum types)
   • Type getter functions
   • Catalogue support
   • Multi-part vitamins (STL)
   • Vitamin dependencies (utilities and sub-vitamins)
5. Design variants - different arm lengths, motor sizes, etc
   • How to incorporate design variants - machine files, assemblies, printed parts, cut parts
   • Assembly guide implications
6. Publishing, collaboration and maintenance
   • Using github, accessing docs
   • Collaboration best practises (inc dropbox)
   • Troubleshooting (esp the build process)

---

Stuff below here is out of date and needs rewriting - refer to the tutorial links above!!!

Assembly Guide

The project structure and automation tools are designed to produce an assembly guide with minimal effort. Many parts of the assembly guide are generated by the build automation tools, typically leaving just the introduction to be written separately. The guide is always named AssemblyGuide.md and is located in the root project directory.

The guide is dynamically rendered into HTML by the AssemblyGuide.htm file - this is published to the project website by the build process (via the gh-pages branch).

Build Automation

Automation tools:

• BOM Generator (bom.py)
• STL Generator (stls.py)
• Vitamins Generator (vitamins.py)
• Views Generator (views.py)
• Publisher (publish.py)

All of the above are wrapped into a single build script (build.py).

BOM Generator

Generates bill-of-material summaries for the overall project and each assembly - in individual files, in markdown format. All of the files are placed in the /bom directory. Each file has a common format:

• A list of Vitamins
• A list of Printed Parts (STL)
• A list of sub-assemblies
• A list of assembly steps

The generated markdown includes links to source files and images (generated by the other tools). The files are designed to be included into the overall Assembly Guide for the project.

STL Generator

Generates .stl files for all of the printed parts in the project and places them in the /stl directory. Also renders views of the printed parts as .png images and places them in the /images directory.

How the script works:

• Parse the /bom/bom.md file for links to .stl parts, add them to a list
• Parse the /assemblies/*.scad files, look for module names that match the required part (and end in _STL), for each:
  • Create a temp .scad file calling the part and execute openscad to render it to an .stl file in the /stl directory
  • Execute a temp .scad file calling the _View module for the part - if it exists and defines a valid view:
  • Render the part, using the specified view parameters, as a .png and place in the /images directory

Vitamins Generator

Generates .stl files for the vitamins in the project and places them in the /vitamins/stl directory. Also renders views of the vitamins as .png images and places them in the /vitamins/views directory.

How the script works:

• Parse the /bom/bom.md file for links to .scad files, extract the vitamin name and type name, add them to a list
• Parse the /vitamins/*.scad files, look for file/module names that match the required vitamin, for each file (and each vitamin type):
  • Execute a temp .scad file calling the _Parts module for the vitamin, and passing in the type name. For each "echo'd" part:
    • Create a temp .scad file calling the vitamin part (passing the type name) and execute openscad to render it to an .stl file in the /vitamins/stl directory
  • Execute a temp .scad file calling the _View module for the vitamin (passing the type name) - if it exists and defines a valid view:
  • Render the vitamin, using the specified view parameters, as a .png and place in the /vitamins/views directory

Views Generator

Renders miscellaneous views as PNG images and places them in the /images directory.

How STLs and Vitamins differ:

Automation Tool	STL	Vitamin
BOM Generator	Placed in the printed parts list	Placed in the vitamins list
Thumbnail view	Placed in the /images dir	Place in the vitamins/views directory, one image per vitamin variant(type)
STL Generator	Placed in the /stl dir ready for printing	Placed in the vitamins/stl directory and used to accelerate on-screen rendering, one STL per vitamin sub-part per variant (type)
AssemblyGuide	Auto-linked to a 3D viewer	not linked

Continuous Integration and Deployment

Teams should use normal git best practices for collaboration - the Shared Repository model is a good place to start. Team members create topic branches for whatever aspect they are working on, then submit a pull request back to the master branch when they are finished.

Pull requests are automatically cloned and validated. If they pass, then they are merged into master. If they fail, then the validation report is posted as a comment against the pull request.

Commits to the master branch trigger the deployment process. The master branch is cloned, re-validated and if the validation passes without errors, then the web content is automatically published (pushed to the gh-pages branch).

NB: Validation reports are in markdown format and are committed back to the master branch prior to publishing to gh-pages.

Flow:

• Static analysis (lint style) - rules vary by .scad type (e.g. assembly, vitamin). Should include checking for various interface modules (e.g. _View)
• Log and .csg analysis - using Openscad output log and dummy.csg
• BOM generation - report errors
• Vitamin STL generation
• Vitamin view rendering
• STL generation
• STL view rendering
• Other views rendering - includes all auto-generated assembly step views
• Build validation report
• If validating a pull request:
  • If errors, then comment against pull request
  • Else, merge pull request
• Else:
  • Auto-commit results back to master
  • If no errors, Publish web content (to gh-pages branch)
• Broadcast notification (twitter)

The ci scripts manage the working clones in a parallel git repo with the Staging suffix. For instance:

• Normal local repo (for dev work): /repos/LogoBot
• ci repo (for cloning and validation): /repos/LogoBotStaging

It's important to execute the ci script from the normal repo!

Static Analysis Rules

Root .scad

Validate...

• Inclusion of global config file

Assemblies

For each scad file in /assemblies - validate...

• Filename format
• Module name matches filename
• Assembly module contains step() calls
• File does not contain any include or use statements
• Any variables have correct naming convention
• Any supplementary modules have correct naming convention
• Any functions have correct naming convention
• Any included _STL modules have associated _View modules
• _View modules contain an echo line with correct structure
• Exists in /config/assemblies.scad

Config

• All utils.scad includes exist, no use statements, no variables
• All vitamins.scad includes exist, no use statements, no variables
• All assembles.scad includes exist, no use statements, no variables
• colors.scad - correct naming conventions

Vitamins

For each .scad file in /vitamins - validate...

• Filename format
• Module name matches filename
• Module accepts a single parameter, or none
• Any include or use statements are within the /vitamins directory or a sub-directory
• Any variables have correct naming convention
• Any supplementary modules have correct naming convention
• Any functions have correct naming convention
• Contains a _View module that accepts a single parameter, or none
• _Part modules contain echo lines with correct structure, and that those echo contents exist as modules
• _View modules contain an echo line with correct structure
• Exists in /config/vitamins.scad

Views

None

Log/CSG Analysis Rules

All

• No syntax errors
• No warnings
• dummy.csg is produced
• dummy.csg contains more than empty group (or groups)

Assemblies

Check global rules, when the assembly module is called.

Vitamins

Check global rules, when the following are called:

• Vitamin module
• _Parts module
• _View module
• any defined Parts

BOM Generation

• Check all referenced .scad files and modules exist - is that done here? or later?

References

• Mendel90 design
• http://www.cannymachines.com/entries/9/openscad_dimensioned_drawings