#Kerfio CNC v1.0.0 — Expanded Application Definition, CNC Guide, UI Help & Getting Started Manual

Project: Kerfio CNC
Version: v1.0.0
Document type: Product definition + user guide + UI reference
Target users: CNC operators, makers, developers, machine builders, and technical users
Primary platform: Desktop app built with Tauri + React/TypeScript, supported by a local Python backend and Raspberry Pi vision node

#Table of Contents

1. What Is Kerfio CNC?
2. Core Product Idea
3. Main Application Components
4. Main User Workflow
5. Getting Started
6. Safety Philosophy
7. Main UI Navigation
8. Dashboard / Home
9. Kerf Section
10. Sketch Section
11. G-code Section
12. Machine Section
13. Camera / Vision Section
14. Job Section
15. Probe Section
16. Macros Section
17. Console Section
18. Settings Section
19. Projects and Recent Work
20. Kerfio AI Assistant
21. Raspberry Pi Vision Node
22. Python Background Service
23. Data Stored in SQLite
24. UI Forms Reference
25. Tool Reference
26. Recommended First-Time Setup Flow
27. Common Workflows
28. Validation, Alerts, and Blocking Conditions
29. File Types
30. Feature Priority for v1.0.0
31. Future Expansion

#What Is Kerfio CNC?

Kerfio CNC v1.0.0 is a modern CNC control and vision-assisted manufacturing application.

It is designed to combine:

• CNC machine control
• G-code sender functionality
• simple 2D sketching
• layered CNC preparation
• live camera view from Raspberry Pi
• vision-assisted positioning
• toolpath preview
• machine state monitoring
• AI-guided help and safe action preparation

Kerfio is not only a G-code sender. It is designed to become a visual CNC operating environment.

The main idea is:

The user should be able to see the real CNC workspace, prepare geometry, assign CNC actions, align work visually, validate safety, preview the toolpath, and run the job with confidence.

#Core Product Idea

Kerfio CNC is built around this workflow:

Sketch → Kerf → Preview → Dry Trace → Run → Inspect

Alternative workflows:

Fusion 360 / SVG / DXF → Kerf → Assign Actions → Generate Toolpath → Run

Existing G-code → G-code Preview → Validate → Run

Camera View → Align Design → Set Work Origin → Generate Toolpath → Run

#Main Product Promise

Kerfio should make CNC operation:

• easier
• safer
• more visual
• more intelligent
• less intimidating
• more professional
• better connected to real machine vision

#Main Application Components

Kerfio CNC v1.0.0 has four major software parts.

#React/Tauri Desktop UI

The user-facing application.

Main responsibilities:

• show all UI sections
• manage user interaction
• display camera/video
• show canvas tools
• show machine/job state
• send requests to the Python backend
• display warnings and confirmations
• provide the Kerfio AI assistant chat UI

Technology:

Tauri v2
React
TypeScript
Vite
Tailwind CSS
shadcn/ui
Zustand
TanStack Query
react-konva
Three.js / React Three Fiber where needed

#Python Background Web API

The local backend service running on the desktop computer.

Main responsibilities:

• serve all UI APIs
• connect to CNC controller
• manage machine state
• stream G-code safely
• manage jobs
• manage projects/files/settings
• connect to Raspberry Pi camera node
• store data in SQLite
• provide logs and diagnostics
• orchestrate AI assistant actions
• enforce safety rules

Technology:

Python
FastAPI
WebSocket
SQLite
pySerial
OpenCV
httpx
Pydantic

#Raspberry Pi Vision Node

A Python app running on Raspberry Pi 5 connected to the dual IMX219 camera module.

Main responsibilities:

• detect left/right cameras
• capture video
• broadcast video over LAN using WebRTC
• provide camera status
• provide snapshots
• provide optional basic image processing
• expose health/status APIs

Technology:

Python
FastAPI
aiortc
OpenCV
Picamera2 if available

#SQLite Database

Local data storage.

Stores:

• settings
• machine profiles
• projects
• recent work
• sketches
• Kerf project metadata
• G-code file metadata
• logs
• job history
• snapshots
• calibration profiles
• macros
• assistant conversations

#Main User Workflow

A typical user workflow:

1. Open Kerfio CNC.
2. Check Dashboard readiness.
3. Connect the CNC controller.
4. Connect Raspberry Pi vision node if using camera.
5. Open or create a project.
6. Create a Sketch or import a design into Kerf.
7. Assign CNC actions to paths.
8. Generate and validate toolpath.
9. Align design with camera if needed.
10. Dry trace the job boundary.
11. Run the job after confirmation.
12. Monitor job progress.
13. Save report/snapshots.

#Getting Started

#Step 1 — Open Kerfio

When the app opens, the user lands on the Dashboard.

The Dashboard should show:

• machine status
• camera status
• backend status
• recent work
• quick actions
• safety alerts

#Step 2 — Create or Select Machine Profile

Go to:

Settings → Machine Profiles

Create a machine profile with:

• machine name
• controller type
• workspace size
• serial port default
• baud rate
• axis limits
• safe feed rates
• probe settings
• camera/calibration relation

Example:

Name: Kerfio CNC v1
Controller: GRBL or FluidNC
Workspace: X 700 mm, Y 500 mm, Z 100 mm
Baud rate: 115200
Units: mm

#Step 3 — Connect Machine

Go to:

Machine → Connection

Select:

• serial port
• baud rate
• controller type
• machine profile

Then click:

Connect

After connection, Kerfio should show:

Connected
Idle
X/Y/Z position
Active coordinate system

#Step 4 — Connect Camera / Vision Node

Go to:

Camera / Vision → Vision Node

Enter Raspberry Pi address:

http://192.168.x.x:8080

Click:

Test Connection
Connect Node

The UI should show:

• left camera online/offline
• right camera online/offline
• stream readiness
• calibration status

#Step 5 — Create a Sketch or Open Kerf

For simple geometry:

Sketch → New Sketch

For CNC manufacturing workflow:

Kerf → New Kerf Project

For existing files:

Kerf → Import SVG

or:

G-code → Open G-code File

#Step 6 — Validate Before Running

Before running any job:

• validate G-code
• check machine bounds
• check machine state
• check work origin
• check camera alignment if used
• dry trace where possible

#Step 7 — Run Safely

Run only after:

• machine is connected
• machine is not alarmed
• job is validated
• toolpath is within limits
• user confirms the operation

#Safety Philosophy

Kerfio controls a real CNC machine. Every movement can be dangerous.

Kerfio must always prefer:

stop
warn
confirm
validate
block unsafe action

over risky automation.

#Always Visible Safety Information

The app shell or active CNC section should always show:

• machine connection
• machine state
• current X/Y/Z
• pause/stop
• alarm state

#Actions Requiring Confirmation

The following actions must not happen silently:

• start job
• resume job
• machine movement from canvas
• set work zero
• home machine
• unlock machine
• soft reset
• probe cycle
• run macro with motion
• send raw G-code
• turn spindle/laser on
• run Kerf toolpath
• dry trace
• apply machine profile changes that affect motion

#Blocked Actions

Kerfio should block action when:

• machine is disconnected
• machine is alarmed
• job is already running
• target is out of bounds
• toolpath validation failed
• calibration is required but missing
• confirmation is missing
• machine profile is invalid

#Main UI Navigation

Recommended main navigation:

Dashboard
Kerf
Sketch
G-code
Machine
Camera / Vision
Job
Probe
Macros
Console
Settings

Optional global elements:

• Kerfio AI Assistant button
• global machine status pill
• global stop/pause control
• app notifications
• active project indicator

#Dashboard / Home

#Purpose

The Dashboard is the home section of the app.

It should be simple, premium, friendly, and minimal.

It is not a full CNC control panel.

Its job is to answer:

Is my machine ready?
Is my camera ready?
What was I working on?
What should I do next?
Are there safety warnings?

#Dashboard Sections

#Welcome Header

Shows:

• greeting
• app name
• short message
• optional help/settings icons

Example:

Welcome back, Babak
Start a new cut, continue a Kerf project, or check your machine status.

#System Readiness Strip

Shows compact status pills:

Machine: Connected
Camera: Online
Backend: Ready
Project: No project open
Safety: Clear

Status levels:

ready
offline
warning
blocked

#Primary Action Card

Shows the best next action.

Possible states:

• continue recent Kerf project
• connect machine
• start first project
• resolve machine alarm
• monitor running job

Example:

Continue Acrylic Panel Cut
Last opened today.
[Continue] [Open Recent]

#Quick Action Cards

Recommended cards:

Kerf
Sketch
G-code
Camera

Each card has:

• icon
• title
• short description
• button or clickable card

#Machine Snapshot Card

Shows simplified machine state:

• connected/disconnected
• Idle/Run/Hold/Alarm
• X/Y/Z work position
• active coordinate system
• controller type

No full jog pad should be shown on Dashboard.

#Vision Snapshot Card

Shows:

