Firmware Update

This documentation is written based on my own experience, using a Windows 7 computer. 
If you are using a different version of Windows, you may see different directory structures,
and if you have Win 8 you may need to perform some other steps not documented here to
make your computer accept the installation of “unverified” software.

NOTE:  While the overall information in this Wiki entry has some value, recent updates to both Arduino and Teensyduino have rendered the
specifics of file numbers etc. obsolete.  thawkins is posting on the forum about a whole new method using different software.  You will use
Visual Studio or Eclipse to do your source-code editing (much better than the Arduino IDE) and then platformio to do the compiling and 
uploading. (Edit Aug 4, 2015)

I could not have performed these operations and prepared this document without the
patient help of PxT.

WHAT IS FIRMWARE? WHAT IS FIRMWARE FLASHING?

Firmware is the program that runs inside the Printrbot. Unlike most desktop and laptop computers, which use disk drives to store their programs, the firmware in the Printrbot is stored in “Flash” memory. Flash memory is not lost or changed when the power is turned off and back on again, but it can be changed intentionally by the user if certain steps are followed.

The Printrbot firmware is a member of an open-source 3D printer program family called Marlin. It controls the motors, the heaters, and the fan. It receives inputs from the thermistors and the “end stop” switches. If so equipped, it can receive input from, and send data to, an LCD display with one or more control switches. The firmware also receives input in the form of G-code commands and inquiries from the USB port – or G-code commands from an SD card. The firmware’s “native language” is G-code.

Note: a small section of flash memory is dedicated to calibration constants and the like; this is what we call the “EEPROM.” The Atmel and Arduino environments anticipate and enforce a strict division between EEPROM and Program Memory. In the Printrbot software, there are G-code commands to change the calibration constants etc. in EEPROM under program control, but Program Memory itself is not modifiable by G-code.

Note: There are variants of G-code. A reference with fairly good descriptions of the commands is here: http://www.reprap.org/wiki/G-code An official list for our version of Marlin is here: https://github.com/ErikZalm/Marlin

WHY WOULD YOU WANT TO “FLASH” IT?

If your Printrboard is not working at all, or exhibiting bizarre behavior, you might want to try reprogramming the firmware; this is called “flashing” the chip. Or, you may wish to change the way it works. However many key parameters are stored in the G-code accessible section of EEPROM, so don't assume you need to re-flash until you have examined all the options that are already available to you.

SHOULD YOU USE PRE-COMPILED OR MODIFY IT YOURSELF?

This is something like the difference between downloading an STL file from Thingiverse compared to designing your own object with a CAD program. There is a big learning curve to doing it yourself, but you have much more freedom to design when you do it yourself.

