Editing Updating EBB firmware

= Introduction =

This page gives instructions on updating the EBB (EiBotBoard) firmware, which may be found on your [[AxiDraw]], [[EggBot]], [[WaterColorBot]], or any other machine using the EBB as its controller. In most cases when the firmware is compatible with the current version of the software that you are using, no update is necessary. However, there may be cases where updating allows you to take advantage of new features in the Inkscape extension, bug fixes, or new commands available.

'''Important caution 1:''' Updating your firmware will reset the EBB to its default state. If you are using a custom USB "nickname", for example with the AxiDraw Naming utility, that nickname will be reset (erased) when updating firmware.

'''Important caution 2:''' If you are experiencing difficulty connecting to your machine over USB, then please '''do not''' update its firmware until those issues are resolved.

The EBB Firmware is open source software distributed under the [https://creativecommons.org/licenses/by/3.0/us/ CC BY 3.0 US] license, with attributions described in the [[EBB_Firmware_License|EBB Firmware License]] (similar to 3-Clause BSD).

== Updater applications for Mac and Windows ==

For most users on Mac and Windows, the most straightforward way to update is to run one of our ready-built applications that updates the firmware to the latest major release. 

As of this writing, that latest major release is version 2.8.1, and firmware updaters are available to download [https://cdn.evilmadscientist.com/dl/eb/public/UpdateEBB_281_Mac.zip here for Mac] and [https://cdn.evilmadscientist.com/dl/eb/public/Firmware_v281_Win.zip here for Windows].

For either platform, connect the EBB to your computer via USB. Close any program that may be trying to communicate with the EBB then run the application, which will automatically update the firmware.

For Linux, or if you need to update to a different specific version of the firmware, please follow the "Manual" updating procedures in the next section.


== Manual updating with mphidflash ==

Besides the automatic updater applications, there are three different tools you can use to update your EBB firmware - a hardware programmer (like the PICKit2 from Microchip), Microchip's HID Bootloader application (which only runs under Windows), or the command-line mphidflash application.

Because one of the primary goals of the EBB ecosystem is to support all three OS platforms (Windows, Linux, Mac OS), this page will discuss the use of mphidflash. This application is cross platform and works identically on all three OSes.  

You will need to be comfortable with a very small amount of command line work to use this tool.

Note for Linux users: The Linux version of mphidflash was developed and tested under Ubuntu.  Other distributions may have additional dependencies. Additionally, this method requires an "x86" type architecture; it does not currently run on Raspberry Pi.
 

=== Procedure ===

* Download the latest version of mphidflash, version 1.4 or newer. It can be found in the [https://github.com/EmbeddedMan/mphidflash mphidflash repository]. There is a single zip file download that has all of the source code plus a directory (or set of directories) with executables in them, one for each OS. Unpack the zip file.
* Some hints about installing this on Ubuntu can be found [http://www.willhackforsushi.com/?p=572 here].
* Open a command shell (terminal window) and navigate (cd) to the directory with the mphidflash executable for your OS. (For Windows users, do Start->Run then type in cmd and click OK.)
* To test that the software is ready and working, try it out as follows:

:For Linux or Mac OS type

::<code>./mphidflash -h</code>

:For Windows type 

::<code>mphidflash -h</code>

: You should see the help text for mphidflash. This shows that you can run the application properly.
* Download the EBB firmware. Easy link [https://cdn.evilmadscientist.com/dl/eb/public/Firmware_v281_raw.zip here]. 
* To "manually" locate an EBB firmware version, look in the [https://github.com/evil-mad/EggBot Eggbot Repository] as "EBB_Firmware." Download the repository contents by clicking the "Download ZIP" link.  Identify the particular EBB firmware "hex file" that you want to program onto your board.  The EiBotBoard Firmware ZIP archive contains several slightly different versions: one for EBB version 1.1 (which shipped with clear-chassis kits in 2009), one for EBB 1.2, and one for EBB version 1.3 and higher-- correct for all more recent versions. If in doubt, use the "EBB 1.3" versions.
* Copy the hex file to the folder that contains the mphidflash exectuable for your OS.
* Connect your EBB to the PC with a USB cable. Plug in power to the EBB.
* Put your EBB in 'bootloader mode' by pressing the PRG button and holding it down while you press and release the RST button. Then you can let go of the PRG button.
* Confirm that your EBB is in bootload mode by looking at the red and green LEDs by the USB connector. They should be blinking back and forth pretty fast.
* From the command line, type (for Linux or Mac)

::<code>./mphidflash -w EBF_v265_BL.unified.hex -r</code>

:For Windows type 

::<code>mphidflash -w EBF_v265_BL.unified.hex -r</code>

:Where "EBF_v265_BL.unified.hex" is the name of the hex file that you want to program.
* Confirm that you get a long series of dots "." on the command line, and that there are no errors. Your EBB will reset itself at the end of the programming process (that's what the '-r' does).
* On Windows, if you have an older firmware and are updating to a relatively newer one, Windows may ask you to find a driver for the device when the EBB resets. You can install the proper windows "INF" driver by downloading and running the EggBot installer for Windows, which Installs the USB driver (the "UBW" driver) from [https://github.com/evil-mad/EggBot/releases GitHub]. If Windows says the drivers are unsigned and do you want to continue, just allow it to install them.
* After you've updated your EBB with fresh firmware, you can check to see that the new firmware was successfully programmed by opening Inkscape, going to Extensions->Eggbot..., click on the Manual tab, select "Check EBB Version" from the drop down list, and click Apply. In the little dialog box that pops up when this process is finished you should see something like "Firmware Version 2.0.2" or whatever your version number is.