• Raspberry Pi node status
• left/right camera status
• calibration status
• last snapshot preview

#Recent Work

Shows recent:

• Kerf projects
• Sketch files
• G-code files

Each item should show:

• name
• type
• last opened time
• open action

#Soft Alerts / Suggestions

Shows helpful messages:

• calibration missing
• machine disconnected
• camera offline
• recent job finished
• G-code validation warning

#Dashboard Tools

Dashboard should have only simple actions:

• Open Kerf
• New Sketch
• Open G-code
• Open Camera
• Connect Machine
• Open Recent
• Open Settings

#Dashboard Should Not Include

Do not place these on Dashboard:

• full jog controls
• full G-code editor
• full console
• full camera canvas
• full Kerf canvas
• full Sketch canvas
• advanced settings
• macro editor
• detailed logs

#Kerf Section

#Purpose

Kerf is the main manufacturing workspace of Kerfio.

It combines:

• geometry
• layers
• camera view
• calibration
• CNC path actions
• toolpath generation
• machine position
• live machine commands
• safety validation

Kerf turns design geometry into CNC action.

#Main Concept

Sketch defines geometry.
Kerf defines how the machine acts on that geometry.

#Kerf Layout

Recommended layout:

Top Bar
Left Toolbar
Center Layered Canvas
Right Properties Panel
Bottom Panel

#Kerf Top Bar

Contains:

• New Kerf Project
• Open Kerf Project
• Save
• Save As
• Load Sketch
• Import SVG
• Import DXF later
• Add Layer
• Generate Toolpath
• Preview
• Dry Trace
• Run
• Pause
• Stop

#Kerf Left Toolbar

Tools:

• Select
• Pan
• Move
• Rotate
• Scale
• Set Origin
• Add Path
• Measure
• Add Point
• Camera Align
• Move Tool Here
• Set Work Zero Here
• Dry Trace Selected

#Kerf Canvas

The Kerf canvas is a layered machine-aware workspace.

It can show:

• machine workspace boundary
• grid
• work origin
• live camera layer
• snapshot layer
• sketch layer
• imported SVG/DXF layer
• toolpath layer
• selected paths
• machine position
• measurement layer
• AI/vision result layer
• safety boundary layer

#Kerf Layer Panel

Layer types:

Camera Layer
Snapshot Layer
Sketch Layer
Imported SVG Layer
Imported DXF Layer
Toolpath Layer
Machine Position Layer
Measurement Layer
Annotation Layer
Vision Result Layer
Safety Boundary Layer

Each layer should support:

• visible/hidden
• locked/unlocked
• selectable/non-selectable
• opacity
• color
• rename
• reorder
• duplicate
• delete where allowed

Important rules:

• camera layer is usually locked and behind geometry
• machine position layer is non-editable
• safety boundary layer should not be deleted
• hidden layers are not rendered
• locked layers cannot be edited

#Kerf Canvas Modes

#Design Mode

Used to arrange geometry.

Actions:

• move layer
• rotate layer
• scale layer
• align design
• position imported sketch

#Operation Mode

Used to assign CNC actions.

Actions:

• select path
• set cut/engrave/drill mode
• set depth/feed/pass
• color path by action

#Camera Alignment Mode

Used to align design with real material.

Actions:

• enable camera layer
• use calibration profile
• freeze frame
• align sketch/toolpath to camera
• set origin from visual reference

#Machine Control Mode

Used for safe machine actions from canvas.

Actions:

• move tool here
• set work zero here
• move to path start
• dry trace selected path

#Preview Mode

Used to inspect generated toolpath.

Actions:

• inspect rapid/cut/plunge/retract moves
• check warnings
• verify bounds

#Run Mode

Used while job is running.

Actions:

• monitor position
• monitor progress
• pause
• stop

Editing should be locked in Run Mode.

#Path Actions

Every path in Kerf can have one CNC action.

v1 actions:

Ignore
Trace / Engrave
Cut On Line
Cut Inside
Cut Outside
Drill Point
Move Only

Future actions:

Pocket
Tabs
Bridges
Lead-in/out
Ramp entry
Multi-tool
Adaptive clearing

#Path Properties Panel

Shows:

• path ID
• path name
• source layer
• path type
• length
• closed/open status
• bounding box
• assigned action
• warnings

#Operation Panel

Shows operation settings:

• action type
• tool type
• cut mode
• depth
• pass count
• step down
• feedrate
• plunge rate
• spindle speed
• laser power
• safe Z
• kerf compensation
• warnings

#Machine Panel in Kerf

Shows:

• connection state
• machine state
• X/Y/Z work position
• machine position
• active coordinate system
• movement command preview

#Vision Panel in Kerf

Shows:

• camera source
• camera layer status
• calibration profile
• snapshot controls
• opacity
• freeze/live mode
• alignment controls

#Safety Panel in Kerf

Shows:

• validation result
• machine alarm
• connection state
• out-of-bounds warnings
• missing calibration
• missing path actions
• unsafe operation warnings

#Kerf Bottom Panel

Tabs:

• G-code Preview
• Console
• Job Progress
• Validation
• Events

#Kerf File

Native Kerf file:

.kerf

Stores:

• machine profile reference
• calibration profile reference
• layer stack
• path actions
• imported sketch references
• camera layer settings
• generated toolpath metadata
• origin
• workspace size
• safety warnings

#Sketch Section

#Purpose

Sketch is a simple 2D vector drawing workspace.

It is for creating clean geometry.

Sketch does not directly control the CNC machine.

#Sketch Workflow

Create Sketch → Draw Geometry → Validate → Save/Export → Load into Kerf

#Sketch Layout

Recommended layout:

Top Bar
Left Toolbar
Center Canvas
Right Properties Panel
Bottom Status Bar

#Sketch Top Bar

Contains:

• New Sketch
• Open Sketch
• Save
• Save As
• Import SVG
• Export SVG
• Export PNG Preview
• Undo
• Redo
• Grid Toggle
• Snap Toggle
• Units Selector
• Canvas Settings

#Sketch Left Toolbar

Tools:

• Select
• Pan
• Line
• Polyline
• Rectangle
• Circle
• Arc
• Point
• Text
• Measure
• Delete

#Sketch Canvas

Features:

• grid
• rulers
• origin marker
• snap guides
• zoom/pan
• selection rectangle
• transform handles
• object selection
• object drawing
• optional machine bed template

#Sketch Right Panel

Tabs:

Properties
Objects
Validation
Document

#Properties Tab

Shows selected object fields.

For line:

• start X/Y
• end X/Y
• length
• angle
• stroke color
• stroke width
• lock/visibility

For rectangle:

• X/Y
• width/height
• rotation
• stroke/fill
• lock/visibility

For circle:

• center X/Y
• radius
• diameter
• stroke
• lock/visibility

For text:

• content
• X/Y
• font size
• font family
• convert to path later

#Objects Tab

Shows:

• object list
• object type
• visibility toggle
• lock toggle
• select
• duplicate
• delete

#Validation Tab

Shows:

• invalid geometry
• zero-length paths
• unsupported objects
• missing units
• objects outside workspace
• export warnings

#Document Tab

Shows:

• sketch name
• units
• workspace size
• grid spacing
• snap settings
• metadata

#Sketch Bottom Bar

Shows:

• mouse coordinates
• zoom
• active tool
• selected object count
• snap status
• units
• validation status

#Sketch File

Native file:

.kerfsketch

Exports:

• SVG
• PNG preview
• native JSON

Imports:

• native Kerfio sketch
• SVG

Later:

• DXF
• PDF vector import

#G-code Section

#Purpose

The G-code section is for loading, editing, validating, previewing, and preparing existing G-code files.

#Main Features

• open .gcode, .nc, .tap, .cnc
• view file summary
• edit G-code
• syntax highlighting
• line numbers
• search
• validate file
• preview toolpath
• show warnings
• send to job runner
• show current execution line

#G-code Layout

Recommended panels:

Top Bar
File Summary
Editor
Preview
Validation Panel
Bottom Console/Warnings

#G-code Top Bar

Contains:

• Open File
• Save
• Save As
• Reload
• Validate
• Analyze
• Preview
• Start Job
• Clear

#File Summary

Shows:

• file name
• line count
• size
• units
• estimated bounds
• estimated duration
• detected commands
• warnings

#Editor

Features:

• line numbers
• syntax highlighting
• current running line highlight
• error line highlight
• command search
• command history
• manual command helper if allowed

#Preview

Shows:

• 2D toolpath
• optional 3D preview
• rapid moves
• cutting moves
• plunge/retract moves
• origin marker
• machine bounds
• toolpath bounds

#Validation

Checks:

• unsupported commands
• out-of-bounds movement
• missing units
• suspicious Z moves
• laser/spindle commands
• relative/absolute mode changes
• no motion commands
• unsafe feed rates

#Machine Section

#Purpose

The Machine section is for direct machine connection and manual control.

It is the main place for:

