EBB (EiBotBoard) - Commands

EBB Commands

Introduction

The EBB firmware is based on the UBW firmware. The same basic command processing framework is used, so the same type of commands are used, and the same type of errors are returned. See the UBW command documentation for an introduction to these topics.

This command reference applies to EBF v1.8 and above. (Any differences between firmware versions are noted below.)

General Notes on Default Software Configuration (Applies to EBF v2.1.4)

When the EBB boots up, the output RB1 (called B1 on the board) is used to control the pen up/down servo. The SP and TP commands default to operating on RB1.
When the EBB boots up, the output RB3 (called B3 on the board) is set to be a digital output, set low, to turn the engraver (if used) off at boot. SE command can be used to enable PWM output on this pin.
When the EBB boots up, it sets RB0 (called B0 on the board) as an input and uses this as an alternate pause button (same function as PRG button during normal operation). Use SC,13,0 (see below) to disable this.
When the EBB boots up, it uses RB4 (called B4 on the board) as an alternate pen up/down digital output (1 when down, 0 when up). You can use this to enable a laser for example. Use SC,14,0 (see below) to disable.

EBB Specific Commands

The "QC" Command (Query Current) - Added in v2.0, bug fixed in 2.0.1

Format: "QC<CR>"
Example: "QC"
Returns: "<REF_RA0_VOLTAGE>,<V+_NET_VOLTAGE><CR>"
<REF_RA0_VOLTAGE> is the voltage on the REF_RA0 net, as expressed as a 10 bit number where 0 = 0.0V and 1023 = 3.3V
<V+_NET_VOLTAGE> is the voltage on the V+ net scaled by the resistor divider R13 and R18
This command reads two analog voltages and returns their raw 10 bit values. You can use this to figure out what the user has set the current adjustment pot to, and to read the voltage coming into the board.
Returns: "0421,0021<CR>OK<CR>"

This command only works properly on EBB hardware v1.3 and above. (The white boards from EMSL are v2.0, and all boards from SparkFun are v2.0 and above) The first value returned is the raw 10 bit analog level on the REF_RA0 input to the stepper driver chip. This voltage level sets the max current that the driver chips allow into the motor coils. The second value returned is the raw 10 bit analog level on the V+ input (i.e. the power coming into the board, but after the first diode), and is scaled so that the input voltage doesn't go above the 3.3V max analog input level for the MCU.

For a v1.5 EBB, the following values were measured for the second returned parameter of the QC command:

Input (V+)    QC second parameter
0.0           449
5.0           513
9.0           574
12.0          604
24.0          775

So one can use these two returned values to check for proper stepper motor driver current and proper power supply input voltage. You could also disable the motors, read the power input voltage, then enable the motors and check it again, giving an approxiate reading of the level of voltage droop on the power supply when the motors are loading it down. Note that V+ is not measured directly, but rather after a diode and through a resistor divider. The diode will drop some voltage (dependant upon current) and there will be some tollerance in the voltage divider. Thus you can't rely upon the raw ADC valule alone to give a precice measurement.

Version History: This command was introduced in v2.0.0, but it had a bug where the upper byte of the result was no being displayed. Version 2.0.2 fixed this bug and the command now works properly.

The "SE" Command (Set Engraver) - Added in v2.1.0

Format: "SE,<state>,<power><CR>"
Example: "SE,1,1023"
<state> is 0 for disable, and 1 for enable. You must include this parameter.
<power> is a value from 0 to 1023 and represents the relative power (% duty cycle of the PWM signal), where 0 is off and 1023 is full on. This parameter is optional.
This command is used to enable and disable the engraver PWM output on RB3 (called B3 on the board), and also set its output power. Use SE,0 to disable this feature.
Returns: "OK<CR>"

The "NI" Command (Node count Increment) - Added in v1.9.5

Format: "NI<CR>"
Example: "NI"
This command increments the 32 bit Node Counter by 1.
Returns: "OK<CR>"

The "ND" Command (Node count Decrement) - Added in v1.9.5

Format: "ND<CR>"
Example: "ND"
This command decrements the 32 bit Node Counter by 1.
Returns: "OK<CR>"

The "BL" Command (BootLoad) - Added in v1.9.5

