APPENDIX A Arduino Paths The installation paths, versions, etc. used in the book, relating to the Arduino IDE and the files to be found within that installation, are listed in the following. Be aware that these paths are valid for a download of the Arduino software as a zip file only. Downloading the installer, or, on Linux, running an install using the package manager for your distribution, may result in a different location. My main workstation is Linux based, so most of the paths and others in the book refer to that, unless there is a specific need to refer to a Windows file or folder for any reason: • $ARDVERS is 1.8.5. • $ARDBASE is the location where I extracted the Arduino installation zip file. This is where you will find the file arduino.exe on Windows or arduino on Linux. These are the Arduino IDE for your operating system. My actual locations are • Linux – /home/norman/arduino-1.8.5 • Windows – c:\users\norman\arduino-1.8.5 • $ARDINST is the location of the main Arduino files for AVR microcontrollers. This is $ARDBASE/hardware/ arduino/avr and, on my Linux system, expands to / home/norman/arduino- 1.8.5/hardware/arduino/ avr. This is where the various cores, bootloaders, variants, and so on are to be found. © Norman Dunbar 2020 557 N. Dunbar, Arduino Software Internals, https://doi.org/10.1007/978-1-4842-5790-6 APPENDIX A ARDUINO PaTHS • $ARDINC is the location of many of the *.h header files and most of the *.c and *.cpp files that comprise the Arduino Language for AVR microcontrollers. This is, on my setup, $ARDINST/cores/arduino which expands to the path /home/norman/arduino- 1.8.5/hardware/ arduino/avr/cores/arduino. • Finally, $AVRINC is where the header files for the version of the AVR Library provided by the Arduino IDE are located. The Arduino Language (eventually) compiles down to calling functions within the AVR Library (henceforth referred to as AVRLib), and the header files are to be found in location $ARDBASE/hardware/tools/ avr/avr/include or /home/norman/arduino-1.8.5/ hardware/tools/avr/avr/include. The following will be helpful on a Linux computer, if you wish to follow the text of the book and view the source code files referred to when I am describing the contents of such files. Listing A-1 is for Linux or MacOS users, while Listing A-2 is for Windows. Listing A-1. shell_exports.sh for Linux and MacOS. export ARDVERS=1.8.5 export ARDBASE="${HOME}"/arduino-"${ARDVERS}" export ARDINST="${ARDBASE}"/hardware/arduino/avr export ARDINC="${ARDINST}"/cores/arduino export AVRINC="${ARDBASE}"/hardware/tools/avr/avr/include Setting up the variable is simple: source shell_exports.sh The corresponding script for Windows users is shown in Listing A-2. 558 APPENDIX A ARDUINO PaTHS Listing A-2. shell_exports.bat for Windows 7 @echo off set ARDVERS=1.8.5 set ARDBASE=%HOMEPATH%\arduino-%ARDVERS% set ARDINST=%ARDBASE%\hardware\arduino\avr set ARDINC=%ARDINST%\cores\arduino set AVRINC=%ARDBASE%\hardware\tools\avr\avr\include Alternatively, you could set the preceding environment variables up in Control Panel’s System applet. You should, obviously, change paths to suit your name and installation. You can now look at files, on Linux, by running the command view ${ARDINC}/Arduino.h You may, of course, replace view with your preferred editor, be it emacs, nano, or similar. If you have the xdgutils package installed, then the following command will open files in the default application: xdg-open ${ARDINC}/Arduino.h Similarly, on Windows, to open files in the default application, simply execute commands similar to the following, within a command-line session: %ARDINC%/Arduino.h This obviously assumes that files with an .h extension will have a default application set up to open them. If not, load them into your favorite text editor. 559 APPENDIX B ATmega328P Pinout Figure B-1 shows the position and names of the pins on an ATmega328P device. Figure B-1. ATmega328P pinout diagram In the preceding diagram, we have the following: • The dark area in the center of the image is a representation of the ATmega328P – if you use your imagination, that is! At the top and bottom are labels identifying the contents of the appropriate columns. © Norman Dunbar 2020 561 N. Dunbar, Arduino Software Internals, https://doi.org/10.1007/978-1-4842-5790-6 APPENDIX B ATMEGa328P PINOUt • Closest to the ATmega328P is the column labeled “Pin,” and the numbers in those columns are the physical pin numbers on the device. The ATmega328P is a 28-pin device. • The next column outward is labeled “AVR” and contains the names of the pins as defined by Atmel/Microchip. The Arduino uses a different naming standard. When reading the data sheet for the ATmega328P, these are the names that will be used. • The columns labeled “PCInt” list the appropriate pin names, again defined by Atmel/Microchip, to be used when running code that handles Pin Change Interrupts. Here you see names such as PCINT0, PCINT5, etc. • The next column outward, labeled “Arduino,” indicates the Arduino pin names which can be used in your sketches. You should be familiar with names like D0, A5, etc. by now, I hope! Do remember the various Dn pins are not named like that in sketches; they just use the number. Pin D5 will be specified as just 5 in a sketch. The analogue pins, A0–A5, do use the A prefix. • Finally, in the columns labeled “ALT,” we have the list of alternate functions for a number of the pins. These alternate functions can be enabled using fuses in some cases or can be selected by setting bits in various control registers as necessary. 562 APPENDIX C ATmega328P Power Restrictions The ATmega328P is limited in the power it can source or sink: • In total, the device can source or sink up to 200 mA maximum. • On each port, however, only up to 100 mA maximum is allowed. • On each individual pin, the limit is 40 mA maximum, but 20 mA is the preferred limit. Exceeding one or more of the power restrictions will probably damage your device and may render it useless, so take care. If you hear a click, notice a strange smell, and see blue smoke, then like me, you have overdone it! The limits given mean that you should be thinking of using some form of a driver, a transistor, or a MOSFET, if you need to drive anything bigger than an LED on each pin. LEDs normally run around 20 mA. At least the red ones do – green and blue take more. A 2N2222 NPN transistor will safely drive up to 1000 mA and, with a 220 Ohm resistor between the Arduino and the base pin, will draw only around 15 mA from the Arduino – well within limits. © Norman Dunbar 2020 563 N. Dunbar, Arduino Software Internals, https://doi.org/10.1007/978-1-4842-5790-6 APPeNDiX C ATMeGa328P POWeR ReStRictiONS C.1. Power in Total The ATmega328P is restricted to a maximum of 200 mA power, sourced or sunk, in total over all the ports and pins. C.2. Power per Port You are advised, in the data sheet, that while each pin within a port can source or sink up to 20 mA, the total current for a single port must be limited to a maximum of 100 mA. This therefore limits each port to a maximum of five pins running at full power. However, on the ATmega328P, there are three ports, and the power restrictions on the entire chip are limited to 200 mA, so it is not possible to drive the microcontroller at capacity on all three ports. C.3. Power per Pin Although each pin can source or sink up to 40 mA, the data sheet warns that this should be restricted to a preferred maximum of 20 mA per pin, bearing in mind that each pin belongs to a port and ports have their own maximum power limit as does the device as a whole. 564 APPENDIX D Predefined Settings The Arduino init() function sets up a number of different features of the AVR microcontroller so that your sketch can make best use of same. These are briefly described in the following, all in one place, for reference. D.1. Global Interrupts Interrupts are enabled globally. D.2. Timer/counter 0 Timer/counter 0 is configured with a divide-by-64 prescaler and in 8-bit Fast Hardware PWM mode to allow analogWrite() on pins D5 and D6. The PWM frequency is System_clock / (Prescaler * 256) = 16e6 / (64 * 256) = 16e6 / 16384 = 976.5625 Hz The Fast Hardware PWM mode simply counts up from 0 to 255, which is 256 different values, and then rolls over to 0 again for the next count up. The data sheet suggests that controlling motor speeds with Fast Hardware PWM isn’t the best of ideas. (No, I don’t know why either!) This would suggest that if you want to control motors, D5 and D6 are not the best pins to be used. © Norman Dunbar 2020 565 N. Dunbar, Arduino Software Internals, https://doi.org/10.1007/978-1-4842-5790-6 AppENDiX D PREDEFiNED SETTiNGs Timer/counter 0 is also set up with an Overflow interrupt which updates the millis() counter via variables timer0_millis, timer0_ overflow_count, and timer0_fract. These three variables account for the 9 bytes of Static RAM (SRAM) that every sketch uses as a minimum. There are two unsigned longs taking up 4 bytes each and one unsigned char using up the final byte.