Thank you fellow maker for purchasing the Buildbotics CNC Controller. By doing so, you are supporting our company vision of providing a world-class Open-Source tool chain for CNC machining. This controller sits squarely at the center of that vision. We think you have made an excellent choice, and are confident that you will agree.
We are working closely with the Open-Source community to continually improve the controller and the Open-Source tools that make up the CNC tool chain. You are formally invited to join the Open-Source community and contribute in any way you choose.
Based on Buildbotics Controller Code Version
February 18th, 2018
This is the first official version of the manual.
March 20th, 2018
* Updated for changes in Control web page to reflect 0.3.20.
* Reversed recommended wiring for Huanyuan RS-485 spindle.
March 31st, 2018
* Added description of wireless connections in the Connections- > Network section.
* Updated the ADMIN page to reflect the new ADMIN- > General and ADMIN- > Network pages, to include a description of the new wifi configuration capability.
Copyright © 2017-2018 by Buildbotics LLC
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "Appendix IV - GNU Free Documentation License".
The name “Buildbotics” and the Buildbotics logo (shown below) are registered trademarks owned by Buildbotics LLC.
Examples of Buildbotics logo images
Neither the Buildbotics name nor the Buildbotics logo may be applied to products or used in sales literature without express written consent from Buildbotics LLC. The Buildbotics name and logo may be used in product reviews and other publications referring to Buildbotics LLC or the Buildbotics CNC Controller.
The information contained in this user ’s manual is for general information purposes only. Buildbotics LLC assumes no responsibility for errors or omissions in the contents of this manual.
In no event shall Buildbotics LLC be liable for any special, direct, indirect, consequential, or incidental damages or any damages whatsoever, whether in an action of contract, negligence or other tort, arising out of or in connection with the use of the Buildbotics CNC Controller or with the contents of this user ’s manual.
Buildbotics LLC reserves the right to make additions, deletions, or modification to the contents of this manual at any time without prior notice.
Quick Start Guide
Following this quick start guide should get you up and running. Refer to the remainder of the manual for more complete and concise descriptions.
Things you need
Buildbotics CNC Controller
Buildbotics premade motor cables
4 wire connectors for each motor. (16-22 AWG wire nuts work fine). You may want to solder final connections.
DC power supply that supplies between 12 and 36 Volts and a Buildbotics premade power supply cable.
Alternatively use a power adapter with a matching plug. The Meanwell GST280A24-C6P is an excellent choice.
Logitech F310 gamepad (if you plan to do local jogging)
Ethernet local area network
A Computer on the same local network with a web browser installed.
Manual or datasheet for your stepper motors.
Refer to the motor manual or datasheet to identify the A+, A- , B+, and B- coil wires. Attach the motors to the Buildbotics premade cables using the following table.
Premade cable wire color
Attach network cable
Plug the Ethernet network cable into the RJ-45, ” ENet ” connector on the back of the controller. Plug the other end into a jack on the local area network.
Connect gamepad (optional)
Plug the Logitech F310 USB gamepad into a “ USB ” port on the back of the controller.
Connect power supply
Attach the red wires on the premade power cable to the V+ connections on the power supply and the black wires to V-. Plug the premade power cable into the power connector, “ 12-36VDC ”, on the back of the controller. Alternatively, if you have a power adapter with a compatible connector (e.g. Meanwell GST280A-C6P), just plug it directly into the power connector.
Turn on the “Enable” switch
Plug in the power supply and turn on the “Enable” switch. The controller LCD screen will illuminate. When “Ready” appears in the upper left corner, it is ready to operate.
Jog motors (if gamepad attached)
Use the joysticks on the gamepad to move the motors.
Connect via web browser
Open a browser on a computer that is connected to the same local network as the controller. Then, enter “bbctrl.local” in the address bar.
Access the configuration screen by selecting the motor label in the left panel of the web page. Motor 0 is associated with the port labeled “ X ” on the back of the controller. Motor 1 is labeled “ Y ”, motor 2 is labeled “ Z ”, and motor 3 is labeled “ A ”.
Do the following things at the configuration screen for each motor port:
- Assign the axis to the motor
- Set the “drive-current” to the full load current found in the motor manual.
- Set the “idle-current” to approximately 20% of that value.
- Set the “step-angle” to the value found in the motor manual.
The remaining values can be set and adjusted based on experimentation with your final machine.
Run test program
Select “Control” from the left panel on the web page to open the Control screen. Then use the “Auto” tab to load new G-Code programs, select existing G-Code programs, delete existing G-Code programs, and inspect G-Code programs. The G-Code program that is loaded into the Auto tab G-Code Program window will be executed when the “Play” button is clicked.
Buildbotics is committed to providing a CNC tool chain that is easy to use, affordable, and completely Open-Source. Key to this commitment is the Buildbotics CNC Controller.
The Buildbotics 4-Axis CNC Controller hardware and software are completely Open-Source. All basic features needed for machine homing and loading and executing G-Code files are included.
An important distinguishing feature of the Buildbotics 4-Axis CNC Controller is that it does not require a dedicated computer to run. Rather, it is a stand-alone device that acts as a web server. Users can configure and control it from a web browser that connects through an Ethernet port.
Another unique feature is the use of very inexpensive Logitech F310 gamepads for local control. Just plug it into one of the USB ports and start jogging the machine on any axis.
Plug a webcam into a USB port and the Buildbotics Controller becomes a video server. You can now keep an eye on cutting operations while you watch the game in another room.
Limit switches, Z-axis probing, PWM spindle control, RS485 spindle control, and e-stop interfaces are all made available through a DB25 connector on the back. A DB25 breakout board provides easy access to these pins.
Two load switches, each capable of supplying up to 10 amps are provided as well. These can be used for powering heater beds, extruders, and whatever else you can think of.
Pre-made cables are provided for connecting to the motors, power supply, and load switches. These cables really save time when connecting up a new machine. To make life even easier, the power connector is compatible with some standard power adapters.
Heat dissipation was carefully considered throughout the design. As a result, the controller electronics are inside a sleek enclosure with no fan. Cuttings won't get sucked into the controller even when operating right next to the CNC machine. Exposed electronics are a thing of the past.
The combination of CAMotics and Buildbotics provides the elusive Open-Source tool chain. This tool chain works great. There ’s still a lot of work to do. Please consider joining our growing list of Open-Source contributors.
Performance is critical for CNC Controllers. The Buildbotics CNC Controller is a powerhouse working on 12-36 Volts DC, supplying up to 6 amps on each motor, and generating over 200,000 steps per second on each axis. S-curve acceleration and deceleration eliminate machine movements caused by sudden starts and stops. These capabilities provide smooth and fast operation on nearly any machine running NEMA 17 or 23 stepper motors and many machines running NEMA 34 stepper motors.
Machine tools are inherently dangerous. Users must be trained on all hazards associated with the machine before use. Examples of hazards commonly associated with machine tools include:
- Electrical energy
- High noise
- Dust (often toxic)
- Toxic gases
- Flying material and parts
- Pinch points
- Sharp edges
- Rotating machinery
- Rapidly moving parts
These hazards are often complicated, and often exacerbated, by allowing computers to control them. The Buildbotics CNC Controller is a computer that controls machine tools. Users must be on constant guard against the possibility that the controller will cause the machine to do something that is unexpected. Users are responsible for mitigating these hazards prior to use of the Buildbotics CNC Controller.
Buildbotics LLC is not responsible for any personal injuries or damages to property that may be caused by the use (or misuse) of the Buildbotics CNC Controller. It is the user ’s responsibility to ensure all hazards, or potential hazards associated with the use of the Buildbotics CNC Controller are mitigated prior to use.
Furthermore, the Buildbotics CNC controller is not designed for use in life-safety or other critical applications. Buildbotics LLC does not authorize the use of the Buildbotics CNC Controller in applications where failures, unexpected behavior, mis-use, or even expected behavior could threaten life safety or cause damage to critical applications.
Users that find these restrictions and limitations unacceptable should contact the Buildbotics LLC customer service department (707)559-8539 for a refund prior to using or energizing the product.
Physical and Electrical Specifications
Width at base
Amps (peak) per motor coil.
Steps per second
Load 1 Current
Load 2 Current
Total output current
Motor coil resistance
Motor coil inductance
The Buildbotics CNC Controller package should include the following items:
- A Buildbotics CNC Controller
- A pre-made power cable
- A 25-pin breakout board
- 4 10 foot long pre-made motor cables
- 2 Load cable stubs
If any of these items are missing or appear to have been damaged during shipping, please contact us at firstname.lastname@example.org or 1(707)559-8539 for resolution.
Turning on the controller
Turn off the “Enable” switch, connect power, and then turn on the “Enable” switch. After enabling the controller, the LCD screen will immediately light up, then display “Controller booting Please wait…” after about 2 seconds, and then fully boot within approximately 17 seconds.
The LCD Display is located on the front panel of the Buildotics Controller and presents status information. The LCD display will immediately illuminate after power is connected and the Enable switch is switched to “Enable”. After enabling the controller, the LCD screen will immediately light up, then display “Controller booting Please wait…” after about 2 seconds, and then fully boot within approximately 17 seconds. Once this display is presented, the Buildbotics Controller is ready to communicate v ia its web server and is ready to control connected motors and other peripherals.
LCD display presented when system initialization and booting has completed
If a gamepad is plugged in, you can scroll through two additional screens by pressing on the left or right side of the screen selector button on the gamepad. One push to the right brings up a status screen that displays the temperature inside the enclosure, the input voltage (IN), the voltage sent to the motors (Out), the total motor current (Mot), the current sent on Load 1 (Ld1) and the current sent on Load 2 (Ld2).
Another push to the right brings up the network screen which shows the hostname and IP address that are assigned to this controller.
Connections to the Buildbotics Controller are made through the back panel, shown here.
The connections include:
- A 100 mbps Ethernet connection (labeled ENet)
- 4 USB ports labeled (USB)
- A DB25 25 pin I/O connector (labeled I/O)
- 4 motor driver ports (labeled X, Y, Z, and A)
- 2 load connectors (labeled L1 and L2)
- A DC Input power connector (labeled 12-36 VDC)
The Buildbotics Controller runs from a single power supply with voltage between 12 and 36 Volts DC.
The 12 to 36 volt power connector can accept voltages from 12 to 36 Volts DC and can sink up to 20 amps of DC current.
Power supply connector pin numbering
The power connector is 6-pin connector. Pins 1, 2, and 3 are on the top row and are connected to ground. Pins 4, 5, and 6 are on the bottom row and are connected to dc power between 12 and 36 volts.
The connector has reverse polarity protection built in. However, connecting power and ground to the top row or to the bottom row simultaneously will provide a short circuit and a potentially violent failure. The connector mates with a Molex 39-01-2060 that is equipped with Molex 39-00-0038 female pins. Buildbotics provides a pre-made power supply cable that connects directly to the power supply connector and can be wired directly to a DC power supply.
Buildbotics recommends using the pre-made power supply cable because attaching wires to the 36-00-0038 female pins and inserting the pins into the 39-01-2060 housing requires some practice. If you choose to build your own cable, make sure that the wire and pins used are big enough to handle the current requirements for your application. The premade power cable is shipped with the Buildbotics controller.
Pre-made power supply cable
The following picture shows a typical power supply connected to the power supply connector using the Buildbotics supplied premade power cable. Notice that the three bottom pins on the power supply connector are attached to the +V terminals and the three top pins on the power supply connector are attached to -V terminals on the DC power supply.
The Power Supply connector on the back of the Buildbotics Controller is compatible with the Mean Well GST280A12-C6P 12-Volt and the Mean Well GST280A24-C6P 24-Volt power supplies. The following picture shows a Mean Well GST280A24-C6P 24-Volt power supply connected to the Buildbotics Controller. If 24 Volts or 12 Volts with 280 watts meet the needs of your application, this is an excellent solution. The Mean Well GST280A24-C6P power supply can be purchased as an add-on option to the Buildbotics CNC Controller.
Buildbotics Controller connected to Mean Well GST280A24-C6P power supply
The Buildbotics Controller offers wired and wireless connections. Wireless connections can be configured using a web browser on the ADMIN- > Network page. (See the Configuration section of this manual.) While Internet access is not required to operate the Buildbotics Controller, it is desired. Internet Access provides direct access to this manual, and makes software upgrades very easy.
After the Buildbotics controller is attached to a network, it can be accessed from the local network by entering the hostname concatenated with .local ( “hostname.local”) or the IP address of the Buildbotics Controller into the address bar on any standard browser. The default hostname is “bbctrl”. So, new controllers can be accessed by putting “bbctrl.local” in the address bar of the browser. The IP address can be acquired by scrolling to the network screen on the controller using the Logitech F310 gamepad.
Enter “hostname.local” (default “bbctrl.local”) or the IP address of the controller in the address bar of a standard browser to access the control screen on the Buildbotics Controller
The Buildbotics Controller connects to standard ethernet networks via the 10/100Mbps Ethernet RJ-45 port on the back panel. To attach the Buildbotics Controller to the local network, simply plug a standard CAT 5 or CAT 6 Ethernet cable into the jack labeled “Enet” on the back of the controller and plug the other end into a network port on an ethernet network router or switch.
Buildbotics Controller connected to Ethernet Cable
The Buildbotics CNC Controller has a built-in wireless adapter and can be configured as a wifi client or a wifi access point.
As a Wifi Client, the Buildbotics Controller and other connected devices communicate through a nearby wireless router.
As a Wifi Access Point, wifi devices connect directly to the Buildbotics Controller and can communicate outside of the Buildbotics wifi network through an Ethernet cable to the outside world (if a connection to the outside world is provided.)
A Logitech F310 gamepad can be used to control movement on the X, Y, Z, and A axes and to scroll through screens on the controller. The gamepad attaches to the Buildbotics CNC Controller via any of the four USB ports on the back panel. Once attached, the gamepad can be used to move the CNC head in any direction at various speeds.
A Logitech F310 gamepad is included with the Buildbotics CNC Controller.
The following image shows the control positions on the Logitech F310 gamepad.
The following table describes the actions that can be achieved using the gamepad.
Simultaneous X and Y movement
Causes the CNC head to move in the direction that the X/Y stick is moved.
X movement only
X/Y stick and Horizontal Lock simultaneously
Restricts movement to X-axis only
Y movement only
X/Y stick and Vertical Lock simultaneously
Restricts movement to Y-axis only
Simultaneous A and Z movement
Causes up and down and rotational movement.
Z movement only
Z/A stick and Vertical Lock simultaneously
Causes up and down movement only.
A movement only
Z/A stick and Horizontal Lock simultaneously
Causes rotational movement only.
Very slow speed
Set movement speed to 1/128 th of full speed.
Set movement speed to 1/32 nd of full speed.
Set movement speed to 1/4 th of full speed.
Set movement speed to full speed.
Scroll to next LCD display
Press right side of Screen selector
Moves to the next LCD display (Initial Display, Status Display, or Network Display)
Scroll to previous LCD display
Press left side of Screen selector
Moves to the previous LCD display (Initial Display, Status Display, or Network Display)
Note - There is a small switch on the back of the Logitech F310 gamepad that is labeled “X” and “D”. It must be switched to the “X” position.
DB25 I/O Port
The Buildbotics controller is equipped with a male DB25 connector for access to a number of I/O ports. The DB25 I/O Port is found on the back panel of the Buildbotics Controller.
DB25 I/O Port
The following table describes each pin on the DB25 I/O port.
V OL , V OH
Logic level load switch output (see note)
V OL , V OH
Logic level load switch output (see note)
Motor 0 Min
Open, V IL
Minimum limit switch on Motor 0
Motor 0 Max
Open, V IL
Maximum limit switch on Motor 0
Motor 1 Min
Open, V IL
Minimum limit switch on Motor 1
3.3 volt source, 26.1 ohms source impedance (see note)
Motor 1 Max
Open, V IL
Maximum limit switch on Motor 1
Motor 2 Min
Open, V IL
Minimum limit switch on Motor 2
Motor 2 Max
Open, V IL
Maximum limit switch on Motor 2
Motor 3 Min
Open, V IL
Minimum limit switch on Motor 3
Motor 3 Max
Open, V IL
Maximum limit switch on Motor 3
Spindle control (negative side of RS485 differential pair)
Spindle control (positive side of RS485 differential pair)
V OL , V OH
Spindle enable (see note)
V OL , V OH
Spindle direction (see note)
V OL , V OH
Spindle speed control (pulse width modulated signal alternating between V OL and V OH ) (see note)
3.3 volt source, 26.1 ohms source impedance (see note)
V OL , V OH
Fault indicator (see note)
Open, V IL
Tool height probe (see note)
Open, V IL
Emergency stop switch (see note)
TBD (see note)
Note - The following table defines the logic values that are used.
Logic output low
Logic output high
Logic input low
Login input high
Voltage found on V3.3 Output when unloaded
Typically, a female DB25 breakout board is used to interface with the DB25 I/O Port. The following image shows a DB25 breakout box that is used for interfacing with the Buildbotics Controller. A DB25 breakout box is supplied with the Buildbotics CNC Controller.
DB25 Breakout board
The Buildbotics Controller has four motor outputs, labeled X, Y, Z, and A. Each motor driver can drive a separate axis with a single motor. Alternatively, two motors can be connected in parallel on a single driver output.
The motor driver outputs can supply up to 6 amps peak current to each coil. Each motor has two coils. The current through each motor coil is an approximated sine wave and there is 90 ° phase shift between the two coil drivers on each motor output. Since the currents are out of phase, the peak total instantaneous current to a single motor output can be as high as 8.48 amps.
The total average motor current is limited to 10 amps. Even still, the sum of the peak motor currents can exceed 10 amps.
Exceeding 10 amps of average current will cause the controller to shut down with a “Motor overload” fault. The average current drawn depends heavily on the load placed on the motors.
Users should refer to the data sheet for the motors being used and configure the motors for the current rating shown in the data sheet. See, the configuration section for more information on this subject.
The voltage output to each motor driver is a pulse width modulated (PWM) voltage with an amplitude equal to the input DC voltage being supplied to the Buildbotics Controller from the power supply.
The motor connectors are shown below. All four motor connectors are wired the same. The connectors mate with Amphenol 10127716-04LF connectors equipped with Amphenol 10127718-001LF female crimp pins.
When connecting motors:
- Connect the B+ pin (lower left) to the positive side of the B coil on the motor.
- Connect the B- pin (upper left) to the negative side of the B coil on the motor.
- Connect the A+ pin (lower right) to the positive side of the A coil on the motor.
- Connect the A- pin (upper right) to the negative side of the A coil on the motor.
These connections will cause your motor shafts to turn either clockwise or counterclockwise. If the motors are turning in the wrong direction, simply reverse either the A+/A- pair or the B+/B- pair. Do not reverse both pairs.
It takes some practice to properly attach the Amphenol 10127716-04LF connectors equipped with Amphenol 10127718-001LF female crimp pins to a cable. In order to avoid this difficulty, the Buildbotics Controller includes four, 10-foot motor cables with connectors that are compatible with the motor connectors. Buildbotics motor cables are wired as follows:
Premade cable wire color
Buildbotics pre-made motor cable
Some CNC machines have two motors driven from a single axis. If an unused motor output is available on the Buildbotics Controller, simply assign the second motor output to the same axis and connect the second axis motor to that axis output.
Alternatively, a single output port can drive two motors by wiring the motors in parallel. In many cases, the two motors will face one-another and must turn in opposite directions.
If the motors must turn in opposite directions, then one of the motors will have either the A+/A- pair reversed or the B+/B- pair reversed (but not both). Notice that the following image shows the B+/B- pair reversed on the motor on the right which causes the motors to turn in opposite directions.
Additional information regarding wiring to the various types of stepper motors is provided in Appendix III - Stepper Motor Wiring
The Buildbotics Controller can control a spindle through a PWM interface. Additionally, it can control a Huanyang VFD through an RS485 interface, which in turn controls the spindle. In most cases, the spindles require their own power source while the Buildbotics Controller only provides the control signals for starting, stopping, and adjusting the speed of the spindle.
The Buildbotics Controller provides an RS485 interface for driving spindles.
RS485 Spindle Connection
Use the following procedure to connect a VFD to the Buildbotics Controller:
- Disconnect power from the VFD controller, the spindle, and the Buildbotics Controller
- Connect the plus side of the RS485 pair to pin 13 on the DB25 breakout board
- Connect the minus side of the RS485 pair to pin 14 on the DB25 breakout board
- Shielded twisted pair cable is recommended for the connection from the Buildbotics Controller. If you use shielded twisted pair cable, connect the shield to ground on the VFD and to a GND pin on the 25-pin breakout board.
- Connect the DB25 breakout board to the back of the Controller
- Reconnect power.
The Buildbotics Controller has been tested and shown to work with the Huanyang HY01D523 Variable Frequency Drive. Please refer to Appendix I for instructions on how to connect and configure the HY01D523 VFD to operate with the Buildbotics Controller.
Use the following procedure to connect to a PWM spindle controller:
- Disconnect power from the spindle, the spindle controller, the spindle power supply, and the Buildbotics Controller.
- Connect Tool Enable pin (15) on the DB25 breakout board to the Enable terminal on the spindle controller.
- Connect the Tool Direction pin (16) on the DB25 breakout board to the Direction terminal on the spindle controller.
- Connect the Spin PWM pin (17) on the DB25 breakout board to the PWM terminal on the spindle controller.
- Connect one of the Gnd pins (7, 19, or 25) on the DB25 breakout board to the Ground terminal on the spindle controller.
- Connect the spindle controller to its power supply. (Refer to the manual for the spindle controller and the spindle power supply.)
- Connect the spindle controller to the spindle. (Refer to the manuals for the spindle and the spindle controller.)
- Connect the DB25 breakout board to the DB25 I/O Port on the Buildbotics Controller.
- Connect power to the Buildbotics Controller and the Spindle power supply.
The Buildbotics Controller has been tested and shown to work with the 400 Watt spindle and controller kit. Please refer to Appendix II for instructions on how to connect and configure the spindle and controller kit to operate with the Buildbotics Controller.
The Buildbotics CNC Controller is able to power miscellaneous DC loads through the L1 and L2 connectors. L1 and L2 are Amphenol Minitek 10127720-06LF connectors and mate with Amphenol 10127716 6-position connectors equipped with 10127718-001LF crimp pins.
The top three pins on L1 and L2 are connected to ground. The bottom three pins of L1 supply a voltage equal to the controller input voltage, as do the bottom three pins of L2. Note, the voltages on L1 and L2 are supplied independently.
Each of L1 and L2 are capable of supplying up to 10 amps. However the total power budget for the Buildbotics Controller is 20 amps, so L1 and L2 cannot both supply 10 amps at the same time.
It takes some practice to properly attach the Amphenol 101277120-06F connectors equipped with Amphenol 10127718-001LF female crimp pins to a cable. In order to avoid this difficulty, the Buildbotics Controller includes two load cable stubs that plug directly into the L1 and L2 outputs. The wiring from the load cable stubs are red and black. The red wires supply the plus voltage and the black wires supply ground.
The total current supplied to all motors and loads cannot exceed 20 amps. The total current is also limited by the current rating of the power supply which is likely to be less than 20 amps. Be cognizant of the total current budget of the Buildbotics Controller, the current rating of the input power supply, and the voltage and power requirements of the loads and stepper motors when deciding whether to drive a load from a Load port on the Buildbotics Controller.
Power consumption budget example
Example - A Buildbotics Controller is powered by a Mean Well HEP-600-36 power supply, which can supply 600 watts (16.7 Amps) at 36 Volts DC. The spindle shown is being driven from L1 and consumes 400 watts, or 11.1 Amps. That leaves 5.6 amps total for the three motors. These particular motors are rated at 1.8 amps peak in each coil, so the total peak current serving the motors is 7.6 Amps. 11.1 + 7.6 = 18.8 amps which exceeds the limit of the power supply. Recall that the all motors and the spindle are rarely draw full current simultaneously, so it is highly likely that this design would work well. However, a very conservative design would make one or more of the following changes:
- Increase the power supply size.
- Use smaller motors.
- Go to a smaller spindle
- Power the spindle from another source
Simply plug a webcam into one of the unused USB ports on the back of the controller. Then, turn on the Buildbotics Controller and the web camera display will automatically become visible in the “Video” tab on the Control Page via a web browser.
Buildbotics has tested the Logitech C615 webcam and shown that it works well when plugged directly into one of the USB ports. Other webcams may require connecting through a powered USB hub to work correctly. Others may not work at all.
The Buildbotics Controller incorporates a Raspberry PI Model 3 computer internally. Webcams shown to be compatible with the Raspberry PI should work well with the Buildbotics controller. The following web site lists many webcams that have been tested with Raspberry PI ’s.
The Buildbotics Controller can be accessed, configured, and controlled from a standard browser.
Connecting to the Buildbotics Controller
The Buildbotics Controller can be accessed from any computer on the same local subnet that is running a standard web browser. If the Buildbotics Controller is attached to the same local subnet as your computer, simply open a web browser and enter “ hostname .local ” in the address bar where hostname is the name of the Buildbotics Controller. The default name is “bbctrl”, so you can access a new Buildbotics Controller by entering “bbctrl.local” in the browser address bar.
Alternatively, enter the IP address for the Buildbotics Controller into the address bar of the browser. The IP address can be acquired by scrolling to the network screen on the L CD display using the g amepad.
Accessing the Buildbotics Controller from outside the local subnet is not supported.
Users will be presented with a web page similar the one shown below after entering hostname. l ocal (or the Buildbotics Controller IP address) into the address bar.
Notice that all pages have the “Save” button in the upper left corner and the “Emergency Stop” button in the upper right.
Whenever any configuration change is made, the “Save” button will turn from grey to green. You must click the green “Save” button before changes are actually sent to the Buildbotics Controller and saved.
Clicking the emergency stop button will stop all motors from turning and disable the spindle (if the spindle is controlled by the Buildbotics Controller). Once clicked, the outer ring on the emergency stop button will turn from solid yellow to blinking between yellow and orange. The Buildbotics Controller will not cause any movement of the motors or re-enable the spindle until the emergency stop button is released by clicking it again. When clicked again, the outer ring will change from blinking between yellow and orange to solid yellow and motion can resume.
Additionally, an emergency stop button can be connected from pin 23 to a ground pin on the Buildbotics Controller DB25 I/O port.
Note that the National Fire Protection Agency (NFPA 79) requires that the class of emergency stop button be determined through a risk assessment. The soft estop button on these web pages and the estop pin (pin 23 on the DB25 I/O connector) are both software controlled, and cannot be used for safety. If your risk assessment requires an emergency stop button to be installed for safety purposes, then Buildbotics LLC recommends installing a “listed “ hardware Emergency Stop button in line with system power.
Configuring the Buildbotics Controller
Configuring Motor Drivers
The Buildbotics Controller has four motor driver ports, labeled X, Y, Z, and A. These correspond to Motor 0, 1, 2, and 3 respectively. Click the motor driver port listed in the left hand pane to access the configuration screen for that port.
After clicking a motor link as shown, the motor driver configuration screen will open. The screenshot shown below is for configuring motor driver 0 (the one labeled X on the back panel). All four motor configuration screens are the same.
Even though the back panel motor ports are labeled X, Y, Z, and A, any axis can be assigned to any port. The axis selection pull-down menu allows selecting the axis that will be assigned to this motor driver port. Available selections include X, Y, Z, A, B, and C.
The “Power” section allows configuring the amount of current that will flow to the motors.
The power-mode pull-down menu allows specifying when current is applied to the motors. Selections available include:
- “disabled” - Current will not be supplied on this motor driver port.
- “always on” - Current will always be supplied on this motor driver port.
- “In-cycle” - This motor driver is enabled whenever any motor is moving.“
- when-moving ” - Current will only be supplied on this motor when it is moving. This selection can be used to save power and reduce heat in the motor and driver.
The drive-current entry box allows setting the maximum peak current in amps that is supplied to each motor coil. Users should look up this value on the motor data sheet. When connecting two motors in parallel on a single port, the maximum current should be set to double that shown in the motor data sheet.
The Idle-current entry allows specifying the holding current in amps that is supplied when the motor is not moving. In many cases, this can be set to zero. Some systems may require a value that is greater than zero to ensure that the motor holds its position when not moving.
Buildbotics recommends starting with “power-mode” set to “when-moving” and “idle-current” set to 0. These settings will minimize the heat generated in the motor drivers and motors. If these values cause problems, then find the best combination through experimentation.
The “Motion” section allows configuring the speed and direction of the motor.
Checking the reverse checkbox causes the axis to move in the opposite direction.
The microsteps pull-down menu allows specifying the level of microstepping to be used for this axis. Microstepping allows smoother and more accurate motion by subdividing motor steps. For instance, setting microstepping to 32 subdivides each motor step into 32 microsteps. Selections available for microsteps per step include 1, 2, 4, 8, 16, 32, 64, and 128. The highest levels of microstepping may cause difficulty at high motor revolutions per minute (RPM). In most cases 32 seems to be a good balance.
The maximum-velocity entry box allows setting the maximum speed at which the axis will move in meters per minute. Typically, users will want this value to be as high as possible without experiencing motor stalls.
A good practice is to experiment with your machine to determine the maximum velocity for each axis, and then set the maximum velocity to about 80% of that value for the actual use of the machine. Note, this is the speed at which rapid moves will occur on your machine. Cutting feed rates are set in G-code and will typically be less than the maximum velocity set in the maximum velocity entry box. The axis will not move at a rate greater than this value even if the feed rate set in G-Code is greater than the value set here.
Often times, stepper motor data sheets provide speed versus torque curves with speed shown in revolutions per minute (RPM). The field just to the right of the max-velocity calculates the motor RPM at maximum velocity based on the maximum velocity, the step angle, and the travel per revolution.
The max-acceleration field sets the maximum acceleration in kilometers/minute 2 . This value is also shown in ‘g-force’ (G’s) where one G is equal to the acceleration of gravity at sea level which is 9.8 m/s 2 (32 ft./s 2 ). Excessive acceleration will cause your motors to stall during acceleration or deceleration. Insufficient acceleration will increase cutting time. Experimentation will help you find the optimum value for this field.
The maximum-jerk entry box allows setting the amount of jerk that the axis will experience when changing from one velocity to another. Jerk is the rate of change of acceleration. The Buildbotics Controller provides smooth S-curve acceleration and this value sets the rate of change of acceleration in kilometers/minute 3 . Higher jerk values will cause acceleration to change more abruptly and potentially cause the axis to jerk at the beginning and end of acceleration periods. These jerks can cause the machine to move. The jerk entry box allows users to maximize acceleration rates while minimizing jerks. The jerk value is converted to G ’s/minute in the field to the right.
The step-angle entry box allows specifying the step angle in degrees that the motor turns with each full motor step. Users should consult the motor data sheet to determine this value. Most modern stepper motors have 200 steps per revolution, or 1.8 ° per step. If this is the case, enter 1.8 in the step angle entry box. The field to the right shows the number of steps per revolution for the step angle given.
The travel-per-revolution entry box tells the controller how far the axis will move in millimeters with each revolution of the motor. The field to the right shows how far the axis will move with each full step. This is a function of the gear ratio of the motor, the number of steps per revolution, and the pitch of the pinion belt, lead screw, or ball screw used to move the axis.
Example - An axis having a ball screw with 2.5 millimeters per turn that is driven by a 10-to-1 gear reduction would move 2.5 x .1 = 0.25 millimeters per turn.
Example - An axis that is driven by a belt and pinion system where the belt pitch is 3 millimeters per tooth and the motor pulley has 20 teeth would move 60 millimeters per revolution.
Example - An axis that uses an 8 millimeter pitch lead screw that is directly driven by the stepper motor would travel 8 millimeters for each revolution.
The “Limits” section allows configuring hard and soft limits for the axis being configured.
The min-soft-limit entry box sets the minimum absolute position in millimeters for the axis. G-Code moves will not go below this position.
The max-soft-limit entry box sets the maximum absolute position in millimeters for the axis. G-Code moves will not go above this position.
The min-switch pull-down menu determines the type of physical limit switch that is used for signaling that the axis has reached its minimum position. The choices are:
- disabled - no limit switch is being used
- normally-open - The switch closes when the minimum position is reached.
- normally-closed - The switch opens when the minimum position is reached.
The max-switch pull-down menu determines the type of physical limit switch that is used for signaling that the axis has reached its maximum position. The choices are:
- disabled - no limit switch is being used
- normally-open - The switch closes when the maximum position is reached.
- normally-closed - The switch opens when the maximum position is reached.
The “Homing” section allows configuring the homing procedure for the axis.
The homing-mode sets the method used for homing the axis. The choices are:
- manual - the axis is manually homed by the user. If manual homing is selected, the search-velocity, latch-velocity, latch-backoff, and zero-backoff fields are not used.
- switch-min - The axis will travel towards its minimum position until the limit switch at the minimum position is activated. This option requires that a switch is installed at the minimum position and configured in the min-switch field for the axis. In this mode, the position will be automatically set to the value in “min-soft-limit” after homing.
- switch-max - The axis will travel towards its maximum position until the limit switch at the maximum position is activated. This option requires that a switch is installed at the maximum position and configured in the max-switch field for the axis. In this mode, the position will be automatically set to the value in “max-soft-limit” after homing.
The homing protocol is as follows:
- The axis travels toward the limit switch at the “search-velocity”. The “search-velocity” should be slow enough to allow the axis stop within the travel distance of the limit switch lever or plunger.
- When the switch activates, the axis stops and backs away by the value in “latch-backoff”. The limit switch deactivates as the axis travels away from the switch.
- The axis travels back to the limit switch at the “latch-velocity”. For maximum homing accuracy, the “latch-velocity” should be significantly slower than the “search-velocity”.
- When the switch activates, the axis stops and backs away by the value given in “zero-backoff”.
The purpose of approaching the limit switch slowly on the second try is to improve repeatability in the homing position.
Configuring the Spindle
Click the “TOOL” link in the left hand pane to access the Tool Configuration page.
The fields in the Tool Configuration screen differ depending on the value selected in the “spindle-type” pull-down menu.
If the Buildbotics Controller does not control a spindle, set the ‘spindle-type’ pull down menu to “DISABLED”. When the spindle is “DISABLED”, the remain fields have no effect.
“The following picture shows what the spindle configuration screen looks like when the “spindle-type” is set to “PWM”.
In this case the “spindle-type” field specifies that the spindle speed will be controlled with Pulse Width Modulation (PWM). Select PWM if the Buildbotics Controller relies on the “Tool Enable” and/or the “Tool Direction” pins on the DB25 I/O port for control even if the speed is not controlled with the PWM output.
The “spin-reversed” checkbox inverts the behavior of the “Tool Direction” pin on the DB25 I/O connector from that specified in the “tool-direction-mode” field.
The “tool-enable-mode” field specifies the behavior of the “Tool Enable” pin on the DB25 I/O connector when the tool is turned on; for instance, when an M3 or M4 G-Code command is issued.
- “disabled” means that the “Tool Enable” pin is not used.
- “lo-hi” means the “Tool Enable” pin switches from a logic low to a logic high to turn on the spindle.
- “hi-lo” means the “Tool Enable” pin switches from a logic high to a logic low to turn on the spindle.
- “tri-lo” means the “Tool Enable” pin switches from a high impedance state to a logic low to turn on the spindle.
- “tri-high” means the “Tool Enable” pin switches from a high impedance state to a logic high to turn on the spindle.
- “lo-tri” means the “Tool Enable” pin switches from a logic low to a high impedance state to turn on the spindle.
- “hi-tri” means the “Tool Enable” pin switches from a logic high to a high impedance state to turn on the spindle.
The “tool-direction-mode” field specifies the action that will be taken on the “Tool Direction” pin on the DB25 I/O connector when the tool is directed to turn in the reverse direction; for instance, when an M4 G-Code command is issued.
- “disabled” means that the “Tool Direction” pin is not used.
- “lo-hi” means the “Tool Direction” pin switches from a logic low to a logic high to turn the spindle in the reverse direction.
- “hi-lo” means the “Tool Direction” pin switches from a logic high to a logic low to turn the spindle in the reverse direction.
- “tri-lo” means the “Tool Direction” pin switches from a high impedance state to a logic low to turn the spindle in the reverse direction.
- “tri-hi” means the “Tool Direction” pin switches from a high impedance state to a logic high to turn the spindle in the reverse direction.
- “lo-tri” means the “Tool Direction” pin switches from a logic low to a high impedance state to turn the spindle in the reverse direction.
- “hi-tri” means the “Tool Direction” pin switches from a logic high to a high impedance state to turn the spindle in the reverse direction.
The “max-spin” field specifies the speed (in RPM) at which the spindle is expected to turn when the PWM duty cycle is at the maximum value as specified in the “pwm-max-duty” field.
The “min-spin” field specifies the speed (in RPM) at which the spindle is expected to turn when the PWM duty cycle is at the minimum value as specified in the “pwm-min-duty” field.
When checked, the “pwm-inverted” checkbox causes the duty cycle fields to mean the percent of time that the PWM output is at a logic low. When unchecked, it causes the duty cycle fields to mean the percent of time that the PWM output is at a logic high.
The “pwm-min-duty” field specifies the percent of time that the “Tool PWM” pin on the DB25 I/O connector will be active when the spindle is turning at the rate specified in the “min-spin” field. The “active” state is specified by the “pwm-inverted” checkbox.
The “pwm-max-duty” field specifies the percent of time that the “Tool PWM” pin on the DB25 I/O connector will be active when the spindle is turning at the rate specified in the “max-spin” field. The “active” state is specified by the “pwm-inverted” checkbox.
The “pwm-freq” field specifies the rate at which PWM pulses are sent out through the “Tool PWM” pin on the DB25 I/O connector.
This picture shows the Tool Configuration screen when HUANYANG is selected in the “spindle-type”.
While the Huanyang spindles support tool enable, spin reversed, and tool direction connections in the same way as the PWM spindles described above, Buildbotics recommends using the RS485 connections on the DB25 I/O connector for controlling Huanyang spindle.
With RS485 control, uncheck “spin-reversed” and disable “tool-enable-mode” and “tool-direction-mode”
“Bus-id” establishes the communications address on the RS485 connection. Set the value in this field to match the communications address in the Huanyang spindle.
Refer to Appendix I for recommendations on configuring the Huanyang spindles for operation with the Buildbotics controller.
Configuring I/O switches
Click the I/O link in the left pane to access the I/O Configuration page.
After clicking the I/O link the I/O Configuration page opens.
The estop pull down menu specifies the type of estop switch connected to the “Estop pin” on the DB25 I/O connector. The options are:
- disabled - No estop switch is being used by the Buildbotics controller. Note - it is still possible that an estop switch is connected to the machine but does not make use of the Buildbotics Controller.
- normally-open - An estop switch is connected to the Buildbotics Controller and the switch is closed when active.
- normally-closed - An estop switch is connected to the Buildbotics Controller and the switch is opened when active.
The probe pull down menu specifies the type of probe switch connected to the “Probe pin” on the DB25 I/O connector. The options are:
- disabled - No probe switch is being used by the Buildbotics Controller.
- normally-open - A probe switch is connected to the Buildbotics Controller and the switch is closed when active.
- normally-closed - A probe switch is connected to the Buildbotics Controller and the switch is opened when active.
“load-1” and “load-2” pull-down menus are associated with the L1 and L2 outputs on the back panel of the Buildbotics controller. The L1 and L2 outputs can be software controlled through G-Code commands or they can be controlled through hardware by applying logic signals to the “Load 1” o r “Load 2” pins on the DB25 I/O connector.
To control the L1 output using the “Load 1 pin” on the DB25 I/O connector, set the “load-1” field to “disabled”. Connect connect the “load 1 pin” to a logic high to turn the L1 output on. Connect the “Load 1 pin” to a logic low to turn the L1 output off.
To control the L2 output using the “Load 2 pin” on the DB25 I/O connector, set the “load-2” field to “disabled”. Connect connect the “Load 2 pin” to a logic high to turn the L2 output on. Connect the “Load 2 pin” to a logic low to turn the L2 output off.
To control the L1 output from software, set the “load-1” field to “lo-hi”. This causes the “Load 1 pin” on the DB25 I/O connector switch to logic high when the L1 output is turned on and switch to logic low when the L1 output is turned off. The “Load 1 pin” can be monitored by external hardware (e.g. LED’s) if desired.
To control the L2 output from software, set the “Load-2” field to “lo-hi”. This causes the “Load 2 pin” on the DB25 I/O connector switch to logic high when the L2 output is turned on and switch to logic low when the L2 output is turned off. The “Load 2 pin” can be monitored by external hardware (e.g. LED’s) if desired.
The “fault” field specifies the behavior of the “fault” pin on the DB25 I/O connector when a fault is active. The state of the “Fault” pin is reflected in the Outputs table on the Control page.
- “disabled” means that the “Fault” pin is not used.
- “lo-hi” means the “Fault” pin switches from a logic low to a logic high to indicate that a fault has occurred.
- “hi-lo” means the “Fault” pin switches from a logic high to a logic low to indicate that a fault has occurred.
- “tri-lo” means the “Fault” pin switches from a high impedance state to a logic low to indicate that a fault has occurred.
- “tri-high” means the “Fault” pin switches from a high impedance state to a logic high to indicate that a fault has occurred.
- “lo-tri” means the “Fault” pin switches from a logic low to a high impedance state to indicate that a fault has occurred.
- “hi-tri” means the “Fault” pin switches from a logic high to a high impedance state to indicate that a fault has occurred.
Click “GCODE” in the left pane to access the GCode Configuration page. The GCode Configuration page allows inserting sequences of ‘G’ and/or ‘M’ codes in G-Code programs. Insertions are possible at the beginning, at the end, and during tool changes. It is often helpful to add comments to the c ommands. Comments are enclosed in parentheses. Some commands cause program execution to pause and wait for the user to take action to resume execution. When the characters ‘MSG,’ are entered at the beginning of the comment, the remainder of the comment is presented to the user in the action dial og that is presented to the user. This helps instruct the user on what action to take before resuming execution.
G and M code commands entered in the “program-start” entry box will be inserted at the beginning of G-Code programs when they are executed. By default, the following G-Code commands are entered in the “program-start” entry box.
(Runs at program start)
G21 (Metric units)
G90 (Absolute distance mode)
G17 (Select XY plane)
Similarly, the “program-end” entry box contains commands that will be inserted at the end of G-Code programs. By default, the following G-Code commands are entered in the “program-end” entry box.
(Runs on M2, program end)
The “tool-change” entry box contains commands that are run every time an M6 (tool change) command is encountered. By default, the “tool-change” entry box contains the following commands:
(Runs on M6, tool change)
M0 M6 (MSG, Change tool)
These commands simply pause execution and prompt the user to change the tool. The following example provides a set of commands that can be used to change the tool and then set the height of the z-axis after the tool change. This example assumes the use of a 0.75 ” (19.05mm) touch probe like the one shown here:
(Runs on M6, tool change)
M0 g0z100x-100y-100 M6 (MSG, Change tool and attach z-probe)
M0 (MSG, Remove probe)
M0 g0z100x-100y-100 M6 (MSG, Change tool and attach z-probe) - Moves the machine to Z = 100, X = -100, and Y = -100. This is meant to raise the machine up high enough to change the bit and put the tool in a place where the probe can sit at a known level. The comment starts with ‘ MSG, ’ so the text “Change tool and attach z-probe” is presented to the user in the action dialog.
f100 says that the feed rate will be 100 mm/minute. This feed rate should be slow to prevent jamming the bit into the surface of the probe. Ideally, the search will stop at the instant that the bit touches the probe.
g38.2 z0 tells the machine to move towards the probe and stop when the probe surface is found. If the search reaches the point that it ‘thinks’ is z = 0 without finding the probe surface, the search will stop and the probing command fails.
g92 z19.05 sets the z axis to 19.05mm, which is the height of the probe base being used in this example.
g0z100 tells the machine move up to Z = 100.
M0 (MSG, Remove probe) reminds the user to remove the probe and waits for the user to click “Continue” to resume execution of the G-Code program.
Hint 1: This example program sets the feed rate to 100 mm/minute and does not reset it to the feed rate that existed before the M6 command was encountered. I t is a good practice to set the feed rate again in the G-Code program after the tool change has completed.
Hint 2: The probe used in this example requires attaching the alligator clip to a point on the router that provides a conductive path to the tip of the bit. It ’s tempting to simply attach the alligator clip to directly to the bit, and this does work. However, if you forget to remove the clip from the bit before resuming execution, the probe will probably be destroyed when the spindle starts spinning. It’s best to find a connection point that is conduc tive to the bit, but doesn’t spin.
Click ADMIN- > General for non-network related administrative functions.
The Firmware section allows checking, upgrading, or uploading firmware for the Buildbotics Controller.
Click “Check” to see if a new version of firmware is available. If the Buildbotics Controller is already at the latest version, a “check mark” will show in the header as shown here.
If a firmware upgrade is available, the header on all pages will show that the new firmware is available. Clicking the orange link will jump to the ADMIN- > General page.
Click “Upgrade” to upgrade to the latest version of Buildbotics Controller firmware. The following dialog is presented.
Enter the Buildbotics Controller password and click Upgrade. The default password is “buildbotics”, but it can be changed on the ADMIN-Network page.
After clicking “Upgrade”, the new firmware will be loaded into the Buildbotics Controller and the controller will automatically reboot.
Click the “Upload” button to load a different version of Buildbotics Controller firmware from a file on the local computer. All versions of Buildbotics Controller firmware are available here . Take caution when uploading old firmware versions, as they may not be compatible with the latest hardware and could cause an unrecoverable failure. It is strongly advised that you contact Buildbotics support personnel through the Buildbotics Forum before attempting to upload an old firmware version.
Checking the “Automatically check for upgrades” checkbox causes the controller to automatically check for new firmware when the Buildbotics Controller is booted, and report the result in the header for all pages as described for the “Check” button.
The Configuration section allows backing up and restoring the configuration of the Buildbotics Controller. This is useful if you need to temporarily change configuration information. For instance, it is not uncommon to temporarily change the “soft limits” on the Z-axis to match the way a G-Code program was set up.
Click “Backup” to save all configuration information to a file on your local computer. A dialog like this is presented.
A file name is suggested that includes the date. Depending on your browser configuration, you may be able to rename the file and save it in any folder you like.
Clicking “Restore” allows restoring a previously saved backup file.
Clicking “Reset” allows resetting the entire configuration to the factory default values.
The “Debugging” section provides the ability to view the system log. You may be asked to copy this information to a file and send it to Buildbotics support personnel if they are assisting in resolving problems.
The ADMIN- > Network page allows changing the controller name, changing the remote shell username and password, and setting up wireless network connections.
The Hostname field displays the name of the Buildbotics Controller. The default name is “bbctrl”. This name can be used to access the Buildbotics Controller using a web browser by entering the value in the Hostname field appended with “.local” in the address bar of a web browser. The hostname can be changed by ent ering a new name in the hostname field and clicking the “Set” button.
The Username field contains the name of a user that can connect to the Buildbotics Controller using a SSH connection. The default value is “bbmc”. The name can be changed if desired by entering a new username and clicking the “Set” button. The SSH connection provides access to a shell on the unix operating system within the Buildbotics Controller.
The password fields allow changing the password for the accessing the Buildbotics controller via a SSH connection and for upgrading the software. The default password is “buildbotics”. You can change the password by entering the current password followed by the new password twice, and then clicking the “Set” button.
To access to Buildbotics Controller using the default username and password, open a terminal and enter the following command:
you@host: ~$ ssh email@example.com
The “Wifi Setup” section allows configuring the Buildbotics Controller to be a Wifi Client or a Wifi Access Point.
The “Mode” pull-down menu offers three options:
- Disabled - This is the default and when selected, the only way to connect to the Buildbotics Controller is through a hard-wired ethernet cable connected to the RJ-45 connector on the back of the controller.
- Client - Allows configuring the controller to be a Wifi Client node.
- Access Point - Allows the Buildbotics Controller to become a wireless access point and serve other wireless nodes.
Selecting “Client” changes the page to look like this:
Enter the name of your local wireless network in the Network (SSID) field and the local wireless network password in the Password field. The network name and network password can be acquired by logging into your wireless router, of by asking you network administrator.
Click “Set” to apply the changes. Clicking “OK” from the following dialog causes the controller to reboot and connect to the wireless network.
Disconnect the wired network. Note, even if the wireless connection fails, the wired connection will work if you reconnect it.
Selecting “Access Point” changes the page to this:
11 wifi channels are available. Select one of them from the pull-down menu. Enter a name for the new wireless network and make up a password. Clicking “Set” presents the following dialog:
Click OK to apply the changes and reboot the controller. After the controller reboots, wireless devices can be rehomed with the new network name and password.
If the controller is acting as an access point and has a hard-wired ethernet cable, any wireless nodes connected through the new network will also have access to the hardwired network, including the internet if it is available.
Click “CHEAT SHEET” in the left pane to access descriptions of all G and M codes.
The cheat sheet is shown in the following image.
A brief description is provided for all G and M codes. More detailed descriptions can be accessed by clicking on the commands. The detailed descriptions are actually provided through the linuxcnc.org web site, and are only accessible if internet access is available.
Clicking “HELP” in the left pane opens a page the provides a link to this manual, a link to the Buildbotics forum, and links to some great Open Source CAD and CAM programs. You are strongly encouraged to check them out.
Operating the Buildbotics Controller
The Control page provides real time status and feedback information about the attached machine, and allows controlling the machine through manual jogging, running G-Code commands, or through G-Code programs.
The Axis table is at the top of the control page and gives the following information for each active axis:
- Position - This is the logical position. G-Code commands and programs will move relative to this position. For instance, the command “G0 X10” will cause the X axis to move to 10mm and 10.000 will reflect in this field. This assumes that metric units are being used.
- Absolute - This is the actual position of the machine relative to its homed value. This value will also show on the Buildbotics controller LCD screen.
- Offset - Offset is equal to Position - Absolute. This is useful when you want your program to run from some position other than home. For instance, the physical home value may be at the lowest position along an axis, but the program causes the axis to move to negative values. The offset can shift the zero position to another point along the axis.
Three action buttons are provided for each axis in the right column of the axis table. These buttons behave differently depending the value assigned to “homing-mode” in the Motor Configuration. The possible homing modes are “manual”, “switch-min”, and “switch-max”.
Two buttons, located above the axis action buttons allow setting the offset or homing all active axes with a single click.
When ‘homing-mode” is set to “manual”, the buttons behave as follows:
In the “manual” homing mode, clicking the “Home axis” (rightmost) button prompts the user to set the absolute position. The Absolute value will be set to the value entered by the user. The Position value will be set to the Absolute value plus the Offset value. The background color for the table row for the axis turns green to indicate that the axis has been homed.
Set axis offset
In the “manual” homing mode, clicking the “Set axis offset” (center) button sets the Offset value to the reciprocal of the current Absolute value and sets the Position value to 0.000.
Set axis position
In the “manual” homing mode, clicking the “Set axis position” (leftmost) button prompts the user for a value and the position is set to that value. The offset value is updated to reflect the difference between the absolute and position values.
When “homing-mode” is set to “switch-min”, the buttons behave as follows:
In the “switch-min” homing mode, clicking the “Home axis” (rightmost) button causes the following procedure to be executed:
- The axis moves toward the minimum limit switch at the velocity specified in the “search-velocity” field until the minimum limit switch is activated.
- The axis backs away from the minimum switch until the “latch-backoff” distance is reached, deactivating the minimum switch.
- The axis moves toward the minimum switch at the latch-velocity until the switch is activated.
- The axis backs away from the minimum switch by the “zero-backoff” distance.
- The “Absolute” value is set to the value in the “min-soft-limit” field.
- The “Position” value is set to the “Absolute” value plus the “Offset” value.
- The background color for the table row for the axis turns green to indicate that the axis has been homed.
Note - this assumes that the minimum switch is configured and working correctly.
Set axis offset
In the “switch-min” homing mode, clicking the “Set axis offset” (center) button sets the Offset value to the reciprocal of the current Absolute value and sets the Position value to 0.000.
Set axis position
In the “switch-min” homing mode, clicking the “Set axis position” (leftmost) button prompts the user for a value and the position is set to that value. The offset value is updated to reflect the difference between the absolute and position values.
In the “switch-max” homing mode, clicking the “Home axis” (rightmost) button causes the following procedure to be executed:
- The axis moves toward the maximum limit switch at the velocity specified in the “search-velocity” field until the maximum limit switch is activated.
- The axis backs away from the maximum switch until the “latch-backoff” distance is reached, deactivating the maximum switch.
- The axis moves toward the maximum switch at the latch-velocity until the switch is activated.
- The axis backs away from the maximum switch by the “zero-backoff” distance.
- The “Absolute” value is set to the value in the “max-soft-limit” field.
- The “Position” value is set to the “Absolute” value plus the “Offset” value.
- The background color for the table row for the axis turns green to indicate that the axis has been homed.
Note - this assumes that the maximum switch is configured and working correctly.
Set axis offset
In the “switch-max” homing mode, clicking the “Set axis offset” (center) button sets the Offset value to the reciprocal of the current Absolute value and sets the Position value to 0.000.
Set axis position
In the “switch-max” homing mode, clicking the “Set axis position” (leftmost) button prompts the user for a value and the position is set to that value. The offset value is updated to reflect the difference between the absolute and position values.
Two status tables are provided near the center of the Control page. These tables provide real-time information about the state of the machine and programs.
Left Status table
The state field reflects the state of the CNC controller. The value in this field is the same as the status displayed in the upper left corner of the LCD screen on the Buildbotics controller. The possible values in the state field are:
The Message field is often blank, but may report a message if the machine is in an unexpected state. More details can be found by selecting the “Messages” tab in lower part of the Control page.
The Units field specifies whether G-Code commands will be interpreted in metric or imperial units. The position, absolute, and offset fields in the status table always present in millimeters. For instance, executing a G20 will change the Units field to IMPERIAL. Then, executing a G0X1 will cause the x axis to move to 1 inch and the position field for the x-ax is will show 25.400.
The Feed field reflects the feed rate in millimeters per minute as set by an executing program or a G-Code “F” command.
The Speed field reflects the rotational speed of the spindle as set by an executing a G-Code “S” command.
Right status table
This field reflects the actual velocity in meters per minute that the machine head is moving relative to the workpiece.
This field reflects the current line being executed in a G-Code program.
This field reflects that tool number that is current being used. The value is set as a result of executing a “T” G-Code command.
Executing a G-Code M7 command causes the “Mist” field to change to “On”. Executing a G-Code M9 command causes the “Mist” field to change to “Off”. If the ‘load-1” field in the I/O configuration page is set to “lo-hi”, the “Mist” field shows whether the L1 output on the back of the Buildbotics Controller is turne d on.
Executing a G-Code M8 command causes the “Coolant” field to change to “On”. Executing a G-Code M9 command causes the “Coolant” field to change to “Off”. If the ‘load-2” field in the I/O configuration page is set to “lo-hi”, the “Mist” field shows whether the L2 output on the back of the Buildbotics Controller is turned on.
The bottom portion of the Control page consists of a tabbed section. There are six tabs in the tabbed sections. Each tab opens a different window.
The Auto tab allows loading new G-Code programs, selecting existing G-Code programs, executing G-Code programs, deleting existing G-Code programs, and inspecting G-Code programs. The G-Code program that is loaded into the scrolling G-Code program window will be executed when the “Play” button is clicked.
T he Upload Program button opens a file selector dialog that allows the user to select G-Code programs on the local computer and upload them to the Buildbotics controller. Once, uploaded, the G-Code program is displayed in the scrolling G-Code program window and added to the drop down list of previously loaded files.
Clicking the Trash button deletes the file that is currently loaded into the scrolling G-Code program window. The user is given the option to delete all previously loaded programs.
The drop down list of previously loaded files allows the user to load G-Code programs that were previously stored in the Buildbotics Controller. Once loaded into the program window, these programs can be executed by clicking the Play button.
The Manual Data Input (MDI) tab allows the user to control the machine by manually entering G-Code commands.
The Play button causes the commands that are currently in the command entry field to be executed.
The Stop button causes any commands that are currently executing to stop.
The command entry field accepts G-Code commands from the user. Hitting the enter key after typing commands into the command entry field causes those commands to be executed.
The scrolling window of command history displays commands that have been executed. The most recent commands are displayed at the top. Clicking a previously executed command in the scrolling window causes that command to be loaded into the command entry field.
The Jog tab allows users to jog the machine on the X, Y, or Z axes. Clicking the outer ring causes the axis to move by 100 mm; the next ring moves 10mm; the third ring moves 1mm; and the inner ring moves .1mm.
The Messages tab displays a running list of error and status messages. The most recent message is appended to the bottom of the list. These messages can assist in troubleshooting problems. The Message field gives a brief description of the issue and the Location field sometimes gives the source code file and line number where the issue was encountered.
The Repeat field reports the number of times that the issue has occurred.
Clicking the Clear button deletes the list of messages.
The indicators tab provides status information about the machine including and output states, power fault conditions, input and output voltage motor and load currents, temperature, and RS485 spindle status (if equipped).
The Inputs table shows the state of all eight limit switch inputs, the E-Stop input, and the Probe input. Green means that a logic high is being read at the DB25 I/O pin input. Black means that a logic low is being read. White means that the input is either disabled or in a high-impedance state. See the Motor configuration section for more information on these pins
The Outputs table shows the state of the “tool-enable”, “tool-direction”, “fault”, “load-1”, and “load-2” pins on the DB25 I/O connector. Green means that a logic high is being asserted at the DB25 I/O pin output. Black means that a logic low is being asserted. White means that the output is either disabled or in a high -impedance state.
The Tool PWM field shows the percentage time (duty cycle) that the PWM output on the DB25 I/O connector is active.
The Fault field shows the state of the “fault” output pin on the DB25 I/O connector unless it has been disabled on the I/O configuration page. If a fault is indicated, look for messages in the Messages tab and Power Faults in the Power Faults table for more information. See the I/O Configuration section for more information on the “ fault” output pin.
See the TOOL and I/O configuration sections for more information on the behavior of these output pins.
The Power Faults table displays a variety of faults that may occur. These include
- Under voltage - If Under voltage is true, the input voltage has fallen below 11 Volts DC and the motor and load outputs have shut down. The most likely causes are:
- The power supply voltage is lower than 12 Volts.
- The power supply cannot supply enough current to support the motor and loads that are connected.
- Over voltage - If Over voltage is true the input voltage has exceeded 39 volts and the motor and load outputs have shut down. Likely causes are:
- The power supply input voltage exceeds 36 Volts.
- A motor stall has caused back EMF voltage that exceeds the energy absorbing capability of the Builbotics Controller. When this happens, the Buildbotics Controller shuts down all loads to protect the motor drivers and the power conditioning circuits.
- Over current - If Over current is true, the total current has exceeded 20 amps and the motor and load outputs have shut down. The Buildbotics Controller shuts down to protect the power conditioning circuits from overheating and becoming damaged.
- Sense error - If Sense error is true, the motor and load outputs have shut down because the initial voltage or current readings were invalid.
- Shunt overload - If Shunt overload is true, the motor and load outputs have shut down due to excessive power being routed through the internal load dump resistor. The most likely cause is that a large motor or a motor with a large inertial load has stalled and the resulting energy that is fed back has exceeded the energy absorbing ability of the Buildbotics Controller.
- Motor overload - If Motor overload is true, the motor and load outputs have shut down due to excessive current being supplied to the motors. This is likely caused by the sum of all motor currents exceeding 10 amps for several seconds. The Buildbotics Controller shuts down to prevent damage to the power conditioning circuits.
- Load 1 shutdown - If Load 1 shutdown is true, the Load 1 output has shut down. This is likely caused by the L1 output current exceeding 10 amps for several seconds. The Buildbotics Controller shuts the L1 output down to prevent damage to the power conditioning circuits.
- Load 2 shutdown - If Load 2 shutdown is true, the L2 output has shut down. This is likely caused by the L2 output current exceeding 10 amps for several seconds. The Buildbotics Controller shuts the L2 output down to prevent damage to the power conditioning circuits.
The Measurements table shows the input voltage from the power supply, the output voltage being supplied to the motor drivers, the total current being supplied to the Motors, the temperature inside the enclosure, the current being supplied to the Load 1 output and the current being supplied to the Load 2 output. Beware that none of these measurements are particularly accurate.
The RS485 Spindle table reports connection status, speed, frequency, current, and temperature as reported by the Huanyang spindle via the RS485 communications port on the DB25 I/O connector. These fields will all be zero if the Huanyang spindle is not connected.
When a webcam is connected to the Buildbotics controller, the video tab provides a display for that live video.
All source code, and hardware design files can be found on github at https://github.com/buildbotics .
Here is a list of problems that could occur. If these suggestions don ’t help resolve the problem contact us on the Buildbotics Forum ( https://forum.buildbotics.com ) or send us email at firstname.lastname@example.org .
LCD screen doesn ’t light up
LCD screen lights up, but doesn ’t boot
Gamepad doesn ’t work correctly
Can ’t access the controller from a web browser
Motor doesn ’t move
Motor turns in the wrong direction
Motor runs too slow or too fast
Motor stalls while running
Motors get hot
Can ’t view video
RS485 spindle doesn ’t work
Huanyuan Spindle doesn ’t work
PWM spindle doesn ’t work
For non-technical help or information (e.g. shipment damage, returns, …)
- Send email to email@example.com .
- Call us at 1(707)559-8539
For technical support:
- Contact us via the Buildbotics forum at forum.buildbotics.com .
- Send email to firstname.lastname@example.org .
- (last resort) Call us at 1(707)559-8539
Appendix I - Connecting and Configuring Huanyang HY01D523 Variable Frequency Drive and Spindle
Use the following steps to connect the Huanyang VFD to the Buildbotics Controller:
- Disconnect power from the Huanyang VFD and from the Buildbotics Controller.
- Connect the RS485 wiring to the Buildbotics Controller as shown in RS485 Spindle section of the manual.
- Remove the front cover from the Huanyang VFD.
- Connect the wire that is attached to pin 14 on the 25-pin breakout board to the RS+ terminal on the VFD.
- Connect the wire that is attached to pin 13 on the 25-pin breakout board to the RS- terminal on the VFD
- Replace the cover.
- Apply power to the VFD (220VAC).
Using procedure in the Huanyang manual, set the following register values:
- Set PD000 to 0 - unlock parameters
- To avoid confusion, reset the VFD to factor resets by setting PD013 to 8.
- Set PD001 to 2 - Command source is RS485
- Set PD002 to 2 - Speed source is RS485
- Set PD163 to 1 - Communications address 1
- Set PD164 to 3 - 38400 b/s
- Set PD165 to 3 - 8 Bit No Parity - RTU
- Set PD000 to 1 - lock parameters
Finally, configure the Buildbotics Controller for spindle control as described in Configuring the Spindle .
Appendix II - Connecting and configuring a spindle and controller kit to the Buildbotics Controller
Appendix III - Stepper Motor Wiring
The Buildbotics CNC Controller provides four bipolar stepper motor drivers. It cannot drive unipolar stepper motors. Fortunately, most stepper motors can be wired up as bipolar motors.
Connecting a stepper motor to a Buildbotics CNC Controller requires properly connecting the four wires from the driver to the right wires on the motor. Unfortunately, stepper motors come in a variety of configurations and it is not always immediately obvious how to hook them up. There are several characteristics that make stepper motors different from one another. One big difference is the number of wires emanating from the motor. It is not uncommon to encounter motors with 4, 5, 6, or 8 wires coming out of the motor. This article discusses each of those configurations.
The Buildbotics CNC Controller provides four motor driver outputs through the back panel on ports labeled X, Y, Z, and A. All four of these ports are wired the same and they look like this:
Each output has four pins. The upper left pin is B-, the lower left is B+, the upper right is A-, and the lower right is A+. B- and B+ must drive one of the motor coils and A- and A+ must drive the other motor coil.
Buildbotics provides pre-made cables that connect to the driver outputs on one end. These cables are color coded such that the A+ wire is red, the A- wire is black, the B+ wire is yellow, and the B- wire is purple.
Connecting 4-wire motors
Connecting 4-wire stepper motors requires connecting A+ and A- to one of the motor coils and B+ and B- to the other motor coil.
The trick is figuring out which wires make up the coil pairs. Here ’s three ways to figure this out:
- Find the documentation for the motor. Assuming you don ’t already have it, read the model number off of the motor and then search for it on the Internet. With a little effort, it is usually possible to get a datasheet for the motor. The datasheet will usually specify the wires by A+, A-, B+, and B-, or at least show which wires by color attach to which coils.
- If you can ’t find the datasheet, but have an ohmmeter, measure the resistance between any two of the motor wires. If you measure a near short, then that pair makes up one coil, and the other two wires make up the other coil. If it is an open, then measure between the first wire and another wire and then to the fourth wire until you find a near short. Notice that I say near short because the coil is a long thin wire and has some resistance. Once the pairs are identified, then arbitrarily assign one pair as “A” and the other as “B” and arbitrarily assign one wire as “+” and the other as “-” within each pair. Then connect the wires as shown. There is a 50% chance that the motor will turn backwards when connecting this way. If it does turn the wrong way simply reverse one (not both) of the pairs and the motor will turn the other direction.
- If you don ’t have an ohmmeter, most people can identify the pairs by feel. Stepper motor shafts turn fairly easily when the motor coils are open, but are more difficult to turn when a coil is shorted. First, leave all four motor coils open and turn the motor shaft to get a feel for how hard it is to turn. Then twist any two wires together. If the motor is significantly harder to turn, then you have shorted one of the coils and identified a pair. If not, disconnect the two wires from each other and connect a third wire to the first wire. If the motor doesn ’t get harder to turn, disconnect the third wire from the first wire and connect the fourth wire. One of the four combinations should be harder to turn and that is one coil and the two wires make up the other coil. Once the pairs are identified, then arbitrarily assign one pair as “A” and the other as “B” and arbitrarily assign one wire as “+” and the other as “-” within each pair. Then connect the wires as shown. There is a 50% chance that the motor will turn backwards when connecting this way. If it does turn the wrong way simply reverse one (not both) of the pairs and the motor will turn the other direction.
Connecting 5-wire motors
5-Wire motors are strictly unipolar motors and cannot be wired as bipolar motors. As such, they are not compatible with the Buildbotics CNC Controller.
Connecting 6-wire motors
6-wire motors can be configured as either unipolar or bipolar series motors. The Buildbotics CNC Controller does not support unipolar motors. The bipolar series connections are shown here.
6-wire motors have two center-tapped coils and expose the ends of the coils and the center tapped conductor of the coil. That ’s three wires for each of the two coils. The center taps are not connected and the coil ends are connected as shown. The trick is figuring out which wires belong to each coil and which of those wires are the center conductor. Here are two methods:
- Find the documentation for the motor. Assuming you don ’t already have it, read the model number off of the motor and then search for it on the Internet. You may have to call the vendor. With a little effort, it is usually possible to get a datasheet for the motor. The datasheet will usually specify the wires by A+, A-, B+, and B-, or at least show which wires by color attach to which coils.
- Use an ohmmeter to identify the individual coils. Any wires that appear to be connected through a few ohms will be part of one coil. Wires that appear to be open are part of the different coils. Arbitrarily choose one of the coils as “A” and the other as “B”. Once the coils have been identified, measure the resistance between each of the three wires on that coil. The resistance between the two coil ends will appear to be about twice the resistance between the either coil end and the coil center tap. When the coil ends have been identified, arbitrarily choose one of the ends to be “+” and the other to be “-” for each coil. Then connect the wires as shown. There is a 50% chance that the motor will turn backwards when connecting this way. If it does turn the wrong way simply reverse one (not both) of the pairs and the motor will turn the other direction.
Connecting 8-wire motors
Eight wire motors can be configured as unipolar, bipolar series, or bipolar parallel motors. The Buildbotics CNC Controller does not support unipolar connections. Before configuring an 8 wire motor, you must first decide whether to configure the motor as a bipolar series or a bipolar parallel motor. Bipolar parallel connected motors will generally provide higher top speed, but will require twice as much current as a series connected motor. A series configuration should be used if the parallel configuration current exceeds the output capability of the driver. This is especially true for larger motors. In the case of the Buildbotics CNC Controller the maximum current is 6 amps for any individual motor port.
The following diagram shows the connections to be made for an 8-wire series connected bipolar stepper motor.
The next diagram shows the connections for an 8-wire parallel connected bipolar stepper motor.
It is not realistic to sort out all of the possible combinations of connections with an ohmmeter or by feel. You need the datasheet for the motor to hook it up. Assuming you don ’t already have it, read the model number off of the motor and then search for it on the Internet. You may have to contact the vendor to get the motor datasheet. The data sheet will usually specify the wires by A1+, A1-, A2+, A2-, B1+, B1-, B2+, and B2-, or something like that. Given that information, simply wire the motors as shown in the diagrams above.
Appendix IV - GNU Free Documentation License
GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. < http://fsf.org/ >
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others .
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has n o effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
- A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
- B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
- C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
- G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
- J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
- K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
- M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
- N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
- O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties —for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Documen t is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation .
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/ .
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Soft ware Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A "Massive Multiauthor Collaboration" (or "MMC") contained in the site means any set of copyrightable works thus published on the MMC site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with … Texts." line with this:
with the Invariant
Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.