g2core REST Resources

PRELIMINARY - FOR DISCUSSION

These preliminary design pages are for discussion of the g2core REST interface:

• g2core REST Interface
• g2core REST Resources
• g2core REST Examples
• g2core REST Swagger

---

Resource Model Overview

Top level resources include:

• Machine: A composite resource describing the machine and its state
• StatusReport: An endpoint for getting status reports for reporting machine state
• Operation: Launch, monitor and control long-running machine actions or sets of actions
• Job: Launch, monitor and control sets of operations that define a complete "job"

Planned in addition to the above:

• OperationMgr resource that orchestrates operations and can be used to declaratively assemble jobs, or to build more interactive control structures for things like pick and place, pipetting, and applications where just sending a Gcode tape is inadequate.
• JobMgr resource that manages queues of jobs and scheduling

A top level view of resources follows with some more resource details provided at the and of this page

Machine Resource

The machine resource exposes machine configuration and state, and is accessed via the Machine REST endpoint.

Machine is a composite resource consisting of a hierarchy of resources that can be accessed individually. Examples include: axis and motor configurations; heater, spindle and coolant controls and feedback, board communications parameters; Gcode power-up defaults and Gcode coordinate system offset tables.

Resource attributes can be static or dynamic. Static attributes are used to configure the machine - like motor configuration settings. Dynamic resources report machine state, like motor power state (e.g. energized / not energized). Most state attributes (dynamic attributes) are read-only. State can be queried at any time, but is typically only of interest during Operations.

A top level view of the machine may include:

• Machine (root)

• Machine configuration (static):

  • Machine information
  • Communications parameters
  • Global machining parameters
  • Axis configurations
  • Motor configurations
  • Digital output configurations
  • Digital input configurations
  • Analog input configurations
  • Spindle configuration and state
  • Coolant configuration and state
  • Heater configuration and state
  • Gcode initialization defaults
  • Gcode offset tables (G54 - G59, G28, G30, G92)

• Machine state (dynamic):

  • Gcode model state
  • POS: Motor position with offsets (work space)
  • MPO: Motor position in machine coordinates
  • OFS: Work space offsets
  • HOM: Homing state
  • PRB: Probing state
  • PWR: Motor power state (motor enables and power levels)
  • DO: Digital output state (current values of outputs / PWM levels)
  • DI: Digital input state (current values of inputs)
  • ADC: Analog input state (current values of inputs)
  • _xx: Diagnostic states

Status_report Resource

Status reports are accessible via the status endpoint, accessing the g2core {sr:n} function with some additional tricks. Status reports are configured via the machine endpoint to set 'watches' on various dynamic attributes that are then collected into a single status report.

• A status report called with no 'value' in the body acts similarly to {sr:n}, the entire status report as configured is returned. This example returns:

{"line":3236,"posx":10.2318,"posy":-20.32,"posz":-2.755,"feed":1250,"vel":1203.33,"unit":1,"stat":5}

- A status report called with a null-valued attribute list in the body will return the values of just those attributes in the list. Example: 

{"posx":n,"posy":n,"posz":n,"vel":n,"stat":n} returns {"posx":10.2318,"posy":-20.32,"posz":-2.755,"vel":1203.33,"stat":5}

- A status report called with a non-null-valued attribute list in the body will return the values of just those attributes in the list that are different from those submitted. Example: 

{"posx":10.2318,"posy":-20.32,"posz":-2.755,"vel":1203.33,"stat":5} returns {"posx":11.4782,"posy":-19.022,"vel":1208.211}

## Operation Resource
The operation resource is a way to initiate and monitor a long-running function - for example a homing sequence or bed leveling tramming. An operation sets up a temporary context through which the caller can initiate an operation, receive status of operation progress, modify operation parameters, or abort the operation. 

- Operation ID: generated by the POST - may be used for later referral
- Operation body: the Gcode and/or JSON to be sent to the machine
- Operation state: the state variables monitored for that operation

Actions:<br>
- Initiate an operation<br>
  Send: `POST /operation` Post as text/plain with gcode or JSON command to be sent to board in the body<br>
  Retn: `operation ID`, e.g. 95. The response is just the id

- Query an operation<br>
  Send: `GET /operation/95` to fetch it's JSON state object<br>
  Retn: Operation state is returned as application/json

- Modify an operation<br>
  Send: `PUT /operation/95` to alter it's JSON state object<br>
  Retn: Operation state is returned as application/json

### Limitations
The following limitations are placed on this initial implementation:

- Operations are a single threaded - only a single operation can be active at a time. An operation must run to completion or be terminated to run another operation. This is not a big limitation as the current generation of machines can generally only run a single operation at a time. One place that would benefit from multi-threading is heaters - running a homing or bed tramming sequence while a heater is heating up. We solve this by breaking the heater cycle into 2 operations, first to set the target temperature and begin heating, second to wait until the heater is up-to-temp. Put homing and bed leveling in between these two. 

- There is no OperationsMgr declarative orchestration resource to to manage complex cycles. At the current time these are programmatic, such as pre-job sequencing and job queueing.

### Common Operations
Any Gcode or JSON sequence can be bundled as an operation, but here are the common ones:

- Jogging
- Run a job file
- Select tool / change tool
- Homing sequence - running one or more axes to limit switches
- Reset machine coordinates - set machine coordinates to arbitrary values
- Bed leveling tramming - consists of three probe actions followed by enabling tramming
- Probe sequence when performed outside of a Gcode program
- Spindle speed changes with delays / detection of speed changes

## Job Resource
The job resource is a specialized resource that can be submitted to an Operation to run a Gcode file. The Job resource provides the file, and can also contain other parameters that are useful for job setup and runtime.

_We need to decide what's in a job. I think this discovery is better done at coding time. It will become apparent what is needed. The job states are notional based on what we can do to a job and what we know about job processing._

- Job
  - Job state: PENDING, RUN, STOP, END, PAUSE, ABORT...
  - Job time
  - Overrides:
    - Feed rate override (on/off, factor)
    - Traverse rate override (on/off, factor)
    - Spindle speed override (on/off, factor)
    - Override coolant settings (manual coolant settings)

The dynamic machine state should be exposed via the Operator during the job operation.