Fusion Bridge

Use this skill when interacting with a Fusion 360 Bridge environment.

Quick start

1. This skill is tied to the official Fusion 360 Bridge repository:
   • https://github.com/smicbee/fusion-360-bridge
   • Use this repo as the source of truth for both the add-in and the OpenClaw plugin.
2. Install the Fusion add-in:
   • Option A (preferred): git clone https://github.com/smicbee/fusion-360-bridge.git
   • Option B: download the repository ZIP from GitHub Releases.
   • Copy fusion-addin/FusionBridge into your Fusion add-ins directory:
     • Windows: %appdata%\\Autodesk\\Autodesk Fusion\\API\\AddIns\\
     • macOS: ~/Library/Application Support/Autodesk/Autodesk Fusion/API/AddIns/
3. Install the OpenClaw plugin from the same repo:

   openclaw plugins install --link <path-to-repo>/openclaw-plugin
   

4. Start/launch Fusion 360 add-in (FusionBridge) and verify it is running.
5. Check GET /ping first, then GET /state.
6. Prefer helper-style snippets for common tasks.
7. Keep raw Python as the fallback whenever a helper is missing or too limiting.

Network requirement for OpenClaw

The bridge listens on TCP port 8765 (inside the repo: 0.0.0.0:8765 by default). OpenClaw must be able to reach this host/port from the machine it runs on.

Workflow

1. Verify bridge health

Check these in order:

• /ping
• /state
• /logs if something looks wrong

If the bridge is not reachable remotely but works locally, suspect bind-address or host firewall.

2. Choose execution style

Use one of these two modes:

• Helper-style Python for repeatable tasks like listing components, showing messages, creating simple geometry, or reading document info.
• Raw Python when the task is custom, exploratory, or needs full Fusion API power.

Do not force a DSL when raw Python is the better fit.

3. Send code with /exec

POST /exec accepts:

• code as a Python string
• optional timeoutSeconds

Current rule for this bridge:

• raw Python is allowed
• code length is not artificially capped
• execution time is capped at 300 seconds

Modeling strategy for future CAD work

When building or modifying geometry through the bridge, prefer this order:

1. Read the sketch carefully and restate the model in words first

   • body size
   • hole positions
   • top/bottom feature intent
   • symmetry or non-symmetry
   • explicit uncertainties

2. Convert all dimensions into one unit system before coding

   • for this bridge/Fusion API flow, use centimeters in code when working with createByReal(...)
   • say the millimeter values back to the user before building if there is ambiguity

3. Build in layers, not in one giant script

   • base body
   • hole pattern
   • top-side features
   • bottom-side features
   • final cleanup/visibility

4. Verify after each layer with machine-readable output

   • print/result body names
   • inspect body count
   • inspect bounding boxes or face counts if needed
   • use /logs when behavior is surprising

5. Avoid blocking popups during the middle of a long build

   • use print(...) and result = ... during the build
   • only use ui.messageBox(...) at the end or for deliberate checkpoints

6. Prefer robust geometry operations over elegant but fragile ones

   • if a direct Hole/Extrude/Cut API path behaves inconsistently in the current Fusion build, fall back to more reliable construction methods
   • prioritize “works reliably on this machine” over ideal API purity

7. Keep old attempt bodies from confusing review

   • rename the newest intended body clearly
   • hide old experiment bodies after a successful iteration
   • do not assume visual output is wrong until old overlapping bodies are ruled out

8. Use helper functions for repetitive work, but keep raw Python available

   • helpers for common tasks
   • raw Python for custom geometry or API workarounds

Lessons learned from the Peroxo disc modeling session

Use these rules when a user iteratively describes a small rotational part with recesses/pads from photos.

1. Freeze known-good milestones

• When the user says a state is correct, treat that body as a checkpoint.
• Keep the checkpoint body visible or easy to restore by name.
• For this session, Peroxo_Disc_V9 became the accepted rollback point.
• When experimenting after a confirmed checkpoint, prefer creating a new body/version instead of mutating the accepted one too aggressively.

1b. Prefer photos plus concrete verbal descriptions

• Ask for photos from multiple angles whenever the geometry is not fully obvious.
• Treat good plain-language descriptions as first-class modeling input, not just measurements.
• Specifically ask about:
  • which face is front/back/top/bottom
  • whether a feature is a recess or a protrusion
  • whether a hole is blind or through
  • whether arcs/roundings bulge inward or outward
• If the user can provide both images and concise descriptions, use both; that combination is much more reliable than either one alone.

2. Separate "blind recess" from "through-hole"

Do not collapse these into one feature unless the user explicitly says they are the same.

For stepped hole language like:

• "the first hole stops before the bottom plate"
• "in the bottom plate there is another 5 mm hole that goes completely through"

model it as:

