Eggbot

Software for the Original EggBot Kit

View the Project on GitHub evil-mad/EggBot

EBB (EiBotBoard) Command Set

This document details the serial command protocol used by the EBB (EiBotBoard). The EBB is an open source USB-based motor control board, designed to drive two stepper motors. The EBB may be used on its own, or found as the control board of such machines as The Original Egg-Bot, The WaterColorBot, or AxiDraw.


Contents

  1. Serial communication and APIs
  2. Introduction to the EBB firmware
  3. Differences between versions
  4. Updating firmware
  5. Addressing issues
  6. Additional resources
  7. Command reference
    1. Syntax and conventions
    2. List of commands
  8. Initial I/O pin configuration
  9. Performance
  10. FAQ
  11. License


Serial communication: High-level interfaces and APIs

The serial protocol described in this document can be used directly, for example from a serial terminal, in order to carry out simple tasks. It can also be accessed from within any program or programming environment that is capable of communicating with a USB serial device. Using this protocol from within high-level computer languages allows one to construct and execute complex motion. All EBB applications and interfaces use this serial protocol, at their lowest levels, in order to manage the motion control.

The serial protocol specifies the fundamental primitives of how the machine operates— for example moving from position (a1,b1) to position (a2,b2) in duration Δt, with the pen-lift servo motor at position z. By contrast, higher level programs may perform tasks such as opening up SVG files and converting them into a set of robotic movements that can be carried out through the serial protocol.

Here are some possible starting points for building higher level applications:


Introduction to the EBB firmware

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 EiBotBoard Firmware v1.8.0 and above. (Any differences between firmware versions are noted below and in release notes.)


Differences between firmware versions

Although the EBB firmware is a continuously evolving code base, we have, since version 2.0.1, taken care to avoid compatibility changes that would affect the most common machines using the EBB: The AxiDraw, EggBot, and WaterColorBot. If you are using one of these machines, there is generally no particular benefit or compelling reason for you to update your firmware to a newer version. (Older machines with older firmware will continue to work just fine with that older firmware.)

That said, there have been many smaller changes in the code between the versions that ship preloaded on the EBB and the latest versions. Most of the changes have been minor bug fixes and new, minor functions that are helpful for less common applications. If you are developing new applications with the EBB, we do encourage you to update to the newest version. If, on the other hand, you are writing new software that targets machines of various ages (for example, new EggBot software), please be aware that many of the machines out there are still using older firmware revisions.

That this documentation refers not only to different versions of the EBB firmware, but also in some cases to legacy versions of the EBB hardware. For example, the "EM" command has different behaviors on different versions of the EBB hardware.


Updating your firmware

Instructions for updating firmware, including easy installers for Mac and Windows, can be found on the Evil Mad Scientist Wiki.


Addressing Issues

If you discover something that does not work as expected in the EBB firmware, please contact us by e-mail, in our forum, or (preferably) file an issue on GitHub : https://github.com/evil-mad/EggBot/issues.

Please include a clear method to reproduce the issue, the expected behavior as well as the observed behavior, and the version number of the EBB firmware version that you are using.


Additional Resources


EBB Command Reference

Syntax and conventions

The following syntax conventions are established to assist with clarity of communication as we describe the EBB commands.

EBB Syntax Conventions:

Additionally, please note that:

The EBB Command Set


"A" — Analog value get


"AC" — Analog Configure


"BL" — Enter Bootloader


"C" — Configure (pin directions)


"CN" — Clear node count [obsolete]


"CS" — Clear Step position


"CK" — Check Input


"CU" — Configure User Options


"EM" — Enable Motors


"ES" — E Stop


"HM" — Home or Absolute Move


"I" — Input (digital)


"LM" — Low-level Move, Step-limited


"LT" — Low-level Move, Time-limited


"MR" — Memory Read


"MW" — Memory Write


"ND" — Node Count Decrement


"NI" — Node Count Increment


"O" — Output (digital)


"PC" — Pulse Configure


"PD" — Pin Direction


"PG" — Pulse Go


"PI" — Pin Input


"PO" — Pin Output


