FreeEMS-Workstation-Howto.tex

\documentclass[12pt,notitlepage,onecolumn,oneside,openany]{memoir}
\usepackage{amsmath,color,examplep,hyperref}
\textwidth=7.0in
\textheight=9.5in
\topmargin=-0.5in
\headheight=0in
\headsep=0.3in
\oddsidemargin=-0.35in
\evensidemargin=-0.35in
\title{\textsf{FreeEMS Workstation HowTo}}
\author{\textsf{Andy Goss}}
\date{\textsf{07/16/2012}}
\begin{document}
\maketitle

\centerline{\textbf{\textsf{This document assumes you are starting with a blank hard drive.}}} 
\centerline{\textbf{\textsf{\textcolor{red}{This means NO OPERATING SYSTEM}.}}}
\\
\textcolor{white}{\textsf{xyz}}
\\
\centerline{\textbf{\textsf{Make sure you start with Chapter 1, Step 1 and do not skip any steps.}}}
\centerline{\textbf{\textsf{\textcolor{red}{They are in this order for a reason!}}}}
\\
\textcolor{white}{\textsf{xyz2}}
\\
\textsf{The purpose of this document is to describe how to setup an Intel or AMD PC with 1 Tb HDD to Dual Boot Windows and Debian Testing (Wheezy) Linux for the average computer user.  The author assumes that the user has installed Windows at least one or more times as instructions for the exact process of installing Windows will not be shown.} \newline
\\
\textsf{Please read through the ENTIRE document before beginning the installation process to make sure you fully understand each step of the process.  The author is not responsible for any actions resulting from you the user following the instruction contained in this HowTo. This is a free world with no strings attached and YOU are responsible for YOUR actions.} \newline
\\
\textsf{To quote Morpheus from the movie "The Matrix": "This is your last chance. After this, there is no turning back. You take the blue pill - the story ends, you wake up in your bed and believe whatever you want to believe. You take the red pill - you stay in Wonderland and I show you how deep the rabbit-hole goes."} \newline
\\
\textsf{I am only your guide, you must make the decision to take the red pill or blue pill...} \newline
\textsf{So if you decide to take the red pill and follow the white rabbit to the land of penguins...} \newline

\pagebreak 

\tableofcontents

\newpage 

