Team Configuration

Customize PenguinCAM for your team's specific CNC machines by uploading a PenguinCAM-config.yaml file to your Onshape documents.

Quick Setup

Configuration Structure

Team Information

Identify your team. This appears in logs and helps us provide support:

team:
  number: 1234
  name: "Your Team Name"

Machine Definitions

Define one or more CNC machines. If you have multiple machines (e.g., a smaller one for prototyping), you can configure each with different settings:

machines:
  main_cnc:
    name: "Omio X8-2200"

    machine:
      dimensions:
        x_max: 22.2    # Work envelope in inches
        y_max: 30.3
        z_max: 3.3

Park Position (Machine Coordinates)

Configure where the machine parks at the end of programs for safe part access. These use G53 (machine coordinates), not work coordinates:

park_position:
  x: 0.5       # X position in machine coords
  y: 0.5       # Y position in machine coords
  z: -0.5      # Z safe clearance below home

Default Tool

Set the default tool diameter that appears when loading a new part:

default_tool:
  diameter: 0.157    # 4mm end mill

Z-Axis Reference System

Configure how deep to cut and safe heights for tool changes:

z_reference:
  sacrifice_board_depth: 0.008    # Cut 0.008" into sacrifice board
  safe_height: 1.5                # Rapid height for tool changes
  clearance_height: 0.5           # Clearance above stock

Material Presets

Define materials with appropriate feed rates and speeds for your machine's rigidity:

materials:
  plywood:
    name: "Plywood"
    feed_rate: 60.0              # Cutting feed rate (IPM)
    ramp_feed_rate: 40.0         # Feed rate for ramping into material
    plunge_rate: 15.0            # Plunge feed rate
    ramp_start_clearance: 0.05   # Clearance before ramping
    ramp_angle: 4.0              # Ramp angle (degrees)
    stepover_fraction: 0.25      # Stepover as fraction of tool diameter

Tab Settings

Configure how parts are secured during perimeter cutting. Two strategies are available:

tabs:
  enabled: true     # Use automatic tabs (they're removed at the end)
  width: 0.25       # Tab width (inches)
  height: 0.15      # How much material left in tab

fixturing:
  pause_before_perimeter: false  # If true, skip tabs and pause for manual fixturing

Choose one strategy:

• Automatic tabs (enabled: true): Tabs are placed automatically and removed as the final step. No manual intervention needed.
• Pause for fixturing (pause_before_perimeter: true): No tabs are placed. Program pauses (M0) before perimeter cut to allow fixturing through milled holes.

Multiple Machines

If your team has multiple CNCs, define each in the config:

version: 2
default_machine: main_cnc

machines:
  main_cnc:
    name: "Main CNC (Omio X8)"
    machine:
      dimensions:
        x_max: 22.2
        y_max: 30.3
    materials:
      plywood:
        feed_rate: 60.0

  prototype_cnc:
    name: "Prototype CNC (Smaller)"
    machine:
      dimensions:
        x_max: 12.0
        y_max: 12.0
    materials:
      plywood:
        feed_rate: 40.0    # Slower for less rigid machine

Users can select which machine to use from the UI dropdown (if more than one is configured).

Google Drive Integration

To enable automatic uploads to Google Drive, configure your Drive folder ID:

google_drive:
  enabled: true
  folder_id: "your-folder-id-here"
  folder_name: "CNC Programs"

To find your folder ID:

1. Open Google Drive and navigate to the folder where you want programs saved
2. Copy the folder ID from the URL:
   https://drive.google.com/drive/folders/ABC123xyz
3. Paste the ID into your config file

Advanced Settings

Hole Detection

Control how PenguinCAM detects and machines holes:

holes:
  detection_tolerance: 0.0001         # Circularity tolerance
  min_millable_multiplier: 1.2        # Min hole = 1.2× tool diameter

Pocket and Hole Contouring