"QB" — Query Button


"QC" — Query Current


"QE" — Query motor Enables and microstep resolutions


"QG" — Query General


"QL" — Query Layer


"QM" — Query Motors

"QM" — Query Motors (Legacy version)


"QP" — Query Pen


"QR" — Query RC Servo power state


"QS" — Query Step position


"QT" — Query EBB nickname Tag


"RB" — ReBoot


"R" — Reset


"S2" — General RC Servo Output


"S2" — General RC Servo Output (Legacy version)


"SC" — Stepper and Servo Mode Configure


"SE" — Set Engraver


"SL" — Set Layer


"SM" — Stepper Move


"SN" — Set node count


"SP" — Set Pen State


"SR" — Set RC Servo power timeout value


"ST" — Set EBB nickname Tag


"T" — Timed Analog/Digital Query


"TP" — Toggle Pen


"QN" — Query node count


"V" — Version query


"XM" — Stepper Move, for Mixed-axis Geometries



Initial I/O pin configuration

In addition to the stepper motor outputs, many applications make use of one or more digital I/O pins.

The most accessible and commonly used of the I/O pins are those in PortB. The eight pins in PortB are physically arranged into 3-pin "header connections", with ground, +5V power, and the "signal" I/O pin itself, from the edge of the board towards the center. Four of these connectors are located "below" the stepper motor terminals, and are labeled as B1, B0, B2, and B3, in order from the "bottom" edge of the board towards the stepper terminals. These four connections are pre-populated with header pins. Four additional connections, B4, B5, B6, and B7 are located on the "bottom" edge of the board, and are not pre-populated with header pins.

On EBB boards v2.5 and above, the 5V power to the pen servo (RB1) is controlled by software, and defaults to an off state at reset; see the SR command.

Pins B1, B0, B2 and B3 are not 5-volt tolerant and any voltage above about 3.6V will damage them. Pins B4, B5, B6 and B7 are 5-volt tolerant and will not be damaged by voltages up to 5.5V.

Because all Port B pins (B0 through B7) have weak pull up resistors, any of these pins can be used to read a switch by connecting a switch between the Port B pin and GND. Use the PI command to read the state of the switch. If that pin is not already an input at boot (see table below) you can make it an input using the PD command.

In addition to the pins of PortB, additional broken-out I/O pins accessible on the EBB include: PortA: RA0,1,2,3,5, PortC: RC0,1,2,6,7, PortD: RD: 0,1,4,5,6,7, and PortE: RE0. Every pin on PortB, PortC and RA6 can source or sink up to 25mA each. All other pins can source or sink up to 4mA each. Note that pins RA0, RC1, RD4, RD5, RD6, RD7 and RE0 are brought out to the I/O header but already have existing analog or digital functions mapped to them and so should only be used for monitoring these signals rather than as GPIO.

All pins of PortB have weak pull ups to 3.3V, which can source between 80 and 400 μA, and are enabled any time the pin is an input. Pull ups are not available on the other (Port A, C, D, E) GPIO pins. Many of the I/O pins can be used for general purpose digital I/O (GPIO), and some can also be used as RC servo outputs, within the limits of S2. With the exceptions listed in the table below and RA0, RC1, RD4, RD5, RD6, RD7 and RE0, all of the broken-out I/O pins are initially configured at boot as digital inputs.

Certain PortB signal pins are specially configured at boot time for typical applications, as summarized in the table below.

Pin Default Direction Default State 5V Tolerant Typical application
RB0 Input Weak pull up No Alternate PRG/Pause button input; see QB
RB1 Output RC Servo Pulses No Pen lift servo output; see SC, SP
RB2 Input Weak pull up No General
RB3 Output Low No Engraver or laser PWM output control
RB4 Output Low Yes Alternate Pen Up/Down I/O (solenoid/laser)
RB5 Input Weak pull up Yes General
RB6 Input Weak pull up Yes General
RB7 Input Weak pull up Yes General


Performance

The EBB has some basic performance limits, which do vary with new firmware releases.