• connecting controller
• seeing machine state
• jogging
• homing
• unlocking
• setting zero
• checking coordinates
• troubleshooting alarms

#Machine Layout

Recommended panels:

Connection Panel
Machine Status
Position Panel
Jog Panel
Coordinate Panel
Safety/Alarm Panel

#Connection Panel

Form fields:

• port
• baud rate
• controller type
• connection mode
• machine profile
• auto query status

Buttons:

• Refresh Ports
• Connect
• Disconnect

#Machine Status Panel

Shows:

• connected/disconnected
• controller type
• firmware info
• state: Idle/Run/Hold/Alarm/Error
• last response
• alarm message
• homed status if available
• limit status if available

#Position Panel

Shows:

• work position X/Y/Z
• machine position X/Y/Z
• active coordinate system
• units
• feedrate
• spindle/laser state

#Jog Panel

Controls:

• X+/X-
• Y+/Y-
• Z+/Z-
• step size
• feedrate
• continuous jog if supported
• cancel jog

#Coordinate Tools

Actions:

• Set X Zero
• Set Y Zero
• Set Z Zero
• Set All Zero
• Go to Work Zero
• Select G54/G55/etc.

#Machine Actions

Actions requiring confirmation:

• Home
• Unlock
• Soft Reset
• Go to position
• Set zero
• Start spindle/laser
• Send raw command

#Camera / Vision Section

#Purpose

The Camera / Vision section is for managing the Raspberry Pi camera node, live streams, snapshots, calibration, and vision tools.

#Main Features

• connect to Pi vision node
• show camera status
• display left/right live video
• take snapshots
• configure camera settings
• manage calibration
• run basic vision tools
• inspect vision results

#Vision Node Connection Form

Fields:

• node IP/address
• port
• protocol
• optional token
• left stream path
• right stream path

Buttons:

• Test Connection
• Connect Node
• Disconnect Node
• Restart Streams

#Camera Status

Shows:

• node online/offline
• left camera status
• right camera status
• stream status
• resolution
• FPS
• last frame time
• last snapshot

#Live View

Modes:

• left camera
• right camera
• dual view
• stereo later
• snapshot view

Controls:

• zoom
• pan
• fullscreen
• freeze frame
• take snapshot
• brightness/contrast
• overlay toggles

#Snapshot Tools

Actions:

• capture left snapshot
• capture right snapshot
• save snapshot
• attach snapshot to project
• use snapshot for calibration
• create snapshot layer in Kerf

#Calibration Tools

Actions:

• start calibration
• add calibration point
• remove point
• solve calibration
• test calibration
• save profile
• activate profile

#Vision Tools

v1 tools:

• detect edge
• detect corner
• detect circle
• detect workpiece boundary
• measure distance
• transform image point to machine point

AI vision tools are advisory only.

#Job Section

#Purpose

The Job section is for monitoring and controlling active or prepared CNC jobs.

#Main Features

• show current job
• start job
• pause/resume
• stop/abort
• show progress
• show current line
• show elapsed/remaining time
• show last command/response
• show job report

#Job States

idle
loaded
ready
running
paused
stopping
stopped
completed
failed
aborted

#Job Controls

Buttons:

• Start
• Pause
• Resume
• Stop
• Abort
• Dry Run
• Open Report

Start/resume/abort require confirmation where appropriate.

#Job Progress Panel

Shows:

• job name
• file name
• current line
• total lines
• percent complete
• elapsed time
• estimated remaining time
• current command
• last response
• warnings/errors

#Probe Section

#Purpose

The Probe section is for touch plate and probing workflows.

v1 focus:

Z touch plate probing

#Probe Status

Shows:

• probe enabled/disabled
• probe triggered/not triggered
• plate thickness
• probe feedrate
• last probe result

#Z Probe Form

Fields:

• plate thickness
• probe feedrate
• maximum travel
• safe Z
• coordinate system

Buttons:

• Start Z Probe
• Cancel Probe
• Save Plate Thickness

#Safety Rules

Probe is blocked if:

• machine disconnected
• machine alarmed
• job running
• probe not configured
• invalid plate thickness
• confirmation missing

#Macros Section

#Purpose

Macros are reusable command sequences.

They can simplify common CNC operations.

#Macro List

Shows:

• macro name
• category
• enabled/disabled
• risk level
• edit
• run

#Macro Categories

Setup
Probing
Parking
Laser
Spindle
Coolant
Maintenance
Custom

#Macro Editor Form

Fields:

• name
• category
• commands
• description
• confirmation required
• enabled
• color/icon

#Macro Safety

Macros must pass through the same safety rules as manual commands.

Motion macros and spindle/laser macros require confirmation.

#Console Section

#Purpose

The Console shows low-level communication with the CNC controller.

It is mainly for debugging and advanced users.

#Console Features

• sent commands
• controller responses
• timestamps
• severity filters
• manual command input
• command history
• clear console
• export logs

#Manual Command Form

Fields:

• command text
• confirmation if dangerous
• send button

Dangerous commands require confirmation:

• movement
• spindle/laser on
• reset
• settings changes
• probing
• work offset changes

#Settings Section

#Purpose

Settings manage app, machine, camera, safety, and assistant configuration.

#Settings Categories

General
UI
Machine
Controller
Camera
Vision
Safety
Logging
Assistant
Developer

#General Settings

Fields:

• language
• units
• startup behavior
• default project folder

#UI Settings

Fields:

• theme
• layout density
• sidebar behavior
• dashboard preferences
• canvas appearance

#Machine Settings

Fields:

• default machine profile
• homing requirement
• soft/hard limits
• max jog feedrate
• max job feedrate

#Controller Settings

Fields:

• controller type
• default port
• baud rate
• status polling interval
• GRBL/FluidNC options

#Camera Settings

Fields:

• default vision node address
• active camera
• default resolution
• FPS
• brightness/contrast
• snapshot folder

#Vision Settings

Fields:

• active calibration profile
• overlay defaults
• detection options
• AI vision provider options

#Safety Settings

Fields:

• require confirmation for run
• require confirmation for vision move
• block out-of-bounds jobs
• block unvalidated jobs
• require homing before job

#Logging Settings

Fields:

• log level
• retain logs for days
• export logs
• clear logs

#Assistant Settings

Fields:

• enable Kerfio Assistant
• provider type
• base URL
• API key
• model
• allow document context
• allow machine status context
• allow cloud AI
• save chat history
• clear history

#Developer Settings

Fields:

• mock mode
• debug panels
• API base URL
• WebSocket URL
• diagnostics tools

#Projects and Recent Work

#Purpose

Projects help group related files and data.

A project may contain:

• Kerf file
• Sketch files
• G-code files
• snapshots
• calibration profile
• machine profile
• job reports
• notes
• history

#Project Actions

• New Project
• Open Project
• Save Project
• Add File
• Attach Snapshot
• View History
• Generate Report

#Recent Work

Dashboard and file dialogs should show recent:

• Kerf projects
• Sketch files
• G-code files
• snapshots
• reports

#Kerfio AI Assistant

#Purpose

Kerfio AI Assistant is an embedded assistant bot named Kerfio.

It can help the user:

• understand the current screen
• explain CNC concepts
• explain G-code
• explain machine errors
• inspect current document/project
• suggest next actions
• prepare safe actions
• navigate the app

#Entry Points

• floating chat button
• top bar assistant icon
• contextual help buttons
• command palette

#Assistant UI

Recommended modes:

Floating compact chat
Right-side docked panel

Chat panel shows:

• assistant name
• context pills
• messages
• suggested prompts
• action cards
• confirmation cards
• input box

#Context Awareness

Kerfio Assistant should understand:

• current route
• machine state
• active project
• open Sketch
• open Kerf project
• selected layer/path/object
• loaded G-code file
• selected G-code line
• job state
• camera state
• calibration state
• validation warnings

#Safe Assistant Actions

Can execute safely:

• open section
• run validation
• take snapshot
• show panel
• explain document
• summarize warnings

Requires confirmation:

• generate toolpath
• save/export
• apply path action
• set work zero
• move tool here
• dry trace
• home/unlock
• probe

Must never silently:

• start job
• move machine
• turn spindle/laser on
• send raw G-code
• bypass safety manager

#Example Prompts

Dashboard:

What should I do next?
Is my machine ready?
Open my last Kerf project.

Kerf:

Is this project ready to run?
Explain selected path action.
Generate toolpath for selected paths.
Why is Run disabled?

Sketch:

Check this sketch for problems.
Create a 100 by 50 mm rectangle.
Can this export to SVG?

G-code:

Explain this G-code file.
What are the job bounds?
Show spindle commands.

Machine:

Why is the machine alarmed?
How do I set work zero?
Guide me through homing.

Camera:

Is camera calibration active?
Help me calibrate the camera.
Take a snapshot.

#Raspberry Pi Vision Node

#Purpose

The Raspberry Pi app is the camera broadcasting service.

It provides:

• left camera stream
• right camera stream
• WebRTC video
• snapshots
• camera health
• basic diagnostics
• optional image processing