For large through-cut features, PenguinCAM can contour the perimeter instead of fully clearing the interior. This saves significant machining time, with the trade-off that the center material must be removed manually afterward (it's held in place by tabs).

pockets:
  contour_threshold: 510    # Area threshold for contouring

The threshold determines when a feature is large enough to benefit from contouring. The formula is:

threshold_area = contour_threshold × tool_diameter² × stepover_percentage

This means tighter stepover (aluminum) has a lower threshold and will contour smaller features, since those features take many more passes to clear. With the default threshold of 510:

• Aluminum (25% stepover): Contours features larger than ~2.0" diameter
• Plywood (65% stepover): Contours features larger than ~3.2" diameter
• Polycarbonate (55% stepover): Contours features larger than ~3.0" diameter

Tube Facing

For teams that machine aluminum tube, configure tube-specific parameters:

tube_facing:
  depth_margin: 0.005               # Extra depth beyond half-height
  max_roughing_depth: 0.3           # Roughing pass depth
  max_finishing_depth: 0.51         # Finishing pass depth

Version 1 vs Version 2

PenguinCAM supports two config formats:

Version 1 (Legacy)

Single machine, flat structure. Still supported for backwards compatibility:

# No version field = Version 1
team_number: 1234
team_name: "Your Team"
machine_x_max: 24.0
machine_y_max: 24.0

Version 2 (Current)

Multiple machines, nested structure. Recommended for new configs:

version: 2
default_machine: main_cnc
machines:
  main_cnc:
    name: "Main CNC"
    ...

If you have an old Version 1 config, it will continue to work. Upgrade to Version 2 to support multiple machines or per-machine material settings.

Validation

When PenguinCAM loads your config, it will:

• Use your custom values where provided
• Fall back to Team 6238 defaults for any missing values
• Display warnings in the UI if materials are incomplete

Check the browser console (F12) after authenticating to see which config was loaded:

✅ Team config loaded: Your Team Name (#1234)

Troubleshooting

Config not loading

If PenguinCAM shows "Using default settings" instead of your config:

• Verify the filename is exactly PenguinCAM-config.yaml (case sensitive)
• Check that the document is shared with your team/organization in Onshape
• Verify the document is shared with the PenguinCAM app (use "Share with applications" tab in Onshape sharing dialog)
• Ensure you're authenticated with Onshape (click the login button)
• Verify the file is valid YAML (use a YAML validator online)

Material shows warning

If you see "⚠️ This material has incomplete settings", it means your config defines the material but is missing some required parameters (feed rate, plunge rate, etc.). The missing values will use plywood defaults.

Multiple teams see the same config

This can happen if your config file is shared publicly. PenguinCAM now filters configs by ownership:

• Only configs owned by your company/organization are used
• If you see someone else's config, verify your file is in your company's Onshape documents
• Don't share your config file publicly - keep it in your team/company folder

Example Configs

Basic Config (Single Machine)

version: 2
default_machine: cnc

team:
  number: 1234
  name: "Your Team Name"

machines:
  cnc:
    name: "Team CNC"

    machine:
      dimensions:
        x_max: 24.0
        y_max: 24.0
        z_max: 4.0

    default_tool:
      diameter: 0.157

    materials:
      plywood:
        name: "Plywood"
        feed_rate: 60.0
        plunge_rate: 15.0

      aluminum:
        name: "Aluminum"
        feed_rate: 45.0
        plunge_rate: 10.0

Multi-Machine Config

version: 2
default_machine: big_cnc

team:
  number: 1234
  name: "Your Team"

machines:
  big_cnc:
    name: "Competition Machine"
    machine:
      dimensions:
        x_max: 48.0
        y_max: 96.0
    materials:
      plywood:
        feed_rate: 80.0

  small_cnc:
    name: "Prototype Machine"
    machine:
      dimensions:
        x_max: 12.0
        y_max: 12.0
    materials:
      plywood:
        feed_rate: 40.0