\chapter{\textsf{Step 1:  Install Windows and Apps}}
\begin{enumerate}
\item \textsf{Install Windows on half of the HDD space by creating an ~500 Gb partition during the Windows installation.}
\textsf{This can be either Windows 32bit or Windows 64bit.  I won't go into detail of how to install Windows, if you aren't familiar with the install process try http://www.google.com.  After Windows has been installed and updated, continue to the next step.}

\item \textsf{We need to install CodeWarrior so that we can load the Serial Monitor program onto the Freescale mc9s12xdp512 microprocessor.  We really aren't interested in the CodeWarrior IDE as a development platform, but we need the HiWave Debugger to flash the Serial Monitor program onto the blank MCU and it is included in the CodeWarrior download and installation process.}\newline
      \textsf{Download and install CodeWarrior for HCS12(X) Microcontrollers (Classic) IDE :} \newline
      \url{http://cache.freescale.com/lgfiles/devsuites/HC12/CW_HC12_v5.1_SPECIAL.exe}

\item \textsf{Download PE Micro's free Unsecure-12 utility for the HCS12(X) MCUs in case you get the Freescale MCU stuck in a Secured state. You can download it here after you register for a free account:} \newline
\url{https://www.pemicro.com/login.cfm?from_url=/downloads/download_file.cfm?download_id=16}

\item \textsf{To use a USBDM/TBDML debug module (USBDM is preferred) with the HiWave debugger then you can clone my github repository which contains the complete information on how to build one and program it along with the Windows 32-bit driver that works with WinXP, Vista and Windows.} 
\begin{itemize}
      \item \textsf{Here is a link to my repository:} \newline
            \url{https://github.com/DeuceEFI/TBDML-12f-GPL}
            \url{https://github.com/DeuceEFI/USBDM}
      \item \textsf{Once you plug in the USBDM/TBDML device into the USB port on your computer, Windows will ask for the location of the driver.} 
      \item \textsf{The Windows 32bit driver for the USBDM is located in the \PVerb{USBDM Driver Installer} directory} 
      \item \textsf{The Windows 32bit driver for the TBDML is located in the \PVerb{bin_tbdml_win_driver_11} directory} 
       
\end{itemize}

\item \textsf{Search for and create a shortcut on your Desktop for hiwave.exe} 
\begin{itemize}
      \item \textsf{Open the shortcut to hiwave.exe that you just created.}
      \item \textsf{The defualt path to hiwave.exe on a 32bit system is:} \newline
            \PVerb{C:\Program Files\Freescale\CWS12v5.1\Prog\hiwave.exe} 
      \item \textsf{The defualt path to hiwave.exe on a 64bit system is:} \newline 
            \PVerb{C:\Program Files(x86)\Freescale\CWS12v5.1\Prog\hiwave.exe}
      \item \textsf{Click on Connection then click on Load..., then click on the Yes button} 
      \item \textsf{For Processor, select HC12.}
      \item \textsf{For Connection, select TBDML.}
      \item \textsf{For the Set Derivative, select MC9S12XDP512.}
      \item \textsf{Now your HiWave debugger is setup to use the TBDML debug module with the Freescale MCU.}
\end{itemize}

\item \textsf{\textbf{Follow these instructions to setup Unsecure-12 in the HiWave debugger to perform the Unsecure task.}}
\begin{itemize}
      
	\item \textsf{Next click on \textbf{TBDML HCS12} then click on \textbf{Command Files}} \newline
	      \textsf{All the files below should be located in:} \newline
		  \PVerb{C:\Program Files\Freescale\CWS12v5.1\(CodeWarrior_Examples)\HCS12X\BankedData\cmd\}
		
	\item \textsf{Click on the \textbf{Startup} tab, then click the \textbf{Browse...} button and locate the} \newline
              \textsf{\textbf{P\&E\_ICD\_Startup.cmd} file, click the \textbf{Open} button, \newline
 			then click the checkbox for \textbf{Enable Command File}.}
              
	\item \textsf{Click on the \textbf{Reset} tab, then click the \textbf{Browse...} button and locate the} \newline
              \textsf{\textbf{P\&E\_ICD\_Reset.cmd} file, click \textbf{Open} button, \newline 
			then click the checkbox for \textbf{Enable Command File}.}
              
	\item \textsf{Click on the \textbf{Preload} tab, then click the \textbf{Browse...} button and locate the} \newline
              \textsf{\textbf{P\&E\_ICD\_Preload.cmd} file, click \textbf{Open} button, \newline
			then click the checkbox for \textbf{Enable Command File}.}
              
	\item \textsf{Click on the \textbf{Postload} tab, then click the \textbf{Browse...} button and locate the} \newline
              \textsf{\textbf{P\&E\_ICD\_Postload.cmd} file, click \textbf{Open} button, \newline
			then click the checkbox for \textbf{Enable Command File}.}
              
	\item \textsf{Click on the \textbf{Vppon} tab, then click the \textbf{Browse...} button and locate the} \newline
              \textsf{\textbf{P\&E\_ICD\_Vppon.cmd} file, click \textbf{Open} button, \newline
			then click the checkbox for \textbf{Enable Command File}.}
              
	\item \textsf{Click on the \textbf{Vppoff} tab, then click the \textbf{Browse...} button and locate the} \newline
              \textsf{\textbf{P\&E\_ICD\_Vppoff.cmd} file, click \textbf{Open} button, \newline
			then click the checkbox for \textbf{Enable Command File}.}
              
	\item \textsf{Click on the \textbf{Unsecure} tab, then click the \textbf{Browse...} button and locate the} \newline
              \textsf{\textbf{P\&E\_ICD\_Erase\_unsecure\_hcs12.cmd} file, click \textbf{Open} button, \newline
			then click the checkbox for \textbf{Enable Command File}.}
              
    \item \textsf{Click on the \textbf{OK} button to save your changes.}
\end{itemize}
\end{enumerate}

\chapter{\textsf{Step 2: Download and create Linux boot media}} 
\textsf{In this step you will need to download and create the appropriate boot media for Debian Testing (Wheezy) 32 bit.
You have a couple of options here, you can either go the route of Method \#1: (download a .iso file and make a CD to boot from) or you can follow Method \#2 (use unetbootin to make a bootable USB Thumb drive).} \newline

\begin{enumerate}
\item \textsf{Download a disk image .iso file of your Linux distribution of choice, here are a few links:} 

\begin{list}{•}{•}
\item \textsf{Debian Testing 32bit CD images:} \newline
\url{http://cdimage.debian.org/cdimage/weekly-builds/i386/iso-cd/}
\item \textsf{Debian Testing 32bit DVD images:} \newline
\url{http://cdimage.debian.org/cdimage/weekly-builds/i386/iso-dvd/}
\end{list}


\textsf{With any of the above .iso files use the CD burning software of your choice to make a bootable CD-ROM to launch the installer. Or you can also use unetbootin as in Method \#2 and follow these directions:} \newline
\url{http://unetbootin.sourceforge.net/#other} \newline
\textsf{to create a bootable USB Thumb drive from the .iso file that you downloaded.}

\item \textsf{Download unetbootin from:} \newline
\url{http://unetbootin.sourceforge.net/unetbootin-windows-latest.exe}\newline
\textsf{Run the unetbootin-windows-latest.exe file while the computer is running from its Windows partition and follow the instructions at:} \newline
\url{http://unetbootin.sourceforge.net/#install} \newline
\textsf{to create a bootable Debian 32bit USB Thumb drive.}
\end{enumerate}

\chapter{\textsf{Install Linux}}

\textsf{Insert the boot media you created in Chapter 2 to install Debian Testing (Wheezy) on the remaining ~500 Gb HDD space.  Now reboot your computer making sure to choose the boot media you just created.} \newline

\begin{enumerate}
\item \textsf{To reduce reduce the number of steps, this example begins at the step where disk detection starts after you have gone through the basic steps of the graphical installer. 
Select “Manual.”  Click Continue.}

\item \textsf{Here, the installer should show either 1 NTFS partition for Windows XP or the 2 NTFS partitions for (Windows Vista or Windows 7) . As you can see, there is free, or unallocated space. Select FREE SPACE, then click Continue.}

\item \textsf{Scroll to “Create a new partition.” Continue.} 

\item \textsf{By default the /boot partition on Debian Testing is allocated a disk space of about 250 MB. Most Linux distributions use 500 MB. I think 1000 MB will do just fine for my system. Continue.}

\item \textsf{If you are installing Debian to dual boot with Windows XP, you do not need to follow any further steps until step 49 so you can skip to step 49 now.  If you are installing Debian to dual boot with Windows Vista or Windows 7, continue to the next step.}

\item \textsf{In Linux, you cannot create more than four primary partitions. And since we already have two primary partitions (for Windows Vista or Windows 7), the installer will by default want to create the first and subsequent Debian partitions as logical partitions. The partition numbers will, therefore, start at 5. The boot partition, which is the first one we are creating, will be /dev/sda5. Note this carefully, because GRUB will be installed on this partition for reasons that I will explain when we get to that step. Click Continue.}

\item \textsf{Click on Logical. Click Continue.}

\item \textsf{Click on Beginning. Click Continue.} 

\item \textsf{On this next Partition Disks screen, select the "Use as:" "Ext3 journaling file system" and "Mount point:" "/boot" for the new partition. Then scroll to “Done setting up the partition.” Click Continue.}

\item \textsf{With /boot created. you can now create other partitions. For this example, I am going to create LVM partitions.}
 
\item \textsf{Select the free space and click Continue.}
 
\item \textsf{Click on “Create a new partition.” Click Continue.} 

\item \textsf{Since this partition will be used as a Physical Volume for LVM, it is okay to use all available space on the disk. Click Continue.}
 
\item \textsf{Click on "Logical". Click Continue.}
 
\item \textsf{Click on “Use as.” Continue.} 

\item \textsf{Select “physical volume for LVM.” If you prefer installing the system on an encrypted LVM (recommended), select “physical volume for encryption.” Scroll to “Done setting up the partition.” Click Continue.} 

\item \textsf{With the PV created, scroll to “Configure the Logical Volume Manager” to create the Volume Group (VG). Click Continue.}
 
\item \textsf{At the "Write the changes to disks and configure LVM" prompt answer "Yes". Note the partition number of the boot partition (partition \#5). That piece of information will come in handy several steps ahead. Click Continue.} 

\item \textsf{Scroll to “Create volume group.” Click Continue.} 

\item \textsf{Give the Volume Group a name. Any name will do. The shorter the better. Capitalization is optional.  I called mine "HU", Click Continue.}
 
\item \textsf{These are all the partitions on the disk. Which one will be made a member of the VG? Only a Physical Volume qualifies to be included in a VG. In this example, that will be /dev/sda6, the Physical Volume that was created earlier. Select /dev/sda6 and Click Continue.}
 
\item \textsf{The Volume Group has been created.} 

\item \textsf{The next task is to create Logical Volumes, which are the equivalents of disk partitions. For this example, only two Logical Volumes will be created: / and swap. You can create more if you like, but for a desktop system, those two should be all you need to create during installation.} 

\item \textsf{Click on "Create logical volume" and click Continue.}
 
\item \textsf{The first step in creating a Logical Volume (LV), is to identify the Volume Group the disk space for the LV will be taken from. Click on "HU" and click Continue.} 

\item \textsf{The first LV will be for /. Like the VG’s name, the names for the LVs can be anything you feel comfortable with. For ease of management, it is better to use a name that reminds you of the mount point of the LV). I like to name the LV that will be used for / as "root" and "swap" for that which will be used for swap.} 

\item \textsf{Name the Logical Volume "root". Click Continue.} 

\item \textsf{How much disk space should be allocated to this "root" LV? I used 494 GB for the / partition. Click Continue.} 

\item \textsf{Click on "Create logical volume" and click Continue.}
 
\item \textsf{Name the Logical Volume "swap". Click Continue.} 

\item \textsf{How much disk space should be allocated to this "swap" LV? I used the remainder of the FREE SPACE (14 GB) for the swap partition. Click Continue.} 

\item \textsf{Scroll to “Finish.” Click Continue.} 

\item \textsf{The last task in creating LVs is to specify a file system and mount points. So, select the first (largest) LV, and click Continue.} 

\item \textsf{Scroll to “Use as” to specify a file system for the / partition. The default on Debian 6 is "Ext3 journaling file system". You can stick with that or choose any other available journaling file system. Click Continue.}
 
\item \textsf{Scroll to “Mount point” and choose the mount point of "/" for the LV. Then scroll to “Done setting up the partition.” Click Continue.} 

\item \textsf{Select the second (smallest) LV, and Click Continue.} 

\item \textsf{Scroll to “Use as” to specify "swap". Click Continue.}

\item \textsf{Scroll to “Done setting up the partition.” Continue.} 

\item \textsf{Scroll to “Finish partitioning and write changes to disk.”  Click Continue.} 

\item \textsf{Debian 6/Ubuntu 11 uses GRUB 2 as the bootloader, and will attempt to install it on the Master Boot Record (MBR) of the hard disk. Note, however, that installing GRUB in the MBR when you are attempting to dual-boot with Windows will overwrite Windows boot files. This is not the recommended approach. It is better to install it in the boot partition of the Debian installation. So, select "No" and click Continue.} 

\item \textsf{All the steps involved in this tutorial are important, but this one is especially so. Remember the partition number of the boot partition? For this example, the boot partition is /dev/sda5. The partition number is, therefore, 5. The device to specify for installing GRUB, in GRUB’s syntax, is (hd0,5). The 0 is the first hard disk and the 5, the partition number. Click Continue.}

\item \textsf{Continue with the rest of the installation. When completed, the system will reboot into Windows. This is expected.}
 
\item \textsf{The final task is to add an entry for Debian Wheezy in Windows’ boot menu. The easiest tool I know of to do that is EasyBCD, a free application from NeoSmart Technologies. You may download the latest version here:} \newline 
      \url{http://neosmart.net/dl.php?id=1} 
      
\item \textsf{Install EasyBCD and launch it.}
 
\item \textsf{This is the main tab of EasyBCD. It shows the only entry in the boot menu. Click on Add New Entry.} 

\item \textsf{On the Add New Entry tab, click on the Linux/BSD tab in the upper part of the window. Debian 6 uses GRUB 2, so select “GRUB 2″ from the Type menu. Edit the Name field to Debian, then click on the Add Entry button. Click on Edit boot Menu.}
 
\item \textsf{Here are the two entries. Windows is the default. You can change the order if you want to. Exit EasyBCD and reboot.} 

\item \textsf{To be sure that it works, boot into Debian. It should prompt you to boot either Windows Vista or Windows 7 if you followed all the steps above. Note that if you attempt to boot into Debian, you will next encounter the GRUB menu.  If you were able to boot into Windows Vista or Windows 7 then you are done with this chapter, continue to chapter 4 to install the Linux libraries and programs.}

\item \textsf{For a dual boot Debian and Windows XP when the installation prompts you to install the GRUB bootloader, allow it to be installed in the Master Boot Record (MBR).}

\item \textsf{Reboot your computer when the Debian install is complete.}

\item \textsf{Notice that when the computer restarts you are presented with the GRUB bootloader and only the Debian choices are available.  Let it boot into the default Debian instance and we will add Windows XP to the boot loader in the next step.}

\item \textsf{Open a terminal and type the following}
      \begin{enumerate}
      \item \texttt{\$ sudo grub-mkdevicemap}
      \item \texttt{\$ sudo update-grub2}
      \end{enumerate}
      
\item \textsf{Reboot your computer.}

\item \textsf{Notice that when the computer restarts you are presented with the GRUB bootloader and now the Debian choices are available along with Microsoft Windows XP.}

\item \textsf{Your installation of both operating systems is now complete.  At this point you should test and make sure that you can boot into both operating systems before continuing.}
\end{enumerate}

\chapter{\textsf{Install Linux Libraries and Programs}}

\begin{enumerate}
\item \textsf{Boot into Debian.}
\item \textsf{Open a Root Terminal, edit \path{/etc/apt/sources.list} and add:} \newline
	\textsf{For 32bit OS:} \newline
\texttt{\# FreeEMS Toolchain} \newline
\texttt{deb http://debs.diyefi.org css-debs binary}

\item \textsf{Open a Terminal window and type:} \newline
      \texttt{\$ sudo gedit /etc/sudoers} \newline
      \textsf{and add your user under root.}

\item \textsf{In the same Terminal window, type:} \newline
      \texttt{sudo gedit /etc/group} \textsf{ and add your username to:} \newline
      \texttt{tty, dialout, sudo, operator, users, iocard and staff} \newline
      \textsf{You may not have all of these, only add your username after the groups that exist on your system.}

\item \textsf{These changes will require a reboot to assign the permissions, so do that now.}

\item \textsf{Open a Terminal window and update apt's database and install upgraded system files:} \newline
      \texttt{\$ sudo apt-get update} \newline
      \texttt{\$ sudo apt-get upgrade}

\item \textsf{Install the tools necessary for MegaTunix:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ sudo apt-get install pkg-config libtool intltool libgtkglext1-dev g++ gcc flex} \newline
      \texttt{\$ sudo apt-get install bison glade libglade2-dev make git-core gdb automake1.9}

\item \textsf{Install the FreeEMS Toolchain so you can compile the firmware:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ sudo apt-get install freeems-toolchain cutecom}

\item \textsf{Install linux-headers:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ sudo apt-get install linux-headers-2.6.32-5-686}
\end{enumerate}

\chapter{\textsf{Install Essential Programs}}

\begin{enumerate}
\item \textsf{Install QT4} \newline
      \textsf{Open a Terminal window and type:} \newline
      \texttt{\$ sudo apt-get update \&\& sudo apt-get install libqt4-dev libqt4-opengl-dev qt4-qmake libqwt-dev libqt4-declarative libqjson-dev}

\item \textsf{Now the system should be ready to compile emstudio, MegaTunix, FreeEMS, FreeEMS-Loader and qserialport!}

\item \textsf{Create a git directory in your home directory:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ mkdir }\PVerb{~/git}

\item \textsf{Change to your new git directory:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ cd } \PVerb{~/git}

\item \textsf{Clone the git repositories for qserialport, freeems-loader, MegaTunix and freeems-vanilla} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ git clone git://gitorious.org/inbiza-labs/qserialport.git} \newline
      \texttt{\$ git clone git://github.com/seank/freeems-loader.git} \newline
      \texttt{\$ git clone git://github.com/djandruczyk/MegaTunix.git} \newline
      \texttt{\$ git clone git://github.com/malcom2073/emstudio.git} \newline
      \texttt{\$ git clone git://github.com/fredcooke/freeems-vanilla.git} \newline
      \newline
      \textsf{This creates a directory within the git directory named after each repository such as:} \newline
      \PVerb{~/git/qserialport} \newline	
      \PVerb{~/git/freeems-loader} \newline
      \PVerb{~/git/MegaTunix} \newline
      \PVerb{~/git/emstudio} \newline
      \PVerb{~/git/freeems-vanilla}

\item \textsf{Start with qserialport since we need it for SeanK's freeems-loader to communicate with the serial port:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ cd } \PVerb{~/git/qserialport} \newline
      \texttt{\$ ./configure} \newline
      \texttt{\$ make} \newline
      \texttt{\$ sudo make install} \newline
      \texttt{\$ sudo /sbin/ldconfig} \newline
\end{enumerate}

\chapter{\textsf{FreeEMS-Loader}}

\textsf{FreeEMS-Loader is the program you will use to load the freeems-vanilla firmware onto your FreeEMS based engine management system, so here are the instructions of how to compile and install this program.} \newline

\begin{enumerate}
\item \textsf{Make sure your freeems-loader git clone is up to date by excuting the following:} \newline
      \textsf{Open a Terminal window and type:} \newline
      \texttt{\$ cd } \PVerb{~/git/freeems-loader} \newline
      \texttt{\$ git pull}

\item \textsf{Next compile freeems-loader:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ cd } \PVerb{~/git/freeems-loader/src} \newline
      \texttt{\$ qmake \&\& make all}

\item \textsf{Next test run freeems-loader:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ ./Freeems-Loader}

\item \textsf{Create a Gnome menu item for FreeEMS-Loader:} \newline
      \textsf{Click on } \texttt{System -> Preferences -> Main Menu} \newline
      \textsf{Click on the "New Menu" button and call the new menu "FreeEMS".}

\item \textsf{Create an application called "FreeEMS-Loader":} \newline
      \textsf{Click on "FreeEMS" and then click on the "New Item" button,} \newline
      \textsf{The Type is "Application", for the Name type in "FreeEMS-Loader" and browse for} \newline
      \PVerb{~/git/freeems-loader/src/Freeems-Loader} \textsf{, then click OK.}
\end{enumerate}

\chapter{\textsf{Install emstudio}}

\textsf{emstudio is the tuning program you will use to make changes to your FreeEMS version 0.2.0 based engine management system so here are the instructions on how to install and run this program.} \newline

\begin{enumerate}
\item \textsf{Make sure your emstudio git clone is up to date by excuting the following:} \newline
      \textsf{Open a Terminal window and type:} \newline
      \texttt{\$ cd } \PVerb{~/git/emstudio} \newline
      \texttt{\$ git pull}

\item \textsf{Now compile emstudio:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ cd } \PVerb{~/git/emstudio} \newline
      \texttt{\$ qmake} \newline
      \texttt{\$ make} \newline

\item \textsf{Now run emstudio:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ cd } \PVerb{~/git/emstudio} \newline
      \texttt{\$ ./emstudio} \newline      
\end{enumerate}

\chapter{\textsf{Install MegaTunix}}

\textsf{MegaTunix is the tuning program you will use to make changes to your FreeEMS version 0.1.0 based engine management system so here are the instructions on how to install this program.} \newline

\begin{enumerate}
\item \textsf{Make sure your MegaTunix git clone is up to date by excuting the following:} \newline
      \textsf{Open a Terminal window and type:} \newline
      \texttt{\$ cd } \PVerb{~/git/MegaTunix} \newline
      \texttt{\$ git pull}

\item \textsf{Now compile MegaTunix:} \newline
      \textsf{In the same Terminal window, type:} \newline
      \texttt{\$ cd } \PVerb{~/git/MegaTunix} \newline
      \texttt{\$ ./autogen.sh} \newline
      \texttt{\$ make} \newline
      \texttt{\$ sudo make install} \newline
      \texttt{\$ sudo /sbin/ldconfig} \newline
\end{enumerate}

\chapter{\textsf{FreeEMS Firmware}}

\textsf{In this chapter are the instructions to build the freeems-vanilla firmware with specific instructions for the Deuce Coupe build.} \newline

\begin{enumerate}
\item \textsf{Make sure your freeems-vanilla git clone is up to date by excuting the following:} \newline
      \textsf{Open a Terminal window and type:} \newline
      \texttt{\$ cd } \PVerb{~/git/freeems-vanilla} \newline
      \texttt{\$ git pull}

\item \textsf{Build the FreeEMS Firmware:} \newline
      \textsf{In the same Terminal window and type:} \newline
      \texttt{\$ cd } \PVerb{~/git/freeems-vanilla/src} \newline
      \texttt{\$ CLIFLAGS="-D DEUCECOUPE=1" make clean s19}

\item \textsf{Your newly built FreeEMS firmware can be found in:} \newline
      \texttt{\$ cd } \PVerb{~/git/freeems-vanilla/src/firmware}

\item \textsf{freeems.serial.monitor.s19 is located in:} \newline
      \texttt{\$ cd } \PVerb{~/git/freeems-vanilla/lib}
\end{enumerate}

\chapter{\textsf{Set User Permission to USB Device}}

\textsf{In this chapter we will setup your USB TBDML debug module so that your normal user can use it without using the \textbf{sudo} command.} \newline

\begin{enumerate}
\item \textsf{Install libusb:} \newline
      \texttt{\$ sudo apt-get install libusb-0.1.4 libusb-1.0-0 libusb-1.0-0-dev libusb-dev}

\item \textsf{To get libusb devices to run without being root:} \newline
	\begin{enumerate}
		\item \textsf{Plug in your USB device and run:} \newline
			\texttt{\$ dmesg | tail} \newline
			\textsf{to find IDVendor and IDProduct of your USB device.} \newline
			\textsf{Example output:} \newline
			\texttt{[49182.484111] usb 2-4: New USB device found, idVendor=0425, idProduct=1000} \newline

		\item \textsf{Modify /etc/udev/udev.conf and ensure that it at least has following settings:} \newline
			\texttt{\$ sudo gedit /etc/udev/udev.conf} \newline		
			\PVerb{udev_root="/dev/"} \newline
			\PVerb{udev_db="/dev/.udevdb"} \newline
			\PVerb{# udev_rules="/etc/udev/rules.d/"} \newline
			\PVerb{# udev_permissions="/etc/udev/permissions.d/"} \newline
			\PVerb{default_mode="0660"} \newline
			\PVerb{udev_log="err"}
	\end{enumerate}
\item \textsf{Create USB udev rule:} \newline
      \texttt{\$ sudo cat > /etc/udev/rules.d/23-usb.rules << "EOF"} \newline
      \texttt{\# Set group ownership for raw USB devices} \newline
      \texttt{\# This is for the TBDML} \newline
      \texttt{ACTION=="add", SUBSYSTEM=="usb", SYSFS\{idVendor\}=="0425", SYSFS\{idProduct\}=="1000", ENV\{DEVTYPE\}=="usb\_device", GROUP="dialout", MODE="0660", SYMLINK+="tbdml-\%k"} \newline
      \texttt{\#This is for the Saleae Logic Analyzer} \newline
      \texttt{ACTION=="add", SUBSYSTEM=="usb", SYSFS\{idVendor\}=="0925", SYSFS\{idProduct\}=="3881", ENV\{DEVTYPE\}=="usb\_device", GROUP="dialout", MODE="0660", SYMLINK+="saleae-\%k"} \newline
      \texttt{EOF}

\item \textsf{Comment out the rule in /lib/udev/rules.d/95-upower-wup.rules} \newline
	  \texttt{\$ gedit /lib/udev/rules.d/95-upower-wup.rules} \newline
      \texttt{Now add a \# to the beginning of the line that reads like the one below:} \newline      
      \texttt{\# SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ATTRS\{idVendor\}=="0403", ATTRS\{idProduct\}=="6001", ATTRS\{serial\}=="A80\?\?\?\?\?", ENV\{UPOWER\_VENDOR\}="Watts Up, Inc.", ENV\{UPOWER\_PRODUCT\}="Watts Up\? Pro", ENV\{UP\_MONITOR\_TYPE\}="wup"} \newline
      \texttt{Save your change} \newline

\item \textsf{Kill and Respawn udev deamon and run the newly created rules:} \newline
      \texttt{\$ sudo skill udevd} \newline
      \texttt{\$ sudo /sbin/udevd -d} \newline

\end{enumerate}

\chapter{\textsf{hcs12mem}}
\textsf{In this chapter we will download and test hcs12mem a Freescale HCS12 flashing utility.} \newline

\textsf{hcs12mem is only to test to make sure you can communicate with the HCS12 core.  You will not be using this utility for flashing anything to the MCU under Linux.} \newline

\begin{enumerate}
\item \textsf{Download hcs12mem from:} \newline
      \url{http://sourceforge.net/projects/hcs12mem/files/latest/download} \newline
      \textsf{I have not been able to get hcs12mem to program the freeems.serial.monitor.s19 file onto a blank HC12S(X) MCU as of the writing of this how-to.  This is considered a work in progress.} 

\item \textsf{Install hcs12mem-1.4.1-linux.deb with GDebi Package Installer. This file will be located in} \newline
      \PVerb{~/Downloads/}

\item \textsf{Copy the Freescale mc9s12xdp512.dat file to the library for hcs12mem:} \newline
      \texttt{\$ sudo cp } \PVerb{~/git/freeems-vanilla/bin/mc9s12xdp512.dat /usr/local/share/hcs12mem/mc9s12xdp512.dat}

\item \textsf{Connect the TBDML USB programmer to the USB port of your PC and connect the BDM cable to the BDM connector on the Freescale Microprocessor (MCU).  The TBDML adapter is only used to program the Serial Monitor program onto the Freescale Microprocessor so that we can communicate with either the FreeEMS-Loader or the MegaTunix-Loader.}

\item \textsf{Test hcs12mem operation to query the Freescale MCU:} \newline
      \texttt{\$ hcs12mem -i tbdml -t mc9s12xdp512} \newline
      \\
      \textsf{You should see output like this:} \newline
      \texttt{andy@DeuceEMS:~/hcs12mem\$ hcs12mem -i tbdml -t mc9s12xdp512} \newline
      \texttt{hcs12mem: Freescale S12 MCU memory loader V1.4.1 (C) 2005-2007 Michal Konieczny 	<mk@cml.mfk.net.pl>} \newline
      \\
      \texttt{target info <single chip MC9S12XDP512 MCU>} \newline
      \texttt{target mcu <MC9S12XDP512> family <S12X>} \newline
      \texttt{USB device USB version <1.1> VID <0x0425> PID <0x1000> device release <0.0.1>} \newline
      \texttt{USB device manufacturer <Freescale> product <TurboBDM Light v0.1>} \newline
      \texttt{USB device config <\#1> power <bus> max current <300mA>} \newline
      \texttt{TBDML hardware version <1.0> firmware version <0.3>} \newline
      \texttt{TBDML detected target frequency <16.000 MHz>} \newline
      \texttt{BDM status <enabled,active,secured> clock <bus>} \newline
      \texttt{S12X part id <0xC410> family <XD> memory <512kB> mask <1.0>} \newline
      \texttt{S12X part security <unsecured> backdoor key <enabled>} \newline
      \texttt{S12X register space <2kB> address range <0x0000-0x07FF>} \newline
      \texttt{S12X RAM size <32kB> space <12kB> address range <0x1000-0x3FFF>} \newline
      \texttt{S12X FLASH module <FTX512K4> size <512kB> state <enabled> ROMHM <no>} \newline
      \texttt{S12X FLASH block <0> protection all <off> high area <2kB> low area <off>} \newline
      \texttt{S12X FLASH block <1> protection all <off> high area <2kB> low area <off>} \newline
      \texttt{S12X FLASH block <2> protection all <off> high area <2kB> low area <off>} \newline
      \texttt{S12X FLASH block <3> protection all <off> high area <2kB> low area <off>} \newline

\item \textsf{Test Erasing the entire Flash memory to default the Freescale MCU:} \newline
      \texttt{\$ hcs12mem -i tbdml -t mc9s12xdp512 –flash-erase-unsecure} \newline
      \textsf{***If you run this command and the CPU goes into Secured mode.  Boot into Windows and run “HiWave Debugger” and Unsecure the CPU.} 

\end{enumerate}

\chapter{\textsf{Build a BDM}}

\textsf{I have used a TBDML in the past to connect the MCU to the HiWave Debugger, I have included a link to my github repository where you can find the information to make your own as well as the driver for Windows XP 32-bit, Vista 32-bit and Windows 7 32-bit editions.} \newline

\textsf{I recommend using a USBDM to connect the MCU to the HiWave Debugger, I have included a link to my github repository where you can find the information to make your own as well as the driver for Windows XP 32-bit.} \newline

\begin{enumerate}
\item \textsf{Clone my USBDM repository from https://github.com/DeuceEFI/USBDM (recommended)}
\item \textsf{Clone my TBDML-12f-GPL repository from https://github.com/DeuceEFI/TBDML-12f-GPL}

\item \textsf{Follow the instructions contained in the file "USBDM_Instructions.md" to build a USBDM and install the 32-bit driver.}
\item \textsf{Follow the instructions in Daniel Malík's instructional PDF to build a TBDML and install the included 32-bit driver.}
\end{enumerate}

\chapter{\textsf{Flashing the Freescale MCU}}

\textsf{In this chapter we will learn how to flash the Serial Monitor (SM) program onto your Freescale Microcontroller Unit.} \newline

\begin{enumerate}

\item \textsf{Boot into Windows.}

\item \textsf{Connect the USBDM/TBDML to your computer.}

\item \textsf{Run the hiwave.exe shortcut you created in Chapter 1, Step 1, Instruction 5.}

\item \textsf{Program the Freescale MCU with the Serial Monitor program by:} 
      \begin{enumerate}
      \item \textsf{Click on  \textbf{TDBML HCS12}}
      \item \textsf{Click on  \textbf{Unsecure}}
      \item \textsf{Click on  \textbf{TDBML HCS12}}
      \item \textsf{Click on  \textbf{Flash}}
      \item \textsf{Click on  \textbf{Load}}
      \item \textsf{Choose \textbf{freeems.serial.monitor.s19}, click on Open.} 
      \item \textsf{Click on Close.}
      \end{enumerate}

\item \textsf{Reset the Freescale MCU to Normal Mode:}
      \begin{enumerate}
      \item \textsf{Click on  \textbf{TDBML HCS12}}
      \item \textsf{Click on \textbf{Reset to Normal Mode}}
      \item \textsf{Exit HiWave Debugger.}
      \end{enumerate}

\end{enumerate}

\chapter{\textsf{Test Serial Monitor}}

\textsf{In this chapter we will learn how to test the Serial Monitor to make sure it is working properly.} \newline

\begin{enumerate}
\item \textsf{Boot back into Debian OR Ubuntu.}

\item \textsf{Open \textbf{cutecom}, click on the \textbf{Hex Output} check box, to the right of \textbf{Send file...} button, make sure \textbf{Plain} is selected and in the other box make sure \textbf{LF line end} is selected.}

      \begin{enumerate}
      \item \textsf{Set it up to use device /dev/ttyF0 or /dev/ttyS0 or /dev/ttyUSB0 (which ever you are using)}
      \item \textsf{The Serial Monitor uses 115200 baud, 8 data bits, 1 stop bit, no parity.}
      \item \textsf{Connect a serial cable to the FreeEMS MCU.}
      \item \textsf{Click \textbf{Open Device}, click on the \textbf{Send file...} button and select the file \textbf{serial.mon.reset}}
      \item \textsf{It should respond back with: e0 08 3e}
      \item \textsf{This means that the Serial Monitor program is running.}  
      \item \textsf{Close out of \textbf{cutecom}.}
      \end{enumerate}
\end{enumerate}

\chapter{\textsf{Load FreeEMS Firmware}}

\textsf{In this chapter we will learn how to load the freeems-vanilla firmware onto your Freescale MCU using Sean's Freeems-Loader.  You will use this procedure to load any firmware files that you compile in the future onto the Freescale MCU.} \newline

\begin{enumerate}
\item \textsf{To load the FreeEMS firmware onto your MCU, open FreeEMS-Loader and do the following:}
      \begin{enumerate}
      \item \textsf{Change the Run/Load switch to Load on the either the Technological Arts board and press the RESET button OR install the shorting jumper on the Load/Run header on the Jaguar PCB and power cycle the PCB to tell the Serial Monitor program to accept an incoming file.} 
      \item \textsf{In FreeEMS-Loader, click on the \textbf{Connect} button.}
      \item \textsf{Click on the \textbf{Open File} button, select the FreeEMS .s19 firmware file you want to load and click on the \textbf{Open} button.}
      \item \textsf{Click on the \textbf{Load} button.  It will now load the file onto the MCU.}
      \item \textsf{Click on the \textbf{Close/Rst} button.}
      \item \textsf{Close FreeEMS-Loader and remember to change the Load/Run switch back to Run on the TA board and press the RESET button or remove the Load/Run shorting jumper on the Jaguar PCB and power cycle the PCB.}
      \end{enumerate}
\end{enumerate}

\chapter{\textsf{Using git}}

\textsf{In this chapter we will learn how to use git.} \newline

\begin{enumerate}
\item \textsf{The following is a list of useful git commands:}
      \begin{enumerate}
    \item \texttt{\textbf{git clone git://github.com/user\_name/repository\_name.git}} \textsf{ -this clones the repository to your computer}
    \item \texttt{\textbf{git pull}} \textsf{ -this retrieves the latest commit changes from the remote repository to your computer}
    \item \texttt{\textbf{git commit -a}} \textsf{ -this allows you edit the commit message before pushing the changes to the repository on the Internet}
    \item \texttt{\textbf{git push}} \textsf{ -this uploads your changes to the repository on the Internet}
    \item \texttt{\textbf{git branch}} \textsf{ -this shows the branches in the repository along with indicating the current branch with an \*}  
    \item \texttt{\textbf{git rev-parse HEAD | cut -c1-10}} \textsf{ -this shows the first 10 digits of the commit hash}  
	\item \texttt{\textbf{git diff --stat}} \textsf{ -this shows the changes you have made to the repository}
	\item \texttt{\textbf{git branch}} \textsf{ -this shows the branches in the repository along with indicating the current branch with an \*}
	\item \texttt{\textbf{git checkout dev}} \textsf{ -this changes the working branch to the \textbf{dev} branch in the repository}
	\item \texttt{\textbf{git fetch}} \textsf{ -Fetches named heads or tags from one or more other repositories, along
       with the objects necessary to complete them.}

\end{document}