Format: "BL<CR>"
Example: "BL"
This command turns off interrupts and jumps into the bootloader. The EBB will enter bootloader mode without having to push any buttons. Note that this command will ONLY work if you have a EBB bootloader version later than 7/3/2010 (the version released on 7/3/2010 has a distinct LED blink mode - the USB LED stays on 3 times longer than the USR LED). With a previous version of the bootloader code, this command may cause the EBB to be come unresponsive.
Returns: "OK<CR>"

The "SN" Command (Set Node count) - Brought back in v1.9.5

Format: "SN,<value><CR>"
Example: "SN,123456789"
This command sets the Node Counter to <value>. <value> is a 32 bit unsigned int.
Returns: "OK<CR>"

The "CN" Command (Clear Node count) - Added in v1.9.3, removed in 1.9.5 and above

Format: "CN<CR>"
Example: "CN"
This command clears the value of the Node Counter (see QN command).
Returns: "OK<CR>"

The "SL" Command (Set Layer) - Added in v1.9.2

Format: "SL,<NewLayerValue><CR>"
Example: "SL,4"
This command set the value of the Layer variable (see QL command).
Returns:"OK<CR>"

The "QL" Command (Query Layer) - Added in v1.9.2

Format: "QL<CR>"
Example: "QL"
This command asks the EBB to report back the current value of the Layer variable. This variable is set with the SL command, as is a single unsigned byte.
Returns: "<CurrentLayerValue><CR>" then "OK<CR>"
Example: "4" then "OK"

The "QN" Command (Query Node count) - Added in v1.9.2

Format: "QN<CR>"
Example: "QN"
This command asks the EBB what the current value of the Node Counter is. The Node Counter is an unsigned long int (8 bytes) value that gets incremented each time an SM command is finished executing.
Returns: "<NodeCount><CR>OK<CR>"
Example: "1234567890" then "OK"

The "QB" Command (Query Button) - Added in v1.9.2

Format: "QB<CR>"
Example: "QB"
This command simply asks the EBB if the PRG button has been pressed since the last QB command or not.
Returns: "1" if the PRG button has been pressed since the last QB command, "0" if it has not, then "OK"

The "QP" Command (Query Pen) - Added in v1.9

Format: "QP<CR>"
Example: "QP"
This command simply asks the EBB what state the pen is in. It will return 1 if the pen is up and 0 if the pen is down. If a pen up/down command is pending in the FIFO, it will only report the new state of the pen after the pen move has been started.
Return Packet: "1" if the pen is UP, "0" if the pen is DOWN, then "OK"

The "TP" Command (Toggle Pen) - Added in v1.9

Format: "TP,<duration><CR>"

<duration> (optional parameter - if no value then 500 is used internally) is a value from 1 to 65,535 and is in milliseconds. It represents the total length of time between when the pen move is started, and when the next command will be executed. Note that this does not have anything to do with how fast the pen moves (which is set with the SC command). The <duration> parameter is to force the EBB not to execute the next command (normally an SM) for some length of time, which gives the system time to allow the pen move to complete and then some extra time before moving the motors (if you set up the pen speed and this duration parameter properly).

This command toggles the state of the pen (up->down and down->up).
Example: "TP"
Return Packet: "OK"

The "SM" Command (stepper motor move)

Format: "SM,<duration>,<axis1>,<axis2><CR>"

<duration> is a value from 1 to 65,535 and is in milliseconds. It represents the total length of time you want this move to take.
<axis1> and <axis2> are values from -32,767 to +32,767 and represent the number of steps for each motor to take in <duration> milliseconds.
If both <axis1> and <axis2> are zero, then a delay of <duration> ms is executed. <axis2> is an optional value, and if it is not included in the command, zero steps are assumed for axis 2.

Use this command to make the motors draw a straight line at constant velocity. The maximum speed that the EBB can generate is 25,000 steps/s. It is helpful to use this command with zeros for both <axis> parameters after moving the pen up or down to give it time to finish moving before starting the next motor move.
Example: "SM,1000,250,-766"
Return Packet: "OK"

The "SP" Command (set pen state)

Format: "SP,<value>,<duration>,<portBpin><CR>"

