%% LyX 1.4.3 created this file. For more info, see http://www.lyx.org/. %% Do not edit unless you really know what you are doing. \documentclass[oneside,english]{book} \usepackage[T1]{fontenc} \usepackage[latin1]{inputenc} \setcounter{secnumdepth}{3} \setcounter{tocdepth}{3} \usepackage{graphicx} \makeatletter %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands. %% Because html converters don't know tabularnewline \providecommand{\tabularnewline}{\\} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands. \newenvironment{lyxcode} {\begin{list}{}{ \setlength{\rightmargin}{\leftmargin} \setlength{\listparindent}{0pt}% needed for AMS classes \raggedright \setlength{\itemsep}{0pt} \setlength{\parsep}{0pt} \normalfont\ttfamily}% \item[]} {\end{list}} \usepackage{babel} \makeatother \begin{document} \title{Hardware Hacking with GNU/Linux and Phoenix-MDK} \author{Pramode C.E} \maketitle \tableofcontents{} \chapter*{Preface} This book is a `work~in~progress'! Part 1 will get you started with the Debian GNU/Linux programming environment. Many of the ideas covered are generic and apply equally well to most other GNU/Linux distributions. If you are really impatient, you can dive straight into part 2! In Part 2, we shall look at how to conduct experiments with the Phoenix MDK (Microcontroller Development kit). The MDK and associated software tools (a GNU/Linux Live CD, a library of routines) will help you to get started with hardware hacking effortlessly. The Phoenix MDK library is designed in such a way that the user need not be aware of the complexities involved in programming the underlying microcontroller (an Atmel ATMega16). For example, by invoking a simple C function and passing it certain parameters, the user will be able to generate a square waveform on a particular pin of the controller. Understanding how these functions are implemented will go a long way towards helping the user craft new routines for his own special requirements; that is the objective of the third part of this book. The Debian GNU/Linux system is packed with plenty of high quality tools of great utility to the hardware hacker - examples include mathematical tools like Octave and schematic entry and PCB design tools like gEDA. The last part of this book will cover a few of these tools. \part{Debian GNU/Linux} \chapter{Introduction to Debian GNU/Linux } If your only previous experience is with proprietary operating systems% \footnote{Which come packaged with such cutting-edge applications like card games and paint programs and with doors and windows always open for wild creatures like viruses, worms and trojan horses!% }, you will find Debian~GNU/Linux to be a breath of fresh air! The three DVD's which constitute it's latest release contain literally thousands of programs for doing everything from wordprocessing to electronic circuit design, PCB fabrication and complex mathematical computations. It is in fact a huge collection of the very best which the Free Software world can offer! This chapter gets you quickly on your feet installing and using Debian. Whether you are a hobbyist, student or Engineer, the one thing that differentiates you from an ordinary user is the fact that you really wish to understand what is going on in your machine. This book doesn't try to hide the complexity of the Operating System by showing you pretty GUI's - instead, the idea is to help you master that complexity! \section{Philosophy of Free Software} Technology doesn't exist in a vaccum - it has great social, ethical, economic, political and environmental implications. The GNU/Linux operating system is much more than a technological achievement - new users should spend some time to understand things like what the {}``Free'' in Free Software really stands for, how Free Software is different from Open Source and so on. The best place to get started is: \begin{quotation} http://www.gnu.org/philosophy/philosophy.html \end{quotation} \section{The GNU/Linux command line interface} You should have a working GNU/Linux system (preferably Debian - but some other distribution will also do) to get the most out of this book. If not, you can follow the instructions given in the Appendix and set up Debian on your own (it is highly recommended that you do it at least once). Once Debian boots up, you will see a graphical login screen. Graphical User Interfaces are undoubtedy a great boon - but if you wish to get the real `feel' of the system, you should be prepared to get acquainted with the `classical' text mode interface. And, unlike what some people might tell you, the command line interface is NOT the epitome of complexity - it is in fact simple and amazingly well designed. But how do you get into this text mode? Type Ctrl-Alt-F1 and there you are% \footnote{You can go back to graphics mode any time by typing Alt-F7% }! \subsection{The GNU/Linux prompt} You need a login name and password to enter into the system. If the login is succesfull, you will see the famous GNU/Linux prompt (assuming that you are logging in as user `guest' on a machine whose name is `debian'): \begin{lyxcode} guest@debian:\textasciitilde{}\$ \end{lyxcode} This is where you will be entering commands. Note that the prompt gives you information like your login name and machine name. Try running one or two simple commands: \begin{lyxcode} guest@debian:\textasciitilde{}\$~echo~hello hello guest@debian:\textasciitilde{}\$~date Thu~Feb~7~20:52:11~IST~2008 guest@debian:\textasciitilde{}\$ \end{lyxcode} \subsection{File System Tour} A typical GNU/Linux installation will have tens of thousands of files spread out over hundreds of nested directories (folders). The very first step in understanding your system is getting a general idea of the layout of these files and directories. \subsubsection{The root directory} The `cd' command can be used to move from one directory to another. The `root~directory' (denoted by the symbol `/') is the where the heirarchy begins - you can do a `cd' and move into the root directory: \begin{lyxcode} guest@debian:\textasciitilde{}\$~cd~/ guest@debian:/\$~pwd / guest@debian:/\$ \end{lyxcode} Note that the prompt has changed - it now displays a `/' after the ':'. The `pwd' command prints the current directory, which is /. The `ls' (list) command displays contents of a directory. Here are some of the names which you might see if you run `ls' in the root directory: \begin{quotation} bin boot cdrom etc dev lost+found sbin \end{quotation} How do you differentiate between files and directories? By running the `ls' command with the option `-l' (ie, you type \emph{`ls~~-l}'). This option gives you a few other details regarding a file - like its size, timestamp, permissions etc. If the entry corresponding to the file which you are looking for starts with the character `d', you can take it to be a directory; if you see a `-' sign as the first character, it is an ordinary file. Because a `file' is a rather complex entity, you might see a few symbols other than these two - the exact meaning of these symbols will be explained later. Most of the names in the root directory represent directories - it's a good idea to get into these folders and understand the kind of data they store. \subsubsection{The directories /bin and /sbin} Assuming that you are currently under the `root' directory, execute the following command: \begin{lyxcode} guest@debian:/\$~cd~bin guest@debian:/bin\$ \end{lyxcode} You are now in the folder `/bin'% \footnote{What we mean by `/bin' is - the folder bin under the root directory.% }. You will see plenty of files when you do an `ls' (almost all of them would be files - you can verify by running `ls~~-l'). What kind of data do these files contain? We can find out by using the `file' command: \begin{lyxcode} guest@debian:/bin\$~file~chown chown:~ELF~32-bit~LSB~executable,~Intel~80386,~ version~1~(SYSV),~for~GNU/Linux~2.4.1,~ dynamically~linked~(uses~shared~libs),~ for~GNU/Linux~2.4.1,~stripped \end{lyxcode} One thing is clear, `chown' is an executable file - and it contains machine code which runs on an Intel 80386 compatible processor. All the files under /bin contain executable machine code of standard GNU/Linux commands. The file `ls' contains the machine code for the command `ls' and the file `chown' contains machine code for the `chown' command. /sbin is similar - only difference is that most of the commands under this folder (like say `rmmod') are needed only by the system administrator. \subsubsection{/etc} One of the files seen under /etc is `passwd'. Each line of this file contains information about a particular user on the system. Type: \begin{lyxcode} guest@debian:/etc\$~man~5~passwd \end{lyxcode} to get more information about the structure of this file. Another very important file under /etc is `inittab'. When a GNU/Linux system boots up, lots of programs are started automatically. Deciding which all programs to start depends on what is called a `run level'. The default run level will be specified in this file. Type `man~5~inittab' to know more about the structure of this file. In general, /etc contains configuration files stored in plain ASCII form% \footnote{Some propreitary systems prefer to store configuration data in binary form. This is a bad idea. Text files are better than binary files - you can use a whole lot of standard text processing utilities to manipulate these files.% }. \subsubsection{/boot} This folder usually contains the machine code of the OS kernel and a few other related files. \subsubsection{/dev} \section{Using the `nano' editor} GNU~Nano is an easy to use text editor. You can invoke it by simply typing `nano' at the command prompt. Enter a few lines of text and save it by typing `Ctrl-O' (WriteOut). Nano will ask you for a file name. Ctrl-X takes you out of Nano - there are many other `Ctrl' commands - Nano displays a list at the bottom of the screen. \chapter{The GNU/Linux development environment} \section{Compiling C programs} A C program is compiled by invoking the GNU C Compiler% \footnote{It might be better to say that GCC stands for the GNU Compiler Collection% } - gcc. The resuting executable will be stored in a file `a.out' which you can execute by simply typing its name: \begin{lyxcode} guest@debian:\textasciitilde{}\$~cc~hello.c guest@debian:\textasciitilde{}\$~./a.out hello,~world guest@debian \end{lyxcode} Compilation is a complex 4 stage process - here is a brief description of the stages. The file being compiled contains the following code: \begin{lyxcode} \#define~MAX~10 main() \{ ~~~~~int~i~=~MAX; \} \end{lyxcode} \subsection{Preprocessing} \subsection{Compilation Proper} \subsection{Assembling} \subsection{Linking} \begin{lyxcode} \end{lyxcode} \section{Debugging C programs} {[}To be written] \section{Building a program from source} {[}To be written] \section{Elementary shell scripting} {[}To be written] \section{Scripting in Python} {[}To be written] \part{The Phoenix MDK} \chapter{Quickstart } Phoenix~MDK is a complete GNU/Linux based platform for rapid prototyping of microcontroller applications. The hardware part consists of a small `main~board' carrying an ATMega16 microcontroller from Atmel and several small `daughter~boards' which can be used for things like serial communication (with the PC), amplifying electrical signals, interfacing with small DC motors etc. The software part consists of a bootable {}``Live'' CD containing Debian GNU/Linux, a software library which simplifies microcontroller programming significantly and a collection of tools and utilities which will be of great use to the hardware hacker. The hardware design, including schematics and PCB layout are freely available from the project home page. All the PCB's are single sided and have been carefully designed so as to make it easy for even inexperienced users to solder the parts himself, if he so desires. The software library is licensed under GPLv3. \section{Hardware} \subsection{The main board} Figure \ref{fig:The-Phoenix-MDK-main} shows the layout of the Phoenix-MDK main board. You can see the Atmega16 controller at the centre. There are sockets marked `Digital~I/O' and `Analog~I/O'% \footnote{You will also see alternate markings PORTA, PORTB, PORTC, PORTD - the next part of this book will explain what these are.% } . You will note that the sockets are numbered on both sides - on one side, the numbering is uniformly zero to seven - this can be ignored for the moment. There are three sets of sockets for Digital I/O (marked 0 to 4, 5 to 12 and 13 to 20) and one set for Analog I/O (marked 0 to 7). The Digital I/O lines can be made HIGH (5V) or LOW (0V) by invoking a function from a C program (that is, the lines act as `output'). It is also possible to check the logic levels on these pins, again by calling some C function (ie, the lines act as `inputs'). % \begin{figure} \caption{The Phoenix-MDK main board} \label{fig:The-Phoenix-MDK-main} \includegraphics{mega16_silk} \end{figure} The `Analog~I/O' lines are connected to the ADC (Analog to digital converter) unit within the ATMega16 microcontroller. They can be used to measure analog voltages (more on this later). The board has a small switch adjacent to the analog I/O lines which can be used to reset the microcontroller. There is a 16 pin LCD connector to which we can attach small text LCD units. The unit can be powered by an external DC 9V supply (which can even be a 9V battery). % \begin{figure} \caption{Phoenix MDK Main board photo} \includegraphics{phmdk} \end{figure} \subsection{The daughter boards} The functionality of Phoenix-MDK is enhanced by several `daughter~boards'. The following boards are currently available: \begin{enumerate} \item A MAX232 based serial port interface (Figure \ref{fig:Connection-MAX232-daughter}) \item USB-RS232 link using AT90S2313 \item H-Bridge (for motor control) \item An eight LED board (Figure \ref{fig:LED-I/O-board}) \item A set of op-amps \item A photosensor board \item A stepper motor/relay driver board \item Piezo Tx/Rx board \end{enumerate} % \begin{figure} \caption{MAX232 communication board} \label{fig:MAX232-communication-board} \includegraphics{max232} \end{figure} % \begin{figure} \caption{LED I/O board} \label{fig:LED-I/O-board} \includegraphics{io} \end{figure} \section{Software} \subsection{The Live CD} All the tools required to use Phoenix-MDK are included in a Debian GNU/Linux Live~CD. The Live~CD helps you try out Phoenix-MDK without installing anything on the computer. You can use it in both text mode and graphics mode. Let's first see how to compile and run a simple program from text mode. \subsubsection{Text mode blinking LED} Once the Debian Live~CD boots up, you will see the standard Unix prompt: \begin{quotation} user@debian:\textasciitilde{}\$ \end{quotation} This is where you will be typing commands. Type the command `ls' to view the files in the current folder. \begin{quotation} user@debian:\textasciitilde{}\$ ls blink.c user@debian:\textasciitilde{}\$ \end{quotation} There is a file called `blink.c' which contains the source code of a simple `LED blinking' application. You can see the contents of the file by using the `cat' command: \begin{quotation} user@debian:\textasciitilde{}\$ cat blink.c \#include main() \{ ~~~~~~~~pin\_mode(PIN0, OUT); ~~~~~~~~while(1) \{ ~~~~~~~~~~~~~~set\_high(PIN0); ~~~~~~~~~~~~~~delay(30000); ~~~~~~~~~~~~~~set\_low(PIN0); ~~~~~~~~\} \} user@debian:\textasciitilde{}\$ \end{quotation} The header file `pmdk.h' has to be included in all programs. The digital I/O pins numbered 0 to 20 (and referred to as PIN0 ... PIN20 in the program) have to be configured as either input or as output before they can be used. The `pin\_mode' function does exactly this - we are making PIN0 act as an output pin. The function `set\_high' makes the corresponding pin go high (5V) and the function `set\_low' makes the pin go low (0V). The `delay' function accepts a value between 0 and 65535 and generates a delay in microseconds equal to twice that value. The code can be compiled by typing: \begin{quotation} compile blink \end{quotation} at the prompt. The compilation process generates a file called `blink.hex' - this is the machine code which we will load into the microcontroller. But, before we do that, we have to set up the hardware properly. One of the daughter~boards coming with the Phoenix-MDK kit lets you connect the main board with the PC's serial port. Connect the daughter board accoriding to figure \ref{fig:Connection-MAX232-daughter}. Use the provided serial cable to link the daughter board with the PC. % \begin{figure} \caption{Connection MAX232 daughter board} \label{fig:Connection-MAX232-daughter} \end{figure} Now, take an LED and a 1K resistor. Connect the longer leg of the LED (+ve terminal) to PIN0 on the main board. Twist the shorter leg of the LED with one of the ends of the resistor and connect the other end of the resistor to GND (which is adjacent to PIN0). Note that the resistor may not plug into GND tightly - you may have to keep the contact by pressing. Our hardware is now ready. Power up the board and press the `reset' switch. Immediately, type the command: \begin{quotation} run blink \end{quotation} at the prompt. The code will get loaded into the controller and it will start running. You will see the LED blinking! The micrcocontroller will wait for maximum 10 seconds (after reset) to get the machine code from the PC. If it doesn't get the new code in time, whatever was previously loaded will start running. So it is essential that you type `run~blink' within 10 seconds after reset. \chapter{Simple Experiments} This chapter takes you on a detailed tour of the Phoenix MDK library. We do this by writing small programs and observing their output with the help of the various daughter boards. \section{Output on LED's} \section{Output on the LCD display} \section{Switch input} \section{Waveform generation} \section{Frequency measurement} \section{PWM Brightness control} \section{Reading a potentiometer} \section{Temperature sensing} \section{Controlling a DC motor} \section{Serial communication with the PC} \part{AVR Microcontroller Architecture and Programming} \chapter{AVR microcontroller Architecture} The modern day microcontroller is a sort of `single~chip~computer'. If you try designing a computer system (say for some control application) using a traditional microprocessor like the 8086, you are likely to abandon the project in frustration very soon. The trouble is that the microprocessor is just one component of the system and you need to add many more (RAM, ROM, timers, counters, interrupt circuitry, I/O ports) to make it complete. This is a non trivial job and requires sophisticated knowledge of processor internals. It's here that the microcontroller comes to our rescue. A mid range 8 bit microcontroller (like the ATMega16, which belongs to the AVR family from Atmel) comes packed with all the above mentioned components (plus a few others like Analog Comparators, Serial USART's, Analog to Digital Converters, Watchdog timers) in a single, 40 pin package. Often, the only extra component required to make the microcontroller work is a power supply! \section{Hardware description} \chapter{Programming AVR microcontrollers using GNU tools} The ATMega16 as well as a lot of other microcontrollers from major vendors like Microchip and Atmel comes equipped with a good amount of `flash' memory - non volatile memory which can be erased using electrical signals. The basic idea is to write programs (mostly in assembly language or C) on the PC and convert them to machine code belonging to the target microcontroller's instruction set. Once this is done, the machine code can be transferred to the non-volatile memory of the microcontroller via simple circuits connected to the serial or parallel port. This process is called `programming' or `burning' the micro. The Debian GNU/Linux installation DVD's (CD's) contain all the tools required to program Atmel's AVR family of microcontrollers. We just have to install them using `synaptic'. \section{Setting up the GNU toolchain} Fire up synaptic and search for `avr'. Install the following packages: \begin{itemize} \item binutils-avr \item gcc-avr \item avr-libc \item uisp \item avrdude \end{itemize} The `binutils-avr' package contains tools like the assembler and the linker. The core compiler is in the package `gcc-avr' ;`avr-libc' contains some library functions. The `uisp' package contains a code burning program called `uisp' and the `avrdude' package contains a more powerful burning program. That's all the software you need to get started! Of course, if you are using the Live CD which comes with the Phoenix MDK, you have all these tools pre-installed! \appendix \chapter{Installing Debian GNU/Linux} {[}To be written] \chapter{More about code burning} Getting the compiled machine code into the microcontroller can be done in two ways: \begin{enumerate} \item You build a dedicated `programming' circuit and use one of the several free software tools available. \item Use a boot loader \end{enumerate} \section{Using a programming circuit} The AVR microcontrollers have three dedicated pins MISO, MOSI and SCK using which we can download code. All that is required is a simple direct connection of these pins with the PC parallel port. You will find schematic for such a direct-avr-parallel-access programmer here: \begin{quotation} http://www.captain.at/electronics/atmel-programmer \end{quotation} Once the programmer is built and powered up, connect it to the PC parallel port and test run with `uisp' (you should be logged in as root): \begin{quotation} uisp -dprog=dapa -dlpt=0x378 \end{quotation} And uisp should display the name of the microcontroller connected to the circuit. Programming tools like `uisp' and `avrdude' are compatible with a variety of burning circuits. The option -dprog is used to identify the circuit currently in use. The -dlpt option specifies the address of the parallel port, which will be 0x378 on all PC's. Note that `uisp' can also access the parallel port via its standard GNU/Linux driver - but direct I/O port access might be simpler because you will not encounter errors caused by the required drivers not being loaded properly. Read the manual page of `uisp' to know more about the various options. If you are using `avrdude', you can verify whether your circuit is working properly by running (as root): \begin{quotation} avrdude -p m16 -c dapa \end{quotation} The -p option chooses the processor (m16 is ATMega16) and the -c option specifies the programming circuit in use. Avrdude needs the GNU/Linux parallel port driver to function properly. Verify that the parallel port driver is loaded by running the command `lsmod' and verifying that the modules ppdev, parport, parport\_pc are present. Also, make sure that there exists a device file called `parport0' under /dev/. If this file is not present, you can create it by typing (as root): \begin{quotation} mknod /dev/parport0 c 99 0 \end{quotation} \subsection{Reading fuse bits} The AVR microcontrollers have two fuse bytes (fuse low and fuse high) which control many things like what type of clock the controller runs on, what is the size of the memory area allotted for the boot loader, whether control should get transferred to the bootloader upon reset etc. Here are the individual bits of the low fuse byte expressed as two 4 bit nibbles. Lower 4 bits (bits 0 to 3, leftmost is bit 3): \begin{quotation} \begin{tabular}{|c|c|c|c|} \hline CKSEL3& CKSEL2& CKSEL1& CKSEL0\tabularnewline \hline \end{tabular} \end{quotation} Higher 4 bits (bits 4 to 7, leftmost is bit 7): \begin{quotation} \begin{tabular}{|c|c|c|c|} \hline BODLEVEL& BODEN& SUT1& SUT0\tabularnewline \hline \end{tabular} \end{quotation} A value of 0xef (binary 1110 1111) can be used if the processor clock is based on an external crystal with frequency between 3 and 8 MHz (the value of CLKSEL1-3 decides the clock source). A value of 0xe1 (1110 0001) should be used to select the internal RC oscillator with frequency 1MHz as the clock source. This is the factory default. Here are the individual bits of the high fuse byte. Lower 4 bits (bits 0 to 3, leftmost bit is bit 3): \begin{quotation} \begin{tabular}{|c|c|c|c|} \hline EESAVE& BOOTSZ1& BOOTSZ0& BOOTRST\tabularnewline \hline \end{tabular} \end{quotation} Higher 4 bits (bits 4 to 7, leftmost bit is bit 7): \begin{quotation} \begin{tabular}{|c|c|c|c|} \hline OCDEN& JTAGEN& SPIEN& CKOPT\tabularnewline \hline \end{tabular} \end{quotation} The BOOTRST bit is by default 1, make it 0 if you want the controller to jump to the `boot loader flash' section upon reset. BOOTSZ0 and BOOTSZ1 have relevance only if you are using a bootloader. Both should be made equal to zero to reserve the maximum amount of memory (2 kilo bytes) for the boot loader and they can be set to one to reserve the least amount of memory (256 bytes) for the boot loader. Refer table 100 of the controller datasheet (page number 257) for more details. Clear EESAVE to zero if you want to make sure that the EEPROM data memory is preserved during a chip erase. Set OCDEN and JTAGEN to one to disable both on-chip-debug as well as JTAG (which is also used for debugging). Usually, we won't be needing them. Clear SPIEN to zero to enable serial program and data downloading. CKOPT is usually set to one. A typical value to use for this fuse byte is 0xd9 (1101 1001). The fuse bits can be read by running: \begin{quotation} uisp -dprog=dapa -dlpt=0x378 --rd\_fuses \end{quotation} Fuse bits can also be accessed using `avrdude' - but it is a bit trickier. \subsection{Writing fuse bits} If you are using uisp: \begin{quotation} uisp -dprog=dapa -dlpt=0x378 --wr\_fuse\_h=0xd9 uisp -dprog=dapa -dlpt=0x378 --wr\_fuse\_l=0xef \end{quotation} If you are using avrdude: \begin{quotation} avrdude -p m16 -c dapa -U hfuse:w:0xd9:m avrdude -p m16 -c dapa -U lfuse:w:0xef:m \end{quotation} The -U option is to specify that what we are going to do next is a memory operation. The next argument, hfuse:w:0xd9:m says - write(w) the high fuse(hfuse) byte with the value 0xd9 specified as an immediate (m) value. The fuse bits have to properly written if the controller is to function as expected. \subsection{Writing machine code} The compiled machine code (stored as a hex file) can be written either using `uisp' or `avrdude'. Using `uisp': \begin{quotation} uisp -dprog=dapa -dlpt=0x378 --erase --upload if=a.hex --verify \end{quotation} Using `avrdude': \begin{quotation} avrdude -p m16 -c dapa -U flash:w:a.hex \end{quotation} \subsection{Writing lock bits} The AVR controllers have lock bits using which we can protect regions of memory from accidental erasure. {[}To be continued] \end{document}