#UI Sections Supported

• Dashboard
• Camera / Vision
• Kerf
• Calibration
• AI Assistant

#Main Pi APIs

GET /api/v1/health
GET /api/v1/node/status
GET /api/v1/cameras
GET /api/v1/cameras/{cameraId}/status
GET /api/v1/streams
POST /api/v1/webrtc/offer
POST /api/v1/snapshots/capture
GET /api/v1/cameras/settings
POST /api/v1/cameras/{cameraId}/settings

#Important Rule

The Raspberry Pi vision node does not control CNC motion.

It only provides camera/video/vision-node data.

#Python Background Service

#Purpose

The Python backend is the local API and safety layer for the app.

It serves every UI section.

#Main Backend Sections

Dashboard API
Machine API
Coordinates API
G-code API
Job API
Camera API
Vision Node API
Vision API
Calibration API
Vision Motion API
Sketch API
Kerf API
Probe API
Macro API
Console API
Settings API
Machine Profile API
Project API
Snapshot API
Report API
Logs API
Diagnostics API
Assistant API
WebSocket API

#Backend Responsibilities

• manage CNC connection
• enforce safety
• manage machine state
• manage G-code streaming
• manage jobs
• store data in SQLite
• connect to Raspberry Pi
• provide camera stream metadata
• manage Sketch/Kerf files
• generate/validate toolpaths
• support AI assistant
• provide WebSocket events

#Data Stored in SQLite

SQLite stores:

• app settings
• machine profiles
• controller connections
• calibration profiles
• camera node settings
• projects
• recent work
• sketch metadata
• Kerf project metadata
• G-code file metadata
• job history
• job reports
• snapshots
• macros
• console logs
• app logs
• assistant conversations
• assistant actions
• diagnostics events

#UI Forms Reference

#Machine Connection Form

Fields:

• port
• baud rate
• controller type
• connection mode
• machine profile
• auto status query

Actions:

• Refresh Ports
• Connect
• Disconnect

#Machine Profile Form

Fields:

• name
• controller type
• default port
• baud rate
• X/Y/Z workspace size
• soft limits
• hard limits
• max jog feedrate
• max job feedrate
• probe enabled
• default plate thickness

#Camera Node Form

Fields:

• node address
• port
• protocol
• optional token
• left stream
• right stream

Actions:

• Test
• Connect
• Disconnect
• Restart Streams

#Camera Settings Form

Fields:

• active camera
• resolution
• FPS
• brightness
• contrast
• exposure
• gain
• flip/rotation
• snapshot format

#Calibration Form

Fields:

• profile name
• camera ID
• machine profile
• calibration points
• method
• accuracy result

Actions:

• Add Point
• Remove Point
• Solve
• Test
• Save
• Activate

#Sketch Document Form

Fields:

• sketch name
• units
• workspace width/height
• grid spacing
• snap enabled
• default stroke

#Sketch Object Properties Form

Fields vary by object:

• line: start/end, length, angle
• rectangle: X/Y, width/height, rotation
• circle: center, radius, diameter
• text: content, font, size
• all: color, stroke width, visible, locked

#Kerf Project Form

Fields:

• project name
• units
• machine profile
• calibration profile
• workspace size
• origin

#Kerf Layer Form

Fields:

• layer name
• type
• visible
• locked
• selectable
• opacity
• color
• z-order

#Kerf Path Action Form

Fields:

• action type
• tool type
• depth
• pass count
• step down
• feedrate
• plunge rate
• spindle RPM
• laser power
• safe Z
• kerf compensation

#G-code Open/Save Form

Fields:

• file path
• file type
• encoding if needed
• reload option

#Job Start Confirmation Form

Shows:

• file/project
• estimated bounds
• warnings
• machine status
• confirmation checkbox/button

#Probe Form

Fields:

• plate thickness
• probe feedrate
• max travel
• safe Z
• coordinate system

#Macro Form

Fields:

• name
• category
• commands
• description
• requires confirmation
• enabled

#Assistant Settings Form

Fields:

• enable assistant
• provider
• base URL
• API key
• model
• allow document context
• allow machine context
• allow cloud AI
• save chat history

#Tool Reference

#Sketch Tools

#Select

Select one or more objects.

#Pan

Move the canvas view.

#Line

Draw a straight line.

#Polyline

Draw connected line segments.

#Rectangle

Draw a rectangle with exact dimensions.

#Circle

Draw a circle by center/radius or bounding box.

#Arc

Draw curved segments.

#Point

Create a point reference. In Kerf, points may become drill/probe/mark points.

#Text

Create simple text for engraving or reference.

#Measure

Measure distance between points or objects.

#Delete

Delete selected objects.

#Kerf Tools

#Select

Select layers, paths, or objects.

#Pan

Move canvas view.

#Move

Move selected layer/object.

#Rotate

Rotate selected layer/object.

#Scale

Scale selected layer/object.

#Set Origin

Define work origin or project origin.

#Add Path

Create a simple path directly in Kerf.

#Measure

Measure distance in machine units.

#Add Point

Add point for drill, probe, marker, or reference.

#Camera Align

Align design with camera view.

#Move Tool Here

Prepare a movement command to selected canvas point. Requires confirmation.

#Set Work Zero Here

Set current or selected point as work zero. Requires confirmation.

#Dry Trace Selected

Move around selected boundary at safe Z. Requires confirmation.

#Machine Tools

#Jog

Manual movement on X/Y/Z.

#Home

Run machine homing cycle.

#Unlock

Unlock controller after alarm or reset.

#Reset

Soft reset controller.

#Go to Zero

Move to current work origin.

#Set Zero

Set current position as work zero.

#Camera Tools

#Live View

Show camera stream.

#Snapshot

Capture still frame.

#Freeze

Pause current frame for inspection.

#Overlay

Show grid/crosshair/toolpath over camera.

#Calibration

Map image coordinates to machine coordinates.

#G-code Tools

#Validate

Check file for possible problems.

#Analyze

Extract bounds, units, commands, and estimate.

#Preview

Render toolpath.

#Run

Start streaming G-code after confirmation.

#Search

Find commands or line numbers.

#Recommended First-Time Setup Flow

1. Open Kerfio.
2. Go to Settings.
3. Create machine profile.
4. Go to Machine.
5. Connect CNC controller.
6. Home machine if required.
7. Go to Camera / Vision.
8. Connect Raspberry Pi vision node.
9. Verify left/right camera streams.
10. Create calibration profile.
11. Create a simple Sketch.
12. Save the Sketch.
13. Open Kerf.
14. Load the Sketch.
15. Assign path actions.
16. Generate toolpath.
17. Dry trace.
18. Run job after confirmation.

#Common Workflows

#Create Simple Shape and Cut

Sketch → New Sketch → Draw Rectangle → Save
Kerf → Load Sketch → Select Rectangle
Operation → Cut Outside
Generate Toolpath → Preview → Dry Trace → Run

#Import SVG From Other App

Kerf → Import SVG
Check scale/units
Assign actions to paths
Generate toolpath
Preview
Run

#Run Existing G-code

G-code → Open File
Analyze
Validate
Preview
Machine connected?
Start Job
Monitor in Job section

#Camera-Assisted Alignment

Camera/Vision → Connect Node
Kerf → Enable Camera Layer
Load design
Select calibration profile
Align design over real material
Set origin
Generate toolpath
Dry trace
Run

#Set Work Zero

Machine → Jog to desired point
Set X/Y/Z Zero
Confirm

or from Kerf:

Kerf → Select point on canvas
Set Work Zero Here
Review target
Confirm

#Probe Z With Touch Plate

Probe → Enter plate thickness
Place touch plate
Start Z Probe
Confirm
Wait for result
Check new Z zero

#Validation, Alerts, and Blocking Conditions

#Alert Levels

Info
Warning
Danger
Blocking

#Common Warnings

• camera offline
• calibration missing
• machine disconnected
• unassigned Kerf paths
• G-code has spindle/laser commands
• file contains unsupported commands
• job estimate unavailable

#Blocking Conditions

• machine alarm
• machine disconnected for run
• out-of-bounds toolpath
• invalid machine profile
• missing confirmation
• unsafe feedrate
• active job conflict
• invalid probe setup
• vision move without calibration

#File Types

#Native Kerfio Files

.kerf          Kerf manufacturing project
.kerfsketch    Sketch document

#CNC Files

.gcode
.nc
.tap
.cnc

#Import/Export Files

.svg
.dxf later
.png preview
.json internal/native

#Project Data

A project folder may contain:

project metadata
Kerf file
Sketch files
G-code files
snapshots
reports
logs
calibration references

#Feature Priority for v1.0.0

#Must Have

• Dashboard
• Machine connection
• Jog controls
• G-code open/validate/preview/run
• Job control
• Console
• Camera node connection
• left/right stream metadata
• snapshots
• Sketch basic drawing
• Kerf layers
• Kerf path actions
• Kerf toolpath generation
• Safety manager
• SQLite persistence
• AI Assistant basic chat/action preparation
• Settings
• Machine profiles
• Calibration profiles

