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
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
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
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)
EBB Command FAQ
Q1) How can I calculate how
long it will take to move from one RC servo position to another?
Specifically in relation to the standard pen-arm servo that is
activated with the SP,1 and SP,0 commands.
A1) By default, with
the latest version of EBB firmware (v2.1.5), we add (or subtract)
the rate value from the current pulse duration every time the
pulse fires until the current pulse duration equals the target
duration. Normally we have 8 servo channels available, and each
gets 3 ms, so that means that each channel can fire once every
24ms. So the rate value gets added or subtracted from the current
pulse duration every 24ms.
For example, if you're currently at a position
(pulse duration) of 10000 and you send a new command to move to
position 15000, then you have a 'distance' of 5000 to go. So
when we start out, our current duration is 10000 and our target
is 15000. If our rate value is 100, then it will take 50 of
these 24ms periods to get from 10000 to 15000, or 1.2seconds
Now, when you're using the SP,0 and SP,1 commands,
the servo_min (defaults to 16000, or 1.3ms) and servo_max
(defaults to 20000, or 1.6ms) get used as the positions. And the
servo_rate_up and servo_rate_down get used as the rates.
So the formula is as follows:
((<servo_max> - <servo_min>) *
.024)/<servo_rate> = total time to move
For the example above
((15000 - 10000) * .024)/100 = 1.2 seconds
EBB Command Reference
The "QC" Command (Query
Current) - Added in v2.0, bug fixed in 2.0.1
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
- Format: "QC<CR>"
- Example: "QC"
- <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.
For a v1.5 EBB, the following values were
measured for the second returned parameter of the QC command:
Input (V+) QC second parameter
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
The "SE" Command (Set Engraver)
- Added in v2.1.0
- 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.
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.
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.
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.
The "SN" Command (Set Node
count) - Brought back in v1.9.5
- This command sets the Node Counter to <value>.
<value> is a 32 bit unsigned int.
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
The "SL" Command (Set Layer) -
Added in v1.9.2
- Example: "SL,4"
- This command set the value of the Layer variable (see QL
The "QL" Command (Query Layer)
- Added in v1.9.2
The "QN" Command (Query Node count) - 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.
"<CurrentLayerValue><CR>" then "OK<CR>"
- Example: "4" then "OK"
- 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
- Returns: "<NodeCount><CR>OK<CR>"
- Example: "1234567890"
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
The "SM" Command (stepper motor
- <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.
- Return Packet: "OK"
The "SP" Command (set pen
- <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
- Example: "SP,1"
- Return Packet: "OK"
The "EM" Command (enable
motors) for EBB v1.1
- 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
- To enable a motor driver, set its <Enable> parameter
- To disable a motor driver, set its <Enable> parameter
- For example, "EM,1,0" will enable motor 1 and disable motor
- 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
- 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
- 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
- Return Packet: "OK"
The "SC" Command (stepper mode
The "S2" Command (general RC
- <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,000,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.
- 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
- 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,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