• one blind recess from the top
• one separate through-hole in the remaining bottom plate

Restate that distinction back to the user before coding if there is any ambiguity.

3. Verify geometry, not just intent

After each critical operation, inspect the resulting body instead of assuming the feature landed correctly.

Useful checks:

• bounding box changed in the expected direction
• expected cylindrical face radius exists
• expected planar face exists at the intended offset
• old bodies are hidden so visuals are not misleading

For example:

• an obround pad extruded on the wrong face may leave the outer bounding box unchanged
• a "5 mm hole" may be missing even if the script succeeded; verify a cylinder with radius 0.25 cm exists

4. Be careful with Fusion face orientation and axes

In this environment, revolve/extrude results may not line up with the intuitive axis you first imagine.

Do not assume:

• PositiveExtentDirection always means "outward"
• the obvious top/bottom face is still planar after multiple edits
• the sketch plane orientation matches your mental picture

Instead:

• inspect the body's bounding box before/after
• inspect planar face origins/normals
• inspect cylinder axes/radii
• if needed, create only the sketch first, let the user confirm it, then extrude

Concrete rule from the Peroxo session:

• after extruding a rear pad/boss, immediately verify the body's rear-most extent changed in the intended direction
• for this kind of part, the accepted manual correction showed the rear pad extends to about y = -0.25 cm, while the main bottom-plate plane sits at about y = -0.1 cm
• if the bounding box stays unchanged, the pad did not land on the exterior
• if the pad grows in the opposite direction, stop and inspect the actual rear-most planar face instead of retrying the same sign blindly
• when a user manually corrects the direction in Fusion, inspect the resulting face origins/areas and encode that pattern into the next attempt
• do not stop at "which way is outward"; also identify which plane is the reference plane for the feature
• in this session, the crucial mistake was extruding from the wrong rear plane even after inspecting the normal correctly
• for multi-level backsides, distinguish explicitly between:
  • main body bottom plane
  • intermediate rear plane(s)
  • outermost boss/pad plane
• when the user manually fixes the part, measure those plane levels and preserve that stack instead of re-deriving it from memory

5. For obround/capsule pads, confirm the sketch before extrusion

For rear pads shaped like an obround/capsule:

• sketch first
• verify the top arc bulges toward the top and the bottom arc toward the bottom
• only then extrude

A reliable pattern is:

• draw the two straight side lines
• draw the top arc with an explicit top midpoint
• draw the bottom arc with an explicit bottom midpoint
• include the center reference hole in the sketch if it helps review

In this session, naming the sketch (Peroxo_rear_obround_sketch) and getting user confirmation before extrusion prevented more guesswork.

6. Mutate less once geometry gets dirty

After several cuts/joins, faces may become torus/NURBS fragments and stop being easy to target.

When that happens:

• stop patching the same body repeatedly
• rebuild a fresh clean version from the last confirmed interpretation
• keep the old body hidden for fallback

This is often faster and safer than trying to repair heavily fragmented topology.

7. Prefer narrow changes after user correction

When the user says:

• "only change the pad"
• "go back to the state before that"
• "leave the outer shape alone"

make the smallest possible change.

Do not combine unrelated fixes in one step. In particular, do not simultaneously:

• change side-wall height
• reinterpret the hole structure
• and modify the rear pad

unless the user explicitly asked for all three.

Operating rules

• Treat the bridge as open inside a trusted environment.
• Prefer concise snippets, but allow large scripts when needed.
• When debugging, inspect /logs before making architectural guesses.
• When testing UI behavior, sending ui.messageBox(...) through /exec is valid and useful.
• If remote access fails while local access works, check whether the bridge is bound to LAN and whether Windows Firewall is blocking port 8765.

Known environment facts

• The bridge exposes /state including pumpMode, queueSize, and busy.
• Default runtime port is 8765.
• The exposed tools are GET /ping, GET /state, GET /logs, and POST /exec.

Read these references when needed

• For endpoint contract and timeout behavior: references/api.md
• For practical request patterns and ready-to-send snippets: references/recipes.md

Response style for future use

When using this skill later:

• first confirm reachability quickly
• then act, instead of re-explaining the whole architecture
• mention helper-style options, but preserve raw Python as the default escape hatch

OpenClaw Plugin integration

This repository also ships an OpenClaw plugin at openclaw-plugin/ and it must be used with the same Fusion Bridge repo above. When installed, prefer these tool names instead of manually calling endpoints:

• fusion_bridge_ping
• fusion_bridge_state
• fusion_bridge_logs
• fusion_bridge_exec

Install from the same source:

cd <path-to-fusion-360-bridge>
openclaw plugins install --link ./openclaw-plugin

Example assumptions for plugin use:

• baseUrl points to the machine running Fusion 360 (default http://localhost:8765).
• If running remote, that machine must be reachable on TCP port 8765.