# How to Design a Robot 3D Model with an LLM and Free CAD: Step-by-Step Guide

> AI Release · @ai_releaseorg · https://ai-release.org/guides/kak-sproektirovat-3d-model-robota-s-pomoschyu-llm-i-bes_en.html

## TL;DR

- **Time to complete:** 60–90 minutes (two thirds of it goes into the JSON spec, not into CAD)
- **Difficulty:** Intermediate
- **You'll need:** FreeCAD (free, open source, ships the `freecadcmd` CLI and a Python console) **or** OpenSCAD (free, script-driven CAD); any LLM chat model or a self-hosted one; Python 3 (bundled with FreeCAD); a slicer to sanity-check the exported STL; ~200 MB of free disk space.

## What you'll get

- `robot_spec.json` — one machine-readable file holding every dimension of the robot; the only thing you edit later.
- `build_robot.py` — a FreeCAD macro that turns the spec into solids and exports `out/robot_body.step` + `out/robot_body.stl`.
- `bracket.scad` — a parametric OpenSCAD file for the small parts (servo brackets, hubs), built with `-D` overrides.
- A numeric verification pass (bounding box, part count, triangle count) that fails loudly instead of producing a pretty but wrong mesh.

The deliverable is deliberately **not** a mesh. Anyone can ask a model for "a robot STL" and get an unparameterised blob that cannot be edited, cannot be rebuilt, and cannot be checked. The angle here: the LLM never emits geometry — it emits a *specification* plus a *script*, and a script is something you can assert against. The two failure modes you are avoiding are (a) a model that quietly invents datasheet values, and (b) a mesh that looks fine in a viewer but is not watertight.

## Quick start

```bash
mkdir -p ~/robot-cad/out && cd ~/robot-cad
printf '%s\n' 'difference(){ cylinder(h=6,d=40,$fn=64); cylinder(h=6,d=6,$fn=32);}' > wheel_hub.scad
openscad -o out/wheel_hub.stl wheel_hub.scad
ls -l out/wheel_hub.stl
```

Details and checks — in the steps below.

## Prompt to copy

```prompt
You are a mechanical design assistant. Output ONE JSON object and nothing else: no prose, no markdown fences, no comments.

Task: convert the robot description below into a parametric specification that a CAD script will consume.

Rules:
1. Every dimension is a bare number in millimetres, degrees, or grams. Never put units inside a value.
2. Every part gets a unique "id" (lowercase snake_case) and a "parent" field.
3. Do not invent part numbers, vendor names, prices, or datasheet values. If a value is unknown, set it to null and add the key to "open_questions".
4. Keep "clearance_mm" as a single top-level value; do not repeat it per part.
5. Do not output geometry, vertex coordinates, meshes, or code.

Required schema:
{
  "schema_version": 1,
  "robot": {"name": str, "drive": "differential", "wheel_count": int},
  "units": {"length": "mm", "angle": "deg"},
  "clearance_mm": number,
  "chassis": {"length_mm": n, "width_mm": n, "height_mm": n, "wall_mm": n},
  "links": [{"id": str, "parent": str|null, "kind": "chassis|bracket|wheel|hub|sensor_mount",
             "bbox_mm": [n, n, n],
             "mount_holes": [{"d_mm": n, "x_mm": n, "y_mm": n}]}],
  "joints": [{"id": str, "type": "fixed|revolute", "parent": str, "child": str,
              "axis": [n, n, n], "origin_mm": [n, n, n]}],
  "open_questions": [str]
}

Robot description:
<describe your robot here: payload, drive type or wheel diameter, battery pack size, which sensors must be mounted, and your printer build volume>

Output the JSON now.
```

Replace before sending: `<describe your robot here …>` (payload, drive, battery, sensors, printer volume) and, optionally, the `kind` list if your robot has parts that do not fit those five categories.

