-
Notifications
You must be signed in to change notification settings - Fork 295
Compatibility Axioms
g2core is used with third-party UI agents that cannot be expected to update on the same schedule as g2core. To avoid breaking extant copies of those UIs, interface changes must be done carefully. Here is a list of do's and dont's to minimize breakage.
-
Do not delete functions. When enhanced functionality is provided - for example the change in spindle control - the old functionality with the existing names and semantics should be retained. It is okay to implement the old names using the new internals, so long as the semantics are the same. The ideal approach is to gracefully extend the old scheme by adding new names that work in conjunction with the old ones, but when that is not feasible, add a complete coherent set of new names while retaining the old set.
-
Do not make the UI agent infer functionality from the version number. Instead ensure that the presence of new functions can be discovered by probing for the new functions individually.
-
Make the probing process efficient. Sending a command and waiting for a NAK (error message) is time-consuming if you have to probe for numerous functions. Asking for a list of supported features is much better, since there is only one send-response delay.
-
Gracefully handle requests for unsupported features. In current versions, if the UI asks for a report format that contains unsupported fields, the g2core parser errors out and ignores fields after the one in error. It would be better to continue parsing, accepting the valid fields, then issue a single report showing the rejected ones.
-
Do not change semantics of existing functions. A case in point is the desire to split the report format setting over multiple lines to work around line length limitations. That is a good thing, but it should be done with a new name instead of by changing the behavior of the existing name.
I realize that the namespace can start to look cluttered with the proliferation of names, but that is a price that must be paid in an ecosystem of many independently-developed components. The companies that have been most successful in the software industry are the ones who have done the best job of compatibility.
Line length limitations for json commands will start to be a problem. I see two paths forward. The first is necessary for compatibility with existing usage, the second is a long term add-on.
- Introduce some form of continuation line so that long json objects can be represented by multiple well-formed lines. This approach works in the context of the existing line-length-limited communications style.
- Migrate toward an improved transport protocol that is not so dependent on line semantics. My choice would be TCP, since it is perhaps the most battle-tested protocol on the planet, and has out-of-band messaging to handle jump-the-queue things like feedholds and override. It can be done efficiently over serial lines by using Van Jacobson header compression over SLIP. Over other channels like Ethernet and WiFi you just use it directly. You just stream the gcode and let TCP handle the flow control.
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