<value> is 0 (for up) or 1 (for down)
<duration> (optional parameter - if no value then 500 is used internally) is a value from 1 to 65,535 and is in milliseconds. It represents the total length of time between when the pen move is started, and when the next command will be executed. Note that this does not have anything to do with how fast the pen moves (which is set with the SC command). The <duration> parameter is to force the EBB not to execute the next command (normally an SM) for some length of time, which gives the system time to allow the pen move to complete and then some extra time before moving the motors (if you set up the pen speed and this duration parameter properly).
<portBpin> (optional - if not present, then 1 is used) Which port B pin you want this output to come out of (values from 0 through 7 are valid) (Note: this parameter is new for EBF 2.1.1 and above)

This command will make the pen go up or down. On EBB versions 1.1, 1.2 and 1.3 this will make the solenoid output turn on and off. On all EBB versions it will also make the RC servo output on RB1 move to the up or down position. Also, by default, it will turn on RB4 or turn off RB4 as a simple digital output, so that you could use this to trigger a laser for example.
Example: "SP,1"
Return Packet: "OK"

The "EM" Command (enable motors) for EBB v1.1

Format: "EM,<EnableAxis1>,<EnableAxis2><CR>"

Everything after <EnableAxis1> is optional
For each axis:

0 will disable that axis (the driver will stop sending current to the motor, so the motor will freewheel)
1 will enable that axis in 1/8th step mode (default)
2 will enable that axis in 1/4 step mode
3 will enable that axis in 1/2 step mode
4 will enable that axis in full step mode

Example: "EM,1,0"
Return Packet: "OK"

The "EM" Command (enable motors) for EBB v1.2 and above

Format: "EM,<Enable1>,<Enable2><CR>"