In software, the equivalent of the STL file is a “hex” file – a file that’s been “pre-compiled” and is ready to flash into the Program memory. If you are just repairing the firmware on a board that has become corrupted somehow, you don’t need to have the “source code” and compile it; you can just “flash” a hex file directly. There are several “pre-compiled” versions of programs for the Printrbot. Printrbot.com makes them available on their web site, and there are other versions available on Github. (Finding files on Github can be challenging for beginners, but using Github is not within the scope of this topic. However, here is an example link to several recent versions of the Printrbot firmware: https://github.com/Printrbot/Marlin/releases).

Note that the Marlin firmware and Printrbot implementations of Marlin are under continuous development. Not all versions of Printrbot firmware are compatible with all models of Printrbots.

Here are some of the variations known as of early 2015:

1. There are differences in how different models of Printrbot define "home" on the Y axis (some are at Y=0 and some are at Y=max).
2. Printrbots made since about mid 2104 have active probes for detecting the bed and performing a geometric correction if the bed is not parallel to the X-Y plane of motion of the printhead; earlier Printrbots just used a simple single-point switch to detect Z=0.
3. Versions of firmware prior to the "Unified" version did not have the M211 and M212 commands used to set the bed dimensions and printhead offset.
4. The Printrboard Rev F was released in late 2014. Firmware for the Rev F board is not compatible with firmware for the earlier versions of the Printrboard (mainly Rev D), and firmware for the earlier versions is not compatible with Rev F boards.

Printrbot.com has a list of which versions of the firmware are compatible with each of the Printrbot models.

If you download a pre-compiled hex file, take a note of the directory where you can find it.

Note: Software is written in some form of human-understandable code. In the case of the Printrbot, the code is written in the C language or its variants (except for a few sections of code written in “assembly” language). The program is really very large, so programmers take advantage of previously-written “libraries” of code, piecing together the functions they want as much as possible from code that is known to be functional, so that they only have to write a smaller part of the code that is brand new and original.

However, computers can’t operate directly on C code; they require “binary” code. So there are programs which transform C code into binary code; these programs are called “compilers” and they can be a bit complex to use.

WHAT IS A BOOTLOADER?

A “bootloader” is a small program that computers use to load their operating software into memory (from the expression “pull yourself up by your bootstraps”). In the case of a computer which runs its program from flash memory, the bootloader provides a convenient way for the user to re-program the flash memory. However, there are several different bootloaders that have been used on Arduino boards, and even boards sold as “Printrboards.” The common ones are called “CDC” and “DFU.” Official Printrbot Printrboards use the DFU bootloader, which has the ability to handle larger Programs than CDC. It is not directly compatible with the Arduino Integrated Development Environment, which is why we need to use FLIP.

Technically, for the very adventurous there is another way to program the Flash memory by using a hardware connection directly to the board instead of the USB port. That approach is not within the scope of this document.

SUMMARY OF MEMORY AREAS IN A PRINTRBOARD

Name	type	content	How it gets changed
Program Memory	Flash	Program to control Printrbot	Using FLIP
EEPROM	Flash	Calibration constants and the like	Under Program control, with M500 command, or by selecting EEPROM in FLIP
RAM (random-access memory)	Static RAM (loses content when power lost)	Active Values for Calibration, stepper counters, etc.	Under Program control
Bootloader	Flash	Used to load Program from USB port	Requires hardware connection to be changed

So the good news is you can't unintentionally damage the bootloader, and EEPROM will be left alone by FLIP unless you actively select to change it.

FLASHING A COMPILED (HEX) VERSION

CAUTION: SAVE YOUR EEPROM VALUES BEFORE FLASHING

Technically, the EEPROM space does not get overwritten when you flash. But if the new software uses the EEPROM differently (like adding new variables) then it will have a new “EEPROM Version Number” and the firmware will use the “Factory Default” (Program Flash) values until you do a new M500 Write to the EEPROM; then the contents and the Version Number will be compatible with the new version. So it’s safest to make a record of all your EEPROM values before you flash new firmware.

After you flash a new program, you can tell whether the program is using EEPROM or Flash memory for its variables by issuing an M501 command. The first line returned will tell you.

"Stored Settings Retrieved" if it got the values from EEPROM or "Hardcoded Default Settings Loaded" if it got the values from FLASH.

HOW TO FLASH A HEX PROGRAM FILE TO THE PRINTRBOARD FROM A MAC COMPUTER

See the guide written by PxT here

HOW TO FLASH A HEX PROGRAM FILE TO THE PRINTRBOARD FROM A LINUX COMPUTER

See the guide written by wd5gnr here

HOW TO FLASH A HEX PROGRAM FILE TO THE PRINTRBOARD FROM A WINDOWS COMPUTER

This flash procedure applies both to hex files you download from the Internet and to hex files you create yourself.

Download & install FLIP from Atmel.com. http://www.atmel.com/tools/FLIP.aspx This comes with instructions on how to install and use it.

Connect to the Printrboard, install a boot jumper, and press the Printrboard’s reset button. (If you don’t have an official “boot jumper” then any means of connecting these two pins electrically will work, such as a small alligator clip or even a modified paper clip. Just be sure not to contact anything else than these two pins because short circuits on the board in the wrong place could damage it.) You can (probably should) leave the jumper in place while flashing.

Note: If your Printrboard is Rev B or C, remove the boot jumper, and replace it when finished flashing

The first time you do this, the USB device will be unrecognized. Windows will try to find a driver for it, but won’t succeed. You may even have to “cancel” the installation of the device driver. Then you can go to Device Manager, find the USB device with a yellow caution triangle, and tell Windows to use the USB driver that comes with FLIP. This is probably located at

C:\Program Files (x86)\Atmel\Flip 3.4.7\usb\atmel_usb_dfu.inf

You only need to do this once.

Now that the Printrboard is connected to a Windows-recognized USB port, run FLIP and get it configured. Under “Device” select “AT90USB1286”. Then click on the USB Plug icon, select USB communications, and “Open;” this should connect FLIP to the board, indicated by several of the icons turning “active” instead of grayed out.

Load your .hex file from the location where you previously saved it (either as a download from the Internet or from your own compilation). Set options to Erase, Confirm, Program, and Verify. Click Run.

After the new program is flashed, you can remove the boot jumper and press Reset again. This will take you back to the normal mode of interfacing through Repetier or Pronterface, etc.

Note: If your Printrboard is Rev B or C, replace the boot jumper and press Reset again.

Note: Even though the FLIP program seems to give you the option to copy the existing hex file from the Printrboard to FLIP (and then to save it as a backup), this option is NOT available in the Arduino environment. You could copy the file back from the board immediately after flashing – but that would be pointless. As soon as the “bootloader” exits, then there are “lock” bits which get set and prevent uploading the firmware from the Printrboard back into FLIP.

____________________________________________________________________________

IF YOU WANT TO MODIFY THE CODE YOURSELF, DO YOU NEED TO BE A C PROGRAMMER?

No, many interesting options are available in sections of the program called “Declarations.” These options allow programmers to write programs with great flexibility, like for different 3D printers, and to change all the important “settings” by changing the Declarations. Think of it as a greatly expanded EEPROM – but in this case the settings will be “burned” into the firmware and are not user-changeable after flashing.

Most of the important Declarations are in files of a type called “header” files, indicated by the simple suffix “.h” Configuration.h and Configuration_Adv.h are the most important ones.

As a matter of self-preservation, I recommend that you make a copy of any file you are changing, and then enter comment information into the first line or two of the modified file so that you know what has been done. For example, copy “Configuration.h” into “Configuration.h.orig” and then make your modifications to Configuration.h.

It may take a little getting used to how these files work, so I’ll give a few examples.

// Actual temperature must be close to target for this long before M109 returns success
#define TEMP_RESIDENCY_TIME 10  // (seconds)
#define TEMP_HYSTERESIS 3       // (degC) range of +/- temperatures considered "close" to the target one
#define TEMP_WINDOW     1       // (degC) Window around target to start the residency timer x degC early.

Anything following a double slash “//” on a line is a comment and is ignored by the compiler. The directive “#define” means that what follows is the definition of a variable name followed by a constant value. Everywhere in the program that the variable name is encountered, the compiler will automatically substitute the value given here.

So if we wanted to decrease the residency time waiting for the temperature to stabilize, we could change the #define to say:

#define TEMP_RESIDENCY_TIME  5  // (seconds)

Another example: the software reports its Version when you connect to Repetier (or Pronterface, etc.) – which issues an M115 command at connection time to query for the version. The Version identification is a string in a file called “Language.h” The code shown below has been "word wrapped" for better visibility; in the program it's all on one line.

#define MSG_M115_REPORT "FIRMWARE_NAME:Marlin V1; Sprinter/grbl mashup for gen6
FIRMWARE_URL:" FIRMWARE_URL " PROTOCOL_VERSION:" PROTOCOL_VERSION
" MACHINE_TYPE:" MACHINE_NAME " EXTRUDER_COUNT:" STRINGIFY(EXTRUDERS) "\n"

It is suggested that you edit this line to indicate your own modifications. It’s safest to change only things that are surrounded by double quotes, e.g.

#define MSG_M115_REPORT "FIRMWARE_NAME:Marlin V1; Sprinter/grbl mashup for gen6
Modified by XX on date FIRMWARE_URL:" FIRMWARE_URL " PROTOCOL_VERSION:"
PROTOCOL_VERSION " MACHINE_TYPE:" MACHINE_NAME " EXTRUDER_COUNT:" STRINGIFY(EXTRUDERS) "\n"

WHAT’S ARDUINO?

The Arduino concept was developed in Italy, starting around 2005. It’s a family of simple, inexpensive single-board computers intended for students and hobbyists. They are built around single-chip computers made by Atmel.

http://en.wikipedia.org/wiki/Arduino

Arduino is now a commercial company that sells boards, and the Arduino Integrated Development Environment (IDE) software is designed to support their boards. A feature of true Arduino boards is that they can be programmed (flashed) directly from the Arduino software running on a host computer.

The Printrboard is not designed or sold by Arduino, even though it is a VERY close relative. Its DFU bootloader is not compatible with the Arduino IDE. So even though the Arduino program will expect you to copy your compiled program into Program Memory using facilities built into the IDE, it won’t work that way. You must instead save the hex file in a safe place and then use FLIP to copy the hex file into Program Memory.

WHAT’S AN INTEGRATED DEVELOPMENT ENVIRONMENT?

An Integrated Development Environment (IDE) is simply a single program which gives you several useful functions for software development in a single “package.”

• The Arduino IDE gives you a specialized Editor which knows the C syntax and displays the content of program source code in a convenient color-coded format.
• The IDE also is “aware” of all the links to other files that constitute the entire body of source code, and it makes these “visible” as tabs so that you can easily explore and move around within the source code.
• The Arduino IDE is specialized for Arduino-compatible boards, so it incorporates some hardware and software compatible specializations that are not normally present in C compilers or IDEs.
• The IDE includes a Compiler so you can create “Object” code (hex files) directly from within the IDE.
• The Arduino IDE also is capable of directly writing the object code to a compatible Arduino board connected to your computer. However, this feature does not work with the Printrboard; you need to use a separate program to copy the hex file to the board. In a Windows environment, this program is FLIP.

NOTE: The Arduino IDE developers evidently did not anticipate programs with as many modules as are contained in the Marlin software. The IDE window shows a large number of tabs for program modules, but it does not show all of them. There is a “down arrow” on screen at the right side of the tabs which opens up a vertical list of modules, but even this vertical list still can’t display all the modules in the program. The way to access every module is to use a combined keystroke: <CTRL><ALT><right or left arrow>.

HOW TO INSTALL THE VERSION 0022 ARDUINO INTEGRATED DEVELOPMENT ENVIRONMENT

Downloaded a pre-configured Arduino IDE build environment from the following:

http://www.reprap-usa.com/download/arduino0022.zip EDIT: This link no longer works.

(EXPLANATION: Pre-configured means that it knows about the Printrboard. The native "pure" software from the Arduino company does not support the Printrboard. There are "extensions" needed for the Arduino software to work with the Printrboard. You can “build” the complete package as described in the next section; alternatively, the "pre-configured" package from reprap-usa includes the basic Arduino software as well as the "extensions" all bundled into one zip file.)

Unzip the file and copy all of the contents into C:\Program Files (x86)\Arduino

NOTE: This pre-built program does not have a Windows “Installer;” if you want to have an icon for it on your desktop or in the Start menu, you will have to do that yourself. Same goes for “file associations.”

The program works. You can run it. You need to find and select the required "Teensylu/Printrboard" board configuration to use as your board.

Caution:  it may not work with all the latest releases of Marlin software.  It’s recommended to use the latest Arduino environment.

You can use the Shift key when compiling so that you can find where the compiler put the .hex file. You MUST copy the hex file to another location BEFORE closing the IDE.

So what's the problem?

The Arduino program picks up on the fact that it's not the latest release. The 0022 version does not have as many options as the newest version; for example it is missing the "Verbose output" option. So the running 0022 program offers to go to the Arduino web site to download and install the latest version. This is optional. To do so, you need to follow the much more complex IDE installation instructions below.

HOW TO INSTALL THE 1.05 or 1.06 ARDUINO IDE IN FOUR STEPS

(Note: Originally I used 1.05, but it has been reported to me that 1.06 is required now, at least on some systems.)

EDIT: The following sequence and version numbers are out of date. It may be better to follow the instructions at https://www.pjrc.com/teensy/td_download.html for steps 1 and 2. Also see http://www.printrbottalk.com/forum/viewtopic.php?f=15&t=10876#p70107 for further comments. Also, I (Retiree Jay) now recommend using Notepad++ as the editor and PlatformIO for compilation. See http://www.printrbottalk.com/forum/viewtopic.php?f=22&t=10160, which is not organized and unified but it has lots of good information.

‘’’1)’’’ Download Arduino 1.05 or 1.06 From http://www.arduino.cc Follow the installation instructions. Note the address where the program is stored. This is probably

