Introduction

Each of the various projects on the Schmalz Haus website (for UBW, UBW32, EiBotBoard, etc.) is provided in both source form and as a compiled HEX file. In order to complile the source code yourself, you may need a little help in understanding what tools (compiler toolchain) is necessary, and how to set things up so you can build and then modify the code yourself. This page describes the tools and process necessary to build Schmalz Haus projects. This page speaks about the UBW32 but applies equally to all boards (and all projects).

Microchip makes integrated circuits. They make the microcontroller that is on the UBW, UBW32 and EBB. They also give away (and also sell) the software necessary to write programs for their microcontrollers. To write software for these parts you can use Microchip's free tool chain, which consists of an IDE, a compiler and (for most projects) an applications library. The applications library consists of header files and C files for several types of software, including a USB stack, a TCP/IP stack, a graphics library, and several others. Also included in the Microchip Applications Library (which is what they call it - or MAL) are lots of example projects to get you started programming with their microcontrollers and software libraries. For example, the UBW, EBB and UBW32 are built on the Microchip USB CDC example project as a starting point.

Because Microchip wants their application libraries to be as generic as possible, they came up with a certain folder structure that your projects must abide by in order to compile properly. For the sake of simplicity I have chosen to change that folder structure somewhat. This web page describes how my projects can be built with free Microchip tools, and the slight modification to the stock Microchip Application Library way of doing things that you need in order to compile the your projects properly.

If you choose to download the whole Microchip Application Library, you will get a C:/Microchip Solutions folder that contains a lot of example code, some documentation, and a folder called Microchip. Inside this Microchip folder are all of the actual files for the various software libraries. It is this Microchip folder that is used for building UBW32 projects. It contains both the USB stack header files as well as the source code files necessary to compile the whole USB stack, which is used for almost all UBW32 projects.

The whole reason this folder hierarchy exists this way is so that you can have multiple projects all referencing the USB stack (or graphics library or whatever) without having to have separate copies of these stacks for each project. Since they are common to all UBW32 projects, you only need one copy of them, and this also makes updating them with newer versions much easier.

Cross platform note:

All of the Microchip tools are currently Windows only. However, this situation is going to change in the very first part of 2011. A new version of MPLAB (called MPLAB X) will become available on Windows, Mac OS and Linux, and all compilers will be released on all platforms, so you can build these projects on any machine.

UBW32 Build Instruction Document

Cadet Lieutenant Adam Schinder was kind enough to allow us to share his document "How To Compile Projects for the UBW32" - if you're having trouble figuring out how to build the example projects, or your own fimrware for the UBW32, his doc may help you out.

Tools Needed to Build Schmalz Haus firmware projects

In order to compile and download any of the projects from this website, you will need to download and install the first two tools (MPLAB and C32 or C18) and then choose either the full MAL or just the Microchip directory and the separate bootloader applications:

• MPLAB

This is Microchip's free IDE. Download and install it.

• C32 (For UBW32)
  
• C18 (For UBW and EiBotBoard)
  

These are Microchip's C compilers for PIC32 (C32) and PIC18 (C18) architectures - use the LITE version if you want. Download and install the proper one for the type of project you want to build.

• Microchip Application Library (MAL)
  

This is a big file of everything from Microchip for USB, SD card, graphics, TCP/IP, etc. It is set up for all Microchip PICs (8,16 and 32 bit) If you don't want to download this whole zip file and expand it, just grab the Microchip.zip file below (it is slightly smaller) which is all you really need. Make sure to put the Microchip folder in the right spot so your project will compile properly. (See below for instructions on where to put it.)

• Microchip Folder from Microchip Application Library (Microchip.zip) with USB stack v2.9j (from MAL 2013-16-15)
  

This is just the Microchip folder from the MAL and it's all you really need. (This is the whole Microchip folder from MAL, but none of the example projects from MAL.)

• PDFSUSB.exe - version 1.0.0
  

You only need this if you are using the Microchip Custom Class bootloader (which comes standard on the UBW board). This application runs on the PC and communicates with the UBW over USB to download new firmware. This application is contained in the MAL and will be installed to C:\Microchip Solutions\USB Tools\Pdfsusb\PDFSUSB.EXE if you download an install the full MAL. Or you can just download the exe from the above link.

• HIDBootloader.zip - version 2.9j
  

You only need this if you are using the Microchip HID Bootloader (which comes standard on UBW32 and EBB boards) to download new firmware over USB. This application is contained in the MAL and will be installed to C:\Microchip Solutions\USB Device - Bootloaders\HID - Bootloader\HIDBootloader.exe if you download and install the full MAL. Or you can just download the exe from the above link.

Directory Setup Instructions

I have set up all of my projects on the UBW, UBW32 and EBB pages to build with the Microchip folder (which contains the headers and C files for the USB stack) to be in the same folder as the project folder. You must set your file system up the same if you want the projects to compile without modifying them. The name of the top level folder does not matter, only that the Microchip folder and the project folder are in the same directory together.

For example, if your top level folder is called "Projects", and the folder that contains the UBW32 project is called "HelloUSBWorld", then you would need the following folder structure:

Projects

   |

   +--> HelloUSBWorld

   |       +-->All project files like *.mcp, *.mcw, *.c, *.h, etc.

   |

   +-->Microchip

           +--->Include

           +--->USB

           +---> etc.

The reason things need to be this way is that the project *.c and *.h files reference files in the Include and USB folders that are inside the Microchip folder, and they need to be located in the proper relative path in order to compile properly.

You can just add more project folders into the "Projects" folder (for example, HelloWorld, or Firmware D, etc.) and they will all reference the USB stack that is in the Microchip folder.

In the above Tools links I have included a link to just the Microchip folder as a zip file so that you can just download it and not the whole MAL to save time.

Build And Program Steps

1. Open MPLAB
2. Load project into MPLAB
3. Press F10 to compile.
4. Put device into bootloader mode (press and hold PRG or PROGRAM button while pressing and releasing RESET or RST button. Then release PRG button)
5. Use PDFSUSB.exe (for UBW) or HIDBootloader.exe (for EBB and UBW32) on your computer to download the HEX file that was just created by the build
6. Reset the board to run your new code

UBW32 Linker file and the HID Bootloader (For UBW32 projects only)

You must be sure to have the procdefs.ld file in your project folder when you build your firmware application for the UBW32 if you are going to download it using the HID Bootloader (which is the standard way for download programs into the UBW32). This file, if present (and named exactly that) will tell the C32 linker to reserve the proper space for the HID bootloader in the resulting HEX file. This file is contained in each of the UBW32 project folders that is on this website. HOWEVER- you must never add the procdefs.ld file to your actual MPLAB project (i.e. don't add it to the Linker folder inside MPLAB). Doing this will result in a HEX file that won't run.