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

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

#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