C:\\Program Files(x86)\Arduino

(If it’s different, then apply the appropriate changes to directories mentioned below.)

NOTE: This IS done with a Windows “Installer” so you will get your desktop and Start menu icons. You still may need to set up file associations.

‘’’2)’’’ Download Teensyduino from the “download and install” link at http://www.pjrc.com/teensy/teensyduino.html Follow the installation instructions, referring to the Arduino program directory if asked. (Note: You MUST have the Arduino system installed first.) You will be asked if you want to install a USB driver; it’s safe to say yes to this. You will also be asked if you want to install any of several libraries; do NOT install any of them. When you tell the installation to proceed, it will take quite a long time to complete the installation; be patient.

‘’’3)’’’ Download http://blog.lincomatic.com/wp-content/uploads/2012/03/at90usb1286txt.zip Unzip the file and you will find three files inside, “boards.txt,” “boards.txt.nopjrc,” and “programmers.txt.” Copy the files from this download into the

C:\\Program Files(x86)/Arduino/hardware/teensy

directory, overwriting the original "boards.txt"

‘’’4)’’’ Rename the directory

c:\Program Files(x86)\Arduino\hardware\teensy\cores\teensy

to

c:\Program Files(x86)\Arduino\hardware\teensy\cores\at90usb1286.