To enable a motor driver, set its <Enable> parameter to 1.
To disable a motor driver, set its <Enable> parameter to 0.
For example, "EM,1,0" will enable motor 1 and disable motor 2.
To set the microstep mode of BOTH motor drivers (the same signals go to both drivers, so you can't set them separately) use a value of 1,2,3,4 or 5 for <Enable1>. When you use a value of 1,2,3,4 or 5 for <Enable1>, the <Enable2> parameter is not needed.
When setting microstep values with <Enable1>:

1 will enable both axis in 1/16th step mode (default on boot)
2 will enable both axis in 1/8th step mode
3 will enable both axis in 1/4 step mode
4 will enable both axis in 1/2 step mode
5 will enable both axis in full step mode

Note that any time an SM command is executed, both motors become 'enabled' before the move starts. Thus it is almost never necessary to issue a "EM,1,1" command to enable both motors.

Example: "EM,2" - this command will set both motors in 1/8th step mode
Example: "EM,0,0" - this command will disable both motors (they will then freewheel)
Example: "EM,1,1" - this command will enable both motors and set them to 1/16th microstep mode.
Return Packet: "OK"

The "SC" Command (stepper mode configure)

Format: "SC,<value1>,<value2><CR>"

<value1> is a number from 0 to 255 - it's meaning is defined below
<value2> is a number from 0 to 65535 - it's meaning depends upon <value1>

This command allows you to set different parameters that effect the operation of the EBB.

SC,1,0 - uses just the solenoid output for pen up/down (no RC servo outputs)
SC,1,2 - uses solenoid and RB1 RC servo output for pen up/down, hardware RC output (default)
SC,2,0 - use built in driver chips for motor control (default)
SC,2,1 - use the following pins for stepper motor control - EBB v1.1 only:

ENABLE1 = RA5
ENABLE2 = RB5
STEP1 = RD1
DIR1 = RD0
STEP2 = RC2
DIR2 = RC0

SC,4,<servo_min> - sets the minimum value for the servo (1 to 65535)
SC,5,<servo_max> - sets the maximum value for the servo (1 to 65535)
SC,8,<maximum_S2_channels> - sets the number of channels, each of duration <S2_channel_duration_ms> before cycling back to channel 1 for S2 command. Values from 1 to 24 are valid. Defaults to 8 on bootup. (new for EBB 2.1.1)
SC,9,<S2_channel_duration_ms> - sets the number of milliseconds before firing the next enabled channel for the S2 command. Defaults to 3ms. (new for EBB 2.1.1)
SC,10,<servo_rate> - sets the rate of change of the servo (when going up/down)
SC,11,<servo_rate_up> - sets the rate of change of the servo when going up (new in v1.9.2)
SC,12,<servo_rate_down> - sets the rate of change of the servo when going down (new in v1.9.2)
SC,13,<use_alt_pause> - turns on (1) or off (0) alternate pause button function on RB0. On by default. For v1.1 boards, it uses RB2 instead. (new in v2.0)
SC,14,<alt_solenoid_output_enable> - enables (1) or disables (0) the alternate pen up/down output on RB4. When enabled, it will follow pen up (0) and pen down (1). Use to enable a laser.

Example: "SC,4,8000"
Return Packet: "OK"

The "S2" Command (general RC servo output)

Format: "S2,<channel>,<duration>,<output_pin>,<rate><CR>"

<channel> is a number from 0 to 8 (with 0 as a special value which shuts off all S2 outputs)
<duration> is a number from 0 to 32,000, and represents the 'on' time in 1/12,000ths of a second (0 = channel off, 1=83us, 32,000 = 3ms)
<output_pin> is a number from 0 to 24, and is the RPx pin number you want this channel to come out on- see schematic for RPx numbers
<rate> is the rate at which to change from the current value to the new value. Use 0 to have changes instant. See below for what this value. Values from 0 to 65535 are valid. Optional parameter.

This command is a generic RC servo output command. It allows you to control the RC servo output system on the EBB. Many I/O pins have RPx numbers (see the schematic) - and you can output RC servo pulses on up to 8 of these RPx pins. Any of them that you want - it doesn't matter to the software. There are seven RC servo 'channels', which have no physical meaning other than we can (by default) only output up to 8 separate signals at once. But you can assign any RPx pin to any channel - that's up to you to manage. The RC servo system will cycle through each of the 8 channels. Each gets 3m of 'time'. (Thus giving a 24ms repeat rate for the whole RC system.) If the current channel is enabled, then at the beginning of its 3ms time slot, it's RPx pin is set high. Then, <duration> time later, the RPx pin is set low. This time is controlled purely by hardware (the ECCP2 in the CPU) so there is no jitter for the pulse durations. <duration> is in units of 1/12,000 of a second, so 32,000 for <duration> would be exactly 3ms.
The number of available channels is normally (by default) 8. This can be changed with the SC,8 command (see above). The S2 RC servo output command cycles from channel 1 through channel <maximum_S2_channels> (normally 8), outputting any enabled channel's pulse from 0ms to 3ms. For a given channel, the repetition rate is determined by <maximum_S2_channels> * <S2_channel_duration_ms> which is normally 8 * 3 or 24ms. Thus, each channel's output pulse will be repeated every 24ms. Note that channel 0 is not a real channel - the <channel> = 0 value is used to disable all S2 functionality. If you change the <maximum_S2_channels> you will change the repetition rate of the pulses.
The <rate> parameter is used to indicate how quickly to move from the current pulse width (servo position) to the new pulse width. If <rate> is zero, then the move is made on the next PWM cycle (i.e. the next time the pin is pulsed). If <rate> is not zero, then <rate> is added to (or subtracted from) the current pulse width each time the pulse is generated until the new target is reached. This means that the units of <rate> are 1/12,000ths of a second per <maximum_S2_channels> * <S2_channel_duration_ms> or 1/12,000ths of a second per 24ms.
The normal pen up/down servo control (SP and TP commands) use S2 channel 1. So if you want to use SP and TP, then leave channel 1 alone and start with channel 2. If you don't care to use SP and TP anymore, then you can use channels 1 through <maximum_S2_channels>.
The S2 command will always make <output_pin> an output before it starts outputting pulses to that pin.
For example, to use RP6 as a RC servo output, and to set it's on-time to 2ms, and using channel 3 of the RC system, you would send the command (note <rate> is optional)

S2,3,24000,6<CR>

S2,0 - will turn off all RC servo support (freeing up CPU time, if that's important to you)
S2,3,0 - will turn off the output on whatever pin channel 3 was assigned to.
Return Packet: "OK"

Questions? E-mail me at my e-mail address

EggBotBoard by Brian Schmalz is licensed under a Creative Commons Attribution 3.0 United States License.
Based on a work at www.schmalzhaus.com/EBB.
Permissions beyond the scope of this license may be available at www.schmalzhaus.com/EBB.