#Should Have

• live WebRTC camera display
• camera layer in Kerf
• dry trace
• probe wizard
• macro system
• recent work
• job reports
• assistant context awareness
• mock mode

#Later

• advanced CAM
• pocketing
• tabs/bridges
• advanced DXF
• stereo depth reconstruction
• autonomous AI inspection
• plugin system
• cloud sync
• marketplace

#Future Expansion

Future Kerfio versions may add:

• advanced tool library
• pocketing and clearing operations
• tabs and bridges
• lead-in/out
• nesting
• multi-tool workflows
• automatic material detection
• AI inspection after job
• stereo depth mapping
• more advanced camera calibration
• plugin system
• cloud project sync
• team/workshop mode
• mobile monitoring
• more controller support

#CNC Fundamentals for Kerfio Users

This section gives general CNC background knowledge so Kerfio users can understand what the application is doing and why each workflow matters.

#What CNC Means

CNC means Computer Numerical Control.

A CNC machine follows a program, usually written as G-code, to move a tool through space. The tool can be:

• a router bit
• an end mill
• a drill
• a laser module
• a pen/marker
• a probe
• a plasma torch in other machines
• a drag knife in some machines

For Kerfio CNC v1.0.0, the primary expected machine type is a light CNC router / laser-compatible custom machine using a controller such as GRBL or FluidNC.

#Main CNC Machine Types

Kerfio is mainly designed for 3-axis CNC-style workflows, but users should understand the wider CNC world.

#The CNC Workflow

A standard CNC workflow usually looks like:

Design → CAM → G-code → Machine Setup → Run → Inspect

In Kerfio, this becomes:

Sketch / external CAD → Kerf / G-code → Preview → Validate → Dry Trace → Run → Inspect

#CAD, CAM, and G-code

#CAD

CAD means Computer-Aided Design.

CAD is where the geometry is created.

Examples:

• Fusion 360
• FreeCAD
• AutoCAD
• LibreCAD
• SolidWorks
• Onshape
• Rhino
• Inkscape for 2D vector design

#CAM

CAM means Computer-Aided Manufacturing.

CAM is where geometry becomes manufacturing instructions.

Examples:

• Fusion 360 Manufacture workspace
• FreeCAD CAM/Path Workbench
• Vectric Aspire/VCarve
• Carbide Create
• Estlcam
• LightBurn for laser workflows

#G-code

G-code is the machine instruction language.

Examples:

G0 X0 Y0
G1 X50 Y20 F800
M3 S10000
M5

Kerfio can load, inspect, validate, preview, and run G-code, but its unique value is that it also adds Sketch, Kerf, and camera-assisted visual workflows.

#How Kerfio Works Alongside CAD Applications

Kerfio should not try to replace professional CAD/CAM software in v1.0.0.

Instead, it should work well beside them.

#Kerfio + Fusion 360

Fusion 360 can be used for:

• precise 2D sketches
• 3D modeling
• parametric CAD
• professional CAM
• toolpath generation
• exporting DXF/SVG/G-code depending workflow

Recommended workflows:

#Workflow A — Fusion 360 for CAD, Kerfio for CNC operation

Fusion 360 sketch/model
→ export DXF/SVG or generate G-code
→ import into Kerfio
→ validate
→ align with camera if needed
→ run safely

#Workflow B — Fusion 360 for CAM, Kerfio for Sender + Vision

Fusion 360 Manufacture
→ generate G-code with correct post-processor
→ open G-code in Kerfio
→ preview and validate
→ set work zero
→ dry trace if possible
→ run

#Workflow C — Fusion 360 for Sketch Export, Kerfio Kerf for Actions

Fusion 360 2D sketch
→ export DXF/SVG
→ Kerfio Kerf imports geometry
→ user assigns Cut Outside / Drill / Trace actions
→ Kerfio generates simple toolpath

Best use:

• Use Fusion 360 for complex design.
• Use Kerfio for visual machine operation, camera alignment, quick validation, and safe execution.

#Kerfio + FreeCAD

FreeCAD can be used for:

• open-source CAD design
• parametric modeling
• technical drawings
• CAM/G-code creation through the CAM/Path workbench

Recommended workflows:

FreeCAD model
→ CAM/Path job creates operations
→ export G-code
→ open G-code in Kerfio
→ validate, preview, run

or:

FreeCAD 2D geometry
→ export SVG/DXF
→ import into Kerfio Kerf
→ assign actions
→ generate toolpath

Best use:

• Use FreeCAD when you want an open-source CAD/CAM workflow.
• Use Kerfio as the machine operator, camera-assisted aligner, and safe sender.

#Kerfio + AutoCAD

AutoCAD is strong for:

• professional 2D drafting
• DWG files
• DXF export
• architectural/mechanical line drawings

Recommended workflow:

AutoCAD drawing
→ export DXF
→ import DXF into Kerfio Kerf
→ check scale and units
→ assign CNC actions
→ generate toolpath

Important:

AutoCAD is CAD, not a CNC sender. For CNC, the drawing still needs manufacturing interpretation: tool diameter, cut inside/outside, depth, passes, feedrate, and safe Z. This is what the Kerf section helps define.

#Kerfio + Inkscape / Illustrator / Vector Apps

For 2D laser/router work:

Inkscape / Illustrator
→ export SVG
→ import SVG into Kerfio Kerf
→ assign actions
→ generate toolpath

Useful for:

• signs
• logos
• engraving
• simple shapes
• decorative panels

#Kerfio + Existing CAM Software

If the user already has CAM software:

CAM software
→ export G-code
→ Kerfio G-code section
→ validate and run

In this workflow, Kerfio should not reinterpret the geometry. It acts as:

• G-code sender
• previewer
• safety validator
• machine monitor
• camera-assisted setup tool

#Kerfio’s Role Compared to CAD/CAM Tools

Kerfio’s strength is not replacing every CAD/CAM tool.

Kerfio’s strength is:

simple visual CNC preparation + machine control + camera alignment + safety + AI guidance

#G-code Knowledge for Kerfio Users

#What G-code Does

G-code tells the machine:

• where to move
• how fast to move
• whether movement is rapid or cutting
• whether spindle/laser is on
• which coordinate system is active
• whether units are mm or inch
• whether positions are absolute or relative

#Common G-code Commands

#G-code Safety Notes

Before running any G-code:

• check units: G20/G21
• check absolute/relative mode: G90/G91
• check work coordinate system: G54 etc.
• check Z moves
• check spindle/laser commands
• check machine bounds
• check feedrates
• check if the file assumes a specific origin
• dry trace if possible

#Why Kerfio Validates G-code

Kerfio should warn about:

• out-of-bounds moves
• unsupported commands
• unclear units
• suspicious Z movements
• spindle/laser activation
• relative mode changes
• missing feedrates
• very high feedrates
• commands dangerous for the active machine profile

#G-code Is Not a Drawing

A G-code file is already a machine program.

It may not preserve original CAD meaning such as:

• which contour was intended as outside cut
• which feature was a hole
• which material was expected
• which tool was expected
• whether tabs were required

Therefore Kerfio should treat imported G-code carefully and show it as a job/program, not as a fully editable CAD document in v1.0.0.

#Toolpath Concepts

#Trace / Engrave

The tool follows a path directly.

Used for:

• engraving
• marking
• shallow lines
• pen plotting
• laser line work

#Cut On Line

The tool center follows the exact path.

Useful when:

• the path itself is the desired centerline
• kerf/tool diameter compensation is not required
• laser line cutting where kerf is small or handled manually

#Cut Outside

The toolpath is offset outside the closed shape.

Used when:

• the outside dimension of the part must be preserved
• cutting an object out of stock material

#Cut Inside

The toolpath is offset inside the closed shape.

Used when:

• cutting a hole, slot, or inner pocket boundary
• the inside dimension must be preserved

#Drill Point

The tool moves to a point and performs a drilling operation.

In v1, this can be simple:

move to point → plunge → retract

#Pocket

A pocket removes material inside a closed area.

Pocketing is more complex and should be future/v1.1+ unless implemented carefully.

#Roughing and Finishing

Professional CNC often uses:

Roughing pass → remove most material
Finishing pass → clean final edge

This improves accuracy, edge quality, and tool life.

Kerfio v1 can mention this and support simple finishing pass later.

#CNC Materials Guide

This section is general educational guidance. Actual speeds, feeds, depth of cut, and tool selection depend heavily on the machine rigidity, spindle/laser, tool quality, workholding, and material grade.

Always test on scrap first.

#Acrylic / Plexiglass / PMMA

Acrylic is common for signs, panels, covers, and transparent parts.

#Characteristics

• can melt if feed is too slow or spindle is too fast
• chips should be actual chips, not dust or melted strings
• transparent acrylic is difficult or impossible for many diode lasers to cut directly
• CNC routing is usually better than diode laser for transparent acrylic
• edge quality depends strongly on tool, chip evacuation, and finishing pass

