Firmware Capabilities Protocol/ua
English • العربية • български • català • čeština • Deutsch • Ελληνικά • español • فارسی • français • hrvatski • magyar • italiano • română • 日本語 • 한국어 • lietuvių • Nederlands • norsk • polski • português • русский • Türkçe • українська • 中文(中国大陆) • 中文(台灣) • עברית • azərbaycanca • |
Contents
- 1 Idea
- 2 Protocol definition
- 3 Currently-defined capabilities
- 3.1 Cap:ARCS
- 3.2 Cap:AUTOLEVEL
- 3.3 Cap:AUTOREPORT_SD_STATUS
- 3.4 Cap:AUTOREPORT_TEMP
- 3.5 Cap:AUTOREPORT_POS
- 3.6 Cap:BABYSTEPPING
- 3.7 Cap:BINARY_FILE_TRANSFER
- 3.8 Cap:BUILD_PERCENT
- 3.9 Cap:CASE_LIGHT_BRIGHTNESS
- 3.10 Cap:CHAMBER_TEMP[ERATURE]
- 3.11 Cap:CONFIG_EXPORT
- 3.12 Cap:COOLER_TEMP[ERATURE]
- 3.13 Cap:CUSTOM_FIRMWARE_UPLOAD
- 3.14 Cap:DOOR
- 3.15 Cap:EEPROM
- 3.16 Cap:EMERGENCY_PARSER
- 3.17 Cap:EP_BABYSTEP
- 3.18 Cap:EXTENDED_M20
- 3.19 Cap:HOST_ACTION_COMMANDS
- 3.20 Cap:HOST_RESCUE
- 3.21 Cap:LASER
- 3.22 Cap:LEVELING_DATA
- 3.23 Cap:LFN_WRITE
- 3.24 Cap:LONG_FILENAME
- 3.25 Cap:MEATPACK
- 3.26 Cap:MOTION_MODES
- 3.27 Cap:MULTI_VOLUME
- 3.28 Cap:OUT_OF_ORDER
- 3.29 Cap:PAREN_COMMENTS
- 3.30 Cap:QUOTED_STRINGS
- 3.31 Cap:PRINT_JOB
- 3.32 Cap:PROGRESS
- 3.33 Cap:PROMPT_SUPPORT
- 3.34 Cap:REPEAT
- 3.35 Cap:RUNOUT
- 3.36 Cap:SDCARD
- 3.37 Cap:SD_WRITE
- 3.38 Cap:SERIAL_XON_XOFF
- 3.39 Cap:SOFTWARE_POWER
- 3.40 Cap:THERMAL_PROTECTION
- 3.41 Cap:SPINDLE
- 3.42 Cap:TOGGLE_LIGHTS
- 3.43 Cap:VOLUMETRIC
- 3.44 Cap:Z_PROBE
Idea
While it is nice if a firmware supports some special features, it would be even better if hosts would detect that these are available so they start using them. Especially with the wild growth of firmware forks and versions, no host can know which variant can handle what. So at least for Repetier-Firmware we introduce with version 1.0 a new simple protocol to tell hosts what features are available, so they can activate them.
Protocol definition
To make it easy to detect, a standard M115 report gets now extended by one or more lines, each line telling what capability. These lines have the following format:
Cap:<NameOfCapability>:<0 or 1>
Notice: no spaces allowed, Name is upper case with underline to separate words. Lines MUST start with "Cap:" so it can be parsed very quickly by hosts.
The last value indicates if that capability is supported or not. The simple absence of a message is not enough since it would be possible, that the firmware simply does not report capabilities at all and host has to make assumptions like showing EEPROM editor even with the risk that it is not available. Whereas a 0 value shows that a function is known, but the functionality is not implemented/active.
Knowing different developers will add other capabilities is no real problem as long as all names differ, so hosts can distinguish them by name. Hosts not understanding a name simply ignore them.
Currently-defined capabilities
Cap:ARCS
The firmware supports high-resolution arc and circle moves with G2 and G3.
Cap:AUTOLEVEL
The firmware supports auto-leveling with G29.
Cap:AUTOREPORT_SD_STATUS
The firmware will auto-report the SD Card status, using M27 S to enable and set the interval.
Cap:AUTOREPORT_TEMP
The firmware can automatically report temperatures. This feature must be enabled by M155 S[interval] so hosts won't get redundant reports from both M105 and this feature.
Cap:AUTOREPORT_POS
The firmware can automatically report the current position. This feature must be enabled by M154 S[interval] so hosts won't get redundant reports from both M114 and this feature.
Cap:BABYSTEPPING
The firmware can do Z babystepping with the M290 command. It may or may not be able to babystepping on the XY axes also.
Cap:BINARY_FILE_TRANSFER
The firmware can receive a Binary File to save on its mounted media with M28 B1 <filename>, completed with M29. See firmware documentation for usage.
Cap:BUILD_PERCENT
The firmware supports setting the progress percentage with M73 P, required to show progress for host-based printing on the machine's display.
Cap:CASE_LIGHT_BRIGHTNESS
The firmware supports setting the case light brightness with M355 S and values 2-255.
Cap:CHAMBER_TEMP[ERATURE]
The firmware has support for a Chamber thermal sensor.
Cap:CONFIG_EXPORT
The firmware supports the M503 C command to export the build-time configuration to the SD Card / Flash Drive. (See Marlin's description of CONFIGURATION_EMBEDDING
for details.)
Cap:COOLER_TEMP[ERATURE]
The firmware has support for a Cooler thermal sensor, for a laser or other device that needs active cooling.
Cap:CUSTOM_FIRMWARE_UPLOAD
The firmware supports M20 F to list all ".bin" files on the firmware-mounted SD Card / Flash Drive.
Cap:DOOR
The firmware sends signals to allow hosts to warn about an open door. The messages are:
DoorOpened
DoorClosed
The door state message may optionally be prefixed with "echo:".
Cap:EEPROM
The firmware is compiled with EEPROM support.
Cap:EMERGENCY_PARSER
The firmware supports immediate execution of commands M108, M112, and M410. With this capability M108 can be used to break out of M0/M1, M109, and M190.
Cap:EP_BABYSTEP
The firmware can do Z babystepping with the M293 and M294 commands. If the firmware also has EMERGENCY_PARSER
then the babystepping will be asynchronous.
Cap:EXTENDED_M20
The firmware supports M20 L to include long filenames in the file listing.
Cap:HOST_ACTION_COMMANDS
The firmware can send //action: commands to inform host software that the machine has paused or is resuming SD-based printing. The following commands should be handled by the host:
pause |
The printer wants the host to pause. |
pause filament_runout T0 |
The printer wants the host to pause for filament runout. The tool is optional. |
paused |
The printer has paused SD printing. |
paused filament_runout T0 |
The printer has paused SD printing for filament runout. The tool is optional. |
resume |
The printer wants the host to resume. |
resumed |
The printer will resume SD printing. |
cancel |
The printer wants to cancel host printing. |
start |
The printer wants the host to start. |
poweroff |
The printer wants the host to kill the power. |
filament_runout T0 |
pause(d) filament_runout **
|
probe_rewipe |
Bed probing failed, so the firmware is trying again. |
probe_failed |
Bed probing failed so the firmware is stopping. |
Cap:HOST_RESCUE
The firmware has M415 to help hosts to recover from an interrupted connection or power loss. See the M415 description on the G-codes page for full details.
Cap:LASER
The firmware can control a Laser with M3, M4, M5 commands.
Cap:LEVELING_DATA
The firmware supports M420 V to report the stored leveling (mesh or matrix) data.
Cap:LFN_WRITE
The firmware supports long filenames in commands that create and delete files such as M28 and M30, and also commands that open files such as M23 and M32.
Cap:LONG_FILENAME
The firmware supports long filenames via the M33 command (used to asynchronously update the user-visible portion of a host-side file browser).
Cap:MEATPACK
The firmware supports the MeatPack stream compression protocol by Scott Mudge as provided by the MeatPack OctoPrint plugin.
Cap:MOTION_MODES
The firmware supports motion modes for G0, G1, G2, G3, G5, and G38, and adds the G80 command to cancel the current motion mode. With motion modes the firmware only needs the parameters for subsequent moves following one of these common motion commands.
Cap:MULTI_VOLUME
The firmware can mount different media volumes via M21 P<id> and possibly M21 S (SD Card) and M21 U (USB Flash Drive). Under this protocol only one volume is mounted at a time.
Cap:OUT_OF_ORDER
Currently all commands are parsed in order with the exception of some emergency commands. These are executed as fast as they get detected. The problem is that they stay in queue until they get handled in correct order to provide the "ok" for host in right order to not confuse host.
Now there are cases where you need to send multiple "emergency" commands like M876 to navigate through e.g. filament change. When you need to purge several times the buffer is full and firmware does not react any more on host navigation.
There are also commands where it would be nice if they work out of order as well because we do not want to wait like babystepping or which are just informational and do not need to be executed in order like M105. Imagine being able to send M115 during slow homing and get updates.
So this is where this extension kicks in. It is designed to be fully backwards compatible to existing hosts. The idea is to have a list of codes that can be executed out of order. These commands get removed from input queue once executed and hence free the input buffer.
Sequence is as follows:
1. Report in M115 the capability for out of order execution:
Cap:OUT_OF_ORDER:1
2. Wait for host to confirm it understands the extension and send supported codes:
M876 S1 out_of_order:M108 M112 M290 M876
Mark feature enabled on the source serial port. When multiple ports exist not all ports may support it. The host now has a list of all codes that are handled out of order. That way the list can be extended any time without requiring host changes.
3. When an out of order command is sent to a port that supports it, it will be executed and confirmed. For example:
ooo M290
Out of order commands should be sent with no line number. That would cause problems for the sequential line numbering of regular commands. With the "ooo" instead of "ok" host knows the emergency buffer is ready and it is safe to send the next out of order command.
Race Condition:
When opening a connection to the board doesn't reset the connection the firmware might have out-of-order enabled while the connecting host does not, and expects an "ok" instead of "ooo" response. To help solve the issue a call of M115
should disable out-of-order automatically until the host reenables it on next seeing the OUT_OF_ORDER
capability. As long as the host sends M115
before any out-of-order commands this will solve the race condition.
Cap:PAREN_COMMENTS
The firmware allows parentheses comments within G-code lines.
Cap:QUOTED_STRINGS
The firmware allows quoted strings to be used as G-code word parameters and as "the string argument."
Cap:PRINT_JOB
The firmware supports the Print Job Timer commands M75 Start, M76 Pause, and M77 Stop.
Cap:PROGRESS
The firmware supports the progress protocol:
- M530 S<printing> L<layer> - Enables explicit printing mode (S1) or disables it (S0). L can set layer count.
- M531 filename - Set the filename being printed.
- M532 X<percent> L<curLayer> - Update current print state progress (X=0..100) and layer L.
This allows a host to enable a special information mode on LCD display, so users see progress in percent, model being printed, layer being printed, and total layer count. (Hosts can also use M117 to show time remaining on the LCD status line.)
This feature should only be enabled if a display is available to show it, otherwise the extra commands are useless.
Cap:PROMPT_SUPPORT
The firmware supports the ability to interact with the host and provide notifications and prompts for users on the host side.
Cap:REPEAT
The firmware can repeat sections of G-code marked with the M808 command when the firmware is running the print from an SD card. This is useful to reduce G-code size when repeating objects on belt printers.
Cap:RUNOUT
The firmware is configured with a Filament Runout Sensor that can be enabled/disabled with M412. It may or may not be able to initiate filament change with M600.
Cap:SDCARD
The firmware can print from an SD Card (or USB Flash Drive). If this capability is absent, use SD commands to check for SD capability.
Cap:SD_WRITE
The firmware can write to the attached media using commands M28 and M29, and may also log incoming commands with M928.
Cap:SERIAL_XON_XOFF
The firmware supports serial XON/XOFF handshaking.
Cap:SOFTWARE_POWER
The firmware supports enabling/disabling power with M80 and M81.
Cap:THERMAL_PROTECTION
The firmware has thermal protection enabled. Hosts can use this item to warn users of a potential fire hazard.
Cap:SPINDLE
The firmware can control a Spindle with M3, M4, M5 commands.
Cap:TOGGLE_LIGHTS
The firmware supports turning the case lights on/off with M355 S1 and M355 S0. (May also support setting case light brightness with S values 2-255.)
Cap:VOLUMETRIC
The firmware supports Volumetric Extrusion with M200 T D.
Cap:Z_PROBE
The firmware supports single point Z probing with G30.