One performance aspect is the duration of the step pulses sent to the stepper driver chips. While the pulses produced by the EBB firmware will always be long enough to guarantee proper operation with the built-in drivers, it is possible to use some of the GPIO pins on the EBB to connect external step/dir driver electronics to drive much larger systems. In this case, the external drivers may have a minimum step pulse length, and so it can be important to know this timing information in that case.

Output step pulse duration for external stepper drivers:

Another important performance measure is the maximum rate at which sequential movement commands can be streamed to the EBB. This rate is expressed as the shortest move duration that can be sent to the EBB as a continuous stream of identical motion commands, such that there are no gaps between the last step of one move and the first step of the next move. For a high enough sustained rate of sufficiently short movement commands, the EBB will not be able to parse and queue each command prior to starting the subsequent move. The available CPU time available for parsing and queueing commands does depend on the active step rate, as the EBB shares CPU time between command parsing and step generation.

The following table shows the minimum move duration, in milliseconds, which the EBB can sustain indefinitely without gaps, under different move commands. The worst case values (highest sustained minimum move duration) were measured with step rates of approximately 25 kHz on both motors — a condition rarely achieved in typical applications. The best case values (lowest sustained minimum move duration) are for low step rates, and was measured at 2.5 kHz. You may be able to sustain movement at these rates with higher motion frequencies.

Command Firmware >= 2.7.0 Firmware < 2.7.0
SM 3-4 ms 4-7 ms
XM 3-4 ms 4-6 ms
LM, LT 3-5 ms 4-6 ms

The times in the table above are measured under conditions where the PC sending the commands is able to sustain the same data rate. In practice, PCs — especially Windows PCs — can have occasional brief gaps when sending long strings of USB commands. The incidence of these gaps depend upon the system configuration, CPU speed, load, other USB communication, and additional factors. Best practice is to try and use fewer, longer-duration movement commands (rather than more, shorter-duration commands) whenever possible, to minimize the effects of both EBB CPU time constraints and any USB performance issues on the PC.


Frequently Asked Questions

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, 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 24 ms. So the rate value gets added or subtracted from the current pulse duration every 24 ms.

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 24 ms periods to get from 10000 to 15000, or 1.2 seconds total.

Now, when you're using the SP,0 and SP,1 commands, the servo_min (defaults to 16000, or 1.33 ms) and servo_max (defaults to 20000, or 1.6 ms) 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.

Q2) What do the LED patterns mean?

A2) There are two applications that live on the EBB: The bootloader and the main EBB firmware. They each have different LED blink patterns. There is a green power LED labeled 3.3V which is always lit as long as either the USB or barrel jack connector is receiving power. It is located next to the large electrolytic capacitor.

The LED timing mechanism used by both bootloader and main EBB applications is sensitive to the commands currently being executed. For example, the timing of the alternating LED pattern when the bootloader is running will change as a new EBB firmware application is being actively programmed.

Bootloader When the bootloader is running (only used to update main EBB firmware), the two LEDs between the USB and barrel jack connectors can take on two different states:

Pattern Description USR/Red USB/Green
Idle Waiting for USB connection with host Off On
Alternating USB connection established to host 200 ms on, 200 ms off, alternating with Green 200 ms on, 200 ms off, alternating with Red

Main EBB Firmware When the main EBB firmware is running (normal operating mode) the two LEDs between the USB and barrel jack connectors can take on three different states:

Pattern Description USR/Red USB/Green
Fast Blink No connection to USB host Off 60 ms on, 60 ms off
Slow Blink Connected to USB host but not enumerated Off 750 ms on, 750 ms off
Short Long Blink Fully enumerated and communicating with USB host Off 365 ms on, 365 ms off, 1.25s on, 365 ms off

The Fast Blink pattern is almost never seen in practice, since the USB host normally enumerates the EBB immediately upon connection with a USB cable. However, if proper drivers are not installed on the host or if there is some other problem with the USB enumeration process the Fast Blink pattern can be observed and used as a debugging aid.


Creative Commons License

EiBotBoard 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.


Extended EggBot documentation available at: http://wiki.evilmadscientist.com/eggbot