#Recommended tool concepts

Common choices:

• single-flute O-flute bit
• sharp carbide cutter
• upcut for chip evacuation
• downcut only if top surface finish is priority and chip evacuation is controlled

#Practical advice

• avoid rubbing; rubbing melts acrylic
• use sharp tools
• use air blast if available
• use shallow passes on weak machines
• leave small stock for finishing pass when quality matters
• protect surface with film if possible
• hold material firmly to avoid vibration

#Kerfio workflow for acrylic

Sketch or import SVG
→ Kerf assign Cut Outside / Cut Inside
→ use conservative depth/pass settings
→ preview
→ dry trace
→ test on scrap
→ run

#Transparent acrylic and diode lasers

Transparent acrylic usually does not absorb many blue diode laser wavelengths effectively. For transparent acrylic cutting, CNC routing or CO₂ laser is usually more appropriate.

#Wood

Wood is common, forgiving, and good for early CNC testing.

#Characteristics

• grain direction matters
• plywood can chip
• softwood cuts easier than hardwood
• MDF creates fine dust
• burning can happen if feed is too slow
• workholding is critical

#Tool concepts

Common choices:

• upcut bit: good chip evacuation, can tear top surface
• downcut bit: cleaner top surface, worse chip evacuation
• compression bit: clean top and bottom in sheet goods
• V-bit: engraving, chamfering, signs
• ball nose: 3D carving
• straight bit: simple routing but often less efficient than spiral bits

#Practical advice

• use dust extraction
• use proper workholding
• choose downcut/compression for plywood top finish
• choose upcut for deep slots if chip evacuation matters
• avoid too slow feed that burns wood
• use tabs or fixtures to prevent parts moving after cutout

#Kerfio workflow for wood

Import or draw shape
→ assign Cut Outside / Drill / Trace
→ preview toolpath
→ check workholding
→ dry trace
→ run

#Aluminum

Aluminum is more demanding than wood and acrylic.

#Characteristics

• requires rigid machine setup
• chip evacuation is critical
• tool can clog if chips weld to cutter
• shallow passes are often needed on light CNC routers
• lubrication or air blast is helpful
• feed/speed must avoid rubbing

#Tool concepts

Common choices:

• single-flute or two-flute carbide end mill for routers
• upcut geometry for chip evacuation
• smaller diameter tools reduce cutting force but are easier to break
• avoid dull tools

#Practical advice

• use conservative depth of cut
• use air blast
• consider lubrication/mist if appropriate and safe
• keep tool stick-out short
• clamp material very firmly
• use adaptive/light passes if CAM supports it
• listen for chatter
• stop if chips become dust, tool gets hot, or aluminum welds to tool

#Kerfio workflow for aluminum

For v1, Kerfio should guide cautiously:

Use professional CAM when possible
Generate G-code in Fusion 360 or FreeCAD CAM
Open in Kerfio
Validate bounds and commands
Run only with conservative settings and good workholding

Kerfio simple Kerf operations may be useful for very light aluminum marking or simple shallow cuts, but complex aluminum milling should be done with proper CAM.

#Tooling and Cutter Basics

#End Mill vs Router Bit

An end mill is commonly used for milling metal and plastics.

A router bit is common for wood routing.

In hobby CNC, the terms are sometimes mixed, but tool geometry matters.

#Number of Flutes

#Upcut

Pulls chips upward.

Pros:

• good chip evacuation
• good for deep slots
• useful for aluminum/plastic chip clearing

Cons:

• can lift material
• can chip top surface of wood/plywood

#Downcut

Pushes chips downward.

Pros:

• cleaner top surface
• helps hold thin sheet down

Cons:

• worse chip evacuation
• can pack chips in slot
• not ideal for deep cuts without strategy

#Compression Bit

Has both upcut and downcut geometry.

Pros:

• clean top and bottom edges
• useful for plywood and laminated sheets

Cons:

• requires correct depth so compression geometry engages properly
• more advanced than simple bits

#V-Bit

Used for:

• engraving
• V-carving
• chamfering
• sign making

#Ball Nose

Used for:

• 3D relief carving
• smooth surfaces
• finishing sculpted shapes

#Flat End Mill

Used for:

• pockets
• profiles
• flat-bottom cuts
• general milling

#Feeds, Speeds, and Chip Load

#Feedrate

Feedrate is how fast the tool moves through the material.

In G-code:

F800

Usually means:

800 mm/min

if the machine is in millimeter mode.

#Spindle Speed

Spindle speed is how fast the cutter rotates.

Usually measured in:

RPM

#Chip Load

Chip load is how much material each cutting edge removes per revolution.

Simplified formula:

Feedrate = spindle RPM × number of flutes × chip load

Kerfio can teach this concept but should not pretend to know perfect values for every machine.

#Too Slow vs Too Fast

Too slow feed:

• rubbing
• burning wood
• melting acrylic
• tool heat
• poor tool life

Too fast feed:

• chatter
• missed steps
• broken tool
• rough finish
• machine overload

#Why Test Cuts Matter

Every DIY CNC differs.

Factors:

• rigidity
• spindle power
• tool sharpness
• material
• workholding
• stepper tuning
• backlash
• controller settings

Kerfio should encourage:

small test cuts
scrap material
conservative settings first
gradual optimization

#Workholding and Setup

Workholding means how the material is fixed to the machine.

Bad workholding is one of the biggest CNC risks.

#Common Workholding Methods

• clamps
• screws
• double-sided tape
• vacuum table
• spoilboard
• fixtures
• tabs in CAM
• masking tape + CA glue method

#Workholding Safety

Before running:

• material must not move
• clamps must not be in toolpath
• screws must not be in toolpath
• tool must clear clamps
• Z safe height must be high enough
• stock thickness must be known

#Kerfio Workholding Support Ideas

Kerfio should eventually support:

• clamp marker layer
• forbidden zone layer
• screw/fixture layer
• camera-visible clamp warning
• dry trace boundary check

For v1, Kerfio can allow users to add a Safety Boundary Layer or Annotation Layer in Kerf.

#Camera-Assisted CNC Concepts

#Why Camera Helps

A camera helps the user:

• see material position
• align design to real material
• select visual points
• take snapshots
• document jobs
• inspect after cutting
• reduce setup mistakes

#Why Calibration Matters

A camera image uses pixels.

The CNC machine uses millimeters.

Calibration maps:

image coordinates → machine coordinates

Without calibration, Kerfio can show the camera but cannot reliably move or align in machine coordinates.

#Camera Limitations

Camera workflows can be affected by:

• lens distortion
• camera angle
• lighting
• camera movement
• material reflectivity
• calibration error
• depth/parallax
• machine vibration

#Best Practice

• mount camera rigidly
• avoid moving camera after calibration
• use good lighting
• recalibrate if camera moves
• verify with known points
• use dry trace before cutting

#Kerfio Materials Presets

Kerfio v1.0.0 can include material presets as educational starting templates, not guaranteed cutting recipes.

#Material Preset Fields

A material preset may include:

• material name
• material type
• recommended tool type
• suggested operation types
• conservative depth/pass suggestion
• notes
• warnings

#Acrylic Preset Example

Material: Acrylic / PMMA
Recommended tool: sharp single-flute O-flute
Operations: cut outside, cut inside, trace
Warnings: avoid melting, use chip evacuation, test on scrap

#Wood Preset Example

Material: Plywood / wood
Recommended tool: upcut/downcut/compression depending finish
Operations: cut outside, drill, trace, V-carve later
Warnings: secure workpiece, manage dust, avoid burning

#Aluminum Preset Example

Material: Aluminum
Recommended tool: sharp single-flute or 2-flute carbide
Operations: shallow profile, drilling, professional CAM preferred
Warnings: requires rigidity, chip evacuation, conservative passes

#Important Warning

Material presets must be shown as:

starting guidance

not guaranteed machine-safe parameters.

The user must validate and test.

#Practical Workflows With External CAD/CAM

#Fusion 360 → Kerfio G-code

1. Design part in Fusion 360.
2. Use Manufacture workspace.
3. Select tool and operations.
4. Post-process for the controller.
5. Export G-code.
6. Open G-code in Kerfio.
7. Validate in Kerfio.
8. Preview.
9. Set work zero.
10. Dry trace if possible.
11. Run.

#Fusion 360 Sketch/DXF → Kerfio Kerf

1. Create 2D sketch in Fusion 360.
2. Export sketch as DXF/SVG where available.
3. Open Kerfio Kerf.
4. Import file.
5. Check units and scale.
6. Assign path actions.
7. Generate toolpath.
8. Preview and dry trace.

#FreeCAD CAM → Kerfio G-code

1. Create model in FreeCAD.
2. Create CAM/Path job.
3. Define tool and operations.
4. Post-process G-code.
5. Open G-code in Kerfio.
6. Validate, preview, run.

