-
Notifications
You must be signed in to change notification settings - Fork 295
g2core REST Interface
PRELIMINARY - FOR DISCUSSION
These preliminary design pages are for discussion of the g2core REST interface:
The g2core REST API is the top layer of the three nested APIs:
- g2core REST API - exposed via node-g2core-server module
- g2core NodeJS API - exposed via node-g2core-api module
- g2core firmware API - exposed via serial and USB from the g2core firmware
The g2core REST API is a RESTful API that allows control of a CNC machine and associated "print jobs". The conceptual model has these layers:
- Host Functions - e.g communications setup, managing files, other non-CNC things
- Machine Setup - job-agnostic machine configuration and actions (e.g. homing)
- Job Setup and Mgmt - job and material setup, pre-job operations, job queuing, etc.
- Job Runtime - job start and stop, pause/resume, status reporting, feedback...
These functions are the domain of the host operating system and don't involve the CNC machine at all. In general the g2core REST API tries not to concern itself with host functions, but some functions such as receiving, storing, and locating files are necessary to upload and manage files over the REST interface. The API may implement:
- File and filesystem primitives such as get, view, edit, write, store
- Advanced viewers such as 3d rendering
Additional host functions are not the domain of this API, may include:
- Communications functions such as wireless setup and connectivity.
- CAD/CAM and other modeling and design
Machine setup reads and writes parameters and initiates actions to configure the CNC machine independently of any given job. They may be done once and once only, periodically, or before or after a job. These may include:
-
Machine Settings exposes machines settings generally not changed on a per-job basis. E.g. communications settings, reporting levels, machine startup defaults. All settings exist at the same level, so it's up the the UI to determine which to show to users, which are "expert", and which should be hidden (if any). Machine configuration is implemented as synchronous REST calls to machine resources.
-
Machine Operations includes actions such as homing, axis tramming or automatic bed leveling that may be run on power up, periodically, or before a job is run. Machine operations are implemented as long-running asynchronous REST calls bundled in an operation resource that provides a monitoring and control context for the duration of the operation.
Job setup and management handles commands to prepare a job for runtime. It may operate on machine resources, perform operations, and on job resources and the job queue (job list), which orders the jobs to be run.
The model for job management is borrowed from commercial printing operations. A 'job jacket' is a container for a job. It includes one or more 'print files', a 'master' JSON doc with job metadata and a declarative control specification, and any other files that make up the job bundle such as multi-file prints, runtime logs, etc. (In implementation the jacket can be a directory containing a bunch of files).
The Job API implements:
- Fetch and manipulate job files
- Define job parameters - e.g. filament type and size
- Preview/check job file
- Queue and order jobs for execution
Job runtime scopes those things that happen while the job is running. It is differentiated from job setup because there are commands that can only be executed during job runtime (e.g. feedholds), and other commands that should not be executed during runtime (e.g. machine configuration). The REST interface implements the following runtime state changes:
- Start/stop job (running the Gcode)
- Pause and resume job (feedhold / cycle start)
- In-job manual operations (tool change, filament restock)
- Report job progress
- Job exception reporting, handling, and job recovery
A Note on Formats: Most of the functions above are accessed using REST/JSON, with the Gcode commands being the exception. We call the Gcode a 'tape' because it's pre-planned motion that executes linearly, does not loop or branch (g2core does not support O codes), and can be controlled like a tape machine. It can be stopped, started, sped up and slowed down, paused and resumed. You may be able to do things in the pauses such as manual tool changes, but that doesn't change the tape itself. Tapes used to actually be paper tapes, just like phones used to have dials and dial tones.
Getting Started Pages
- Home
- What is g2core?
- Who uses g2core?
- Jerk-Controlled Motion
- Getting Started with g2core
- Connecting to g2core
- Configuring g2core
- Flashing g2core
- Troubleshooting
Reference Pages
- Gcodes
- Mcodes
- Text Mode
- JSON Communications
- GPIO Digital IO
- Alarms & Exceptions
- Power Management
- Coordinate Systems
- Status Reports
- Status Codes
- G2 Communications
- Tool Offsets and Selection
- Probing
- Feedhold, Resume, Job Kill
- Marlin Compatibility
- 9 Axis UVW Operation
- gQuintic Specs
Discussion Topics
- Roadmap
- GPIO for 1.X Releases
- Toolheads
- Raster Streaming Prototol
- g2core REST Interface
- Gcode Parsing
- G2 3DP Dialect
- Consensus Gcode
- Digital DRO
- Overview of Motion Processing
Developer Pages
- Development & Contribution
- Branching and Release - DRAFT
- Getting Started with g2core Development
- Project Structure & Motate
- Compiling G2
- OSX w/Xcode
- OSX/Linux Command Line
- Windows10 w/AtmelStudio7
- Debugging G2 on OSX
- Board and Machine Profiles
- Arduino Due Pinout
- Arduino DUE External Interfaces
- Diagnostics
- Debugging w/Motate Pins
- Development Troubleshooting
- g2core Communications
- Git Procedures
- Windows 10 / VMware 8 Issues
- Dual Endpoint USB Internals
- G2core License
- VSCode Setup
- Compatibility Axioms
- Wiki History