kopia lustrzana https://github.com/evil-mad/EggBot
3277 wiersze
236 KiB
HTML
3277 wiersze
236 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1">
|
|
<title>EBB Command Set Documentation</title>
|
|
|
|
<link rel="stylesheet" href="stylesheets/styles.css">
|
|
<link rel="stylesheet" href="stylesheets/github-light.css">
|
|
<script src="javascripts/scale.fix.js"></script>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
|
|
|
|
<!--[if lt IE 9]>
|
|
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
|
|
<style>
|
|
td {text-align: center}
|
|
ul.no_bullets {
|
|
list-style-type: none; /* Remove bullets */
|
|
padding-left: 50px;
|
|
padding-bottom: 15px;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="wrapper">
|
|
<header>
|
|
<h1>Eggbot</h1>
|
|
<p>Software for the Original EggBot Kit</p>
|
|
<p class="view"><a href="https://github.com/evil-mad/EggBot">View the Project on GitHub <small>evil-mad/EggBot</small></a></p>
|
|
<ul>
|
|
<li><a href="https://github.com/evil-mad/EggBot">View On <strong>GitHub</strong></a></li>
|
|
</ul>
|
|
</header>
|
|
<section>
|
|
<h1>
|
|
<a id="eggbot" class="anchor" href="#eggbot" aria-hidden="true">
|
|
<span aria-hidden="true" class="octicon octicon-link"></span></a>EBB (EiBotBoard) Command Set, Firmware v3.0+
|
|
</h1>
|
|
|
|
<p>
|
|
This document details the serial command protocol used by the <a href="http://www.schmalzhaus.com/EBB/">EBB</a> (EiBotBoard) with firmware v3.0 and higher. Legacy documentation for prior versions is <a href="ebb2.html">available here</a>.
|
|
</p>
|
|
<p>
|
|
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 <a href="http://egg-bot.com">The Original Egg-Bot</a>, <a href="http://watercolorbot.com">The WaterColorBot</a>, or <a href="http://axidraw.com">AxiDraw</a>.
|
|
</p>
|
|
|
|
<hr>
|
|
|
|
<h2>Contents</h2>
|
|
|
|
<ol>
|
|
<li><a href="#apis">Serial communication and APIs</a></li>
|
|
<li><a href="#introduction">Introduction to the EBB firmware</a></li>
|
|
<li><a href="#version_differences">Major Changes in Firmware v3.0</a></li>
|
|
<li><a href="#updating">Updating firmware</a></li>
|
|
<li><a href="#issues">Addressing issues</a></li>
|
|
<li><a href="#additional_resources">Additional resources</a></li>
|
|
<li><a href="#EBB_Command_Reference">Command reference</a></li>
|
|
<ol>
|
|
<li><a href="#syntax">Syntax and conventions</a></li>
|
|
<li><a href="#commands">List of commands</a></li>
|
|
</ol>
|
|
<li><a href="#states">Initial I/O pin configuration</a></li>
|
|
<li><a href="#performance">Performance</a></li>
|
|
<li><a href="#faq">FAQ</a></li>
|
|
<li><a href="#license">License</a></li>
|
|
</ol>
|
|
|
|
<p />
|
|
<hr />
|
|
<p />
|
|
|
|
<h2><a name="apis"></a>Serial communication: High-level interfaces and APIs</h2>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
The serial protocol specifies the fundamental primitives of how the machine operates— for example moving from position (<i>a1</i>,<i>b1</i>) to position (<i>a2</i>,<i>b2</i>) in duration Δ<i>t</i>, with the pen-lift servo motor at position <i>z</i>. 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.
|
|
</p>
|
|
<p>
|
|
Here are some possible starting points for building higher level applications:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
The Inkscape-based drivers <a href="https://github.com/evil-mad/EggBot">for the EggBot</a>, <a href="https://github.com/evil-mad/wcb-ink">for the WaterColorBot</a>, and <a href="https://github.com/evil-mad/axidraw">for AxiDraw</a> are written in python, and use this serial protocol. The codebases from those projects are excellent resources for getting started.
|
|
</li>
|
|
<li>
|
|
The <a href="http://processing.org">Processing</a>-based program <a href="https://github.com/evil-mad/robopaint-rt">RoboPaint RT</a> is designed to control the WaterColorBot through a real-time interface. This program is written in Processing (Java), and serves as a good example of how to manage the EBB through Processing.
|
|
</li>
|
|
<li>
|
|
<a href="https://github.com/evil-mad/robopaint">RoboPaint</a> is a stand-alone cross-platform program to drive the WaterColorBot (as well as EggBot and AxiDraw). RoboPaint is written in javascript and (while running) provides several APIs that can be used to control machines based on the EBB:
|
|
<ul>
|
|
<li>
|
|
RoboPaint, under the hood, uses the <a href="https://github.com/techninja/cncserver/">cncserver</a> and its RESTful API to operate. It is a relatively low level interface, with similar functionality to the serial protocol, plus a few helpful utilities.
|
|
</li>
|
|
<li>
|
|
The higher-level <a href="https://github.com/evil-mad/robopaint-mode-remote/blob/master/API.md">RoboPaint remote print API</a> allows local or remote "printing" of SVG files to EBB based machines, when attached to a computer running RoboPaint.
|
|
</li>
|
|
<li>
|
|
The simplified ("GET only") <a href="https://github.com/techninja/cncserver/blob/master/scratch/SCRATCH.API.md">Scratch API</a> provides a method of controlling EBB based machines from the address bar of a web browser, or from simple programming languages that can retrieve data from an URL.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a href="https://github.com/techninja/cncserver/">cncserver</a> can be run on its own, from the command line, as a javascript-based RESTful API server to control EBB-based machines. (You can also run it by simply launching RoboPaint.)
|
|
</li>
|
|
</ul>
|
|
|
|
<p />
|
|
<hr />
|
|
<p />
|
|
|
|
<h2><a name="introduction"></a>Introduction to the EBB firmware</h2>
|
|
|
|
<p>
|
|
The documentation on this page is for the to EiBotBoard Firmware v3.0 and above. If you are using an older version of the firmware (most likely in the 2.0 series), please refer to the <a href="ebb2.html">EBB 2.8.1 documentation</a> which documents prior syntax and prior changes to the syntax between versions (for versions prior to EBB 3.0). Individual command descriptions in this document may note changes between EBB 2.8.1 and 3.0, but generally do not describe version history prior to 2.8.1.
|
|
</p>
|
|
<p>
|
|
The EBB firmware was originally based on the UBW firmware. Its <a href="http://www.schmalzhaus.com/UBW/Doc/FirmwareDDocumentation_v145.html">command documentation</a> has an introduction to the UBW command processing framework, but this stand-alone document does not refer to it further.
|
|
</p>
|
|
<p>
|
|
Although the EBB firmware is a continuously evolving code base, we have, since version 2.0.1, taken care to minimize 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 and it is working well for you, there is generally no requirement to <a href="https://wiki.evilmadscientist.com/Updating_EBB_firmware">update your firmware</a> to a newer version.
|
|
</p>
|
|
<p>
|
|
There are, of course, many <a href="EBBReleaseNotes.html">smaller changes</a> in the code between the versions on older EBB firmware and the latest versions. If you are developing new applications with the EBB, we encourage you to update to the newest version. On the other hand, if 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.
|
|
</p>
|
|
<p>
|
|
As we will note in the next section, EBB firmware v3.x labels a <i>transitional</i> version between the v2.x syntax and planned future version syntax. While it maintains compatibility for existing applications that use the EBB (with firmware 2.x), it also introduces changes for compatibility with the future version syntax. These include deprecations of some commands and queries. There is also a new "unified" syntax -- disabled by default -- for responses to commands and queries. Enabling this syntax allows one to develop or adapt programs that use the EBB for future compatibility with a future firmware version.
|
|
</p>
|
|
|
|
<p />
|
|
<hr />
|
|
<p />
|
|
|
|
<h2><a name="version_differences"></a>Major Changes in Firmware v3.0</h2>
|
|
|
|
<p>
|
|
EBB firmware v3.x is a transitional series introducing new features, optional in v3.x, which will become standard in a future firmware version, and deprecating some commands and queries. If you are updating a custom application that uses the EBB firmware and are migrating it from a pre-3.0 version, please read this section carefully as it does describe potentially breaking changes.
|
|
</p>
|
|
<p>
|
|
The most important change is the introduction of a <b>future syntax mode</b>, which is off by default, and which can be enabled by the command <a href="#CU"><code>CU,10,1</code></a>. Future syntax mode does not change the syntax that is used to send commands or queries to the EBB; it changes the format of <i>responses</i> to commands and queries. With future syntax mode enabled, these responses will use the format that is planned for a future firmware version, rather than the default "legacy" response format. The legacy response format will be removed in that future firmware version and should be considered to be deprecated. (See notes on the <code><a href="#CU">CU</a></code> command.)
|
|
</p>
|
|
|
|
<p>
|
|
The following are potentially breaking changes in the command and structure, and commands:
|
|
<ul>
|
|
<li><code><a href="#QG">QG</a></code> — Query General. The meanings of bits 6 and 7 has changed.</li>
|
|
<li><code><a href="#S2">S2</a></code> — General RC Servo Output.</li> Maximum number of simultaneous RC servo outputs reduced from 24 to 8.
|
|
<li>
|
|
<code><a href="#PC">PC</a></code>,
|
|
<code><a href="#PG">PG</a></code>,
|
|
<code><a href="#T">T</a></code>, and commands removed as per <a href="https://github.com/evil-mad/EggBot/issues/216">issue #216</a></li>
|
|
</ul>
|
|
</p>
|
|
|
|
<p>
|
|
The following commands and queries have been deprecated as of EBB firmware v3.0, and will be removed in a future firmware version. They are functional,
|
|
but should be migrated to use suggested alternatives instead.
|
|
<ul>
|
|
<li><code><a href="#QB">QB</a></code> — Query Button. <i>Migrate to:</i> <code><a href="#QG">QG</a></code>. </li>
|
|
<li><code><a href="#QM">QM</a></code> — Query Motors. <i>Migrate to:</i> <code><a href="#QG">QG</a></code>.</li>
|
|
<li><code><a href="#QP">QP</a></code> — Query Pen. <i>Migrate to:</i> <code><a href="#QG">QG</a></code>.</li>
|
|
<li><code><a href="#ND">ND</a></code> — Node count Decrement. <i>Migrate to:</i> <code><a href="#SL">SL</a></code></li>
|
|
<li><code><a href="#NI">NI</a></code> — Node count Increment. <i>Migrate to:</i> <code><a href="#SL">SL</a></code></li>
|
|
<li><code><a href="#QN">QN</a></code> — Query Node count. <i>Migrate to:</i> <code><a href="#QL">QL</a></code></li>
|
|
<li><code><a href="#I">I</a></code> — Input (digital). <i>Migrate to:</i> <code><a href="#PI">PI</a></code></li>
|
|
<li><code><a href="#O">O</a></code> — Output (digital). <i>Migrate to:</i> <code><a href="#PO">PO</a></code></li>
|
|
</ul>
|
|
</p>
|
|
|
|
<p>
|
|
Additional deprecated commands that will be removed in a future firmware version:
|
|
<ul>
|
|
<li><code><a href="#A">A</a></code> — Analog value get</li>
|
|
<li><code><a href="#AC">AC</a></code> — Analog configure</li>
|
|
<li><code><a href="#CU">CU,1</a></code> — Legacy syntax</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<p>
|
|
Please see the <a href="EBBReleaseNotes.html">release notes</a> for additional information about differences between versions.
|
|
</p>
|
|
|
|
<p />
|
|
<hr />
|
|
<p />
|
|
|
|
<h2><a name="updating"></a>Updating your firmware</h2>
|
|
|
|
<p>
|
|
Instructions for updating firmware, including easy installers for Mac and Windows, can be found on the <a href="https://wiki.evilmadscientist.com/Updating_EBB_firmware">Evil Mad Scientist Wiki</a>.
|
|
</p>
|
|
|
|
<p />
|
|
<hr />
|
|
<p />
|
|
|
|
<h2><a name="issues"></a>Addressing Issues</h2>
|
|
|
|
<p>
|
|
If you discover something that does not work as expected in the EBB firmware, please contact us by <a href="http://shop.evilmadscientist.com/contact">e-mail</a>, in our forum, or (preferably) file an issue on GitHub : <a href="https://github.com/evil-mad/EggBot/issues">https://github.com/evil-mad/EggBot/issues</a>.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p />
|
|
<hr />
|
|
<p />
|
|
|
|
<h2><a name="additional_resources"></a>Additional Resources</h2>
|
|
<ul>
|
|
<li><a href="http://www.schmalzhaus.com/EBB/EBBConfig.html">Boot up configuration information</a></li>
|
|
<li>Hardware documentation for the EBB can be found on the <a href="http://www.schmalzhaus.com/EBB/">main EBB page</a>.</li>
|
|
<li><a href="EBBReleaseNotes.html">EBB firmware release notes</a> for versions 2.0.1 up through the newest version.</li>
|
|
</ul>
|
|
|
|
<p />
|
|
<hr />
|
|
<p />
|
|
|
|
<h2><a name="EBB_Command_Reference"></a>EBB Command Reference</h2>
|
|
|
|
<h3><a name="syntax"></a>Syntax and conventions</h3>
|
|
|
|
<p>
|
|
The following syntax conventions are established to assist with clarity of communication as we describe the EBB commands.
|
|
</p>
|
|
|
|
<h4>EBB Syntax Conventions:</h4>
|
|
|
|
<ul>
|
|
<li>Command format descriptions and examples are set in <code>code font</code>, with a shaded background.</li>
|
|
<li>Query response format descriptions and examples are also set in the same <code>code font</code>.</li>
|
|
<li><i>Italics</i> are used to represent variables and adjustable parameters.</li>
|
|
<li>Square brackets (<code>[ ]</code>) are used to enclose optional items.</li>
|
|
<li>Angle brackets (<code>< ></code>) are used to represent individual control characters, such as <code><CR></code> for carriage return or <code><NL></code> for newline, in command and query format descriptions.</li>
|
|
<li>Individual control characters may also be given by their backslash-escaped representation, as in <code>\r</code> for carriage return or <code>\n</code> for linefeed, in the context of literal command examples.</li>
|
|
<li>All unitalicized text and punctuation within a command description must be used literally.</li>
|
|
</ul>
|
|
|
|
<h4>Additionally, please note that:</h4>
|
|
|
|
<ul>
|
|
<li>All commands are composed of ASCII characters</li>
|
|
<li>All commands are case insensitive.</li>
|
|
<li>No whitespace (including spaces, tabs, or returns) is allowed within a command.</li>
|
|
<li>All commands must have a total length of 256 bytes or fewer, including the terminating <code><CR></code> .</li>
|
|
</ul>
|
|
|
|
<h3><a name="commands"></a>The EBB Command Set<br></h3>
|
|
|
|
<ul>
|
|
<li><a href="#A">A</a> — Analog value get</li>
|
|
<li><a href="#AC">AC</a> — Analog Configure</li>
|
|
<li><a href="#BL">BL</a> — enter BootLoader</li>
|
|
<li><a href="#C">C</a> — Configure</li>
|
|
<li><a href="#CK">CK</a> — Check Input</li>
|
|
<li><a href="#CU">CU</a> — Configure User Options</li>
|
|
<li><a href="#CS">CS</a> — Clear Step position</li>
|
|
<li><a href="#EM">EM</a> — Enable Motors</li>
|
|
<li><a href="#ES">ES</a> — E Stop</li>
|
|
<li><a href="#HM">HM</a> — Home or Absolute Move</li>
|
|
<li><a href="#I">I</a> — Input</li>
|
|
<li><a href="#L3">L3</a> — Low-level Move with Jerk</li>
|
|
<li><a href="#LM">LM</a> — Low-level Move</li>
|
|
<li><a href="#LT">LT</a> — Low-level Move, Time Limited</li>
|
|
<li><a href="#MR">MR</a> — Memory Read</li>
|
|
<li><a href="#MW">MW</a> — Memory Write</li>
|
|
<li><a href="#ND">ND</a> — Node count Decrement</li>
|
|
<li><a href="#NI">NI</a> — Node count Increment</li>
|
|
<li><a href="#O">O</a> — Output</li>
|
|
<li><a href="#PC">PC</a> — Pulse Configure</li>
|
|
<li><a href="#PD">PD</a> — Pin Direction</li>
|
|
<li><a href="#PG">PG</a> — Pulse Go</li>
|
|
<li><a href="#PI">PI</a> — Pin Input</li>
|
|
<li><a href="#PO">PO</a> — Pin Output</li>
|
|
<li><a href="#QB">QB</a> — Query Button</li>
|
|
<li><a href="#QC">QC</a> — Query Current</li>
|
|
<li><a href="#QE">QE</a> — Query motor Enables and microstep resolutions</li>
|
|
<li><a href="#QG">QG</a> — Query General</li>
|
|
<li><a href="#QL">QL</a> — Query Variable</li>
|
|
<li><a href="#QM">QM</a> — Query Motors</li>
|
|
<li><a href="#QN">QN</a> — Query Node count</li>
|
|
<li><a href="#QP">QP</a> — Query Pen</li>
|
|
<li><a href="#QR">QR</a> — Query RC Servo power state</li>
|
|
<li><a href="#QS">QS</a> — Query Step position</li>
|
|
<li><a href="#QT">QT</a> — Query EBB nickname Tag</li>
|
|
<li><a href="#QU">QU</a> — Query Utility</li>
|
|
<li><a href="#RB">RB</a> — Reboot</li>
|
|
<li><a href="#R">R</a> — Reset</li>
|
|
<li><a href="#S2">S2</a> — General RC Servo Output</li>
|
|
<li><a href="#SC">SC</a> — Stepper and servo mode Configure</li>
|
|
<li><a href="#SE">SE</a> — Set Engraver</li>
|
|
<li><a href="#SL">SL</a> — Set Variable</li>
|
|
<li><a href="#SM">SM</a> — Stepper Move</li>
|
|
<li><a href="#SN">SN</a> — Set Node count</li>
|
|
<li><a href="#SP">SP</a> — Set Pen State</li>
|
|
<li><a href="#SR">SR</a> — Set RC Servo power timeout</li>
|
|
<li><a href="#ST">ST</a> — Set EBB nickname Tag</li>
|
|
<li><a href="#T">T</a> — Timed Digital/Analog Read</li>
|
|
<li><a href="#T3">T3</a> — Low-level Move with Jerk, Time Limited</li>
|
|
<li><a href="#TD">TD</a> — Paired "Dual T3" Low-level Move With Jerk, Time-limited</li>
|
|
<li><a href="#TP">TP</a> — Toggle Pen</li>
|
|
<li><a href="#TR">TR</a> — Test Rate</li>
|
|
<li><a href="#V">V</a> — Version Query</li>
|
|
<li><a href="#XM">XM</a> — Stepper Move, for Mixed-axis Geometries</li>
|
|
</ul>
|
|
|
|
<p/>
|
|
<p/>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="A"></a>"A" — Analog value get</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>A<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>A,<i>Channel</i>:<i>Value</i>,<i>Channel</i>:<i>Value</i></code> . . . <code><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>A,<i>Channel</i>:<i>Value</i>,<i>Channel</i>:<i>Value</i></code> . . . <code><CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.2.3 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
Query all analog (ADC) input values.
|
|
</p>
|
|
<p>
|
|
When one or more analog channels are enabled (see <code><a href="#AC">AC</a></code> command below), the "A" query will cause the EBB to return a list of all enabled channels and their associated 10 bit values.
|
|
</p>
|
|
<p>
|
|
The list of channels and their data will always be in sorted order from least (channel) to greatest. Only enabled channels will be present in the list.
|
|
</p>
|
|
<p>
|
|
The <i>Value</i> returned for each enabled channel will range from 0 (for 0.0 V on the input) to 1023 (for 3.3 V on the input).
|
|
</p>
|
|
<p>
|
|
The channel number and ADC value are both padded to 2 and 4 characters respectively in the A response.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>A,00:0713,02:0241,05:0089:09:1004<NL></code> if channels 0, 2, 5 and 9 are enabled.
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>A,00:0713,02:0241,05:0089:09:1004<CR><NL></code> if channels 0, 2, 5 and 9 are enabled.
|
|
</li>
|
|
|
|
<li>
|
|
NOTE 1: The EBB's analog inputs are only rated for up to 3.3 V. Be careful not to put higher voltages on them (including 5 V) or you may damage the pin.
|
|
</li>
|
|
<li>
|
|
NOTE 2: If you connect an ADC pin to GND (0.0 V) it will likely not read exactly 0. It will be a bit higher than that. (A typical value is 0023.) This is because of the way that the analog input reference voltages are supplied to the microcontroller.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Unchanged since firmware v2.2.3.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">This command is deprecated in v3.0:</span>
|
|
It will continue to work up until a future firmware version, but it will be removed in that future firmware version.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="AC"></a>"AC" — Analog Configure</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>AC,<i>Channel</i>,<i>Enable</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>AC<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.2.3 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Channel</i>: An integer in the range of 0 to 15 (inclusive). The analog input channel number that you wish to enable or disable. </li>
|
|
<li><i>Enable</i>: A value of either 1 or 0. A value of 1 will enable the channel. A value of 0 will disable the channel.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>Configure an analog input channel.</p>
|
|
<p>
|
|
Use this command to turn on or turn off individual analog channels. Once a channel is turned on, it will begin converting analog values to digital values and the results of the conversions will be displayed in the returned value of the "A" Command. See "A" command above. You can turn on and off any of the 16 analog channels individually on this microcontroller. Once a channel is turned off, it will no longer show up in the "A" packet returned value list.
|
|
</p>
|
|
<p>
|
|
The channel numbers correspond to lines ANx on the EBB schematic and on the datasheet of the microcontroller. For example, pin 11 of the PIC, which is labeled RB2 and comes out as the RB2 pin on the servo header, has the text "RB2/AN8/CTEDG1/PMA3/VMO/REFO/RP5" next to it on the CPU symbol. This means that this pin is internally connected to Analog Channel 8. See chapter 21 of the <a href="http://ww1.microchip.com/downloads/en/DeviceDoc/39931d.pdf">PIC18F46J50 datasheet</a> to read more about the ADC converter.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">This command is deprecated in v3.0:</span>
|
|
It will continue to work up until a future firmware version, but it will be removed in that future firmware version.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="BL"></a>"BL" — Enter Bootloader</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>BL<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span>No response</li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span>No response</li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.5 and newer (with changes)</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>Enter bootloader mode.</p>
|
|
<p>
|
|
This command turns off interrupts and jumps into the bootloader, so that new firmware may be uploaded. This particular method of entering bootloader mode is unique in that no physical button presses are required. Once the EBB receives this command, no response is sent back to the PC.
|
|
</p>
|
|
<p>
|
|
Once in bootloader mode, the EBB will not be able to communicate using the same USB serial port method that the normal firmware commands use. A special bootloader PC application (that uses USB HID to communicate with the bootloader on the EBB) must be run in order to upload new firmware HEX files to the EBB.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="C"></a>"C" — Configure (pin directions)</h4>
|
|
|
|
<ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Command:</span>
|
|
<code>C,<i>PortA_IO</i>,<i>PortB_IO</i>,<i>PortC_IO</i>,<i>PortD_IO</i>,<i>PortE_IO</i><CR></code>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>C<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>PortA_IO</i>: An integer from 0 to 255. Value written to TRISA register.</li>
|
|
<li><i>PortB_IO</i>: An integer from 0 to 255. Value written to TRISB register.</li>
|
|
<li><i>PortC_IO</i>: An integer from 0 to 255. Value written to TRISC register.</li>
|
|
<li><i>PortD_IO</i>: An integer from 0 to 255. Value written to TRISD register.</li>
|
|
<li><i>PortE_IO</i>: An integer from 0 to 255. Value written to TRISE register.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command takes five bytes worth of parameters, one for each TRISx register in the processor, and writes those values down into the TRIS registers. There is a TRIS register for each 8-bit wide I/O port on the processor, and it controls each pin's direction (input or output). A 0 in a pin's bit in the TRIS register sets the pin to be an output, and a 1 sets it to be an input.
|
|
</p>
|
|
<p>
|
|
This command is useful if you want to set up the pin directions for each and every pin on the processor at once. If you just one to set one pin at a time, use the <code>PC</code> command.
|
|
</p>
|
|
<p>
|
|
This command does not need to be used to configure analog inputs. The <code>AC</code> command is used for that.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="CS"></a>"CS" — Clear Step position</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>CS<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>CS<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> Added in v2.4.3</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command zeros out (i.e. clears) the global motor 1 step position and global motor 2 step position. It also zeros out both step accumulators.</p>
|
|
<p>See the <code><a href="#QS">QS</a></code> command for a description of the global step positions.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="CK"></a>"CK" — Check Input</h4>
|
|
|
|
<ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Command:</span> <code>CK,<i>pVal_1</i>,<i>pVal_2</i>,<i>pVal_3</i>,<i>pVal_4</i>,<i>pVal_5</i>,<i>pVal_6</i>,<i>pVal_7</i>,<i>pVal_8</i><CR></code>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Response (future mode):</span>
|
|
<p><code>CK<NL></code></p>
|
|
<p><code>Param1=</code><i>pVal_1</i><code><NL></code></p>
|
|
<p><code>Param2=</code><i>pVal_2</i><code><NL></code></p>
|
|
<p><code>Param3=</code><i>pVal_3</i><code><NL></code></p>
|
|
<p><code>Param4=</code><i>pVal_4</i><code><NL></code></p>
|
|
<p><code>Param5=</code><i>pVal_5</i><code><NL></code></p>
|
|
<p><code>Param6=</code><i>pVal_6</i><code><NL></code></p>
|
|
<p><code>Param7=</code><i>pVal_7</i><code><NL></code></p>
|
|
<p><code>Param8=</code><i>pVal_8</i><code><NL></code></p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Response (legacy mode; default):</span>
|
|
<p><code><CR><NL></code></p>
|
|
<p><code>Param1=</code><i>pVal_1</i><code><CR><NL></code></p>
|
|
<p><code>Param2=</code><i>pVal_2</i><code><CR><NL></code></p>
|
|
<p><code>Param3=</code><i>pVal_3</i><code><CR><NL></code></p>
|
|
<p><code>Param4=</code><i>pVal_4</i><code><CR><NL></code></p>
|
|
<p><code>Param5=</code><i>pVal_5</i><code><CR><NL></code></p>
|
|
<p><code>Param6=</code><i>pVal_6</i><code><CR><NL></code></p>
|
|
<p><code>Param7=</code><i>pVal_7</i><code><CR><NL></code></p>
|
|
<p><code>Param8=</code><i>pVal_8</i><code><CR><NL></code></p>
|
|
<p><code>OK<CR><NL></code></p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span>All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>pVal_1</i> An unsigned one byte integer from 0 to 255.</li>
|
|
<li><i>pVal_2</i> A signed one byte integer from -128 to 127.</li>
|
|
<li><i>pVal_3</i> An unsigned two byte integer from 0 to 65535.</li>
|
|
<li><i>pVal_4</i> A signed two byte integer from -32768 to 32767.</li>
|
|
<li><i>pVal_5</i> An unsigned four byte integer from 0 to 4294967295.</li>
|
|
<li><i>pVal_6</i> A signed four byte integer from -2147483648 to 2147483647.</li>
|
|
<li><i>pVal_7</i> A case sensitive character.</li>
|
|
<li><i>pVal_8</i> A case forced upper case character.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command is used to test out the various parameter parsing routines in the EBB. Each parameter is a different data type. The command simply prints out the values it parsed to allow the developer to confirm that the parsing code is working properly.
|
|
</p>
|
|
<p>For <i>pVal_7</i>, any type-able character is accepted as input.</p>
|
|
<p>For <i>pVal_8</i>, any type-able character is accepted, and converted to upper case before printing.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="CU"></a>"CU" — Configure User Options</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command: </span><code>CU,<i>Param_Number</i>,<i>Param_Value</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode): </span><code>CU<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default): </span><code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions: </span>All</li>
|
|
<li><span style="font-weight: bold;">Execution: </span>Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Param_Number</i> : See below for acceptable values. Specifies what <i>Param_Value</i> means.</li>
|
|
<li><i>Param_Value</i> : An integer from -32768 to 32767. Acceptable values depend on value of <i>Param_Number</i></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
The <code>CU</code> command allows for configuring various run time options. The configuration options chosen with this command do not survive a reboot, and they will return to their default values on a reset or boot.
|
|
</p>
|
|
<p>
|
|
<ul>
|
|
<li>
|
|
<i>Param_Number</i> = 1 : <b>Enable Command Response</b>
|
|
<p>
|
|
This sub-command enables or disables the <code>OK</code> response after the EBB receives and parses a command. Turning off the <code>OK</code> response can help speed up the execution of many back to back commands. This sub-command has no effect when Future Syntax Mode is active.
|
|
</p>
|
|
<ul>
|
|
<li>If <i>Param_Value</i> = 1, then <code>OK</code> response to commands is enabled (default at boot).</li>
|
|
<li>If <i>Param_Value</i> = 0, then <code>OK</code> response to commands is disabled.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 2 : <b>Enable Command Parameter Limit Check</b>
|
|
<p>
|
|
Turning off the limit checking for the stepper motor motion commands will prevent error messages from being sent back to the PC, which may make processing of the data returned from the EBB easier. It will also slightly speed up the command parsing of these commands.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
If <i>Param_Value</i> = 0, then stepper motor motion commands (<code>SM</code>,<code>XM</code>,<code>HM</code>,<code>LM</code>,<code>LT</code>,<code>T3</code>,<code>L3</code>,) will limit their parameter limit checking.
|
|
</li>
|
|
<li>
|
|
If <i>Param_Value</i> = 1, then stepper motor motion commands will perform all parameter limit checking and return error messages if any parameter limits are exceeded (default at boot).
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 3 : <b>Enable Empty FIFO Indication</b>
|
|
<p>
|
|
Using the red LED to indicate an empty FIFO can aid in debugging certain types of problems. When enabled, this option will cause the red LED (labeled "USR" on the board) to light any time there is no motion command in the FIFO. In other words, the LED will light any time there is no motion command waiting to be executed as soon as the current motion command is finished.
|
|
</p>
|
|
<ul>
|
|
<li>If <i>Param_Value</i> = 0, then the red LED will not be used to indicate an empty FIFO (default at boot).</li>
|
|
<li>If <i>Param_Value</i> = 1, then the red LED will be used to indicate an empty FIFO.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 4 : <b>Set new FIFO size</b>
|
|
<p>
|
|
This command will set the FIFO to a new depth, measured in commands. <i>Param_Value</i> needs to be a decimal number between 1 and the maximum possible FIFO size. At boot, the FIFO will be one command deep. This command allows setting the FIFO depth to be larger, up to the limit returned from the <code>QU,2</code> query. Trying to set the FIFO size larger than the maximum possible FIFO size will result in the FIFO size being set to the maximum possible FIFO size. The <code>QU,3</code> query can be used to read out the current FIFO size.
|
|
</p>
|
|
<p>
|
|
If there are any currently executing motion commands, or if there are any commands waiting in the FIFO, the execution of this command will block and wait for the FIFO to be completely empty and any executing motion commands to finish before allowing the change to FIFO size.
|
|
</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 10 : <b>Enable Future Syntax Mode</b>
|
|
<p>
|
|
When enabled, <b>future syntax mode</b> changes the response sent after each command or query to have a relatively consistent format. (This syntax is said to be "future syntax" because it is the formatting that will be default in a future firmware version.)
|
|
</p>
|
|
<p>
|
|
When the EBB boots up, future syntax mode is disabled; which we can abbreviate as being in <b>legacy syntax mode</b>. Legacy syntax mode <i>does not</i> have a consistent pattern of responses nor line endings in those responses. However, it is backward compatible with previous EBB firmware versions.
|
|
</p>
|
|
<p>
|
|
Whereas legacy syntax mode often (but not always) uses an <code>OK<CR><NL></code> at the end of a response, future syntax mode will always print out the one or two character command, followed by <code><NL></code> if there is no additional data in the response packet. If there is additional data in the response packet, then the response packet will consist of the one or two letter command, followed by a comma, then any response data, then <code><NL></code>.
|
|
</p>
|
|
<p>
|
|
For example, when future syntax mode is turned on, the response to the <code>QR</code> command might be <code>QR,1<NL></code>. For comparison, the response to the <code>QR</code> when it is off (in legacy syntax mode) would be <code>1<NL><CR>OK<CR><NL></code>
|
|
</p>
|
|
<p>
|
|
Because part of the response back to the PC is generated before the command is executed, changing the syntax mode with <code>CU,10</code> produces a non-standard response. Sending <code>CU,10,1</code> when in legacy mode will result in a response of <code><NL></code>. Sending <code>CU,10,0</code> when in future mode will result in a response of <code>CUOK<CR><NL></code>. (For future compatibility of your code, you may want to ensure that either response is acceptable.)
|
|
</p>
|
|
<ul>
|
|
<li>If <i>Param_Value</i> = 0, Legacy syntax mode: line endings and responses consistent with previous EBB firmware versions will be used (default at boot).</li>
|
|
<li>If <i>Param_Value</i> = 1, Future syntax mode: consistent line endings and responses will be used for all commands and queries.</li>
|
|
</ul>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 50 : <b>Auto Enable Motors</b>
|
|
<p>
|
|
The stepper motor drivers are normally enabled any time any stepper motor command is executed. However, there may be times when it is desired to leave one or the other disabled while a stepper motion command is executing. The Auto Enable Motors setting allows you to turn off the automatic enabling of stepper motor drivers. This will then require you to manually enable whichever stepper driver you want using the <code>EM</code> command.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
If <i>Param_Value</i> = 0, then the stepper motor drivers will not be automatically enabled at the beginning of every stepper motion command.
|
|
</li>
|
|
<li>
|
|
If <i>Param_Value</i> = 1, then the stepper motor drivers will be automatically enabled at the beginning of every stepper motion command. (Default at boot)
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 51 : <b>Limit Switch Mask</b>
|
|
<p>
|
|
If the Limit Switch Mask is nonzero, the PortB pin states will be checked every 40 μs. For any bit in the mask which is set, if that pin's state matches the corresponding bit state in the Limit Switch Target, then a Limit Switch Stop will be executed immediately.
|
|
</p>
|
|
<p>
|
|
A Limit Switch Stop terminates any currently executing motion command and deletes any motion command in the motion FIFO. New stepper motion commands will be ignored until the condition is cleared. To clear the Limit Switch Stop condition, set the Limit Switch Mask value to zero with <code>CU,51,0</code>. The Limit Switch Stop condition can also be cleared by executing any <a href="#EM">EM</a> command or by resetting (e.g., rebooting) the EBB.
|
|
</p>
|
|
<p>
|
|
If Limit Switch Replies are enabled (<code>CU,53,1</code>) then a Limit Switch Stop will also cause the sending of a packet from the EBB. (See the Limit Switch Replies setting below.)
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<i>Param_Value</i> : Any value from 0 to 255 is allowed. The <i>Param_Value</i> becomes the new Limit Switch Mask value. The default value for the Limit Switch Mask is 0 at reset, thus disabling the Limit Switch feature.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 1:</span>
|
|
A limit switch is connected to PortB pin 2 such that it is normally high but the switch closure brings the pin low. Send <code>CU,52,0</code> to set the target value of bit 2 to a 0, then <code>CU,53,1</code> to enable the Limit Switch Reply. Then, use <code>CU,51,4</code> to set the mask value for bit 2, arming the limit switch system. If, at some point, subsequent stepper motion commands were to create motion that closed the limit switch, that would trigger a Limit Switch Stop and send a Limit Switch Reply. Before any further motion can occur, the PC would send a <code>CU,51,0</code> command to clear the limit switch condition.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 2:</span>
|
|
There are three limit switches on PortB pins 2, 5 and 7. Each is normally low and high once closed. Send <code>CU,52,164</code> to set bits 2, 5 and 7 of the Limit Switch Target, and <code>CU,53,1</code> to enable the Limit Switch Reply. Then, use <code>CU,51,164</code> to set bits 2, 5, and 7 of the Limit Switch Mask, which enables the feature. If any of the three limit switches closes, the Limit Switch Stop would occur and the Limit Switch Reply would be sent. If it is important to know exactly which limit switch was the one that triggered the Limit Switch Stop, examine the response packet from the Limit Switch Reply.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 52 : <b>Limit Switch Target</b>
|
|
<p>
|
|
The Limit Switch Target is used along with the Limit Switch Mask (<code>CU,51</code>) to configure the limit switch function. For bits that are set in the limit switch mask, those portB digital input values are compared to the corresponding bits in this Limit Switch Target. If the input value matches the target value, the Limit Switch Stop will be triggered.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<i>Param_Value</i> : Any value from 0 to 255 is allowed. The <i>Param_Value</i> becomes the new Limit Switch Target value. The default value for the Limit Switch Target is 0 at reset.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 53 : <b>Enable Limit Switch Reply</b>
|
|
<p></p>
|
|
<ul>
|
|
<li>
|
|
If <i>Param_Value</i> = 0, then no Limit Switch Reply packet will be sent when a limit switch condition is triggered (default at boot).
|
|
</li>
|
|
<li>
|
|
If <i>Param_Value</i> = 1, then, when a Limit Switch Stop is triggered, a packet will be sent from the EBB to the PC of the form <code>Limit switch triggered. PortB=XX\n</code> where <code>XX</code> is the value of the PortB inputs at the moment of the Limit Switch Stop, as two hexadecimal digits. Unlike regular EBB responses, this response is asynchronous, at the moment of the Limit Switch Stop, and not directly in response to a command or query. (The response will be made between replies from command parsing, so as to not interrupt the reply from a command.)
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 54 : <b>Enable Command Checksums</b>
|
|
<p></p>
|
|
<ul>
|
|
<li>
|
|
If <i>Param_Value</i> = 0, then checksums at the end of commands are not required. (Default at boot).
|
|
</li>
|
|
<li>
|
|
If <i>Param_Value</i> = 1, then checksums at the end of commands are required.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Turning on checksums for commands allows the EBB to check that all of the command bytes made it successfully across USB to the EBB. USB has it's own checksums/CRCs and so guarantees proper data delivery at a lower level, but these application level checksums provide a way for the PC to know that the full command string that it created was properly received by the EBB. If checksums have been turned on, and no checksum is provided, an error message will be sent back to the PC and the command will not be executed. If checksums have been turned on and an incorrect checksum is provided, the EBB will return an error message back to the PC which will include the expected checksum and the command will not be executed.
|
|
</p>
|
|
<p>
|
|
To add a checksum to a command, simply add a comma and a one to three digit decimal number (from 0 to 255) at the very end of the command. The checksum should be 0x100 - (sum of all command bytes up to but not including the comma preceding the checksum). This is commonly referred to as the '8-bit checksum 2s compliment'.
|
|
</p>
|
|
<p>
|
|
Enabling checksums does add a small bit of additional processing time to each command, which reduces the maximum number of commands per second that the EBB can accept.
|
|
</p>
|
|
<p>
|
|
The website <a href="https://www.scadacore.com/tools/programming-calculators/online-checksum-calculator/">https://www.scadacore.com/tools/programming-calculators/online-checksum-calculator/</a> can be used to compute checksums for a command. Take the desired command, paste it into the ASCII Input field, click AnalyzeDataAscii and then look at the CheckSum8 2s Complement field. Take that value (which is in hex) and convert it to decimal to use as the checksum for your command.
|
|
</p>
|
|
<p>
|
|
<span style="font-weight: bold;">Example 1:</span> If you want to send the command <code>SM,1000,1000,1000</code> with a checksum, you would send <code>SM,1000,1000,1000,153</code>. The 153 on the end is the checksum of all of the bytes up to but not including the comma before the checksum.
|
|
</p>
|
|
<p>
|
|
<span style="font-weight: bold;">Example 2:</span> If you want to send the command <code>CU,54,0</code> (to turn off checksums) with a checksum but you don't know what the checksum should be, you could send an invalid checksum like <code>CU,54,0,0</code>. This will result in the response <code>!8 Err: Checksum incorrect, expected 119</code>. So you would know that the proper checksum value for this command is 119 and could send <code>CU,4,0,119</code>.
|
|
</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 60 : <b>Set new power lost threshold</b>
|
|
<p>
|
|
This command will set a new <i>Power_Lost_Threshold</i>. The <i>Param_Value</i> needs to be a decimal number between 0 and 1023 and is in units of 0.295V. At boot the <i>Power_Lost_Threshold</i> will be zero. Every 2ms the EBB will compare the voltage at the barrel jack (V+) with <i>Power_Lost_Threshold</i>. If V+ is ever less than <i>Power_Lost_Threshold</i>, then bit 6 in the result of the <code>QG</code> command will be set. Setting <i>Power_Lost_Threshold</i> to zero (as it is at boot) effectively disables this feature. If bit 6 of the <code>QG</code> result is set, then after the execution of <code>QG</code> it will be cleared. The <code>QU,60</code> query can be used to read back the current value of <i>Power_Lost_Threshold</i> at any time. After setting a new value of <i>Power_Lost_Threshold</i> with <code>CU,60</code> make sure to execute a <code>QG</code> query to clear bit 6 in case it was set. For example to set the <i>Power_Lost_Threshold</i> to 12V you would use <code>CU,60,404</code>.
|
|
</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 61 : <b>Set new Stepper Disable Timeout value</b>
|
|
<p>
|
|
This command will set the <i>Stepper_Disable_Timeout</i>. The <i>Param_Value</i> needs to be a decimal number between 0 and 65534 and is in units of seconds. At boot the <i>Stepper_Disable_Timeout</i> is zero, which disables this feature. Any time <i>Stepper_Disable_Timeout</i> is not zero the feature is enabled.
|
|
</p>
|
|
<p>
|
|
When enabled, this feature will count down <i>Stepper_Disable_Timeout</i> seconds after the last motion command. When the count reaches zero, it will disable the two stepper motor drivers. This makes the stepper motors freewheel as well as reduces the current draw of the EBB significantly. If a new <i>Stepper_Disable_Timeout</i> value is set while the countdown is already ongoing, the countdown will begin again using the new value. If a new motion command is executed while counting down, the countdown will be stopped and will start back at <i>Stepper_Disable_Timeout</i> when all motion commands are complete.
|
|
</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 250 : <b>Enable GPIO ISR Debug pins</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 251 : <b>Enable debug USART end of move values printing</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 252 : <b>Enable debug USART every ISR move values printing</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 253 : <b>Enable debug UART command echo</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 254 : <b>Enable Lock Up Mode</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 255 : <b>Enable command parsing USB debug printing</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 256 : <b>Disable parsed moves from entering FIFO</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 257 : <b>Enable RC7 indicator of command parsing</b>
|
|
<p>This is an internal software debugging and testing command.</p>
|
|
<p>
|
|
This parameter is new for <code>CU</code> in EBB firmware v3.0.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span>
|
|
<p><code>CU,50</code>, <code>CU,51</code>, <code>CU,52</code>, <code>CU,53</code>, <code>CU,250</code> through <code>CU,257</code> were added in v3.0.</p>
|
|
</li>
|
|
|
|
<li><span style="font-weight: bold;">Deprecation notice:</span> <code>CU,1</code> is deprecated as of EBB firmware v3.0 and will be removed in a future firmware version. <code>CU,10</code> will be allowed, but will have no effect in that future firmware version. (What is now "future" syntax will be the default syntax in future firmware version)</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="EM"></a> "EM" — Enable Motors</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>EM,<i>Enable1</i>,<i>Enable2</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span><code>EM<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span><code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<p>
|
|
For each stepper motor (<i>Enable1</i> for motor1 and <i>Enable2</i> for motor2), an integer in the range of 0 through 5, inclusive. An <i>Enable</i> value of 0 will disable that motor (making it freewheel), while a nonzero value will enable that motor. This command is also used to set the step resolution of the stepper motors.
|
|
</p>
|
|
<p>The allowed values of <i>Enable1</i> are as follows:</p>
|
|
<ul>
|
|
<li>0: Disable motor 1 </li>
|
|
<li>1: Enable motor 1, set global step mode to 1/16 step mode (default step mode upon reset)</li>
|
|
<li>2: Enable motor 1, set global step mode to 1/8 step mode</li>
|
|
<li>3: Enable motor 1, set global step mode to 1/4 step mode</li>
|
|
<li>4: Enable motor 1, set global step mode to 1/2 step mode</li>
|
|
<li>5: Enable motor 1, set global step mode to full step mode</li>
|
|
</ul>
|
|
<p>The allowed values of <i>Enable2</i> are as follows:</p>
|
|
<ul>
|
|
<li>0: Disable motor 2</li>
|
|
<li>1 through 5: Enable motor 2 (at whatever the previously set global step mode is)</li>
|
|
</ul>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Description:</span>
|
|
<p>Enable or disable stepper motors and set step mode.</p>
|
|
<p>
|
|
Each stepper motor may be independently enabled (energized) or disabled (causing that motor to freewheel). When disabled, the driver will stop sending current to the motor, so the motor will "freewheel" — it will not be actively driven, but instead will present little resistance to being turned by external torques.
|
|
</p>
|
|
<p>
|
|
When enabled, the stepper motor driver actively drives current through the coils, causing the motors to 'lock' (i.e. be very difficult to turn by external torques).
|
|
</p>
|
|
<p>
|
|
Each of the motor movement commands (like SM, XM, and LM) automatically enable both motors before they begin their motion, but do not change the global step mode.
|
|
</p>
|
|
<p>
|
|
The stepper motors may be configured to be in whole, half, quarter, eighth, or sixteenth step modes. When using a motor with a native resolution of 200 steps per revolution, these settings would produce effective stepping resolutions of 200, 400, 800, 1600, and 3200 steps per revolution, respectively. Using fine sub-steps ("microstepping") gives higher resolution at the cost of decreasing step size reproducibility and decreasing maximum step speed. Note that the microstep mode is set for both motors simultaneously, using the parameter value of <i>Enable1</i>. It is not possible to set the step mode separately for each motor. Thus there is just one global step mode, and it is set by the value of <i>Enable1</i>.
|
|
</p>
|
|
<p>
|
|
Because only <i>Enable1</i> can set the global step mode, <i>Enable2</i> simply enables or disables axis 2, and can not change the previously set step mode on its own.
|
|
</p>
|
|
<p>
|
|
Note that this version of the command is for current versions of the EBB hardware, v1.2 and newer. (This includes all versions manufactured since September 2010.)
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,1,0\r</code> Enable motor 1, set global step mode to 1/16th and disable motor 2
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,1,0\r</code> Enable motor 1, set global step mode to 1/16th and disable motor 2
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,2\r</code> Set global step mode to 1/8 enable motor 1, and do not change motor 2's enable status. (<i>Enable2</i> is optional)
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,2\r</code> Set global step mode to 1/8 enable motor 1, and do not change motor 2's enable status. (<i>Enable2</i> is optional)
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,3,3\r</code> Set global step mode to 1/4 and enable both motors.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,3,3\r</code> Set global step mode to 1/4 and enable both motors.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,0,1\r</code> Enable motor 2, disable motor 1, and continue to use previously set global step mode
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,0,1\r</code> Enable motor 2, disable motor 1, and continue to use previously set global step mode
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,0,0\r</code> Disable both motors (both will freewheel)
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,0,0\r</code> Disable both motors (both will freewheel)
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,3,1\r</code> Enable both motors and set to 1/4 step mode
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>EM,3,1\r</code> Enable both motors and set to 1/4 step mode
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Unchanged since firmware 2.8.0
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="ES"></a>"ES" — E Stop</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>ES[,DisableMotors]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>ES,<i>Interrupted</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>Interrupted</i><NL><CR>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.2.7 and newer (with changes)</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate </li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>DisableMotors</i> This is an optional parameter with a value of 0 or 1. If it is a 1, then both stepper drivers will be disabled. If it is 0 or not present, then the stepper drivers will be left in this current state.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
Use this query to abort any in-progress stepper motor moves and flush the motion FIFO. It will immediately stop the stepper motors. In addition, if any motion command was currently executing or in the FIFO when the command arrives the <i>Interrupted</i> return value will be a 1.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Returned values:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Interrupted</i>: 0 if no FIFO or in-progress move commands were interrupted, 1 if a motor move command was in progress or in the FIFO
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span>
|
|
<code>ES,0<NL></code> Indicates that no stepper motion command was executing at the time, and the FIFO was empty.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span>
|
|
<code>0<NL><CR>OK<CR><NL></code> Indicates that no stepper motion command was executing at the time, and the FIFO was empty.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span>
|
|
<code>ES,1<NL></code> Indicates that a stepper command was interrupted (and/or that the FIFO was not empty).
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span>
|
|
<code>1<NL><CR>OK<CR><NL></code> Indicates that a stepper command was interrupted (and/or that the FIFO was not empty).
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="HM"></a>"HM" — Home or Absolute Move</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span><code>HM,<i>StepFrequency</i>[,<i>Position1</i>,<i>Position2</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span><code>HM<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span><code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.6.2 and newer (with changes)</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>StepFrequency</i> is an unsigned integer in the range from 2 to 25000. It represents the step frequency, in steps per second, representing typical speed during the movement.
|
|
</li>
|
|
<li>
|
|
<i>Position1</i> and <i>Position2</i> (optional) are 32 bit signed integers in the range of -2147483648 to 2147483647. If provided, they represents the position, relative to home, that motor1 and motor2 will travel to. If <i>Position1</i> is provided <i>Position2</i> must also be provided.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command will cause the two stepper motors to move from their current position, as defined by the global step counters, either to Home (0, 0) or to a new position that you specify relative to the Home position. It is worth noting that this is the only EBB motion command for which you can specify an absolute position to move to; all other motion commands are relative to the current position. This command is intended for "utility" moves, to or from a specific point, rather than for smooth or fast motion.
|
|
</p>
|
|
<p>
|
|
The current position at any given moment is stored in the global step counters, and can be read with the <code><a href="#QS">QS</a></code> query. This position <i>does not</i> refer to an absolute position in physical space, but rather the location where the motors were enabled. The global step counters are reset to zero whenever the motors are enabled, disabled, or have their microstep size changed (all via the <code>EM</code> command). The step counter can also be cleared directly by the <code><a href="#CS">CS</a></code> command.
|
|
</p>
|
|
<p>
|
|
The step rate at which the move should happen is specified as a parameter. If no destination position is specified, then the move is towards the Home position (0, 0).
|
|
</p>
|
|
<p>
|
|
The maximum (25000 steps/s) and minimum (0.00001164 steps/s) step speed will not be violated no matter what parameters are used. The <code>HM</code> command will limit its step speeds such that they stay within those bounds.
|
|
</p>
|
|
<p>
|
|
The command will wait until all previous motor motion ceases before executing. There is also a further delay, typically about 5 ms, between when the <code>HM</code> command begins execution and when its motion actually begins.
|
|
</p>
|
|
<p>
|
|
There is a limitation to <i>Position1</i> and <i>Position2</i>. When they are each added to the negative of the respective current global positions to compute the number of steps necessary to complete this <code>HM</code> move, the sum must not overflow a signed 32 bit number. An overflow like this will generate an error. Note that this situation is very unlikely to occur, as 0x7FFFFFFF steps (the maximum number of steps a signed 32 bit int can represent) will take 23 hours to execute at the highest step rate (25Ks/s).
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Available since firmware 2.7.0. In v3.0, the command was updated to allow larger input paramters and slower minimum speeds and will now always travel in a straight line.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="I"></a>"I" — Input (digital)</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>I<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>I,<i>PortA</i>,<i>PortB</i>,<i>PortC</i>,<i>PortD</i>,<i>PortE</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>I,<i>PortA</i>,<i>PortB</i>,<i>PortC</i>,<i>PortD</i>,<i>PortE</i><CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads every PORTx register (where x is A through E) and prints out each byte-wide register value as a three digit decimal number. This effectively reads the digital values on each and every pin of the processor and prints them out. If you need the value of a particular pin, you can extract it from the value printed for that port by looking at the binary bit within the byte for that pin. For example, if you wanted to read the value of RB4, you would look at the 5th bit (0x10) of the PortB byte in the return packet.
|
|
</p>
|
|
<p>
|
|
For pins that are set as outputs, or are set as analog inputs, or are set as something other than digital inputs, this query will still convert the voltage on the pin to a digital value of 1 or 0 (using the standard voltage thresholds specified in the processor datasheet) and return all of their values.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example:</span><code>I<CR></code></li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span>
|
|
<code>I,128,255,130,000,007<NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span>
|
|
<code>I,128,255,130,000,007<CR><NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">This command is deprecated in v3.0:</span>
|
|
It will continue to work up until a future firmware version, but it will be removed in that future firmware version.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="LM"></a>"LM" — Low-level Move, Step-limited</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span><code>LM,<i>Rate1</i>,<i>Steps1</i>,<i>Accel1</i>,<i>Rate2</i>,<i>Steps2</i>,<i>Accel2</i>[,<i>Clear</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>LM<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.7.0 and above</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Rate1</i> and <i>Rate2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. They represent step rates for axis 1 and 2, and are added to each axis step accumulator every 40 μs to determine when steps are taken. The sign of each <i>Rate</i> parameter can determine the initial motor direction. See direction note below.
|
|
</li>
|
|
<li>
|
|
<i>Steps1</i> and <i>Steps2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. Each number gives the movement distance — the total number of steps — for the given axis, axis 1 or axis 2. The sign of each <i>Steps</i> parameter can determine the initial motor direction. See direction note below.
|
|
</li>
|
|
<li>
|
|
<i>Accel1</i> and <i>Accel2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Rate</i> values every 40 μs and control acceleration or deceleration during a move.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Direction note:</span>
|
|
<p>Normally the sign of the <i>Rate</i> parameters are used to indicate initial motor direction. When <i>Rate</i> signs are used for direction, then <i>Steps</i> parameters should be positive. However, if the sign of <i>Rate</i> is positive, then the sign of the <i>Steps</i> parameters can be used to control initial motor direction instead. Internally, if an axis has a negative <i>Steps</i> and a positive <i>Rate</i>, the EBB code will flip the sign on <i>Rate</i> and <i>Steps</i> as well as <i>Accel</i> to make the math work out.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
<b>Overview:</b> This low-level command causes one or both motors to move for a given number of steps, and allows the option of applying a constant acceleration to one or both motors during their movement. The motion terminates for each axis when the required number of steps have been made, and the command is complete when the both motors have reached their targets.
|
|
</p>
|
|
<p>
|
|
This command, as compared to the similar <code><a href="#LT">LT</a></code> command, allows you to specify an exact step position, but is more difficult to use since the moves for the two axes may complete at different times.
|
|
</p>
|
|
<p>
|
|
This is a low-latency command where the input values are parsed and passed directly into motion control FIFO of the EBB. No time is lost doing any math operations or limit checking, so maximum command throughput can be achieved. (See <a href="https://github.com/evil-mad/EggBot/issues/73">GitHub issue #73</a> for more information about the motivation for this command.) While individual movement commands may be as short as a single step, there are practical limits to the rate at which commands can be issued, as discussed under <a href="#performance">Performance</a>.
|
|
</p>
|
|
<p>
|
|
<b>Methods and consequences:</b>
|
|
Each axis has a separate 32 bit Accumulator to control its timing. When the <code>LM</code> command is called, the Accumulator may be initialized to zero or left alone, depending on the value of the <i>Clear</i> argument. The initial value of <i>Rate</i> for each axis is adjusted by subtracting <i>Accel</i>/2 from it. Then, every 40 μs (at a rate of 25 kHz) the following operations are executed for each axis, if the total number of steps to be taken is nonzero:
|
|
</p>
|
|
<ol>
|
|
<li>Update the value <i>Rate</i> = <i>Rate</i> + <i>Accel</i>.</li>
|
|
<li>If the new (<i>Rate</i> < 0), then "roll it over" with <i>Rate</i> = <i>Rate</i> + 2<sup>31</sup>.</li>
|
|
<li>The value of <i>Rate</i> is added to the Accumulator.</li>
|
|
<li>If the new Accumulator value is greater than or equal to 2<sup>31</sup> (2147483648 decimal; 0x80000000 hex), then:
|
|
|
|
<ul>
|
|
<li>The motor on that axis moves one step.</li>
|
|
<li>2<sup>31</sup> is subtracted from the Accumulator for that axis. </li>
|
|
</ul></li>
|
|
<li>Check to see if the total number of steps moved equals <i>Steps</i>.
|
|
If true, the move is complete for this axis; no further steps will be taken.</li>
|
|
<li>Check if the move is complete for both axes. If so, exit the LM command.</li>
|
|
</ol>
|
|
|
|
<p>
|
|
A restriction on the parameters is that motion must be possible on at least one axis. That is to say, you must ensure that both <i>Steps</i> is nonzero <i>and</i> that either <i>Rate</i> or <i>Accel</i> are nonzero for at least one axis of motion, or no motion will occur.
|
|
</p>
|
|
<p>
|
|
Because the parameters for each axis determine how long the move will take <i>for that axis</i>, one axis may finish stepping before the other. In extreme cases, one axis will finish moving long before the other, which can lead to (correct but) unintuitive behavior. For example, in an XY movement command both axes could travel same distance yet have axis 1 finish well before axis 2. The apparent motion would be a diagonal XY movement for the first part of the transit time, followed by a straight movement along axis 2. To the eye, that transit appears as a "bent" line, or perhaps as two distinct movement events.
|
|
</p>
|
|
<p>
|
|
<b>Computing values:</b> The value of <i>Rate</i> can be computed from a motor step frequency <i>F</i>, in Hz, as:
|
|
</p>
|
|
<ul class="no_bullets">
|
|
<li><i>Rate</i> = 2<sup>31</sup> × 40 μs × <i>F</i> , or</li>
|
|
<li><i>Rate</i> ≈ 85,899.35 s × <i>F</i>.</li>
|
|
</ul>
|
|
<p>
|
|
In the case of constant velocity, where <i>Accel</i> is zero, the value of <i>Rate</i> can thus be computed from the number of steps and desired total travel time <i>t</i>, in seconds, as <i>Rate</i> = 2<sup>31</sup> × 40 μs × ( <i>Steps</i> / <i>t</i> ), or <i>Rate</i> ≈ 85,899.35 s × ( <i>Steps</i> / <i>t</i> ). This computation (along with most of the others in the section) should be performed as a floating point operation, or at least with 64 bit precision, since <i>Steps</i> × 2<sup>31</sup> may take up to 63 bits.
|
|
</p>
|
|
<p>
|
|
The <i>Accel</i> value is added to <i>Rate</i> every 40 μs. It can be positive or negative. This is used to cause an axis to accelerate or decelerate during a move. The theoretical final "velocity rate" after <i>T</i> intervals of 40 μs each, starting with initial rate <i>Rate</i> is:
|
|
</p>
|
|
<ul class="no_bullets">
|
|
<li><i>Rate</i><sub>Final</sub> = <i>Rate</i> + <i>Accel</i> × <i>T</i></li>
|
|
</ul>
|
|
<p>
|
|
The value of <i>Accel</i> can be calculated from the initial value <i>Rate</i>, its desired final value <i>Rate</i><sub>Final</sub>, and the number <i>T</i> of 40 μs intervals that the movement will take:
|
|
</p>
|
|
<ul class="no_bullets">
|
|
<li><i>Accel</i> = ( <i>Rate</i><sub>Final</sub> - <i>Rate</i> ) / <i>T</i></li>
|
|
</ul>
|
|
<p>
|
|
If an LM command begins with a specified <i>Rate</i> and <i>Accel</i>, as well as a (possibly unknown) initial Accumulator value <i>C</i><sub>0</sub>, then the Accumulator value <i>C</i><sub>T</sub> after <i>T</i> intervals of 40 μs each is given by:
|
|
</p>
|
|
<ul class="no_bullets">
|
|
<li><i>C</i><sub>T</sub> = <i>C</i><sub>0</sub> + <i>Rate</i> × <i>T</i> + (1/2) <i>Accel</i> × <i>T</i><sup>2</sup></li>
|
|
</ul>
|
|
<p>
|
|
(This formula may look familiar from elementary physics, as it has the form: <i>x</i>(t) = <i>x</i><sub>0</sub> + <i>v</i><sub>0</sub><i>T</i> + (1/2) <i>a</i><i>T</i><sup>2</sup>.) The number of motor steps traveled along the axis during the command can be found from this by dividing the Accumulator value <i>C</i><sub>T</sub> by 2<sup>31</sup> and rounding down the result. Thus the step count after <i>T</i> intervals is given by:
|
|
</p>
|
|
<ul class="no_bullets">
|
|
<li><i>Steps</i> = <span style="font-weight: bold;">Floor</span>( ( <i>C</i><sub>0</sub> + <i>Rate</i> × <i>T</i> + (1/2) <i>Accel</i> × <i>T</i><sup>2</sup> ) / 2<sup>31</sup> )
|
|
</ul>
|
|
<p>
|
|
This is a quadratic equation, and the exact movement time for a given number of steps can be computed by solving for <i>T</i> using the quadratic formula. If you already know the final speed, then the approximate movement time <i>t</i> in seconds can be found by dividing the number of steps by the average step frequency over the move:
|
|
</p>
|
|
<ul class="no_bullets">
|
|
<li><i>t</i> ≈ <i>Steps</i> / <i>F</i><sub>AVE</sub> = 2 × <i>Steps</i> / ( <i>F</i><sub>0</sub> + <i>F</i><sub><i>t</i></sub> )</li>
|
|
</ul>
|
|
<p>
|
|
Here, <i>F</i><sub>0</sub> and <i>F</i><sub><i>t</i></sub> are the initial and final step frequencies <i>F</i> for the move. From this, we can also calculate the approximate move duration <i>T</i> in terms of 40 μs intervals, using <i>Rate</i> = 2<sup>31</sup> × 40 μs × <i>F</i> and <i>t</i> = 40 μs × <i>T</i>:
|
|
</p>
|
|
<ul class="no_bullets">
|
|
<li><i>T</i> ≈ 2<sup>31</sup> × <i>Steps</i> / <i>R</i><sub>AVE</sub> = 2<sup>32</sup> × <i>Steps</i> / ( <i>Rate</i> + <i>Rate</i><sub>Final</sub> )</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 1:</span> Suppose that we wanted to start moving an axis at 45 steps/s, and end at 250 steps/s, over a total of 60 steps. By the above formulas, we know that our starting <i>Rate</i> is 3865471, our ending <i>Rate</i><sub>Final</sub> is 21474836, and our move time is 60/((45 + 250)/2) = 0.4068 seconds (or <i>T</i> = 10169 intervals). We find <i>Accel</i> from the change in <i>Rate</i> over the number of intervals: (21474836 - 3865470)/10169 = 1732. We then have the following LM command:
|
|
<ul class="no_bullets">
|
|
<li><code>LM,3865471,60,1732,0,0,0</code></li>
|
|
</ul>
|
|
Notice that we are only using axis 1 in this example. You can of course use both axes at the same time, but you usually need to be careful that the times for each axis match up.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 2:</span> <code>LM,33865471,1000,0,0,0,0\r</code> This example will move axis 1 at a constant speed of 45 steps/s for 1000 steps. Axis 2 does not move.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 3:</span> <code>LM,85899346,10,0,17180814,2,0\r</code> This example will cause a 10 ms long move, where axis 1 takes a step every 1 ms, and axis 2 takes a step every 5 ms. Axis 1 will step for 10 steps, and axis 2 will step for 2 steps, and they will both finish together at the end of the 10 ms. This is a constant-rate move without acceleration or deceleration on either axis.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 4:</span> <code>LM,85899346,500,0,85899346,250,0\r</code> This example will step both axis at a 1 ms/step rate, and axis 1 will step for 500 steps and axis 2 will step for 250 steps. This is <i>usually</i> not what you want in practice; it's usually better if the moves for each axis terminate at the same time. This is a "constant-rate" move without acceleration or deceleration on either axis.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 5:</span> <code>LM,17180814,6,0,57266231,20,0\r</code> This example will create a 30 ms long move, with axis 1 stepping 6 times and axis 2 stepping 20 times. There is no acceleration or deceleration on either axis.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 6:</span> <code>LM,42950000,50,13400,0,0,0\r</code> This example will start with axis 1 stepping at 500 steps/second and end with axis 1 stepping at 800 steps/second. It lasts for a duration of 50 steps. Axis 2 does not move. The move will take 77 ms to complete.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 7:</span> <code>LM,17179000,75,-687,8592000,75,687\r</code> This example will start with axis 1 at 200 steps/second, and axis 2 at 100 steps/second. Over the course of 75 steps each, they will end at a speed of 100 steps/second for axis 1 (that is, decelerating) and 200 steps/second for axis 2. The move will take 500 ms.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Added in firmware v2.7.0.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> As of firmware v3.0, using a negative number for either <i>Rate</i> argument to control motion direction is deprecated. It will still work, but this functionality has been replaced by using a negative number to either <i>Step</i> argument. In a future firmware version the ability to use negative <i>Rate</i> arguments will be removed.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="L3"></a>"L3" — Low-level Move With Jerk</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span><code>L3,<i>Rate1</i>,<i>Steps1</i>,<i>Accel1</i>,<i>Jerk1</i>,<i>Rate2</i>,<i>Steps2</i>,<i>Accel2</i>,<i>Jerk2</i>[,<i>Clear</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>L3<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v3.0 and above</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Rate1</i> and <i>Rate2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. They represent step rates for axis 1 and 2, and are added to each axis step accumulator every 40 μs to determine when steps are taken. The sign of each <i>Rate</i> parameter can determine the initial motor direction. See direction note below.
|
|
</li>
|
|
<li>
|
|
<i>Steps1</i> and <i>Steps2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. Each number gives the movement distance — the total number of steps — for the given axis, axis 1 or axis 2. The sign of each <i>Steps</i> parameter can determine the initial motor direction. See direction note below.
|
|
</li>
|
|
<li>
|
|
<i>Accel1</i> and <i>Accel2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Rate</i> values every 40 μs and control acceleration or deceleration during a move.
|
|
</li>
|
|
<li>
|
|
<i>Jerk1</i> and <i>Jerk2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Accel</i> values every 40 μs and control jerk during a move.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Direction note:</span>
|
|
<p>Normally the sign of the <i>Rate</i> parameters are used to indicate initial motor direction. When <i>Rate</i> signs are used for direction, then <i>Steps</i> parameters should be positive. However, if the sign of <i>Rate</i> is positive, then the sign of the <i>Steps</i> parameters can be used to control initial motor direction instead. Internally, if an axis has a negative <i>Steps</i> and a positive <i>Rate</i>, the EBB code will flip the sign on <i>Rate</i> and <i>Steps</i> as well as <i>Accel</i> to make the math work out.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command is extremely similar to the <code><a href="#LM">LM</a></code> command. In fact, if both <i>Jerk1</i> and <i>Jerk2</i> are zero, this command is exactly <code><a href="#LM">LM</a></code> command. The difference is in the addition of the two jerk parameters. When there are non-zero values for the jerk parameters, an additional step before step 1 (see the 'Methods and consequences' section in the <code><a href="#LM">LM</a></code> command description) adds the jerk term to the accel term.
|
|
</p>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 1:</span>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 2:</span>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="LT"></a>"LT" — Low-level Move, Time-limited</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>LT,<i>Intervals</i>,<i>Rate1</i>,<i>Accel1</i>,<i>Rate2</i>,<i>Accel2</i>[,<i>Clear</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>LT<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.7.0 and above</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Intervals</i> is an unsigned 32 bit integer in the range from 0 to 4294967295, which specifies the duration of time, in units of 40 μs intervals, that the command executes for.
|
|
</li>
|
|
<li>
|
|
<i>Rate1</i> and <i>Rate2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. The sign of each <i>Rate</i> parameter controls <i>the direction</i> that the axis should turn initially. The absolute value abs(<i>Rate</i>) of each <i>Rate</i> is added to its axis step Accumulator every 40 μs to determine when steps are taken.
|
|
</li>
|
|
<li>
|
|
<i>Accel1</i> and <i>Accel2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Rate</i> values every 40 μs and control acceleration or deceleration during a move.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
<b>Overview:</b> This low-level command causes one or both motors to move for a given duration of time, and allows the option of applying a constant acceleration to one or both motors during their movement. The motion terminates for each axis when the required number of time intervals has elapsed.
|
|
</p>
|
|
<p>This command, as compared to the similar <code><a href="#LM">LM</a></code> command, makes it much easier to construct motion sequences that smoothly follow one another, but trades off the ability to exactly specify a destination in the process. You may wish to use sequences of LT commands, followed by a <code><a href="#HM">HM</a></code> command, in order to both move quickly and end up at a specific location.
|
|
</p>
|
|
<p>
|
|
This is a low-latency command where the input values are parsed and passed directly into motion control FIFO of the EBB. No time is lost doing any math operations or limit checking, so maximum command throughput can be achieved. While individual movement commands may be as short as a single 40 μs time interval, there are practical limits to the rate at which commands can be issued, as discussed under <a href="#performance">Performance</a>.
|
|
</p>
|
|
<p>
|
|
<b>Methods and consequences:</b> The <code>LT</code> function is essentially identical to the <code><a href="#LM">LM</a></code> in every aspect of its operation <i>except</i> that it terminates after a set number of intervals rather than after a set number of steps. That is to say, in the sequence of operations executed every 40 μs, when the check is made to see if the move is complete, the time elapsed — not the step count — is checked.
|
|
</p>
|
|
<p>
|
|
With that in mind, all of the formulas from the description of the <code><a href="#LM">LM</a></code> command, for computing step rates, acceleration, distance, and time are all still applicable when working with <code>LT</code>.
|
|
</p>
|
|
<p>
|
|
Once exception should be noted: Since there is no <i>Step</i> argument in this command to indicate the direction that each motor should turn, the input <i>Rate</i> arguments are given a sign. The sign of <i>Rate</i> indicates <i>only</i> which direction the motor should turn. Only its absolute value |<i>Rate</i>| is input to the routines that calculate and manage the motor step frequency. When using the formulas from the <code><a href="#LM">LM</a></code> command description, use the unsigned value |<i>Rate</i>|.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 1:</span> Suppose that we wanted to start moving an axis at 45 steps/s, and end at 250 steps/s, over a total of 60 steps. Following Example 1 from <code><a href="#LM">LM</a></code>, we know that our starting <i>Rate</i> is 3865471, our ending <i>Rate</i><sub>Final</sub> is 21474836, and our move time is 60/((45 + 250)/2) = 0.4068 seconds (or <i>T</i> = 10169 intervals). We find <i>Accel</i> from the change in <i>Rate</i> over the number of intervals: (21474836 - 3865470)/10169 = 1732. We then have the following LT command, adding the <code>,3</code> value on the end to clear the Accumulator:
|
|
<ul class="no_bullets">
|
|
<li><code>LT,10169,3865471,1732,0,0,3</code></li>
|
|
</ul>
|
|
Since this command does not explicitly specify the number of steps to be traveled, you may want to carefully check your math, or use tools like <code><a href="#QS">QS</a></code> or <code><a href="#HM">HM</a></code> command following a move like this.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 2:</span> <code>LT,25000,33865471,0,0,0\r</code> This example will move axis 1 at a constant speed of 45 steps/s for one second (25000 intervals). Axis 2 does not move.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 3:</span> <code>LT,12500,17179000,-687,8592000,687\r</code> This example will start with axis 1 at 200 steps/second, and axis 2 at 100 steps/second. Over the course of 500 ms, they will end at a speed of 100 steps/second for axis 1 (that is, decelerating) and 200 steps/second for axis 2. The move will cover 75 steps on each axis.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Added in v2.7.0.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="MR"></a>"MR" — Memory Read</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>MR,<i>Address</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>MR,<i>Data</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>MR,<i>Data</i><CR><NL></code></li>
|
|
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Address</i>: An integer from 0 to 4095. Represents the address in RAM to read.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads one byte from RAM and prints it out. The <i>Data</i> is always printed as a three digit decimal number.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span><code>MR,422\r</code>
|
|
<p>This query would read from memory address 422 and print out its current value.</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span>
|
|
<code>MR,071<NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span>
|
|
<code>MR,071<CR><NL></code>
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="MW"></a>"MW" — Memory Write</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>MW,<i>Address</i>,<i>Data</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>MW<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Address</i>: An integer from 0 to 4095. Represents the address in RAM that <i>Data</i> will be written to.</li>
|
|
<li><i>Data</i>: An integer from 0 to 255. Represents the byte of data to write to <i>Address</i>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command writes one byte to RAM. In order for this command to be useful, you will need to know what addresses in RAM are useful to you. This would normally be available by reading the source code for the EBB firmware and looking at the .map file for a particular version build to see where certain variables are located in RAM
|
|
</p>
|
|
<p>Writing to areas in RAM that are currently in use by the firmware may result in unplanned crashes.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="ND"></a>"ND" — Node Count Decrement</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>ND<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>ND<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.5 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command decrements the 32 bit Node Counter by 1.</p>
|
|
<p>See the <code><a href="#QN">QN</a></code> command for a description of the node counter and its operations.</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v1.9.5</li>
|
|
<li><span style="font-weight: bold;">Deprecation notice:</span> <code>ND</code> is deprecated as of EBB firmware v3.0 and will be removed in a future firmware version. It is recommended to use <a href="#SL">SL</a>/<a href="#QL">QL</a> instead.</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="NI"></a>"NI" — Node Count Increment</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>NI<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>NI<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.5 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command increments the 32 bit Node Counter by 1.</p>
|
|
<p>See the <code><a href="#QN">QN</a></code> command for a description of the node counter and its operations.</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v1.9.5</li>
|
|
<li><span style="font-weight: bold;">Deprecation notice:</span> <code>NI</code> is deprecated as of EBB firmware v3.0 and will be removed in a future firmware version. It is recommended to use <a href="#SL">SL</a>/<a href="#QL">QL</a> instead.</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="O"></a>"O" — Output (digital)</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>O,<i>PortA</i>,[<i>PortB</i>,<i>PortC</i>,<i>PortD</i>,<i>PortE</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>O<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>PortA</i>: An integer from 0 to 255. Represents the new value to write to the LATA register.</li>
|
|
<li><i>PortB</i>: (optional) An integer from 0 to 255. Represents the new value to write to the LATB register.</li>
|
|
<li><i>PortC</i>: (optional) An integer from 0 to 255. Represents the new value to write to the LATC register.</li>
|
|
<li><i>PortD</i>: (optional) An integer from 0 to 255. Represents the new value to write to the LATD register.</li>
|
|
<li><i>PortE</i>: (optional) An integer from 0 to 255. Represents the new value to write to the LATE register.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command simply takes its arguments and write them to the LATx registers. This allows you to output digital values to any or all of the pins of the microcontroller. The pins must be configured as digital outputs before this command can have an effect on the actual voltage level on a pin.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">This command is deprecated in v3.0:</span>
|
|
It will continue to work up until a future firmware version, but it will be removed in that future firmware version.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="PC"></a>"PC" — Pulse Configure</h4>
|
|
|
|
<ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Command:</span> <code>PC,<i>Length0</i>,<i>Period0</i>[,<i>Length1</i>,<i>Period1[,<i>Length2</i>,<i>Period2</i>[,<i>Length3</i>,<i>Period3</i>]]]</i><CR></code>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>PC<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Length0</i>: An integer from 0 to 65535. This length represents the number of milliseconds RB0 will go high for.
|
|
</li>
|
|
<li>
|
|
<i>Period0</i>: An integer from <i>Length0</i> to 65535. Represents the number of milliseconds between rising edges on RB0.
|
|
</li>
|
|
<li>
|
|
<i>Length1</i>, <i>Length2</i>, <i>Length3</i>: (optional) Each is an integer from 0 to 65535, that represents the number of milliseconds RB<i>x</i> will go high for, where the value of <i>x</i> is 1, 2, or 3
|
|
</li>
|
|
<li>
|
|
<i>Period1</i>, <i>Period2</i>, <i>Period3</i>: (optional) Each is integer from <i>RBx_Len</i> to 65535, that represents the number of milliseconds between rising edges on RB<i>x</i>, where the value of <i>x</i> is 1, 2, or 3
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command sets up the internal parameters for the <code>PG</code> command. The parameters come in pairs, and the first number in the pair represents the number of milliseconds that a pin (one of RB0, RB1, RB2 and RB3) goes high for, and the second number represents the number of milliseconds between rising edges for that pin. The first pair, for pin RB0, is required. The other three pairs (for RB1, RB2 and RB3) are optional and any number of them (from zero to three) can be included. Pairs which are not included are simply treated as zeros and that pin is not used for output of pulses.
|
|
</p>
|
|
<p>
|
|
When the <code>PG,1</code> command is sent, any pairs from the <code>PC</code> command where both values are non-zero and the Rate is greater than the Length will create pulses on that pin.
|
|
</p>
|
|
<p>
|
|
While the pulses are going, new <code>PC</code> commands can be sent, updating the pulse durations and repetition rates.
|
|
</p>
|
|
<p>
|
|
This command is only available for pins RB0, RB1, RB2 and RB3. If you wish to leave a pin alone (i.e. not create pulses on it) just set its Length and Period values to zero.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PC,100,150\r</code> After sending a <code>PG,1</code> command, this Length and Period would causes RB0 to go high for 100 milliseconds, then low for 50 milliseconds, then high for 100 milliseconds, etc.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PC,12,123,0,0,2000,10000\r</code> After sending a <code>PG,1</code> command, these parameters would cause pin RB0 to go high for a duration of 12 milliseconds, repeating every 123 milliseconds. Pin RB1 would be untouched. Pin RB2 would go high for 2 seconds every 10 seconds. And pin RB3 would be untouched (because the last pair of Length and Period are omitted and thus treated as 0,0).
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PC,1,2,1,2,1,2,1,2\r</code> After sending a <code>S2,0,4</code> (to turn off RC servo output on pin RB1) and <code>PG,1</code> (to turn on pulse generation), these parameters would cause all four pins (RB0, RB1, RB2, and RB3) to output square waves with a 50% duty cycle and 500 Hz frequency.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Unchanged since firmware 2.6.6
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">This command is not included in v3.0:</span>
|
|
Commands PC, PG, T have been marked as "not in use" and tentatively removed in this firmware release. If your application does use one or more of these commands, please contact us and let us know. If we don't hear from at least a couple of users that these are important, we'll go ahead and remove them permanently in a future firmware version.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="PD"></a>"PD" — Pin Direction</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>PD,<i>Port</i>,<i>Pin</i>,<i>Direction</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>PD<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Port</i>: is one of the following letters: A,B,C,D,E. It specifies which port on the processor is to be used.</li>
|
|
<li><i>Pin</i>: is an integer in the range from 0 through 7. It specifies the pin to be used.</li>
|
|
<li><i>Direction</i>: is either 0 (output) or 1 (input) </li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command sets one of the processor pins to be an input or an output, depending on the <i>Direction</i> parameter.</p>
|
|
<p>
|
|
This command is a very low-level I/O command. Higher level commands (like <code><a href="#SM">SM</a></code>, <code><a href="#S2">S2</a></code>, etc.) will not change the direction of pins that they need after boot, so if this command gets used to change the pin direction, be sure to change it back before expecting the higher level commands that need the pin to work properly.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PD,C,3,0\r</code> This command would set pin PC3 (or Port C, pin 3) as a digital output.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="PG"></a>"PG" — Pulse Go</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>PG,<i>Value</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>PG<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Value</i>: is either 0 or 1. A value of 0 will stop the pulses, a value of 1 will start the pulses.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command turns on (<code>PG,1</code>) or turns off (<code>PG,0</code>) the Pulse Generation on pin RB0 (and optionally on RB1, and/or RB2 and/or RB3). It uses the parameters from the <code>PC</code> command to control the pulse width and repetition rate on each pin. See the <code><a href="#PC">PC</a></code> — Pulse Configure command for complete details.
|
|
</p>
|
|
<p>
|
|
This command does not turn off any other commands. So if you want to use the Pulse Generation on pins that already have <code><a href="#S2">S2</a></code> RC Servo outputs or other outputs on them, be sure to turn those other outputs off yourself before starting the Pulse Generation, or the two signals will get mixed together and create outputs you do not desire.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PG,1\r</code> This command would turn on pulse generation as per the parameters specified in the latest <code>PC</code> command.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PG,0\r</code> This command would turn off pulse generation on any pins (RB0, RB1, RB2 or RB3) which have non-zero Length and Period values from the latest <code>PC</code> command.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">This command is not included in v3.0:</span>
|
|
Commands PC, PG, T have been marked as "not in use" and tentatively removed in this firmware release. If your application does use one or more of these commands, please contact us and let us know. If we don't hear from at least a couple of users that these are important, we'll go ahead and remove them permanently in a future firmware version.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="PI"></a>"PI" — Pin Input</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>PI,<i>Port</i>,<i>Pin</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>PI,<i>Value</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>PI,<i>Value</i><CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Port</i>: is one of the following letters: A,B,C,D,E. It specifies which port on the processor is to be used.</li>
|
|
<li><i>Pin</i>: is an integer in the range from 0 through 7. It specifies the pin to be used.</li>
|
|
<li><i>Value</i>: is a 0 or 1. It reflects the state of the pin when read as a digital input.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads the given port and pin as a digital input. No matter what direction the pin is set to, or even if the pin is being used as an analog input, the pin can still be read as a digital input.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PI,D,2\r</code> This query would read pin RD2 (or Port D, pin 2) as a digital input and return the pin's value.
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span><code>PI,1<NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span><code>PI,1<CR><NL></code>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="PO"></a>"PO" — Pin Output</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>PO,<i>Port</i>,<i>Pin</i>,<i>Value</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>PO<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Port</i>: is one of the following letters: A,B,C,D,E. It specifies which port on the processor is to be used for the output.</li>
|
|
<li><i>Pin</i>: is an integer in the range from 0 through 7. It specifies the pin to be used for the output.</li>
|
|
<li><i>Value</i>: is either 0 or 1. It specifies the logical value to be output on the pin.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command outputs a digital value of a 0 (0V) or 1 (3.3V) on one of the pins on the processor, as specified by <i>Port</i> and <i>Pin</i>.
|
|
</p>
|
|
<p>
|
|
This command will not change a pin's direction to output first, so you must set the pin's direction to be an output using the <code>PD</code> command first if you want anything to come out of the pin.
|
|
</p>
|
|
<p>
|
|
This command is a very low-level I/O command. Many other higher level commands (like <code><a href="#SM">SM</a></code>, <code><a href="#S2">S2</a></code>, etc.) will over-write the output state of pins that they need. This commands allows you low-level access to every pin on the processor.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>PO,C,7,1\r</code> This command would set the pin RC7 (or Port C, pin 7) to a high value.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="QB"></a>"QB" — Query Button</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QB<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QB,<i>State</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>State</i><CR><NL>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.2 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This query checks whether the PRG button on the EBB has been pressed since the last QB query or not. </p>
|
|
<p>The returned value <i>State</i> is 1 if the PRG button has been pressed since the last QB query, and 0 otherwise.</p>
|
|
<p>One of the GPIO input pins, B0, can also be used to initiate a "button press" event. B0 is normally pulled high, but if it is taken low, then that registers as though the PRG button itself was pressed. To ensure that a "button press" is registered, ensure that B0 is pulled low for at least 40 microseconds. This "alt_prg" feature is enabled by default but can be disabled with the <code><a href="#SC">SC</a></code> command.</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v1.9.2</li>
|
|
<li><span style="font-weight: bold;">Deprecation notice:</span> <code>QB</code> is deprecated as of EBB firmware v3.0 and will be removed in a future firmware version. It is recommended to use <a href="#QG">QG</a> instead.</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QC"></a>"QC" — Query Current</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QC<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QC,<i>RA0_VOLTAGE</i>,<i>V+_VOLTAGE</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>RA0_VOLTAGE</i>,<i>V+_VOLTAGE</i><CR><NL>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.2.3 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads two analog voltages and returns their raw 10 bit values. You can use this to read the current setpoint for the stepper motor, and to read the input power that the board is receiving.
|
|
</p>
|
|
<p>The two returned values are:</p>
|
|
<ul>
|
|
<li>
|
|
<i>RA0_VOLTAGE</i>, the voltage on the REF_RA0 net. It is expressed as a zero-padded 4-digit 10 bit number where 0 = 0.0V and 1023 = 3.3V
|
|
<p>
|
|
This value yields the voltage level at the REF_RA0 input to the stepper driver chip. This is the control voltage that sets the maximum instantaneous (not average) current that the driver chips allow into the motor coils.
|
|
</p>
|
|
<p>
|
|
The maximum current is given approximately by <i>I_max</i> = <i>RA0_VOLTAGE</i>/1.76. Thus, a voltage of 3 V at REF_RA0 would correspond to a maximum motor current of about 1.7 A.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>V+_VOLTAGE</i> is the voltage on the V+ net, scaled by a voltage divider. It is expressed as a zero-padded 4-digit 10 bit number where 0 = 0.0V and 1023 = 3.3V
|
|
<p>
|
|
This value yields the voltage level at on the EBB's V+ power net, which is the "motor" power coming into the board, as measured after the first input protection diode.
|
|
</p>
|
|
<p>
|
|
The value of <i>V+_VOLTAGE</i> as read on the ADC pin is scaled so that it does not exceed the 3.3 V maximum analog input level for the MCU. The scaling is performed by a voltage divider (comprised of R13 and R18 on the EBB), which gives a scaling factor of (1/11) on EBB boards v2.2 and earlier, and a scaling factor of (1/9.2) on EBB boards v2.3 and newer. As there is tolerance on the resistors, these scaling factors should be considered to be only approximate.
|
|
</p>
|
|
<p>
|
|
If one also wishes to compare the to the voltage read to that at the power input, it is necessary to also account for both the forward voltage across the input diode: the "diode drop" across the input diode is about 0.3 V at the current levels typically encountered.
|
|
</p>
|
|
<p>
|
|
The value of <i>V+_VOLTAGE</i> may be very useful in determining whether or not the EBB is plugged into power. One might also compare the value of this voltage with and without the motors enabled, in order to monitor and detect if the power supply voltage should droop due to load on the motors.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QC,0394,0300<NL></code>
|
|
<p>This query has returned values of 394 for RA0_VOLTAGE and 300 for V+_VOLTAGE.</p>
|
|
<p>
|
|
The first returned value, 0394, indicates a voltage of 1.27 V at REF_RA0. This indicates that the maximum motor current is currently set to 0.72 A.
|
|
</p>
|
|
<p>
|
|
The second returned value, 0300, indicates a voltage of 0.96 V at the V+ ADC input. Scaling by 9.2 (for the voltage divider on an EBB v2.3) and adding 0.3 V (for the diode drop), this indicates that the "actual" input voltage is about 9.1 V.
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>0394,0300<CR><NL>OK<CR><NL></code>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Unchanged since firmware 2.2.3.
|
|
<p>
|
|
Note also that this query only works properly on EBB hardware v1.3 and above. (White EBBs from Evil Mad Scientist are v2.0 or newer, and EBBs from SparkFun are v2.0 and above.)
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QE"></a>"QE" — Query motor Enables and microstep resolutions</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QE<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QE,<i>Motor1_State</i>,<i>Motor2_State</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>Motor1_State</i>,<i>Motor2_State</i><CR><NL>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.8.0 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads the current state of the motor enable pins and the microstep resolution pins. It then returns two values which encode the motor enable/disable state and (if enabled) microstep resolution.
|
|
</p>
|
|
<p>
|
|
There is only one value for the microstepping resolution since both motor drivers share the same MS1, MS2 and MS3 lines on the EBB. So the two values returned by this command will either be the same (if both motors are enabled) or one or both of them will be zero. But they will never show that the two motors are both enabled and have different microstep resolutions.
|
|
</p>
|
|
<p>The two returned values are:</p>
|
|
<ul>
|
|
<li>
|
|
<i>Motor1_State</i>
|
|
<p>
|
|
<ul>
|
|
<li>0: Motor 1 is disabled</li>
|
|
<li>1: Motor 1 is enabled and is set to full step</li>
|
|
<li>2: Motor 1 is enabled and is set to 1/2 steps</li>
|
|
<li>4: Motor 1 is enabled and is set to 1/4 steps</li>
|
|
<li>8: Motor 1 is enabled and is set to 1/8 steps</li>
|
|
<li>16: Motor 1 is enabled and is set to 1/16 steps</li>
|
|
</ul>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Motor2_State</i>
|
|
<p>Same as for Motor1_State but for Motor 2.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QE,16,16<NL></code>
|
|
<p>Both motors are enabled and set to 1/16th microsteps.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>16,16<CR><NL>OK<CR><NL></code>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QE,0,4<NL></code>
|
|
<p>Motor 1 is disabled and motor 2 is enabled and set to 1/4 steps.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>0,4<CR><NL>OK<CR><NL></code>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QG"></a>"QG" — Query General</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QG<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code><i>QG,Status Byte</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>Status Byte</i><CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.6.2 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads the status of eight bits of information, and returns them as a bit field expressed as a single hexadecimal byte.
|
|
</p>
|
|
<p>The returned status byte consists of the following status bits:</p>
|
|
<p>
|
|
<table border="1" cellpadding="2" cellspacing="2" style="margin-left:10%;width:80%;">
|
|
<tbody>
|
|
<tr style="font-weight:bold;">
|
|
<td style="text-align:left">Bit</td>
|
|
<td>7</td>
|
|
<td>6</td>
|
|
<td>5</td>
|
|
<td>4</td>
|
|
<td>3</td>
|
|
<td>2</td>
|
|
<td>1</td>
|
|
<td>0</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="font-weight:bold;text-align:left">Decimal Value</td>
|
|
<td>128</td>
|
|
<td>64</td>
|
|
<td>32</td>
|
|
<td>16</td>
|
|
<td>8</td>
|
|
<td>4</td>
|
|
<td>2</td>
|
|
<td>1</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="font-weight:bold;text-align:left;">Name</td>
|
|
<td>Limit Switch Triggered</td>
|
|
<td>Power Lost Flag</td>
|
|
<td>PRG</td>
|
|
<td>PEN</td>
|
|
<td>CMD</td>
|
|
<td>MTR1</td>
|
|
<td>MTR2</td>
|
|
<td>FIFO</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 7: Limit Switch Triggered</div> This bit is 1 if the limit switch triggered. It will be a 0 if the Limit Switch Trigger has not fired or if the limit switch feature is disabled. If set, executing this query will clear the bit.
|
|
</p>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 6: Power Lost Flag</code></div> This bit is 1 if the V+ power input has gone below <code>Power_Lost_Threshold</code> since the last time the <code>QG</code> query was executed. If set, executing this query will clear the bit. See <code>CU,60</code>.
|
|
</p>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 5: PRG — PRG Button Pressed</div> This bit will be 1 if the PRG button has been pushed since the last <code>QG</code> or <code><a href="#QB">QB</a></code> query. Otherwise it will be 0. Note that input B0 can be used to trigger a "button push" event; see the description of <code><a href="#QB">QB</a></code> for more information.
|
|
</p>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 4: PEN — Pen is up</div> This bit is 1 when the pen is up, and 0 when the pen is down. The pen status is given by the position of the pen-lift servo output, which can be controlled with the <code><a href="#SP">SP</a></code> command and can be read with the <code><a href="#QP">QP</a></code> query. Note that this is the <i>commanded state</i> of the pen, and that it does physically take time to lift from or lower to the page.
|
|
</p>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 3: CMD — Command Executing</div> This bit will be 1 when a command is being executed, and 0 otherwise. The command may be a command that causes motion (like a motor move command) or any other command listed in this document as 'Execution: Added to FIFO motion queue'.
|
|
</p>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 2: MTR1 — Motor 1 moving</div> This bit is 1 when Motor 1 is in motion and 0 when it is idle.
|
|
</p>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 1: MTR2 — Motor 2 moving</div> This bit is 1 when Motor 2 is in motion and 0 when it is idle.
|
|
</p>
|
|
<p>
|
|
<div style="font-weight:bold;">Bit 0: FIFO — FIFO motion queue not empty</div> This bit will be 1 when a command is executing <i>and</i> a one or more commands are awaiting execution in the FIFO motion queue. It is 0 otherwise. The <b>CMD</b> bit will always be 1 when the <b>FIFO</b> bit is 1; if the FIFO is not empty, then a command is currently executing. Additional information about the motion queue can be found in the description of the <code><a href="#QM">QM</a></code> query.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Equivalence to <code><a href="#QM">QM</a></code> query:</span>
|
|
<p>
|
|
Bits 0, 1 2, and 3 are exactly identical to the <i>FIFOStatus</i>,<i>Motor2Status</i>,<i>Motor1Status</i> and <i>CommandStatus</i> result fields (respectively) of the <code>QM</code> query.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QG,3E<NL></code>
|
|
<p>
|
|
This query return value of <code>3E</code>, which corresponds to <code>0011 1110</code> in binary, indicates that the limit switch has not been triggered, the power has not gone below the set threshold, the PRG button has been pressed, the pen is down, a command is being executed, Motor 1 and Motor 2 are moving, and the FIFO motion queue is empty.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>3E<CR><NL></code>
|
|
<p>This query returns value of <code>3E</code>, which corresponds to <code>0011 1110</code> in binary, indicates that the limit switch has not been triggered, the power has not gone below the set threshold, the PRG button has been pressed, the pen is down, a command is being executed, Motor 1 and Motor 2 are moving, and the FIFO motion queue is empty.</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> V3.0: bit 7 now reports if the limit switch trigger has fired. Also with v3.0 bit 6 now reports the power lost flag. If you have PC code which is relying upon the old meanings of these bits (bit 7 was showing the state of the RB5 pin and bit 6 was showing the state of the RB2 pin) it will need to be updated to use v3.0. On 5/7/2024 the meaning of bit 4 was corrected. Previous versions had the state inverted.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QL"></a>"QL" — Query Variable</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QL[,<i>VariableIndex</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QL,<i>VariableValue</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>VariableValue</i><CR><NL>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.2 and newer, v3.0 has added <i>VariableIndex</i></li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>VariableIndex</i> is an integer between 0 and 31 and is optional. If not provided, a <i>VariableIndex</i> of zero will be assumed.</li>
|
|
</ul>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query allows retrieval of a temporary <i>VariableValue</i> stored in EBB RAM. Each variable value is an unsigned byte, and up to 32 of theses values can be stored in the 32 possible <i>VariableIndex</i> locations. Set the value of any of the variables with the <code><a href="#SL">SL</a></code> command. Because <i>VariableIndex</i> is optional and is assumed to be zero if not supplied, this new version of the <code>QL</code> command is backward compatible with the older version before v3.0. The <i>VariableValue</i> in the response is a decimal value from 0 to 255. All 32 values are set to 0 at reset.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>QL<CR></code></li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QL,4<NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>4<CR><NL>OK<CR><NL></code>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>QL,21<CR></code></li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QL,242<NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>242<CR><NL>OK<CR><NL></code>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v1.9.2</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> V3.0 adds the <i>VariableIndex</i> parameter.</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QM"></a>"QM" — Query Motors</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QM<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QM,<i>CommandStatus</i>,<i>Motor1Status</i>,<i>Motor2Status</i>,<i>FIFOStatus</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>QM,<i>CommandStatus</i>,<i>Motor1Status</i>,<i>Motor2Status</i>,<i>FIFOStatus</i><NL><CR></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.4.4 and above</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
Use this query to see what the EBB is currently doing. It will return the current state of the 'motion system', each motor's current state, and the state of the FIFO.
|
|
</p>
|
|
<ul>
|
|
<li><i>CommandStatus</i> is nonzero if any "motion commands" are presently executing, and zero otherwise.</li>
|
|
<li><i>Motor1Status</i> is 1 if motor 1 is currently moving, and 0 if it is idle.</li>
|
|
<li><i>Motor2Status</i> is 1 if motor 2 is currently moving, and 0 if it is idle.</li>
|
|
<li><i>FIFOStatus</i> is 1 if the FIFO is not empty, and 0 if the FIFO is empty.</li>
|
|
</ul>
|
|
<p>
|
|
The definition of a "motion command" is any command that has a time associated with it. For example, all <code><a href="#SM">SM</a></code> commands. Also, any Command (like <code><a href="#S2">S2</a></code>, <code><a href="#SP">SP</a></code>, or <code><a href="#TP">TP</a></code>) that uses a <i>delay</i> or <i>duration</i> parameter. All of these commands cause the motion processor to perform an action that takes some length of time, which then prevents later motion commands from running until they have finished.
|
|
</p>
|
|
<p>
|
|
It is important to note that with all existing EBB firmware versions, only a very limited number of "motion commands" can be executing or queued simultaneously. By default, with a FIFO size of 1 command, there can only be three motion commands in play at a time. One (the first one) will be actually executing. Another one (the second) will be stored in the FIFO buffer that sits between the USB command processor and the motion engine that executes motion commands. Then the last one (the third) will be stuck in the USB command buffer, waiting for the FIFO to be emptied before it can be processed. Once these three command spots are "filled," the whole USB Command processor will block (i.e. lock up) until there is space in the FIFO and the third motion command can be processed and put into the FIFO. This means that no USB commands can be processed by the EBB once the third motion command gets "stuck" in the USB Command processor. Using the QM query can help prevent this situation by allowing the PC to know when there are no more motion commands to be executed, and so can send the next one on.
|
|
</p>
|
|
<p>
|
|
The same process happens if the FIFO size is increased in size using the <code>CU,4,x</code> command. There can be one command that is being executed, some number of commands in the FIFO, and if the FIFO fills up, then one command 'stuck' in USB parsing until space opens up in the FIFO.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v2.4.4</li>
|
|
<li><span style="font-weight: bold;">Deprecation notice:</span> <code>QM</code> is deprecated as of EBB firmware v3.0 and will be removed in a future firmware version. It is recommended to use <a href="#QG">QG</a> instead.</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QN"></a>"QN" — Query node count</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QN<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code><i>QN,NodeCount</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>NodeCount</i><CR><NL>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.2 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span> Query the value of the Node Counter.
|
|
<p>
|
|
This command asks the EBB what the current value of the Node Counter is. The Node Counter is an unsigned 32-bit value that gets incremented or decremented with the <code>NI</code> and <code>ND</code> commands, or set to a particular value with the <code>SN</code> command. The Node Counter can be used to keep track of progress during various operations as needed.
|
|
</p>
|
|
<p>
|
|
The value of the node counter can also be manipulated with the following commands:
|
|
<ul>
|
|
<li><code>SN</code> — Set Node count</li>
|
|
<li><code>NI</code> — Node count Increment</li>
|
|
<li><code>ND</code> — Node count Decrement</li>
|
|
<li><code>CN</code> — Clear node count [obsolete]</li>
|
|
</ul>
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QN,1234567890<NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>1234567890<CR><NL></code> then <code>OK<CR><NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span>
|
|
Added in v1.9.2
|
|
</li>
|
|
<li><span style="font-weight: bold;">Deprecation notice:</span> <code>QN</code> is deprecated as of EBB firmware v3.0 and will be removed in a future firmware version. It is recommended to use <a href="#SL">SL</a>/<a href="#QL">QL</a> instead.</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QP"></a>"QP" — Query Pen</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QP<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QP,<i>PenStatus</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>PenStatus</i><NL><CR>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads the current pen state from the EBB. It will return <i>PenStatus</i> of 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.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QP,1<NL></code></li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>1<NL><CR>OK<CR><NL></code></li>
|
|
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v1.9</li>
|
|
<li><span style="font-weight: bold;">Deprecation notice:</span> <code>QP</code> is deprecated as of EBB firmware v3.0 and will be removed in a future firmware version. It is recommended to use <a href="#QG">QG</a> instead.</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QR"></a>"QR" — Query RC Servo power state</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QR<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QR,<i>RCServoPowerState</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>RCServoPowerState</i><NL><CR>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.6.0 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query reads the current RC Servo power control state from the EBB. It will return <i>RCServoPowerState</i> of 1 if the RC Servo is receiving power and 0 if it is not.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QR,1<NL></code></li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>1<NL><CR>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v2.6.0</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QS"></a>"QS" — Query Step position</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span><code>QS<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span><code>QS,<i>GlobalMotor1StepPosition</i>,<i>GlobalMotor2StepPosition</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span><code><i>GlobalMotor1StepPosition</i>,<i>GlobalMotor2StepPosition</i><NL><CR>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span>Added in v2.4.3</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query prints out the current Motor 1 and Motor 2 global step positions. Each of these positions is a 32 bit signed integer, that keeps track of the positions of each axis. The <code>CS</code> command can be used to set these positions to zero.
|
|
</p>
|
|
<p>
|
|
Every time a step is taken, the appropriate global step position is incremented or decremented depending on the direction of that step.
|
|
</p>
|
|
<p>
|
|
The global step positions can be be queried even while the motors are stepping, and it will be accurate the instant that the query is executed, but the values will change as soon as the next step is taken. It is normally good practice to wait until stepping motion is complete (you can use the <code>QM</code> query to check if the motors have stopped moving) before checking the current positions.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>QS,1421,-429<NL></code></li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>1421,-429<NL><CR>OK<CR><NL></code></li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span>
|
|
<p>Added in v2.4.3</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QT"></a>"QT" — Query EBB nickname Tag</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>QT<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>QT,<i>Name</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code><i>Name</i><CR><NL>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.5.4 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This query gets the EBB's "nickname", which is set with the <code><a href="#ST">ST</a></code> command. It simply prints out the current value of the EBB's nickname. If a nickname has not yet been set, then it will print out an empty line before sending the <code>OK</code>. The name field can be anywhere from 0 to 16 bytes in length.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (future mode):</span> If the EBB's nickname has been set to "East EBB" then the output of this command would be:
|
|
<code>QT,East EBB<NL></code>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> If the EBB's nickname has been set to "East EBB" then the output of this query would be:
|
|
<code>East EBB<CR><NL>OK<CR><NL></code>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v2.5.4</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="QU"></a>"QU" — Query Utility</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command: </span><code>QU,<i>Param_Number</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode): </span><code>QU,<i>Return_Value</i><NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default): </span><code>QU,<i>Return_Value</i><CR><NL>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions: </span>v3.0 and above</li>
|
|
<li><span style="font-weight: bold;">Execution: </span>Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Param_Number</i> : See below for acceptable values. Specifies what <i>Return_Value</i> means.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
The <code>QU</code> query returns one of several values based on <i>Param_Number</i>. It is used to retrieve miscellaneous internal values from the firmware. Rather than creating a new query for each value, <code>QU</code> is a single query to retrieve any of the following values:
|
|
</p>
|
|
<p>
|
|
<ul>
|
|
<li>
|
|
<i>Param_Number</i> = 1 : <b>Read out captured PortB pin states at last limit switch trigger</b>
|
|
<p><i>Return_Value</i> will be a two digit hexadecimal number from 00 to FF. It represents the state of all PortB pins at the exact time that the last limit switch trigger happened.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 2 : <b>Read out maximum supported FIFO length</b>
|
|
<p>
|
|
<i>Return_Value</i> will be a one to three digit decimal number from 0 to 255. It represents the maximum possible size of the motion FIFO in commands. Before using <code>CU,4,<i>New_FIFO_Size</i></code> to set the FIFO size, be sure to use this query to find out the maximum possible size for the FIFO for this version of firmware.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 3 : <b>Read out current FIFO length</b>
|
|
<p>
|
|
<i>Return_Value</i> will be a one to three digit decimal number from 0 to 255. It represents the current size of the motion FIFO in commands. On boot it starts out at 1. All firmware versions prior to v3.0 had a fixed FIFO size of 1. Starting with v3.0 the FIFO size starts out at 1 but can be increased using the <code>CU,4,<i>New_FIFO_Size</i></code> command. Increasing the FIFO size will allow for shorter commands and less chance of FIFO underrun.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 4 : <b>Read out software stack high water value</b>
|
|
<p>
|
|
Every millisecond the EBB samples the software stack pointer. It keeps track of the highest value seen. This is called the stack high water value. This query will return that stack high water value in <i>Return_Value</i> as a three digit hexadecimal number. In v3.0 of the firmware the stack starts at 0xE00 and grows up, so if <i>Return_Value</i> is E71, then the maximum stack pointer value seen indicates that 0x71 bytes of stack were used at that point. The stack overflows if it goes over 0xEBF.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 5 : <b>Read out software stack high water value and reset it to zero</b>
|
|
<p>
|
|
This query is identical to <code>QU,4</code> except that it also resets the stack high water value to zero.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 6 : <b>Read out number of commands currently waiting in the FIFO</b>
|
|
<p>
|
|
This query returns the instantaneous number of waiting commands in the FIFO as a two digit decimal number.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 60 : <b>Read out <i>Power_Lost_Threshold</i></b>
|
|
<p>
|
|
This query will print out the current value of <i>Power_Lost_Threshold</i> as a one to four digit decimal number.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 61 : <b>Read out <i>Stepper_Disable_Timeout</i></b>
|
|
<p>
|
|
This query will print out the current value of <i>Stepper_Disable_Timeout</i> as a one to five digit decimal number. Note that this is not the current countdown value, but rather the 'starting point' value that was set with the <code>CU,61</code> command.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<i>Param_Number</i> = 200 : <b>Read out current value of both axis accumulators</b>
|
|
<p>
|
|
This query will print out the current value of acc_union[0] and acc_union[1] as 32 bit unsigned decimal numbers. This is really only useful for software verification testing.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="RB"></a>"RB" — ReBoot</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>RB<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.5.4 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command causes the EBB to drop off the USB, then completely reboot as if just plugged in. Useful after a name change with the <code>ST</code> command. There is no output after the command executes.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Added in v2.5.4
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="R"></a>"R" — Reset</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>R<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>R<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command re-initializes the the internal state of the EBB to the default power on state. This includes setting all I/O pins in their power on states, stopping any ongoing timers or servo outputs, etc. It does NOT do a complete reset of the EBB - this command does not cause the EBB to drop off the USB and come back, it does not re-initialize the processor's internal register, etc. It is simply a high level EBB-application reset. If you want to completely reset the board, use the <code>RB</code> command.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>R<CR></code></li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (future mode):</span> <code>R<NL></code></li>
|
|
<li><span style="font-weight: bold;">Example Return Packet (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="S2"></a> "S2" — General RC Servo Output</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span><code>S2,<i>Position</i>,<i>Output_Pin</i>[,<i>Rate</i>[,<i>Delay</i>]]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Command:</span> <code> S2,0<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>S2<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.2.0 and later</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue (with one exception; see below)</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Position</i>, a number in the range 0 to 65535.
|
|
<p>The "on time" of the signal, in units of 1/12,000,000th of a second (about 83.3 ns).</p>
|
|
</li>
|
|
<li>
|
|
<i>Output_Pin</i>, a number in the range 0 to 24.
|
|
<p>The physical RPx pin number to use for generating the servo pulses.<br></p>
|
|
</li>
|
|
<li>
|
|
<i>Rate</i> (optional), a number in the range 0 to 65535.
|
|
<p>The rate at which to change to the new setting.</p>
|
|
</li>
|
|
<li>
|
|
<i>Delay</i> (optional), a number in the range 0 to 65535.
|
|
<p>Delay before next command, milliseconds.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command allows you to control the RC servo output system on the EBB, to configure generic RC servo outputs.
|
|
</p>
|
|
<p>
|
|
<b>Servo channels and time slices:</b> Including the pen-lift servo, there are (by default) 8 software-defined RC servo 'channels', which have no physical meaning other than we can output up to 8 separate signals at once. These channels are internally assigned as you use the S2 command to create additional servo outputs, up to a maximum of 8 (this maximum can be changed with the SC,8,X command).
|
|
</p>
|
|
<p>
|
|
Many I/O pins on the MCU have RPx numbers (please refer to the schematic), and you can output RC servo pulses on up to 8 of these RPx pins at once.
|
|
</p>
|
|
<p>
|
|
The RC servo system will cycle through each of the 8 channels. Each gets a 3 ms "slice" of time. Each channel is repeated every 24 ms.
|
|
</p>
|
|
<p>
|
|
If a given servo output is enabled, then at the beginning of its 3 ms time slot, its RPx pin is set high. Then, <i>Position</i> time later, the RPx pin is set low. This time is controlled by hardware (the ECCP2 in the CPU) so there is very little jitter in the pulse durations. <i>Position</i> is in units of 1/12,000 of a second, so 32000 for <i>Position</i> would be about 2.666 ms. A value of 0 for the <i>Position</i> parameter will disable servo output on the given RPn pin, and that internal servo channel will be deallocated. If the <i>Position</i> value is greater than the amount of time allocated for each channel (by default, 3 ms) then the smaller of the two values will be used to generate the pulse.
|
|
</p>
|
|
<p>
|
|
The number of available channels at boot is 8. This can be changed with the SC,8 command. The S2 RC servo output command cycles from channel 1 through channel <i>Maximum_S2_Channels</i> (normally 8), outputting any enabled channel's pulse from 0 ms to 3 ms. For a given channel, the repetition rate is determined by <i>Maximum_S2_Channels</i> * <i>S2_Channel_Duration_MS</i> which is normally 8 * 3 or 24 ms. Thus, each channel's output pulse will be repeated every 24 ms. However, if you change the <i>Maximum_S2_Channels</i> you will change the repetition rate of the pulses. The <i>S2_Channel_Duration_MS</i> parameter can also be adjusted with the RC,9 command.
|
|
</p>
|
|
<p>
|
|
<b>Delay:</b> The <i>Delay</i> argument gives the number of milliseconds to delay the start of the next command in the motion queue. This is an optional argument that defaults to 0, giving no added delay, thus allowing the next motion command to begin immediately after the S2 command has started.
|
|
</p>
|
|
<p>
|
|
<b>Motion Queue:</b> In all cases but one, S2 commands are added to the motion queue, even if their <i>Delay</i> parameters are 0. This means that they will always execute in their correct place in the stream of SM, TP, etc. commands. (The special command <code>S2,0,<i>Output_Pin</i><CR></code> disables the servo output for <i>Output_Pin</i> immediately and is not added to the queue.)
|
|
</p>
|
|
<p>
|
|
<b>Slew rate:</b> The <i>Rate</i> argument is used to control how quickly the output changes from the current pulse width (servo position) to the new pulse width. If <i>Rate</i> is zero, then the move is made on the next PWM cycle (i.e. the next time the pin is pulsed). If <i>Rate</i> is nonzero, then the value of <i>Rate</i> 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 <i>Rate</i> are 1/12,000th of a second per <i>Maximum_S2_Channels</i> * <i>S2_Channel_Duration_MS</i> or 1/12,000th of a second per 24 ms. The slew rate is completely independent of the <i>Delay</i>.
|
|
</p>
|
|
<p>
|
|
<b>Collisions with SP and TP:</b> The normal pen up/down servo control (SP and TP) commands internally use the S2 command to manage their actions through one of the software-defined channels. If desired, you can use the S2 command to disable this channel, for example if you need access to all four channels.
|
|
</p>
|
|
<p>
|
|
<b>Turn-on condition:</b> Note that the S2 command will always make <i>Output_Pin</i> an output before it starts outputting pulses to that pin.
|
|
</p>
|
|
<p>
|
|
<b>Disabling an S2 servo output:</b> A special command, <code>S2,0,<i>Output_Pin</i><CR></code>, will turn off the RC servo output for <i>Output_Pin</i>. This special command is executed <i>immediately</i>; unlike regular S2 commands, it is NOT added to the FIFO motion queue.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
RPx vs pin number (and label on the board) table:<br>
|
|
<table border="1" cellpadding="2" cellspacing="2" style="margin-left:10%;width:80%;">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><b>RPx</b><b><br></b></td>
|
|
<td valign="top">RP0<br></td>
|
|
<td valign="top">RP1<br></td>
|
|
<td valign="top">RP2<br></td>
|
|
<td valign="top">RP3<br></td>
|
|
<td valign="top">RP4<br></td>
|
|
<td valign="top">RP5<br></td>
|
|
<td valign="top">RP6<br></td>
|
|
<td valign="top">RP7<br></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><b>Pin</b><b><br></b></td>
|
|
<td valign="top">REF_RA0<br></td>
|
|
<td valign="top">RA1<br></td>
|
|
<td valign="top">RA5<br></td>
|
|
<td valign="top">RB0<br></td>
|
|
<td valign="top">RB1<br></td>
|
|
<td valign="top">RB2<br></td>
|
|
<td valign="top">RB3<br></td>
|
|
<td valign="top">RB4<br></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><b>Label</b><b><br></b></td>
|
|
<td valign="top"><br></td>
|
|
<td valign="top"><br></td>
|
|
<td valign="top"><br></td>
|
|
<td valign="top">B0<br></td>
|
|
<td valign="top">B1<br></td>
|
|
<td valign="top">B2<br></td>
|
|
<td valign="top">B3<br></td>
|
|
<td valign="top">B4<br></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<table border="1" cellpadding="2" cellspacing="2" style="margin-left:10%;width:80%;">
|
|
<tbody>
|
|
<tr>
|
|
<td valign="top"><b>RPx</b><b><br></b></td>
|
|
<td valign="top">RP8<br></td>
|
|
<td valign="top">RP9<br></td>
|
|
<td valign="top">RP10<br></td>
|
|
<td valign="top">RP11<br></td>
|
|
<td valign="top">RP13<br></td>
|
|
<td valign="top">RP17<br></td>
|
|
<td valign="top">RP18<br></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><b>Pin</b><b><br></b></td>
|
|
<td valign="top">RB5<br></td>
|
|
<td valign="top">RB6<br></td>
|
|
<td valign="top">RB7<br></td>
|
|
<td valign="top">RC0<br></td>
|
|
<td valign="top">RC2<br></td>
|
|
<td valign="top">RC6<br></td>
|
|
<td valign="top">RC7<br></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><b>Label</b><b><br></b></td>
|
|
<td valign="top">B5<br></td>
|
|
<td valign="top">B6<br></td>
|
|
<td valign="top">B7<br></td>
|
|
<td valign="top"><br></td>
|
|
<td valign="top"><br></td>
|
|
<td valign="top"><br></td>
|
|
<td valign="top"><br></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>S2,24000,6\r</code> Use RP6 as a RC servo output, and set its on-time to 2 ms.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>S2,0,5\r</code> Turn off the output on RP5 (which is pin RB2) so it stops sending any pulses.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>S2,10000,5,100\r</code> Send a 0.83 ms pulse out pin RB2, and force a pause of 100 ms before the next motion command can start.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>S2,27500,5,10,50\r</code> Start the pulse on RB2 moving from wherever it is at now towards 2.28 ms at a rate of 0.173 ms/S, with a 10 ms delay before the next motion command can begin.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Added in firmware v2.2.0
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Maximum RC servo channel count reduced from 24 to 8 in v3.0.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="SC"></a> "SC" — Stepper and Servo Mode Configure</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>SC,<i>Value1</i>,<i>Value2</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>SC<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Value1</i> is an integer in the range from 0 to 255, which specifies the parameter that you are adjusting.</li>
|
|
<li><i>Value2</i> is an integer in the range from 0 to 65535. It specifies the value of the parameter given by <i>Value1</i>.</li>
|
|
<li>See the list of these parameters (<i>Value1</i>) and allowed values (<i>Value2</i>), below.</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command allows you to configure the motor control modes that the EBB uses, including parameters of the servo or solenoid motor used for raising and lowering the pen, and how the stepper motor driver signals are directed.
|
|
</p>
|
|
<p>The set of parameters and their allowed values is as follows:</p>
|
|
</li>
|
|
<ul>
|
|
<li>
|
|
<code>SC,1,<i>Value2</i></code> Pen lift mechanism. <i>Value2</i> may be 0, 1 or 2. Early EggBot models used a small solenoid, driven from an output signal on pin RB4.
|
|
<ul>
|
|
<li><code>SC,1,0</code> Enable only the solenoid output (RB4) for pen up/down movement.</li>
|
|
<li><code>SC,1,1</code> Enable only the RC servo output (RB1) for pen up/down movement.</li>
|
|
<li><code>SC,1,2</code> Enable both the solenoid (RB4) and RC servo (RB1) outputs for pen up/down movement (default)</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<code>SC,2,<i>Value2</i></code> Stepper signal control. <i>Value2</i> may be 0, 1 or 2.
|
|
<ul>
|
|
<li><code>SC,2,0</code> Use microcontroller to control on-board stepper driver chips (default)</li>
|
|
<li>
|
|
<code>SC,2,1</code> Disconnect microcontroller from the on-board stepper motor drivers and drive external step/direction motor drivers instead. In this mode, you can use the microcontroller to control external step/direction drivers based on the following pin assignments:
|
|
<ul>
|
|
<li>ENABLE1: RD1</li>
|
|
<li>ENABLE2: RA1</li>
|
|
<li>STEP1: RC6</li>
|
|
<li>DIR1: RC2</li>
|
|
<li>STEP2: RA5</li>
|
|
<li>DIR2: RA2</li>
|
|
</ul>
|
|
Note also that in this mode, you can externally drive the step/direction/enable lines of the on board stepper motor drivers from the pins of J4 and J5. (Please refer to the schematic for where these pins are broken out.)
|
|
</li>
|
|
<li>
|
|
<code>SC,2,2</code> Disconnect microcontroller from both the built-in motor drivers and external pins. All step/dir/enable pins on the PIC are set to inputs. This allows you to control the on-board stepper motor driver chips externally with your own step/dir/enable signals. Use the pins listed in the schematic from J5 and J4.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<code>SC,4,<i>Servo_Min</i></code> Set the minimum value for the RC servo output position. <i>Servo_Min</i> may be in the range 1 to 65535, in units of 83.3 ns intervals. This sets the "Pen Up" position.
|
|
<br />
|
|
Default: 12000 (1.0 ms) on reset.
|
|
</li>
|
|
<li>
|
|
<code>SC,5,<i>Servo_Max</i></code> Set the maximum value for the RC servo output position. <i>Servo_Max</i> may be in the range 1 to 65535, in units of 83.3 ns intervals. This sets the "Pen Down" position.
|
|
<br />
|
|
Default: 16000 (1.33 ms) on reset.
|
|
<br />
|
|
If the <code>SP,3</code> command is sent to the EBB, this <i>Servo_Max</i> value will be set equal to the <i>Servo_Min</i> value.
|
|
</li>
|
|
<li>
|
|
<code>SC,8,<i>Maximum_S2_Channels</i></code> Sets the number of RC servo PWM channels, each of <i>S2_Channel_Duration_MS</i> before cycling back to channel 1 for S2 command. Values from 1 to 8 are valid for <i>Maximum_S2_Channels</i>.
|
|
<br />
|
|
Default: 8 on reset.
|
|
</li>
|
|
<li>
|
|
<code>SC,9,<i>S2_Channel_Duration_MS</i></code> Set the number of milliseconds before firing the next enabled channel for the S2 command. Values from 1 to 6 are valid for <i>S2_Channel_Duration_MS</i>.
|
|
<br />
|
|
Default: 3 ms on reset.
|
|
</li>
|
|
<li>
|
|
<code>SC,10,<i>Servo_Rate</i></code> Set rate of change of the servo position, for both raising and lowering movements. Same units as <i>Rate</i> parameter in <code><a href="#S2">S2</a></code> command.
|
|
</li>
|
|
<li>
|
|
<code>SC,11,<i>Servo_Rate_Up</i></code> Set the rate of change of the servo when going up. Same units as <i>Rate</i> parameter in <code><a href="#S2">S2</a></code> command.
|
|
</li>
|
|
<li>
|
|
<code>SC,12,<i>Servo_Rate_Down</i></code> Set the rate of change of the servo when going down. Same units as <i>Rate</i> parameter in <code><a href="#S2">S2</a></code> command.
|
|
</li>
|
|
<li>
|
|
<code>SC,13,<i>Use_Alt_Prg</i></code> - turns on (1) or off (0) alternate pause button function on RB0. On by default. For EBB v1.1 boards, it uses RB2 instead. See the description of <code><a href="#QB">QB</a></code> for more information.
|
|
</li>
|
|
</ul>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SC,4,8000\r</code> Set the pen-up position to give a servo output of 8000, about 0.66 ms.</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SC,1,1\r</code> Enable only the RC servo for pen lift; disable solenoid control output.</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Maximum_S2_Channels maximum value changed from 24 to 8 in version 3.0.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="SE"></a> "SE" — Set Engraver</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>SE,<i>State</i>[,<i>Power</i>[,<i>Use_Motion_Queue</i>]]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>SE<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.1.0 and newer (with changes) </li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>State</i> may be either 0 to disable or 1 to enable the engraver output.</li>
|
|
<li><i>Power</i> is an optional argument, with allowed values of integers in the range 0 to 1023.</li>
|
|
<li><i>Use_Motion_Queue</i> is an optional argument, with allowed values of 0 (immediate) or 1 (use motion queue).</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
The <i>Power</i> argument represents the power (duty cycle of the PWM signal), where 0 is always off and 1023 is always on. If this optional argument is not included, then the power will be set at 512 (50%) duty cycle.
|
|
</p>
|
|
<p>
|
|
If the <i>Use_Motion_Queue</i> parameter has the value of 1, then this SE command will be added to the motion queue just like SM and SP commands, and thus will be executed when the previous motion commands have finished. Note that if you need to use this argument, the <i>Power</i> argument is not optional. If <i>Use_Motion_Queue</i> has value 0 (or if it is omitted) the command is executed immediately, and is not added to the queue.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SE,1,1023\r</code> Turns on the engraver output with maximum power</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SE,0\r</code> Turns off the engraver output</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SE,0,0,1\r</code> Adds a command to the motion queue, that (when executed) turns off the engraver output.</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Unchanged since firmware v2.4.1</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="SL"></a> "SL" — Set Variable</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>SL,<i>VariableValue</i>[,<i>VariableIndex</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>SL<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.2 and newer, v3.0 has added <i>VariableIndex</i></li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>VariableValue</i> is an integer between 0 and 255 and is required.</li>
|
|
<li><i>VariableIndex</i> is an integer between 0 and 31 and is optional. If not provided, a <i>VariableIndex</i> of zero will be assumed.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command allows storage of temporary values in the EBB RAM. Each variable value is an unsigned byte, and up to 32 of theses values can be stored in the 32 possible <i>VariableIndex</i> locations. The values can be read out by using the <code><a href="#QL">QL[,<i>VariableIndex</i>]</a></code> query. Because <i>VariableIndex</i> is optional and is assumed to be zero if not supplied, this new version of the <code>SL</code> command is backward compatible with the older version before v3.0. The values are not retained across EBB reboots or resets; they are all cleared to 0 at reset.
|
|
</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SL,4\r</code> Sets the value of variable zero to the value of 4.</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SL,125,19\r</code> Sets the value of variable 19 to the value of 125.</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v1.9.2</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> In v3.0 the optional <i>VariableIndex</i> parameter was added.</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="SM"></a> "SM" — Stepper Move</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>SM,<i>Duration</i>,<i>AxisSteps1</i>[,<i>AxisSteps2</i>[,<i>Clear</i>]]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>SM<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All (with changes)</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Duration</i> is an unsigned 32 bit integer in the range from 0 to 4294967295, which specifies the duration of time, in units of milliseconds, that the command executes for.
|
|
</li>
|
|
<li>
|
|
<i>AxisSteps1</i> and <i>AxisSteps2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647, giving movement distance in steps.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
Use this command to make the motors draw a straight line at constant velocity, or to add a delay to the motion queue.
|
|
</p>
|
|
<p>
|
|
If both <i>AxisSteps1</i> and <i>AxisSteps2</i> are zero, then a delay of <i>Duration</i> ms is executed. <i>AxisSteps2</i> is an optional value, and if it is not included in the command, zero steps are assumed for axis 2. If <i>Clear</i> is used, then <i>AxisSteps2</i> is required.
|
|
</p>
|
|
<p>
|
|
The sign of <i>AxisSteps1</i> and <i>AxisSteps2</i> represent the direction each motor should turn.
|
|
</p>
|
|
<p>
|
|
The minimum speed at which the EBB can generate steps for each motor is 0.00001164 steps/second. The maximum speed is 25,000 steps/second. If the SM command finds that this speed range will be violated on either axis, it will use the maximum (or minimum) speed to complete the move.
|
|
</p>
|
|
<p>
|
|
While individual movement commands may be as short as a single step, there are practical limits to the rate at which commands can be issued, as discussed under <a href="#performance">Performance</a>.
|
|
</p>
|
|
<p>
|
|
If the command is used as a delay, <i>Duration</i> is capped at 100000 ms.
|
|
</p>
|
|
<p>
|
|
Note that internally the EBB generates an Interrupt Service Routine (ISR) at the 25 kHz rate. Each time the ISR fires, the EBB determines if a step needs to be taken for a given axis or not. The practical result of this is that all steps will be 'quantized' to the 25 kHz (40 μs) time intervals, and thus as the step rate gets close to 25 kHz the 'correct' time between steps will not be generated, but instead each step will land on a 40 μs tick in time. In almost all cases normally used by the EBB, this doesn't make any difference because the overall proper length for the entire move will be correct.
|
|
</p>
|
|
<p>A value of 0 for <i>Duration</i> is invalid and will be rejected.</p>
|
|
<p>If both <i>AxisStep1</i> and <i>AxisStep2</i> are zero then a <i>Duration</i> value above 100000 will be capped at 100000.</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span> <code>SM,1000,250,-766\r</code>
|
|
Move axis 1 by 250 steps and axis2 by -766 steps, in 1000 ms of duration.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Parameter values expanded to 32 bits and minimum speed lowered in v3.0.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="SN"></a>"SN" — Set node count </h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>SN,<i>Value</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>SN<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9.5 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Value</i> is an unsigned 32-bit integer.</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command sets the Node Counter to <i>Value</i>.</p>
|
|
<p>See the <code><a href="#QN">QN</a></code> command for a description of the node counter and its operations.</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Example:</span> <code>SN,123456789\r</code> Set node counter to 123456789.</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Added in v1.9.5</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="SP"></a>"SP" — Set Pen State </h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>SP,<i>Value</i>[,<i>Duration</i>[,<i>PortB_Pin</i>]]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>SP<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All (with changes)</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue for some parameter values, not added to FIFO motion queue for others</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Value</i> is either 0, 1, 2 or 3.</li>
|
|
<li><i>Duration</i> (optional) is an integer from 1 to 65535, which gives a delay in milliseconds.</li>
|
|
<li><i>PortB_Pin</i> (optional) is an integer from 0 through 7.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command instructs the pen to go up or down.</p>
|
|
<ul>
|
|
<li>When a <i>Value</i> of 0 is used, a servo move will be added to the FIFO motion queue which will move the servo to the <i>Servo_Max</i> position (as set by the <code>SC,5</code> command below, which is normally the pen-down position).</li>
|
|
<li>When a <i>Value</i> of 1 is used, a servo move will be added to the FIFO motion queue which will move the servo to the <i>Servo_Min</i> position (as set by the <code>SC,4</code> command below, which is normally the pen-up position).</li>
|
|
<li>When a <i>Value</i> of 2 is used, the servo will be immediately start a move to the <i>Servo_Min</i> position (as set by the <code>SC,4</code> command), bypassing the FIFO motion queue. The <i>Duration</i> parameter is ignored if present.</li>
|
|
<li>When a <i>Value</i> of 3 is used, the servo will be immediately start a move to the <i>Servo_Min</i> position (as set by the <code>SC,4</code> command), bypassing the FIFO motion queue. The value of <i>Servo_Max</i> will also be set equal to <i>Servo_Min</i>, and any servo commands currently in the FIFO motion queue will have their target positions set to <i>Servo_Min</i>. This not only immediately begins lifting the pen off the paper, but it also prevents any queued servo moves from lowering the pen back down onto the paper. The <i>Duration</i> parameter is ignored if present.</li>
|
|
</ul>
|
|
<p>
|
|
Note that conventionally, we have used the <i>Servo_Min</i> (<code>SC,4</code>) value as the 'Pen up position', and the <i>Servo_Max</i> (<code>SC,5</code>) value as the 'Pen down position'.
|
|
</p>
|
|
<p>
|
|
The <i>Duration</i> argument 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 is not related to how fast the pen moves, which is set with the <code><a href="#SC">SC</a></code> command. Rather, it is an intentional delay of a given <i>Duration</i>, to force the EBB not to execute the next command (often an <code><a href="#SM">SM</a></code>) for some length of time, which allows the pen move to complete and possibly some extra settling time before moving the other motors.
|
|
</p>
|
|
<p>If no <i>Duration</i> argument is specified, a value of 0 milliseconds is used internally.</p>
|
|
<p>
|
|
The optional <i>PortB_Pin</i> argument allows one to specify which portB pin of the MCU the output will use. If none is specified, pin 1 (the default) will be used.
|
|
</p>
|
|
<p>
|
|
<b>Default positions:</b> The default position for the RC servo output (RB1) on reset is the 'Pen up position' (<i>Servo_Min</i>), and at boot <i>Servo_Min</i> is set to 12000 which results in a pulse width of 1.0 ms on boot. <i>Servo_Max</i> is set to 16000 on boot, so the down position will be 1.33 ms unless changed with the "SC,5" Command.
|
|
</p>
|
|
<p>
|
|
<b>Digital outputs:</b> On older EBB hardware versions 1.1, 1.2 and 1.3, this command will make the solenoid output turn on and off. On all EBB versions it will 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.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span>
|
|
<code>SP,1<CR></code> Move pen-lift servo motor to <i>servo_min</i> position.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Added in firmware 2.2.4
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> <i>Value</i> parameter values of 2 and 3 added in version 3.0.1.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="SR"></a>"SR" — Set RC Servo power timeout value</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>SR,<i>Value</i>[,<i>State</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>SR<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span>v2.6.0 and above</li>
|
|
<li><span style="font-weight: bold;">Execution:</span>Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Value</i> is a decimal unsigned long integer (32-bit) representing the number of milliseconds to wait after the last servo move before shutting off power to the RC Servo (RB1).</li>
|
|
<li><i>State</i> is value of either 0 or 1, and is optional. It represents an immediate new state for the servo power (1 = on, 0 = off).</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command sets a new RC Servo power timeout value and optionally a new immediate power state.</p>
|
|
<p>The <i>Value</i> argument is in milliseconds.</p>
|
|
<p>If <i>Value</i> is 0, then the auto-poweroff feature is disabled and the power will not be turned off to the RC servo once applied.</p>
|
|
<p>On boot, the EBB will use a default value of 60 seconds. This means that 60 seconds after the last servo motion command, the RC servo power will be turned off.</p>
|
|
<p>On boot, the power to the RC Servo (on pin RB1) will be off.</p>
|
|
<p>Whenever any command that moves the RC Servo is received, power will also be turned on to the RC Servo connector (RB1), and the RC Servo countdown timer will be started. When the timer reaches 0, the power to the RC servo connector will be shut off.</p>
|
|
<p>Only EBB boards v2.5 and above have the necessary power switch hardware. On other versions of the EBB hardware, the power to the servo is always on.</p>
|
|
<p>Pin RA3 of the MCU is used to control the RC Servo power. So from software version 2.6.0 and above, this pin is now dedicated to RC Servo power control and can't be easily used for other things.</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span>
|
|
<code>SR,60000,1<CR></code> Set new RC servo power timeout value to 1 minute and turn power to the servo on.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Unchanged since firmware v2.6.5
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="ST"></a>"ST" — Set EBB nickname Tag</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>ST,<i>NewNameString</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>ST<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.5.5 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>NewNameString</i>: A string of ASCII characters from 0 to 16 characters in length.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>This command sets the EBB's "nickname". This is an arbitrary, user settable string, which is stored in flash memory across reboots.</p>
|
|
<p>
|
|
After setting the EBBs nickname and rebooting, the EBB's USB Device Name will have the nickname appended at the end, after a comma. So if no name is set the Device Name will be "EiBotBoard,". But if the nickname is set to "East EBB", then the Device Name will be "EiBotBoard,East EBB". (The exact device name that appears to your computer is platform dependent.) The nickname will also appear as the USB device's "serial number." Note that the change may not be recognized by your computer until after you reboot the EBB. See the <code><a href="#RB">RB</a></code> command.
|
|
</p>
|
|
<p>
|
|
The nickname string can be any combination of ASCII characters, including an empty string which will clear the EBB's nickname. For best compatibility, use a nickname that is 3-16 characters in length, without apostrophes or quotation marks (single or double quotes) within the name.
|
|
</p>
|
|
<p>
|
|
Since calling this command requires a change to a particular flash memory cell-- which can only be changed a finite number of times -- it is best practice to avoid any use that involves automated, repeated changes to the nickname tag.
|
|
</p>
|
|
<p>Use the <code><a href="#QT">QT</a></code> command to retrieve the nickname at any time.</p>
|
|
</li>
|
|
<li><span style="font-weight: bold;">Version History:</span> Unchanged since firmware v2.5.5</li>
|
|
</ul>
|
|
|
|
<hr class="short"/>
|
|
<h4><a name="T"></a>"T" — Timed Analog/Digital Query</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>T,<i>Duration</i>,<i>Mode</i><CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>T<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Duration</i> is from 1 to 65535 and represents the delay, in milliseconds, between reads for a given mode.</li>
|
|
<li><i>Mode</i> is 0 for digital or 1 for analog.</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This query turns on (or off) the timed digital (I packet) or analog (A packet) queries of pins. Using the T query you can set up a repeated query of input pins, and the generation of an I or A packet back to the PC. Each of the two modes (analog/digital) is independent of the other and can have a different duration time.
|
|
</p>
|
|
<p>
|
|
For example, to turn the digital queries of all pins on, with a time of 250 ms between queries, use <code>T,250,0</code>. Then, every 250 ms, the EBB will query all of the pins, and send an I response packet to the PC. This I response packet is exactly the same as the response to an <code>I</code> query, and simply contains the binary values of each pin of each port. To turn on the analog queries of any enabled analog inputs every 400 ms, use <code>T,400,1</code>. This will cause the EBB to query all enabled analog inputs every 400 ms and send back an A packet (exactly the same as the reply to the <code>A</code> query) repeatedly. Note that while digital mode will query every pin, analog mode will only query (and report) the pins that are current configured as analog inputs. Pins do not have to be set to be digital inputs to be queried - no matter what the pin is set to, the <code>I</code> response packet will query the pin's digital state.
|
|
</p>
|
|
<p>
|
|
To turn off a mode, use 0 for the duration parameter. Thus <code>T,0,0</code> will turn off digital mode, and <code>T,0,1</code> will turn off analog mode.
|
|
</p>
|
|
<p>
|
|
The EBB is actually sampling the digital input pins at an extremely precise time interval of whatever you sent in the T query. The values of the pins are stored in a buffer, and then packet responses are generated whenever there is 'free time' on the USB back to the PC. So you can count the I packet responses between rising or falling edges of pin values and know the time between those events to the precision of the value of <i>Duration</i>. This is true for digital mode. For analog mode the inputs are sampled every 1 ms. Each time the <code>A</code> timer times out, the latest set of analog values is used to create a new <code>A</code> packet and that is then sent out.
|
|
</p>
|
|
<p>
|
|
Just because the EBB can kick out <code>I</code> and <code>A</code> packets every 1 ms (at its fastest) doesn't mean that your PC app can read them in that fast. Some terminal emulators are not able to keep up with this data rate coming back from the EBB, and what happens is that the EBB's internal buffers overflow. This will generate error messages being sent back from the EBB. If you write your own custom application to receive data from the EBB, make sure to not read in one byte at a time from the serial port - always ask for large amounts (10K or more) and then internally parse the contents of the data coming in. (Realizing that the last packet may not be complete.)
|
|
</p>
|
|
<p>
|
|
If an attempt is made to have all 13 channels of analog be reported any faster than every 4 ms, then an internal EBB buffer overflow occurs. Be careful with the speed you choose for A packets. The maximum speed is based upon how many analog channels are being sent back.
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span><code>T,250,0<CR></code>
|
|
Turn on digital reading of pins and generation of <code>I</code> packet every 250 ms.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Note:</span>
|
|
If the <code>I</code> or <code>A</code> packet responses stop coming back after you've done a <code>T</code> query, and you didn't stop them yourself (with a <code>T,0,0</code> or <code>T,0,1</code>) then what's happened is that the internal buffer in the EBB for <code>I</code> or <code>A</code> packet data has been filled up. (There is room for 3 <code>I</code> packets and 3 <code>A</code> packets.) This means that the USB system is too busy to get the packet responses back to the PC fast enough. You need to have less USB traffic (from other devices) or increase the time between packet responses.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">This command is not included in v3.0:</span>
|
|
Commands PC, PG, T have been marked as "not in use" and tentatively removed in this firmware release. If your application does use one or more of these commands, please contact us and let us know. If we don't hear from at least a couple of users that these are important, we'll go ahead and remove them permanently in a future firmware version.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="T3"></a>"T3" — Low-level Move With Jerk, Time-limited</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>T3,<i>Intervals</i>,<i>Rate1</i>,<i>Accel1</i>,<i>Jerk1</i>,<i>Rate2</i>,<i>Accel2</i>,<i>Jerk2</i>[,<i>Clear</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>T3<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> 3.0 and above</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Intervals</i> is an unsigned 32 bit integer in the range from 0 to 4294967295, which specifies the duration of time, in units of 40 μs intervals, that the command executes for.
|
|
</li>
|
|
<li>
|
|
<i>Rate1</i> and <i>Rate2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. They represent step rates for axis 1 and 2, and are added to each axis step accumulator every 40 μs to determine when steps are taken. The sign of each <i>Rate</i> parameter determines the initial motor direction.
|
|
</li>
|
|
<li>
|
|
<i>Accel1</i> and <i>Accel2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Rate</i> values every 40 μs and control acceleration or deceleration during a move.
|
|
</li>
|
|
<li>
|
|
<i>Jerk1</i> and <i>Jerk2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Accel</i> values every 40 μs and control jerk during a move.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command is extremely similar to the <code><a href="#LT">LT</a></code> command. In fact, if both <i>Jerk1</i> and <i>Jerk2</i> are zero, this command is exactly <code><a href="#LT">LT</a></code> command. The difference is in the addition of the two jerk parameters. When there are non-zero values for the jerk parameters, an additional step before step 1 (see the 'Methods and consequences' section in the <code><a href="#LM">LM</a></code> command description) adds the jerk term to the accel term.
|
|
</p>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 1:</span>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 2:</span>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="TD"></a>"TD" — Paired "Dual T3" Low-level Move With Jerk, Time-limited</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>TD,<i>Intervals</i>,<i>Rate1A</i>,<i>Rate1B</i>,<i>Accel1</i>,<i>Jerk1</i>,<i>Rate2A</i>,<i>Rate2B</i>,<i>Accel2</i>,<i>Jerk2</i>[,<i>Clear</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>TD<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> 3.0.1 and above</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Intervals</i> is an unsigned 32 bit integer in the range from 0 to 4294967295, which specifies the duration of time, in units of 40 μs intervals, that the command executes for.
|
|
</li>
|
|
<li>
|
|
<i>Rate1A</i>, <i>Rate1B</i>, <i>Rate2A</i> and <i>Rate2B</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. They represent step rates for axis 1 and 2, and are added to each axis step accumulator every 40 μs to determine when steps are taken. The sign of each <i>Rate</i> parameter determines the initial motor direction. See below for an explanation of where each set of rates is used.
|
|
</li>
|
|
<li>
|
|
<i>Accel1</i> and <i>Accel2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Rate</i> values every 40 μs and control acceleration or deceleration during a move.
|
|
</li>
|
|
<li>
|
|
<i>Jerk1</i> and <i>Jerk2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647. These values are added to their respective <i>Accel</i> values every 40 μs and control jerk during a move.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command is for creating specially-crafted back-to-back time-limited moves with jerk. Internally, the <code>TD</code> command takes its parameter values and creates
|
|
two <code>T3</code> commands that are loaded into the FIFO. It is a faster way to create "S-curves" accelerations than sending two <code>T3</code> commands separately.
|
|
</p>
|
|
<p>The <code>TD</code> command loads the two <code>T3</code> commands as follows:
|
|
<ol>
|
|
<li>
|
|
<code>T3,Intervals,Rate1A,0,Jerk1,Rate2A,0,Jerk2[,Clear]<CR></code>
|
|
</li>
|
|
<li>
|
|
<code>T3,Intervals,Rate1B,Accel1,-Jerk1,Rate2B,Accel2,-Jerk2[,Clear]<CR></code>
|
|
</li>
|
|
</ol>
|
|
</p>
|
|
|
|
<li>
|
|
<span style="font-weight: bold;">Example 1:</span>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example 2:</span>
|
|
<p>
|
|
[[ coming soon ]]
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="TP"></a> "TP" — Toggle Pen </h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>TP[,<i>Duration</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>TP<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v1.9 and newer </li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li><i>Duration</i>: (Optional) an integer in the range of 1 to 65535, giving an delay in milliseconds.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command toggles the state of the pen (up->down and down->up). EBB firmware resets with pen in 'up' (<i>Servo_Min</i>) state.
|
|
</p>
|
|
<p>
|
|
Note that conventionally, we have used the <i>Servo_Min</i> (<code>SC,4</code>) value as the 'Pen up position', and the <i>Servo_Max</i> (<code>SC,5</code>) value as the 'Pen down position'.
|
|
</p>
|
|
<p>
|
|
The optional <i>Duration</i> argument 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 is not related to how fast the pen moves, which is set with the <code><a href="#SC">SC</a></code> command. Rather, it is an intentional delay of a given <i>Duration</i>, to force the EBB not to execute the next command (often an <code><a href="#SM">SM</a></code>) for some length of time, which allows the pen move to complete and possibly some extra settling time before moving the other motors.
|
|
</p>
|
|
<p>
|
|
If no <i>Duration</i> argument is specified, a value of 0 milliseconds is used internally.
|
|
</p>
|
|
<p>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Unchanged since firmware v2.2.1
|
|
</li>
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="TR"></a> "TR" — Test Rate</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>TR,<i>StepRate</i>,<i>AxisSteps1</i>[,<i>AxisSteps2</i>[,<i>Clear</i>]]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>TR<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><TR></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> Added in v3.0</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li><span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>StepRate</i> is an unsigned 32 bit integer in the range from 0 to 4294967295, which specifies step rate in steps/second for the move.
|
|
</li>
|
|
<li>
|
|
<i>AxisSteps1</i> and <i>AxisSteps2</i> are signed 32 bit integers in the range from -2147483648 to 2147483647, giving movement distance in steps.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command is used to test some of the refactored math in version 3.0.
|
|
</p>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Added in v3.0.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="V"></a> "V" — Version query</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>V<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>V,EBBv13_and_above EB Firmware Version 2.4.2<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>EBBv13_and_above EB Firmware Version 2.4.2<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> All</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Immediate </li>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command prints out the version string of the firmware currently running on the EBB. The actual version string returned may be different from the example above.
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr class="short" />
|
|
<h4><a name="XM"></a> "XM" — Stepper Move, for Mixed-axis Geometries</h4>
|
|
|
|
<ul>
|
|
<li><span style="font-weight: bold;">Command:</span> <code>XM,<i>Duration</i>,<i>AxisStepsA</i>,<i>AxisStepsB</i>[,<i>Clear</i>]<CR></code></li>
|
|
<li><span style="font-weight: bold;">Response (future mode):</span> <code>XM<NL></code></li>
|
|
<li><span style="font-weight: bold;">Response (legacy mode; default):</span> <code>OK<CR><NL></code></li>
|
|
<li><span style="font-weight: bold;">Firmware versions:</span> v2.3.0 and newer</li>
|
|
<li><span style="font-weight: bold;">Execution:</span> Added to FIFO motion queue</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Arguments:</span>
|
|
<ul>
|
|
<li>
|
|
<i>Duration</i> is an integer in the range from 1 to 2147483647, giving time in milliseconds.
|
|
</li>
|
|
<li>
|
|
<i>AxisStepsA</i> and <i>AxisStepsB</i> are integers, each in the range from -2147483648 to 2147483647, giving movement distances in steps.
|
|
</li>
|
|
<li>
|
|
<i>Clear</i> is an optional integer in the range 0 - 3. If it is 0 then neither accumulator are cleared at the start of the command. If it is 1 then the step accumulator for motor1 is zeroed at the start of the command. If it is 2, then the step accumulator for motor2 is zeroed at the start of the command. If it is 3, then both accumulators are cleared.
|
|
</li>
|
|
</ul>
|
|
<li>
|
|
<span style="font-weight: bold;">Description:</span>
|
|
<p>
|
|
This command takes the <i>AxisStepsA</i> and <i>AxisStepsB</i> values, and creates a call to the <code><a href="#SM">SM</a></code> command with the SM command's <i>AxisSteps1</i> value as <i>AxisStepsA</i> + <i>AxisStepsB</i>, and <i>AxisSteps2</i> as <i>AxisStepsA</i> - <i>AxisStepsB</i>. Because of these additions and subtractions, be certain that the values provided for <i>AxisStepsA</i> and <i>AxisStepsB</i> do not cause an overflow or underflow of a 32 bit signed value when the addition and subtraction happen.
|
|
</p>
|
|
<p>
|
|
This command is designed to allow cleaner operation of machines with mixed-axis geometry, including CoreXY, H-Bot gantry machines, and current AxiDraw models.
|
|
</p>
|
|
<p>
|
|
If both <i>AxisStepsA</i> and <i>AxisStepsB</i> are zero, then a delay of <i>duration</i> ms is executed.
|
|
</p>
|
|
<p>
|
|
The minimum speed at which the EBB can generate steps for each motor is 0.00001164 steps/second. The maximum speed is 25,000 steps/second. If the XM command finds that this speed range will be violated on either axis, it will output an error message declaring such and it will not complete the move. Note that the range is checked on Axis 1 and Axis 2, NOT on Axis A and Axis B. (That is, the range is checked after performing the sum and difference.) While individual movement commands may be as short as a single step, there are practical limits to the rate at which commands can be issued, as discussed under <a href="#performance">Performance</a>.
|
|
</p>
|
|
<p>
|
|
Note that internally the EBB generates an ISR at the 25 kHz rate. Each time the ISR fires, the EBB determines if a step needs to be taken for a given axis or not. The practical result of this is that all steps will be 'quantized' to the 25 kHz (40 μs) time intervals, and thus as the step rate gets close to 25 kHz the 'correct' time between steps will not be generated, but instead each step will land on a 40 μs tick in time. In almost all cases normally used by the EBB, this doesn't make any difference because the overall proper length for the entire move will be correct.
|
|
</p>
|
|
<p>A value of 0 for <i>Duration</i> is invalid and will be rejected.</p>
|
|
<p>If both <i>AxisStepsA</i> and <i>AxisStepsB</i> are zero then a <i>Duration</i> value above 100000 will be capped at 100000.</p>
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Example:</span>
|
|
<code>XM,1000,550,-1234\r</code> Move 550 steps in the A direction and -1234 steps in the B direction, in duration 1000 ms.
|
|
</li>
|
|
<li>
|
|
<span style="font-weight: bold;">Version History:</span> Added in v2.3.0
|
|
<span style="font-weight: bold;">Version History:</span> Increased range of parameters and lowered slowest allowed step rate in v3.0.
|
|
</li>
|
|
</ul>
|
|
|
|
<hr>
|
|
|
|
<h2><a name="states"></a>Initial I/O pin configuration</h2>
|
|
|
|
<p>In addition to the stepper motor outputs, many applications make use of one or more digital I/O pins.
|
|
</p>
|
|
|
|
<p>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.
|
|
</p>
|
|
|
|
<p>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 <code><a href="#SR">SR</a></code> command.
|
|
</p>
|
|
|
|
<p>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.
|
|
</p>
|
|
|
|
<p>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
|
|
<code><a href="#PI">PI</a></code> 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 <code><a href="#PD">PD</a></code> command.
|
|
</p>
|
|
|
|
<p>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.
|
|
</p>
|
|
|
|
<p>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 <code><a href="#S2">S2</a></code>.
|
|
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.
|
|
</p>
|
|
|
|
<p>Certain PortB signal pins are specially configured at boot time for typical applications, as summarized in the table below.
|
|
</p>
|
|
|
|
<p />
|
|
|
|
<table border="1" cellpadding="2" cellspacing="2"
|
|
style="margin-left:3%;width:94%;">
|
|
|
|
<tbody>
|
|
<tr style="font-weight:bold;">
|
|
<td>Pin</td>
|
|
<td>Default Direction</td>
|
|
<td>Default State</td>
|
|
<td>5V Tolerant</td>
|
|
<td>Typical application</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB0</td>
|
|
<td>Input</td>
|
|
<td>Weak pull up</td>
|
|
<td>No</td>
|
|
<td>Alternate PRG/Pause button input; see <code><a href="#QB">QB</a></code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB1</td>
|
|
<td>Output</td>
|
|
<td>RC Servo Pulses</td>
|
|
<td>No</td>
|
|
<td>Pen lift servo output; see <code><a href="#SC">SC</a></code>, <code><a href="#SP">SP</a></code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB2</td>
|
|
<td>Input</td>
|
|
<td>Weak pull up</td>
|
|
<td>No</td>
|
|
<td>General</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB3</td>
|
|
<td>Output</td>
|
|
<td>Low</td>
|
|
<td>No</td>
|
|
<td>Engraver or laser PWM output control</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB4</td>
|
|
<td>Output</td>
|
|
<td>Low</td>
|
|
<td>Yes</td>
|
|
<td>Alternate Pen Up/Down I/O (solenoid/laser)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB5</td>
|
|
<td>Input</td>
|
|
<td>Weak pull up</td>
|
|
<td>Yes</td>
|
|
<td>General</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB6</td>
|
|
<td>Input</td>
|
|
<td>Weak pull up</td>
|
|
<td>Yes</td>
|
|
<td>General</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RB7</td>
|
|
<td>Input</td>
|
|
<td>Weak pull up</td>
|
|
<td>Yes</td>
|
|
<td>General</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p />
|
|
<br />
|
|
<p />
|
|
|
|
<h2><a name="performance"></a>Performance</h2>
|
|
|
|
<p>The EBB has some basic performance limits, which do vary with new firmware releases.
|
|
</p>
|
|
|
|
<p>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.
|
|
</p>
|
|
<p style="padding-left:5%">
|
|
Output step pulse duration for external stepper drivers:
|
|
<ul style="padding-left:10%">
|
|
<li>EBB firmware 2.7.0 and above: 1.6 - 2.3 μs.</li>
|
|
<li>EBB firmware 2.6.5 and below: 2.8 - 3.0 μs.</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
The following table shows the minimum move duration, in milliseconds, which the EBB can sustain indefinitely without gaps, using different move commands. All times were measured with step rates of approximately 25 kHz on both motors — a worst case condition rarely achieved in typical applications.
|
|
</p>
|
|
|
|
<p />
|
|
|
|
<table border="1" cellpadding="2" cellspacing="2"
|
|
style="margin-left:10%;width:80%;">
|
|
<tbody>
|
|
<tr style="font-weight:bold;">
|
|
<td>Command</td>
|
|
<td>Firmware >= 3.0.0</td>
|
|
<td>Firmware >= 2.7.0 and < 3.0.0</td>
|
|
<td>Firmware < 2.7.0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>SM</td>
|
|
<td>2 ms</td>
|
|
<td>3-4 ms</td>
|
|
<td>4-7 ms</td>
|
|
</tr>
|
|
<tr>
|
|
<td>LM</td>
|
|
<td>4 ms</td>
|
|
<td>3-4 ms</td>
|
|
<td>4-6 ms</td>
|
|
</tr>
|
|
<tr>
|
|
<td>L3 </td>
|
|
<td>4 ms</td>
|
|
<td>---</td>
|
|
<td>---</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p />
|
|
<br />
|
|
<p />
|
|
|
|
<h2><a name="faq"></a>Frequently Asked Questions</h2>
|
|
|
|
<p>
|
|
<b>Q1)</b> 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 <code>SP,1</code> and <code>SP,0</code> commands.
|
|
</p>
|
|
<p>
|
|
<b>A1)</b> 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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
Now, when you're using the <code>SP,0</code> and <code>SP,1</code> commands, the <i>Servo_Min</i> (defaults to 16000, or 1.33 ms) and <i>Servo_Max</i> (defaults to 20000, or 1.6 ms) get used as the positions. And the <i>Servo_Rate_Up</i> and <i>Servo_Rate_Down</i> get used as the rates. So the formula is as follows:
|
|
</p>
|
|
<p>
|
|
((<i>Servo_Max</i> - <i>Servo_Min</i>) * .024)/<i>Servo_Rate</i> = total time to move
|
|
</p>
|
|
<p>
|
|
For the example above. ((15000 - 10000) * .024)/100 = 1.2 seconds.
|
|
</p>
|
|
|
|
<p>
|
|
<b>Q2)</b> What do the LED patterns mean?
|
|
</p>
|
|
<p>
|
|
<b>A2)</b> 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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
<b>Bootloader</b> 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:
|
|
<table border="1" cellpadding="2" cellspacing="2"
|
|
style="margin-left:10%;width:80%;">
|
|
<tbody>
|
|
<tr style="font-weight:bold;">
|
|
<td>Pattern</td>
|
|
<td>Description</td>
|
|
<td>USR/Red</td>
|
|
<td>USB/Green</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Idle</td>
|
|
<td>Waiting for USB connection with host</td>
|
|
<td>Off</td>
|
|
<td>On</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Alternating</td>
|
|
<td>USB connection established to host</td>
|
|
<td>200 ms on, 200 ms off, alternating with Green</td>
|
|
<td>200 ms on, 200 ms off, alternating with Red</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</p>
|
|
<p>
|
|
<b>Main EBB Firmware</b> 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:
|
|
<table border="1" cellpadding="2" cellspacing="2"
|
|
style="margin-left:10%;width:80%;">
|
|
<tbody>
|
|
<tr style="font-weight:bold;">
|
|
<td>Pattern</td>
|
|
<td>Description</td>
|
|
<td>USR/Red</td>
|
|
<td>USB/Green</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Fast Blink</td>
|
|
<td>No connection to USB host</td>
|
|
<td>Off</td>
|
|
<td>60 ms on, 60 ms off</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Slow Blink</td>
|
|
<td>Connected to USB host but not enumerated</td>
|
|
<td>Off</td>
|
|
<td>750 ms on, 750 ms off</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Short Long Blink</td>
|
|
<td>Fully enumerated and communicating with USB host</td>
|
|
<td>Off</td>
|
|
<td>365 ms on, 365 ms off, 1.25s on, 365 ms off</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<hr />
|
|
|
|
<p />
|
|
|
|
<div style="text-align: center;">
|
|
<a rel="license" href="http://creativecommons.org/licenses/by/3.0/us/"><img alt="Creative Commons License" src="images/88x31.png" style="border: 0px solid ; width: 88px; height: 31px;"></a><p />
|
|
</div>
|
|
<span xmlns:dc="http://purl.org/dc/elements/1.1/" property="dc:title">EiBotBoard</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.schmalzhaus.com/EBB" property="cc:attributionName" rel="cc:attributionURL">Brian Schmalz</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/us/">Creative Commons Attribution 3.0 United States License</a>. Based on a work at <a xmlns:dc="http://purl.org/dc/elements/1.1/" href="http:///www.schmalzhaus.com/EBB" rel="dc:source">www.schmalzhaus.com/EBB</a>. Permissions beyond the scope of this license may be available at <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.schmalzhaus.com/EBB" rel="cc:morePermissions">www.schmalzhaus.com/EBB</a>.
|
|
|
|
<p />
|
|
<hr>
|
|
<p />
|
|
<p>Extended EggBot documentation available at: <a href="http://wiki.evilmadscientist.com/eggbot">http://wiki.evilmadscientist.com/eggbot</a></p>
|
|
</section>
|
|
</div>
|
|
<footer>
|
|
<p>Project maintained by <a href="https://github.com/evil-mad">Evil Mad Scientist Laboratories</a></p>
|
|
<p>Hosted on GitHub Pages — Theme by <a href="https://github.com/orderedlist">orderedlist</a></p>
|
|
</footer>
|
|
<!--[if !IE]><script>fixScale(document);</script><![endif]-->
|
|
</body>
|
|
</html>
|