#FreeCAD/LibreCAD/AutoCAD DXF → Kerfio Kerf

1. Create clean 2D drawing.
2. Remove unnecessary construction lines.
3. Export DXF.
4. Import into Kerfio Kerf.
5. Check scale and units.
6. Assign actions.
7. Generate toolpath.

#Inkscape SVG → Kerfio Kerf

1. Create vector design.
2. Convert text to paths if needed.
3. Save/export SVG.
4. Import SVG into Kerfio Kerf.
5. Assign operations by path.
6. Generate toolpath.

#Recommended Kerfio Help Topics for AI Assistant

To make Kerfio AI Assistant useful, the guide should be split into knowledge files.

Suggested topics:

cnc_fundamentals
gcode_basics
cad_cam_workflow
fusion360_workflow
freecad_workflow
autocad_dxf_workflow
materials_acrylic
materials_wood
materials_aluminum
tooling_basics
feeds_speeds_basics
workholding_basics
camera_alignment
kerf_section
sketch_section
safety_policy
troubleshooting

These should be indexed in SQLite FTS and semantic search so the assistant can answer user questions.

#More Troubleshooting Topics

Kerfio should cover these common issues.

#Cut Size Is Wrong

Possible causes:

• wrong steps/mm
• wrong units
• wrong scaling on import
• DXF/SVG unit mismatch
• belt/pulley/leadscrew calibration issue
• machine losing steps

Kerfio should guide:

check units → test 100 mm move → calibrate steps/mm → check import scale

#Acrylic Melts

Possible causes:

• feed too slow
• spindle too fast
• dull tool
• poor chip evacuation
• too many flutes
• too deep pass

#Wood Burns

Possible causes:

• feed too slow
• dull tool
• spindle too fast
• poor chip evacuation
• repeated rubbing

#Aluminum Chips Weld to Tool

Possible causes:

• poor chip evacuation
• feed/speed wrong
• no lubrication/air
• dull tool
• too deep cut
• machine not rigid enough

#Toolpath Is Outside Machine Bounds

Possible causes:

• wrong work zero
• wrong units
• imported geometry too large
• design placed outside workspace
• incorrect machine profile size

#Camera Alignment Is Wrong

Possible causes:

• camera moved after calibration
• wrong calibration profile
• lens distortion
• poor lighting
• incorrect scale
• parallax
• non-flat material

#Machine Stops During Job

Possible causes:

• alarm/limit trigger
• lost connection
• controller buffer issue
• power issue
• serial communication issue
• emergency stop
• G-code error

#Additional Safety Guidance

Kerfio should always remind users:

• use a physical emergency stop
• know where the stop button is
• do not rely only on software stop
• keep hands away from moving machine
• wear eye protection
• manage dust and fumes
• ventilate laser/acrylic cutting areas
• secure workpiece
• check clamps
• check tool tightness
• verify spindle/laser off before setup
• dry trace risky jobs
• test new material/tool settings on scrap

#Glossary Additions

#External References Consulted

These references are useful for keeping Kerfio documentation and AI knowledge grounded:

• Autodesk Fusion documentation: DXF export and sketch export workflows.
• FreeCAD CAM/Path Workbench documentation: CAM jobs and G-code generation.
• Autodesk DXF reference: DXF as a CAD interchange format.
• GRBL documentation: real-time commands, status reports, and controller communication.
• CNC tooling and feed/speed references from CNC Cookbook, Onsrud, Mekanika, and other machining guides.
• General CNC machining overview references from engineering/manufacturing documentation.

Kerfio should not copy proprietary documentation. It should summarize general concepts and link users to official documentation where appropriate.

#CAD, CAM, CNC, Laser, and Manufacturing File Formats

Kerfio should include a file-format reference because users will import designs from different software and run files generated by different CAM tools.

#Native Kerfio File Formats

#G-code and CNC Program Files

Important:

A G-code file is already a machine program, not a design file.

Kerfio should treat G-code as executable instructions and validate it carefully.

#2D CAD and Vector Formats

#3D CAD Exchange Formats

Kerfio v1.0.0 is not a full 3D CAD/CAM system. For 3D models, users should use Fusion 360, FreeCAD, or another CAM tool to generate G-code, then use Kerfio to validate, preview, align, and run.

#Raster Image Formats

Raster images are pixels, not clean CNC geometry. They are useful as references, camera snapshots, and possibly future engraving sources.

#Laser-Specific and Design Workflow Formats

#Recommended File Workflow by Task

#Deep G-code Guide for Kerfio Users

#What Is G-code?

G-code is the common name for a family of machine-control commands used by CNC machines, 3D printers, laser machines, and other automated equipment.

A G-code program is a text file made of lines such as:

G21
G90
G0 X0 Y0 Z5
G1 Z-1 F100
G1 X50 Y0 F500
M5

Each line usually tells the controller to:

• set a mode
• move to a coordinate
• turn spindle/laser on/off
• set feedrate
• change coordinate system
• run a special machine function

#Why G-code Is Controller-Specific

G-code is not perfectly universal.

Different controllers and firmware may interpret some commands differently.

Examples:

• GRBL
• FluidNC
• LinuxCNC
• Mach3/Mach4
• Marlin
• Smoothieware
• Duet/RepRapFirmware
• Industrial Fanuc/Haas/Siemens-style controllers

Kerfio v1.0.0 should focus on GRBL/FluidNC-style controllers first.

#G-code Line Structure

Example:

G1 X50.0 Y20.0 Z-1.0 F800

Meaning:

#Modal Commands

Many G-code commands are modal.

This means they remain active until changed.

Example:

G90
G1 X10 F500
Y20
X0

After G90, the machine stays in absolute mode. After G1, following coordinate-only lines may still use controlled linear movement.

Kerfio validation should understand modal state.

#Units

G21 ; millimeters
G20 ; inches

This is very important.

If a file was created in inches but the user expects millimeters, the job size can be dangerously wrong.

#Absolute vs Relative Movement

G90 ; absolute
G91 ; relative

Absolute mode:

Move to X10 means go to coordinate X=10.

Relative mode:

Move X10 means move 10 units from current position.

Relative mode can be useful but dangerous if misunderstood.

#Work Coordinate Systems

Common work coordinate systems:

G54
G55
G56
G57
G58
G59

These define different work offsets.

Most basic jobs use:

G54

Kerfio should show the active coordinate system clearly.

#Motion Commands

Important:

G0 can move very fast. It should generally happen at safe Z above the material.

#Spindle and Laser Commands

Common commands:

M3 ; spindle/laser on
M4 ; spindle/laser on, controller-specific dynamic/reverse mode
M5 ; spindle/laser off
S1000 ; speed or power value depending controller

For diode laser workflows, S may represent power. For spindle workflows, it may represent RPM or controller-specific spindle speed.

Kerfio should warn whenever a file contains spindle/laser activation commands.

#Feedrate

Feedrate is set using F.

Example:

G1 X100 F800

If units are millimeters, this usually means:

800 mm/min

#Comments

Comments can appear as:

( This is a comment )
; This is also a comment in many senders/controllers

Kerfio should display comments but not treat them as commands.

#Common GRBL Real-Time Commands

For GRBL-style controllers:

These are not normal G-code lines. They are real-time control commands.

#What Kerfio Should Show for G-code

For a loaded G-code file, Kerfio should show:

• file name
• line count
• units
• bounds
• estimated duration
• commands used
• spindle/laser commands
• unsupported commands
• active coordinate system if detectable
• validation warnings
• preview segments
• current line during job

#G-code Guide for Users

Before running G-code:

1. Confirm units.
2. Confirm origin/work zero.
3. Confirm machine profile size.
4. Preview toolpath.
5. Check Z moves.
6. Check spindle/laser commands.
7. Check clamps/workholding.
8. Dry trace if possible.
9. Run with attention.

#How Kerfio Controls a CNC Machine

#Control Chain

The CNC control chain is:

Kerfio React UI
→ Python FastAPI Backend
→ Serial/Network connection
→ CNC controller firmware
→ Stepper drivers / spindle / laser outputs
→ Motors and machine motion

The UI never directly talks to the CNC controller.

The backend is the safety and communication layer.

#Main Controller Connection Types

Kerfio v1.0.0 should support or prepare for:

#What the Backend Does

The Python backend:

1. lists available serial ports
2. opens connection
3. reads controller greeting
4. sends status requests
5. parses machine status
6. sends commands safely
7. streams G-code line-by-line
8. manages controller responses
9. handles pause/resume/stop
10. logs commands and responses
11. blocks unsafe actions
12. updates UI through WebSocket

#Command Queue

Kerfio should use a command queue.

Why:

• avoids sending commands too fast
• tracks controller responses
• allows pause/stop
• preserves order
• improves reliability

Command flow:

UI action
→ backend API request
→ safety validation
→ command queue
→ serial writer
→ controller
→ response parser
→ state update
→ UI WebSocket event

#Status Polling