## Requirements and setup
![Illustration: Requirements and setup](https://ai-release.org/guides/img/kak-sproektirovat-3d-model-robota-s-pomoschyu-llm-i-bes-en-1.jpg?v=1795337466)


- Linux, macOS, or Windows. The commands below are bash; on Windows use the same binaries from PowerShell with `\` replaced by `` ` ``.
- FreeCAD installed and its CLI on `PATH` (`freecadcmd` on Linux/macOS, `FreeCADCmd.exe` on Windows). Check the exact binary name for your build in the FreeCAD documentation — it differs between packages.
- OpenSCAD installed if you want the small-parts workflow (`openscad` CLI).
- Python 3 available as `python3`. FreeCAD bundles its own interpreter; do not mix them (see Troubleshooting).
- An LLM endpoint. If the spec must not leave your machine, run the model yourself — the setup is described in [How to add AI to your home server](https://ai-release.org/guides/kak-podklyuchit-ii-k-domashnemu-serveru-poshagovoe-ruko.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

Pre-flight checklist:

- [ ] `freecadcmd --version` prints a version line (run `FreeCADCmd --version` on Windows)
- [ ] `openscad --version` prints a version line
- [ ] `python3 --version` prints 3.x
- [ ] `mkdir -p ~/robot-cad/out` succeeds
- [ ] You know your printer's build volume in mm

**Example:** on a clean Linux box `freecadcmd --version` returns one line starting with the release number; if the shell answers `command not found`, the CLI is not on `PATH` and the rest of the guide will fail at Step 2.

## Step 1. Turn the robot description into a JSON spec

**What to do:** send the prompt above to your model, save the reply verbatim as `robot_spec.json`, then validate it before touching CAD.

**Why:** a JSON spec is diffable, reviewable and re-runnable. When the battery changes size you edit one number instead of re-prompting and hoping the model returns the same robot. Validation catches the one thing models do badly here: filling unknown values with plausible-looking numbers.

**Example** of an accepted spec (trimmed):

```json
{
  "schema_version": 1,
  "robot": {"name": "diffbot_v1", "drive": "differential", "wheel_count": 4},
  "units": {"length": "mm", "angle": "deg"},
  "clearance_mm": 0.2,
  "chassis": {"length_mm": 160, "width_mm": 120, "height_mm": 45, "wall_mm": 3},
  "links": [
    {"id": "chassis_plate", "parent": null, "kind": "chassis", "bbox_mm": [160, 120, 5],
     "mount_holes": [{"d_mm": 3.2, "x_mm": 15, "y_mm": 15}]},
    {"id": "servo_bracket_fl", "parent": "chassis_plate", "kind": "bracket", "bbox_mm": [40, 20, 25],
     "mount_holes": [{"d_mm": 2.5, "x_mm": 20, "y_mm": 10}]}
  ],
  "joints": [
    {"id": "j_wheel_fl", "type": "revolute", "parent": "chassis_plate",
     "child": "servo_bracket_fl", "axis": [0, 1, 0], "origin_mm": [70, 50, 0]}
  ],
  "open_questions": ["battery pack dimensions"]
}
```

`clearance_mm` is the air gap left between mating printed parts; `0.2` is a starting value, not a measured one — confirm the right value for your printer and material in its documentation and tune it with a test print.

**How to check:**

```bash
python3 -c "import json;d=json.load(open('robot_spec.json'));print(len(d['links']),'links');print(d['open_questions'])"
```

Expected output on the example above:

```
2 links
['battery pack dimensions']
```

If `open_questions` is not empty, resolve each item (measure the battery, ask the vendor, check the datasheet) and patch the JSON **before** Step 2. An unresolved question always becomes a wrong wall thickness later.

## Step 2. Generate the CAD script and build headless
![Illustration: Step 2. Generate the CAD script and build headless](https://ai-release.org/guides/img/kak-sproektirovat-3d-model-robota-s-pomoschyu-llm-i-bes-en-2.jpg?v=1795337473)


**What to do:** ask the model to convert the spec into a FreeCAD macro, save it as `build_robot.py`, run it with the FreeCAD CLI. Small parts go through OpenSCAD instead.

**Why:** running the build from the CLI makes the model reproducible — same spec in, same STEP out, no GUI clicks to forget. FreeCAD's Python API is the bridge: `Part.makeBox` and friends build solids, `Import.export` writes STEP (a precise interchange format), `Mesh.export` writes STL (what the slicer eats).

```python
# build_robot.py — run with: freecadcmd build_robot.py
import json, os
import FreeCAD as App
import Part, Mesh, Import

spec = json.load(open("robot_spec.json"))
ch = spec["chassis"]
doc = App.newDocument("robot")

plate = Part.makeBox(ch["length_mm"], ch["width_mm"], ch["height_mm"])
Part.show(plate, "chassis_plate")
obj = doc.getObject("chassis_plate")

os.makedirs("out", exist_ok=True)
Import.export([obj], "out/robot_body.step")
Mesh.export([obj], "out/robot_body.stl")

bb = obj.Shape.BoundBox
assert abs(bb.XLength - ch["length_mm"]) < 0.01, bb.XLength
assert abs(bb.YLength - ch["width_mm"]) < 0.01, bb.YLength
print("OK bbox", bb.XLength, bb.YLength, bb.ZLength)
print("OK parts", len(spec["links"]))
```

Module and function names in the FreeCAD Python API (`Import.export`, `Mesh.export`) have been stable for a while, but confirm them against the FreeCAD Python API documentation for your build before relying on them in CI.

For a bracket, OpenSCAD keeps the parameters in one place and lets you override them from the command line:

```scad
// bracket.scad — servo bracket driven by robot_spec.json values
w = 40; d = 20; h = 25; wall = 3; hole_d = 2.5; eps = 0.01;
difference() {
  cube([w, d, h]);
  translate([wall, wall, -eps]) cube([w - 2*wall, d - 2*wall, h + 2*eps]);
  translate([w/2, d/2, -eps]) cylinder(h = h + 2*eps, d = hole_d, $fn = 32);
}
```

```bash
freecadcmd build_robot.py
openscad -o out/servo_bracket_fl.stl -D 'wall=3' -D 'hole_d=2.5' bracket.scad
```

The `-D` flags set variables at build time, so one `.scad` file serves every bracket size in the spec. If you want this prompt→script step to run unattended next to a model server, the deployment pattern is in [How to Deploy a Local LLM on Kubernetes](https://ai-release.org/guides/kak-razvernut-lokalnuyu-ii-model-na-kubernetes-poshagov.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

**How to check:**

```bash
echo $?; ls -l out/
```

Expected: `0`, then `robot_body.step`, `robot_body.stl` and `servo_bracket_fl.stl` with non-zero sizes, and the line `OK bbox 160.0 120.0 45.0` printed by the assertions. A `0`-byte STL means the export ran before the shape existed.

## Step 3. Verify the model numerically and in the slicer
![Illustration: Step 3. Verify the model numerically and in the slicer](https://ai-release.org/guides/img/kak-sproektirovat-3d-model-robota-s-pomoschyu-llm-i-bes-en-3.jpg?v=1795337477)


**What to do:** run the table below, then drop the STL into your slicer and confirm the holes and the build volume.

**Why:** the viewer shows you a shaded surface; it does not tell you the part is 3 mm too wide or that the STL is empty. Numeric checks fail fast, and the slicer is the closest thing to the real print.

| Check | Command | Pass condition |
|---|---|---|
| Spec parses | `python3 -c "import json;json.load(open('robot_spec.json'))"` | exit code `0`, no output |
| Part count matches spec | `python3 -c "import json;print(len(json.load(open('robot_spec.json'))['links']))"` | equals the `OK parts` line from Step 2 |
| STL is not empty | see snippet below | `triangles:` > 0 |
| Bounding box | `freecadcmd build_robot.py` | `OK bbox <L> <W> <H>` matching `chassis` |
| Fits the printer | slicer → object dimensions | ≤ build volume on all axes |

```bash
python3 - <<'PY'
import struct
with open("out/robot_body.stl", "rb") as f:
    f.seek(80)
    print("triangles:", struct.unpack("<I", f.read(4))[0])
PY
```

**Example:** the snippet prints `triangles: 12` for a plain box — a box has 12 triangles. If it prints `triangles: 0`, the export wrote a header but no geometry; re-run Step 2 and read the assertion output.

Final success looks like: three files in `out/`, `OK bbox` and `OK parts` lines in the terminal, and a slicer preview where the mount holes are open on both faces and the part sits inside the bed outline.

## Troubleshooting

**Problem. The build script dies before creating anything.**
- Ошибка: `ModuleNotFoundError: No module named 'FreeCAD'`
- Причина: you ran the file with the system `python3` instead of the FreeCAD interpreter. The `FreeCAD` module only exists inside FreeCAD's bundled Python.
- Решение: run `freecadcmd build_robot.py` (or `FreeCADCmd build_robot.py` on Windows). Keep plain `python3` for JSON-only checks.

**Problem. OpenSCAD exports a file but the slicer shows holes in the surface.**
- Ошибка: `WARNING: Object may not be a valid 2-manifold and may need repair!`
- Причина: two solids share a face exactly, so the boolean leaves coincident surfaces. The `-eps` offsets in the bracket script exist for this reason.
- Решение: push every subtracted volume at least `eps = 0.01` mm past the surface (`translate([..., -eps])`) and re-run `openscad -o out/servo_bracket_fl.stl bracket.scad`; the warning disappears and the slicer reports the model as manifold.

**Problem. A boolean between two solids fails.**
- Ошибка: `<class 'Part.OCCError'>: BRep_API: command not done`
- Причина: the cutting tool is tangent to the target — same height, same edge, or zero overlap. The kernel refuses degenerate results.
- Решение: extend the tool by `eps` on the cutting axis, e.g. make a hole cylinder `h + 2*eps` tall, then rebuild with `freecadcmd build_robot.py`. Exact wording of the message depends on the OpenCASCADE build — check the documentation if yours differs.

## Summary and next steps

You now have a spec-driven robot model: edit `robot_spec.json`, re-run two commands, and the STEP/STL rebuild with assertions guarding the dimensions. Next, extend the spec with the joints you skipped and add a second assertion for every hole diameter the screws depend on.

## FAQ

**Can this be done fully offline?**
Yes. The prompt only asks for a JSON object, so any local model works, and FreeCAD/OpenSCAD build without a network connection. The only online step is the model call, which you can replace with a self-hosted endpoint.

**Why not just ask the LLM for an STL file?**
Because mesh output cannot be parameterised or checked. A model that writes a script you can assert against gives you a rebuildable model; a mesh gives you one unverifiable blob per prompt.

**How do I change one dimension later?**
Edit the single number in `robot_spec.json` and re-run `freecadcmd build_robot.py` and the `openscad -D` line. Everything downstream — bounding box, hole positions, export — is derived from the spec.

**What if the chassis is larger than my printer bed?**
Split it in the spec: give the chassis two or more `links` whose bounding boxes each fit the build volume, and add a `joint` connecting them. The build script then exports one STL per link, and you print and bolt them together.