You should now have a working Arduino IDE which can be used to compile code for the Printrboard.

HOW TO EDIT AND COMPILE, PREPARING A HEX VERSION

Using the Arduino IDE, do a File Open and select Marlin.pde. This will load a file that in turn links to dozens more files to create the complete Marlin program. This includes the Configuration.h file that you may have modified.

Using the Tools menu, select the target Board. A long list will open up; select an entry that includes the word “Printrboard” (and if more than one Printrboard choice is presented, don’t use one mentioning the CDC bootloader).

Click the arrow in the upper-left corner that says “verify” on the tooltip. The Arduino program will then perform a “compile” operation; this will take a minute or two. If you have selected “verbose” mode (or held the shift key when pressing the verify arrow) then you will see lots of activity scrolling in the log window at the bottom of the screen. There will be many lines printed out in red, saying “Warning…” and many other lines printed out in white. It’s safe to ignore the Warnings. If your program compiles without Errors then the very last line you see in the log file will be the location and file name of the finished hex file.

Arduino (and Teensyduino) want to load the firmware onto your board all by themselves. But there is an incompatibility, which is why we use FLIP instead. So you need to make the hex file that Arduino creates available for FLIP.

BEFORE YOU CLOSE THE ARDUINO IDE, use your File Manager to copy the finished hex file from the temp directory where it resides to another directory of your choice. You will need to know this location when you open FLIP to flash the board. Then it’s safe to close the IDE. Follow the steps above in the Flashing Firmware section to flash this new hex file image into your Printrboard.

Currently the Teensyduino add-ons to the Arduino software (which are pre-bundled above) work up to Arduino v1.05. They will not work with the Arduino BETA which is available.