GRBL-style controllers can return status when asked with:

?

Status may include:

• machine state
• machine position
• work position
• feed/spindle
• buffer
• coordinate offset
• pins/limits depending config

Kerfio should poll status at a controlled interval and not overload the controller.

#G-code Streaming

A G-code sender must carefully send program lines and wait for controller responses such as:

ok
error:x
ALARM:x

Kerfio should:

• strip comments where appropriate
• keep original line mapping
• track sent lines
• track acknowledged lines
• pause safely
• stop/abort carefully
• show current line
• show errors clearly

#Why Safety Manager Is Required

The backend safety manager checks:

• machine connected
• machine not alarmed
• active job state
• target position within limits
• feedrate within limits
• action confirmation
• calibration validity
• toolpath validation

No dangerous action should bypass this layer.

#Machines Supported by Kerfio

#Primary Supported Machine Class in v1.0.0

Kerfio v1.0.0 should primarily support:

3-axis GRBL/FluidNC-style CNC router/laser machines

Especially:

• DIY CNC routers
• desktop CNC routers
• light aluminum/wood/acrylic CNC machines
• diode laser engraver/cutter frames
• hybrid CNC + laser machines
• GRBL-compatible controllers
• FluidNC ESP32-based controllers

#Likely Compatible Controllers

#Machine Types by Use

#CNC Router

Supported conceptually and primary target.

Use:

• wood
• acrylic
• foam
• plastics
• light aluminum with proper setup

#Diode Laser Machine

Supported conceptually through laser/spindle command awareness and Kerf laser actions.

Use:

• engraving wood
• engraving coated materials
• cutting thin compatible materials
• marking
• not ideal for transparent acrylic cutting

#Hybrid CNC + Laser

Very relevant to Kerfio.

The app should support:

• machine profile with spindle/laser capability
• operation type: spindle or laser
• safety warnings for active tool
• separate operation presets

#Pen Plotter / Marker

Could be supported through Trace/Move operations.

Useful for:

• testing
• drawing
• calibration
• marking material

#D Printer

Not the primary target.

Some concepts overlap, but Kerfio is not a slicer or 3D printer host.

#CNC Mill

Small/light mills may be conceptually compatible if controller is GRBL-like.

But professional metal milling requires careful CAM and machine-specific setup.

#CNC Plasma

Not target for v1. Requires special torch height control, plasma safety, pierce delay, and different workflows.

#CNC Lathe

Not target for v1. Lathe G-code and coordinate logic differ significantly.

#Axis Support

v1.0.0 target:

3-axis: X, Y, Z

Future:

A-axis rotary
dual Y motors awareness
tool changer awareness
spindle control improvements
laser-specific modes

#Expanded CNC Glossary and Abbreviations

#General Terms

#Coordinates and Motion

#Tooling

#Cutting Parameters

#G-code Abbreviations

#File Format Abbreviations

#Help Center Structure for App and Website

This document should become the foundation for the in-app help center, website documentation, and AI assistant knowledge base.

Recommended help center categories:

#Getting Started

• What is Kerfio?
• First setup
• Create machine profile
• Connect controller
• Connect camera
• First Sketch
• First Kerf project
• First G-code run

#Kerfio UI Guide

• Dashboard
• Sketch
• Kerf
• G-code
• Machine
• Camera / Vision
• Job
• Probe
• Macros
• Console
• Settings
• AI Assistant

#CNC Basics

• CNC fundamentals
• CAD/CAM/G-code
• Coordinates
• Work zero and machine zero
• Homing and limits
• Toolpaths
• Feeds and speeds
• Materials
• Tooling
• Workholding
• Safety

#File Formats

• Kerfio native files
• G-code files
• SVG
• DXF/DWG
• STEP/IGES/STL
• Raster images
• Laser design files

#External Software Workflows

• Fusion 360 to Kerfio
• FreeCAD to Kerfio
• AutoCAD to Kerfio
• Inkscape to Kerfio
• Existing CAM to Kerfio

#Troubleshooting

• machine disconnected
• camera offline
• G-code validation error
• out-of-bounds toolpath
• wrong scale
• acrylic melting
• wood burning
• aluminum chatter
• run disabled
• calibration wrong

#Safety

• emergency stop
• machine setup
• laser safety
• spindle/router safety
• dust/fume safety
• workholding
• dry trace
• validation

#AI Assistant

• what Kerfio Assistant can do
• what it cannot do
• Sketch/Kerf document editing
• language support
• memory
• OpenRouter setup
• local knowledge search

#AI Knowledge Base Split Recommendation

For the AI assistant, split this document into smaller Markdown files.

Recommended files:

01_app_overview.md
02_getting_started.md
03_dashboard.md
04_sketch.md
05_kerf.md
06_gcode_section.md
07_machine.md
08_camera_vision.md
09_job.md
10_probe.md
11_macros.md
12_console.md
13_settings.md
14_ai_assistant.md
15_cnc_fundamentals.md
16_gcode_guide.md
17_file_formats.md
18_external_cad_workflows.md
19_materials_acrylic.md
20_materials_wood.md
21_materials_aluminum.md
22_tooling.md
23_feeds_speeds.md
24_workholding.md
25_camera_alignment.md
26_controller_connection.md
27_supported_machines.md
28_glossary.md
29_troubleshooting.md
30_safety.md

Each file should have frontmatter:

---
id: gcode_guide
title: G-code Guide
category: cnc_knowledge
version: 1.0.0
sections: [gcode, machine, kerf]
risk_level: safe
---

#Additional Useful Features for Future Kerfio Documentation

Future help center and assistant knowledge should include:

• controller-specific GRBL guide
• controller-specific FluidNC guide
• post-processor recommendations
• sample safe test G-code
• sample Sketch exercises
• sample Kerf projects
• machine calibration guide
• steps/mm calibration guide
• backlash testing guide
• camera calibration printable target
• material test-cut templates
• laser focus test guide
• spindle runout check guide
• clamp/safety boundary workflow
• beginner CNC checklist
• pre-run checklist
• post-job inspection checklist
• maintenance checklist

#Pre-Run Checklist

Kerfio should include a pre-run checklist.

Before running:

Machine connected
Correct machine profile selected
Workpiece firmly held
Tool installed and tightened
Correct tool selected
Spindle/laser setup checked
Work zero set
Safe Z checked
G-code/toolpath validated
Toolpath inside machine bounds
Clamps outside toolpath
Camera alignment verified if used
Dry trace completed if needed
Emergency stop accessible
Dust/fume control ready
User is watching the first movement

#Post-Job Checklist

After job:

Spindle/laser off
Machine stopped
Tool clear of material
Job completed without alarm
Part still secure
Inspect cut quality
Save job report if needed
Save snapshot if useful
Clean chips/dust
Record material/tool settings if successful

#Beginner Test Files and Exercises

Kerfio should include or generate simple test exercises.

#Movement Test

Purpose:

verify X/Y/Z directions and scale

#50 mm Square Test

Purpose:

check dimensional accuracy

#Circle Test

Purpose:

check backlash and axis calibration

#Drill Point Test

Purpose:

verify point positioning

#Camera Alignment Test

Purpose:

verify camera-to-machine calibration

#Dry Trace Test

Purpose:

verify work origin and job boundary before cutting

#Final Help-Center Foundation Summary

The Kerfio help center should teach three things:

1. How to use Kerfio.
2. How CNC workflows work.
3. How to work safely and intelligently.

The AI assistant should use the same help-center materials as its local knowledge base.

This creates one consistent source of truth for:

in-app help
website documentation
AI assistant answers
developer documentation
user onboarding
troubleshooting

#Updated Final Summary

Kerfio CNC v1.0.0 should be both:

a practical CNC control application

and:

a learning-friendly CNC environment

The app should guide users from simple geometry to safe machine execution.

It should help users understand:

• CAD vs CAM vs G-code
• how to use Fusion 360, FreeCAD, AutoCAD, and SVG/DXF tools beside Kerfio
• how Sketch and Kerf fit into the workflow
• what G-code does
• why validation matters
• how material choice affects tooling and settings
• why workholding, safe Z, and dry trace matter
• how camera alignment works
• how to avoid common CNC mistakes

Kerfio’s strongest value is:

Visual CNC preparation + camera-assisted alignment + safe control + AI guidance.

#Final Summary

Kerfio CNC v1.0.0 should be understood as:

A modern, visual, safety-first CNC application that combines machine control, simple design, layered manufacturing preparation, live camera vision, local project storage, and an embedded AI assistant.

The most important sections are:

• Dashboard for simple readiness and next actions
• Sketch for drawing geometry
• Kerf for turning geometry into CNC action
• Machine for connection and control
• Camera / Vision for real-world visual alignment
• G-code for existing job files
• Job for execution monitoring
• Settings for configuration
• Kerfio AI Assistant for help, guidance, and safe action preparation

The application must remain:

simple for the user
professional in design
strict in safety
modular in architecture
ready for future AI/vision growth