Difference between revisions of "Printer Command Set"

From Cartesian Co. Wiki
Jump to: navigation, search
Line 1: Line 1:
 
= Overview =
 
= Overview =
  
See [[Printer Command Set Table]] for a table of command byte-code mappings.
+
Rapid prototyping hardware such as 3D printers and CNC routers often interpret [http://en.wikipedia.org/wiki/G-code G-code] instructions. G-code is well suited to multi-tool vector based plotting, which printing a circuit is not. A communication protocol has been specifically designed for the Argentum which should be easy for the hobbyist community to experiment with.
 +
 
 +
Each command has a byte-code identifier and zero or more parameters that include unsigned and signed 8, 16, and 32 byte integers; null terminated arrays; and arrays of a length defined by a preceding integer parameter. The command name, e.g. ''getPosition'', is used in the AgInterface Python controller and the command handler functions in the firmware. When extending the command set or implementing a serial controller or file writer, keep in mind the following:
 +
 
 +
* The commands are byte-packed (for computers to read). As in, the numbers are signed or unsigned integers of a particular byte-size. In contrast, G-code uses string representations of numbers (for humans to read). Unfortunately, this means it is not easy to write commands manually.
 +
* Ideally, commands that &quot;set&quot; information or make the printer perform a function have uppercase ASCII byte-code identifiers, and commands that &quot;get&quot; information have lowercase. This is not a requirement, and eventually the human readable ASCII characters may run out.<br />
 +
* The AVR microcontroller is little-endian, so be careful if you're using some exotic controller hardware.
 +
 
 +
The Argentum Printer can read commands from the serial interface or files on an SD card. When reading from a file, the responses are ignored. See [[Printer Command Set Table]] for a table of command byte-code mappings.
  
 
= Command Set Functions =
 
= Command Set Functions =
Line 7: Line 15:
 
== Position and movement ==
 
== Position and movement ==
  
=== setPosition ===
+
=== getPosition ===
  
 
<blockquote>Command: 'p'
 
<blockquote>Command: 'p'
Line 15: Line 23:
 
Get the current head position in steps, relative to the zero-point.
 
Get the current head position in steps, relative to the zero-point.
  
=== getPosition ===
+
=== setPosition ===
  
 
<blockquote>Command: 'P', ''xpos'': int16, ''ypos'': int16
 
<blockquote>Command: 'P', ''xpos'': int16, ''ypos'': int16
Line 39: Line 47:
 
Move the head by ''dx'' steps horizontally and ''dy'' steps vertically.
 
Move the head by ''dx'' steps horizontally and ''dy'' steps vertically.
  
=== getHeadSpeed ===
 
 
<blockquote>Command: 's'
 
 
Response: ''speed'': uint8
 
</blockquote>
 
=== setHeadSpeed ===
 
 
<blockquote>Command: 'S', ''speed'': uint8
 
 
Response: none
 
</blockquote>
 
 
== Cartridge ==
 
== Cartridge ==
  
Line 63: Line 59:
 
=== fire ===
 
=== fire ===
  
<blockquote>Command: 'F', ''cartridge'': uint8, ''primitive'': uint8, ''address'': uint8, ''count'': uint8
+
<blockquote>Command: 'F', ''cartridge'': uint8, ''nozzle'': uint8, ''count'': uint8
  
 
Response: none
 
Response: none
 
</blockquote>
 
</blockquote>
Fire the nozzle at ''address'' of ''primitive'' of cartridge number ''cartridge'' a total of ''count'' times.
+
Fire the ''nozzle'' number of cartridge number ''cartridge'' a total of ''count'' times.
  
 
=== printRow ===
 
=== printRow ===
Line 79: Line 75:
 
For example, for ''cartridge'' 0b11 and ''stepsPerDot'' of 100, the bytes would be ordered: [ dot0-cartridge1-address1, dot0-cartridge1-address2, ..., dot0-cartridge1-address13, dot0-cartridge2-address0, dot0-cartridge2-address0, ..., dot99-cartridge2-address13 ]
 
For example, for ''cartridge'' 0b11 and ''stepsPerDot'' of 100, the bytes would be ordered: [ dot0-cartridge1-address1, dot0-cartridge1-address2, ..., dot0-cartridge1-address13, dot0-cartridge2-address0, dot0-cartridge2-address0, ..., dot99-cartridge2-address13 ]
  
== Calibration ==
+
== Configuration ==
  
=== getCalibration ===
+
=== getConfig ===
  
<blockquote>Command: 'c', ''field'': uint8
+
<blockquote>Command: 'c', ''field'': uint16
  
Response: ''value'': int16
+
Response: ''value'': uint32
 
</blockquote>
 
</blockquote>
 
Get the calibration ''value'' of ''field''. The field may be:
 
Get the calibration ''value'' of ''field''. The field may be:
  
* 0x01 -
+
* HEAD_SPEED_X (0x01) for the time between X-axis motor steps, in microseconds.
* 0x02 -
+
* HEAD_SPEED_Y (0x02) for the time between Y-axis motor steps, in microseconds.
  
=== setCalibration ===
+
=== setConfig ===
  
<blockquote>Command: 'C', ''field'': uint8, ''value'': int16
+
<blockquote>Command: 'C', ''field'': uint16, ''value'': int32
  
 
Response: none
 
Response: none
Line 146: Line 142:
 
=== wait ===
 
=== wait ===
  
<blockquote>Command: 'W', ''milliseconds'': uint16
+
<blockquote>Command: 'W', ''milliseconds'': uint32
  
 
Response: none
 
Response: none
 
</blockquote>
 
</blockquote>
 
Pause reading commands for ''milliseconds'' number of milliseconds.
 
Pause reading commands for ''milliseconds'' number of milliseconds.
 +
 +
=== fileAction ===
 +
 +
<blockquote>Command: 'B', ''filename'': uint8[], 0x00, ''mode'': uint8, ''dataLength'': uint32, ''data'': uint8[''dataLength'']
 +
 +
Response: ''status'': uint8
 +
</blockquote>
 +
Perform an action on a file named ''filename'', a null-terminated string, on the SD card. This can be used to write commands to the SD card and then execute it.
 +
 +
The parameter ''mode'' must be one of:
 +
 +
* FILE_WRITE (0x01) to write to a file, overwriting any previous data if it exists.
 +
* FILE_APPEND (0x02) to append to a file, requiring that the file already exists.
 +
* FILE_EXECUTE (0x03) to execute the commands contained in a file.
 +
 +
For FILE_WRITE and FILE_APPEND commands, the ''dataLength'' must be the byte length of the ''data'' buffer to be transferred. If ''filename'' is FILE_SERIAL (0xFF), both write and append commands will output to the serial interface.
 +
 +
For FILE_EXECUTE commands, a ''filename'' must be given, and the ''dataLength'' parameter must be 0x00 and no ''data'' be sent.
 +
 +
The response ''status'' is:
 +
 +
* EXECUTE_SUCCESS (0x00) on successful completion.
 +
* NO_SD_CARD (0x01) if there is no SD card present.
 +
* NO_FILE_EXISTS (0x02) if the ''mode'' is set to FILE_EXECUTE or FILE_APPEND and the file corresponding to ''filename'' does not exist.
 +
* UNKNOWN_CMD (0x03) if an unknown command is encountered while executing the file.
 +
* UNKNOWN_PARAM (0x04) if an unknown ''mode'' parameter is given or the ''mode'' is FILE_EXECUTE and the ''dataLength'' parameter is not 0x00.
  
 
=== gCode ===
 
=== gCode ===
  
<blockquote>Command: 'G', ''string'': uint8[], 0x00
+
<blockquote>Command: 'G', ''cmd'': uint8[], 0x00
  
 
Response: none
 
Response: none
 
</blockquote>
 
</blockquote>
Execute a null terminated string of GCODE.
+
Execute a null terminated G-code command.
  
 
=== extendedCommand ===
 
=== extendedCommand ===

Revision as of 00:19, 31 December 2013

Overview

Rapid prototyping hardware such as 3D printers and CNC routers often interpret G-code instructions. G-code is well suited to multi-tool vector based plotting, which printing a circuit is not. A communication protocol has been specifically designed for the Argentum which should be easy for the hobbyist community to experiment with.

Each command has a byte-code identifier and zero or more parameters that include unsigned and signed 8, 16, and 32 byte integers; null terminated arrays; and arrays of a length defined by a preceding integer parameter. The command name, e.g. getPosition, is used in the AgInterface Python controller and the command handler functions in the firmware. When extending the command set or implementing a serial controller or file writer, keep in mind the following:

  • The commands are byte-packed (for computers to read). As in, the numbers are signed or unsigned integers of a particular byte-size. In contrast, G-code uses string representations of numbers (for humans to read). Unfortunately, this means it is not easy to write commands manually.
  • Ideally, commands that "set" information or make the printer perform a function have uppercase ASCII byte-code identifiers, and commands that "get" information have lowercase. This is not a requirement, and eventually the human readable ASCII characters may run out.
  • The AVR microcontroller is little-endian, so be careful if you're using some exotic controller hardware.

The Argentum Printer can read commands from the serial interface or files on an SD card. When reading from a file, the responses are ignored. See Printer Command Set Table for a table of command byte-code mappings.

Command Set Functions

Position and movement

getPosition

Command: 'p'

Response: xpos: int16, ypos: int16

Get the current head position in steps, relative to the zero-point.

setPosition

Command: 'P', xpos: int16, ypos: int16

Response: none

Move the head to step position (xpos, ypos), relative to the zero-point.

zeroPosition

Command: 'Z'

Response: none

Zero the head position Makes the current position be location (0, 0).

incrementPosition

Command: 'M', dx: int16, dy: int16

Response: none

Move the head by dx steps horizontally and dy steps vertically.

Cartridge

testFire

Command: 'T', cartridge: uint8, count: uint8

Response: none

Fire all of cartridge's nozzles by iterating over address signals count times. The cartridge number uses bit places to address multiple cartridges, e.g. a value of 0b01 corresponds to the first cartridge, 0b10 corresponds to the second cartridge, and 0b11 corresponds to both the first and second cartridges.

fire

Command: 'F', cartridge: uint8, nozzle: uint8, count: uint8

Response: none

Fire the nozzle number of cartridge number cartridge a total of count times.

printRow

Command: 'R', cartridge: uint8, stepsPerDot: uint8, numDots: uint16, data: uint8[]

Response: none

Burst mode firing. Print numDots dots with stepsPerDot X-axis steps between them. The total distance travelled will be stepsPerDot × numDots steps. The firing information is in the data array, which is of length num-set-bits(cartridge) × numDots × 13 bytes. Each byte represents primitive signal values. The format is ordered first by dot position, then by cartridge number as it appears from least-significant bit to most significant, and then by address from 1 to 13.

For example, for cartridge 0b11 and stepsPerDot of 100, the bytes would be ordered: [ dot0-cartridge1-address1, dot0-cartridge1-address2, ..., dot0-cartridge1-address13, dot0-cartridge2-address0, dot0-cartridge2-address0, ..., dot99-cartridge2-address13 ]

Configuration

getConfig

Command: 'c', field: uint16

Response: value: uint32

Get the calibration value of field. The field may be:

  • HEAD_SPEED_X (0x01) for the time between X-axis motor steps, in microseconds.
  • HEAD_SPEED_Y (0x02) for the time between Y-axis motor steps, in microseconds.

setConfig

Command: 'C', field: uint16, value: int32

Response: none

Set the calibration of field to value. See getCalibration for the list of valid fields and their corresponding byte codes.

getVersion

Command: 'v'

Response: majorRevision: uint16, minorRevision: uint16

Get the firmware version number.

Peripherals

digitalRead

Command: 'd', pinNumber: uint8

Response: value: uint8

Read the digital value of pinNumber pin (Arduino numbering). Automatically sets required registers to allow input. Response value is 0x00 for false, and 0x01 for true.

digitalWrite

Command: 'D', pinNumber: uint8, value: uint8

Response: none

Write the digital value of pinNumber pin (Arduino numbering). Automatically sets required registers to allow output. The value argument is 0x00 for false, or else true. The firmware will not be responsible for making sure the pin isn't already used for motor or cartridge control.

analogRead

Command: 'a', pinNumber: uint8

Response: value: uint16

Read the analogue (ADC) value of pinNumber pin (Arduino numbering). Automatically sets required registers to allow input. Response value is the ADC reading. The firmware will not be responsible for making sure the pin isn't already used for motor or cartridge control, or for checking that the pin is ADC capabable.

analogWrite

Command: 'A', pinNumber: uint8, dutyCycle: uint8

Response: none

Write the analogue (PWM) value of pinNumber pin (Arduino numbering). Automatically sets required registers to allow output. The dutyCycle argument can be between 0x00 (0% duty cycle) and 0xFF (100% duty cycle). The firmware will not be responsible for making sure the pin isn't already used for motor or cartridge control, or for checking that the pin is PWM capabable.

Other

wait

Command: 'W', milliseconds: uint32

Response: none

Pause reading commands for milliseconds number of milliseconds.

fileAction

Command: 'B', filename: uint8[], 0x00, mode: uint8, dataLength: uint32, data: uint8[dataLength]

Response: status: uint8

Perform an action on a file named filename, a null-terminated string, on the SD card. This can be used to write commands to the SD card and then execute it.

The parameter mode must be one of:

  • FILE_WRITE (0x01) to write to a file, overwriting any previous data if it exists.
  • FILE_APPEND (0x02) to append to a file, requiring that the file already exists.
  • FILE_EXECUTE (0x03) to execute the commands contained in a file.

For FILE_WRITE and FILE_APPEND commands, the dataLength must be the byte length of the data buffer to be transferred. If filename is FILE_SERIAL (0xFF), both write and append commands will output to the serial interface.

For FILE_EXECUTE commands, a filename must be given, and the dataLength parameter must be 0x00 and no data be sent.

The response status is:

  • EXECUTE_SUCCESS (0x00) on successful completion.
  • NO_SD_CARD (0x01) if there is no SD card present.
  • NO_FILE_EXISTS (0x02) if the mode is set to FILE_EXECUTE or FILE_APPEND and the file corresponding to filename does not exist.
  • UNKNOWN_CMD (0x03) if an unknown command is encountered while executing the file.
  • UNKNOWN_PARAM (0x04) if an unknown mode parameter is given or the mode is FILE_EXECUTE and the dataLength parameter is not 0x00.

gCode

Command: 'G', cmd: uint8[], 0x00

Response: none

Execute a null terminated G-code command.

extendedCommand

Command: 0xFF, cmd: uint8[]

Response: varies

Execute a command in the secondary command set.