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. Addressing issues
  5. Additional resources
  6. Command reference
    1. Syntax and conventions
    2. List of commands
  7. FAQ
  8. 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 their 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 EggBot, WaterColorBot and (more recently,) the AxiDraw. 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 (which may be a low as v2.0.1) 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.

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


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 (for EBB hardware v1.1)


"EM" — Enable Motors (for EBB hardware v1.2 and newer)


"ES" — E Stop


"I" — Input (digital)


"LM" — Low-level Move


"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


"QL" — Query Layer


"QM" — Query Motor

"QM" — Query Motor


"QP" — Query Pen


"QS" — Query Step position


"R" — Reset


"SC" — Stepper and Servo Mode Configure


"SE" — Set Engraver


"SL" — Set Layer


"SM" — Stepper Move


"SN" — Set node count


"SP" — Set Pen State


"T" — Timed Analog/Digital Read


"S2" — General RC Servo Output (versions prior to v2.2.0)


"S2" — General RC Servo Output (v2.2.0 and newer)


"TP" — Toggle Pen


"QN" — Query node count


"V" — Version query


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




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


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