Arduino Software Internals A Complete Guide to

How Your Arduino Language and Hardware Work

Together 2nd Edition Norman Dunbar pdf download

https://ebookname.com/product/arduino-software-internals-a-
complete-guide-to-how-your-arduino-language-and-hardware-work-
together-2nd-edition-norman-dunbar/

Get Instant Ebook Downloads – Browse at https://ebookname.com

Instant digital products (PDF, ePub, MOBI) available
Download now and explore formats that suit you...

Make Arduino Bots and Gadgets Six Embedded Projects

with Open Source Hardware and Software 1st Edition Tero
Karvinen

https://ebookname.com/product/make-arduino-bots-and-gadgets-six-
embedded-projects-with-open-source-hardware-and-software-1st-
edition-tero-karvinen/

Arduino Cookbook 2nd Edition Michael Margolis

https://ebookname.com/product/arduino-cookbook-2nd-edition-
michael-margolis/

Beginning Arduino 2nd Edition Michael Mcroberts (Auth.)

https://ebookname.com/product/beginning-arduino-2nd-edition-
michael-mcroberts-auth/

Evolution What the Fossils Say and Why It Matters 2.

Edition Donald R. Prothero

https://ebookname.com/product/evolution-what-the-fossils-say-and-
why-it-matters-2-edition-donald-r-prothero/
The Fisherman s Cause Atlantic Commerce and Maritime
Dimensions of the American Revolution 1st Edition
Christopher P. Magra

https://ebookname.com/product/the-fisherman-s-cause-atlantic-
commerce-and-maritime-dimensions-of-the-american-revolution-1st-
edition-christopher-p-magra/

The PowerScore GMAT Critical Reasoning Bible A

Comprehensive System for Attacking the GMAT Critical
Reasoning Questions 1st Edition David M. Killoran

https://ebookname.com/product/the-powerscore-gmat-critical-
reasoning-bible-a-comprehensive-system-for-attacking-the-gmat-
critical-reasoning-questions-1st-edition-david-m-killoran/

A Course in Mathematical Analysis Volume II Metric and

Topological Spaces Functions of a Vector Variable 1st
Edition D.J.H. Garling

https://ebookname.com/product/a-course-in-mathematical-analysis-
volume-ii-metric-and-topological-spaces-functions-of-a-vector-
variable-1st-edition-d-j-h-garling/

Coaching Skills 1st Edition Jenny Rogers

https://ebookname.com/product/coaching-skills-1st-edition-jenny-
rogers/

American Drama in the Age of Film 1st Edition Zander

Brietzke

https://ebookname.com/product/american-drama-in-the-age-of-
film-1st-edition-zander-brietzke/
Welfare States under Pressure 1st Edition Peter Taylor-
Gooby

https://ebookname.com/product/welfare-states-under-pressure-1st-
edition-peter-taylor-gooby/
MAKER
I N N O VAT I O N S
SERIES

Arduino
Software
Internals
A Complete Guide to How Your Arduino
Language and Hardware Work Together
—
Second Edition
—
Norman Dunbar
Maker Innovations Series
Jump start your path to discovery with the Apress Maker Innovations series! From the basics of
electricity and components through to the most advanced options in robotics and Machine Learning,
you’ll forge a path to building ingenious hardware and controlling it with cutting-edge software. All
while gaining new skills and experience with common toolsets you can take to new projects or even
into a whole new career.
The Apress Maker Innovations series offers projects-based learning, while keeping theory and
best processes front and center. So you get hands-on experience while also learning the terms of the
trade and how entrepreneurs, inventors, and engineers think through creating and executing hardware
projects. You can learn to design circuits, program AI, create IoT systems for your home or even city,
and so much more!
Whether you’re a beginning hobbyist or a seasoned entrepreneur working out of your basement
or garage, you’ll scale up your skillset to become a hardware design and engineering pro. And often
using low-cost and open-source software such as the Raspberry Pi, Arduino, PIC microcontroller,
and Robot Operating System (ROS). Programmers and software engineers have great opportunities
to learn, too, as many projects and control environments are based in popular languages and operating
systems, such as Python and Linux.
If you want to build a robot, set up a smart home, tackle assembling a weather-ready meteorology
system, or create a brand-new circuit using breadboards and circuit design software, this series has all
that and more! Written by creative and seasoned Makers, every book in the series tackles both tested
and leading-edge approaches and technologies for bringing your visions and projects to life.

More information about this series at https://link.springer.com/bookseries/17311.

Norman Dunbar

Arduino Software Internals

A Complete Guide to How Your Arduino
Language and Hardware Work Together

Second Edition
Norman Dunbar
Rawdon
West Yorkshire, UK

ISBN-13 (pbk): 979-8-8688-0170-9 ISBN-13 (electronic): 979-8-8688-0171-6

https://doi.org/10.1007/979-8-8688-0171-6

Copyright © 2024 by Norman Dunbar

This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned,
specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in
any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by
similar or dissimilar methodology now known or hereafter developed.
Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of
a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the
trademark owner, with no intention of infringement of the trademark.
The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such,
is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights.
While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors
nor the editors nor the publisher can accept any legal responsibility for any errors or omissions that may be made. The publisher
makes no warranty, express or implied, with respect to the material contained herein.

Managing Director, Apress Media LLC: Welmoed Spahr

Acquisitions Editor: Miriam Haidara
Development Editor: James Markham
Coordinating Editor: Jessica Vakili

Cover designed by eStudioCalamar

Distributed to the book trade worldwide by Apress Media, LLC, 1 New York Plaza, New York, NY 10004, U.S.A. Phone
1-800-SPRINGER, fax (201) 348-4505, e-mail orders-ny@springer-sbm.com, or visit https://www.springeronline.com. Apress
Media, LLC is a California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM
Finance Inc). SSBM Finance Inc is a Delaware corporation.
For information on translations, please e-mail booktranslations@springernature.com; for reprint, paperback, or audio rights,
please e-mail bookpermissions@springernature.com.
Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook versions and licenses are also
available for most titles. For more information, reference our Print and eBook Bulk Sales web page at http://www.apress.com/
bulk-sales.
Any source code or other supplementary material referenced by the author in this book is available to readers on Github
(https://github.com/Apress). For more detailed information, please visit https://www.apress.com/gp/services/source-code.

If disposing of this product, please recycle the paper.

This book is dedicated to my wife, Alison, who occasionally
allows me to have some time to myself, programming,
attempting to build things (with or without “Internet of”), and
writing notes, articles, and/or this book.
Another person to whom I am grateful is Alison’s late maternal
grandmother, Minnie Trees (yes, I did call her Bonsai!), who
gifted me an Arduino Duemilanove starter kit and rekindled my
long-lost (for over 35 years) interest in building things with
electronics.
The book is also dedicated to the myriad of people and
companies or organizations around the world who freely give
their time and skills to produce open source software and
hardware, for the benefit of others or just for fun.
If I may paraphrase the words of Isaac Newton, I too stand on
the shoulders of giants, so here’s to the giants, the little people,
and all the medium-sized ones too, who may or may not become
giants themselves. Let’s hope the fun never stops.
Finally, my own motto is Don’t think! Find out! Hopefully, this
book will help you do exactly that.
Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Arduino Installation Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Coding Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 Number Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 The Arduino Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Coming Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Arduino Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 Settings.json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.1 Finding Other Hidden Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.2 Setting Tab Stops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Globally Defined Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Boards.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.1 Arduino Uno Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4 Boards.local.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5 Platform.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.5.1 Build Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.5.2 Pre- and Post-Build Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.6 Programmers.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.7 Compiling a Sketch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.7.1 Arduino Sketch (*.ino) Preprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.7.2 Arduino Sketch (*.ino) Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.7.3 After the Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.8 The Arduino main() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.9 Header File Arduino.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.9.1 Header File avr/pgmspace.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.9.2 Header File avr/io.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.9.3 Header File avr\interrupt.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.9.4 Header File binary.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.9.5 Header File WCharacter.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.9.6 Header File WString.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.9.7 Header File HardwareSerial.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.9.8 Header File USBAPI.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.9.9 Header File pins_arduino.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.10 The init() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.10.1 Enabling the Global Interrupt Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.10.2 Enabling Timer 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

vii
viii Contents

2.10.3 Timer 0 Overflow Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2.10.4 Configuring Timer 1 and Timer 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.10.5 Initializing the Analog-to-Digital Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.10.6 Disabling the USART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3 Arduino Language Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.1 What Are We Looking At? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.2 Digital Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.2.1 Function pinMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.2.2 Function digitalRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.2.3 Function digitalWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.3 Analog Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.3.1 Function analogReference() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.3.2 Function analogRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.3.3 Function analogWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
3.4 Advanced Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.4.1 Function tone() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.4.2 Function noTone() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
3.4.3 Function pulseIn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
3.4.4 Function pulseInLong() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.4.5 Function shiftIn() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.4.6 Function shiftOut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.5 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.5.1 Function delay() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.5.2 Function delayMicroseconds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.5.3 Function micros() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.5.4 Function millis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.6 Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
3.6.1 Function interrupts() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.6.2 Function noInterrupts() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.6.3 Function attachInterrupt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.6.4 Function detachInterrupt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
3.7 Bits and Bobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.7.1 Macro bit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.7.2 Macro bitClear() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
3.7.3 Macro bitRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
3.7.4 Macro bitSet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
3.7.5 Macro bitWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
3.7.6 Macro bitToggle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
3.7.7 Macro highByte() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.7.8 Macro lowByte() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.7.9 Macro sbi() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
3.7.10 Macro cbi() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
4 Arduino Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.1 The Print Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.1.1 Class Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.1.2 Using the Print Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Contents ix

4.2 The Printable Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

4.2.1 An Example Printable Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.3 The Stream Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.3.1 Class Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
4.4 The HardwareSerial Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.4.1 Interrupt Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
4.4.2 Class Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
4.5 The String Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5 Converting to the AVR Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.2 Numbering Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
5.2.1 Decimal Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
5.2.2 Binary Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
5.2.3 Hexadecimal Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
5.3 Binary Logical Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
5.3.1 NOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
5.3.2 AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
5.3.3 OR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.3.4 XOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.4 Replacing the Arduino Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.4.1 The ATmega328P Pins and Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.4.2 Replacing pinMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.4.3 Replacing digitalWrite() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.4.4 Enabling Internal Pull-Up Resistors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.4.5 Replacing digitalRead() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5.4.6 Toggling Output Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
5.4.7 Installing digitalToggle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6 Alternatives to the Arduino IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.1 What Are the Alternatives? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.2 PlatformIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
6.2.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
6.2.2 Installing PlatformIO IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
6.2.3 Testing PlatformIO Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
6.2.4 PlatformIO for Arduino-Style Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
6.2.5 PlatformIO for AVR-Style Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
6.2.6 Burning Bootloaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.2.7 Using Your Own IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
6.2.8 Adding Additional Boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
6.2.9 PlatformIO Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
6.3 Arduino Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
6.3.1 Obtaining the Arduino CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
6.3.2 Installing the Arduino CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.3.3 Configuring the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
6.3.4 Creating Sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
6.3.5 Unknown Boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
6.3.6 Installing Platforms or Cores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6.3.7 Compiling Sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
x Contents

6.3.8 Uploading Sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

6.3.9 Uploading Sketches with an ICSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
6.3.10 Burning Bootloaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
6.3.11 Serial Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
6.3.12 Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
6.3.13 A Simple Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
6.3.14 Library Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
6.3.15 Board Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
7 ATmega328P Configuration and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
7.1 ATmega328P Fuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
7.1.1 Low Fuse Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
7.1.2 Low Fuse Factory Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
7.1.3 Arduino Low Fuse Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
7.1.4 High Fuse Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
7.1.5 High Fuse Factory Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
7.1.6 Arduino High Fuse Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
7.1.7 Extended Fuse Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
7.1.8 Extended Fuse Factory Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
7.1.9 Arduino Extended Fuse Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
7.2 Brown Out Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
7.3 The Watchdog Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
7.3.1 Watchdog Timer Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
7.3.2 Amended Sketch setup() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
7.3.3 Watchdog Timer Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
7.3.4 The Watchdog Timer Control Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
7.3.5 Enabling the Watchdog Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
7.3.6 Setting the Watchdog Timer Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
7.3.7 Disabling the Watchdog Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
7.4 Putting the AVR to Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
7.4.1 Sleep Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
7.4.2 Sleep and the Analog Comparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
7.5 Power Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
7.5.1 Power Consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
7.5.2 Power Reduction Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
7.5.3 Saving Arduino Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
7.5.4 The Power Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
7.6 Bootloaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
7.6.1 Flash Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
7.6.2 Lock Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
7.6.3 Installing the Uno (Optiboot) Bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
7.6.4 Optiboot Bootloader Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
8 ATmega328P Hardware—Timers and Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
8.1 Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
8.1.1 Timer 0 (Eight Bits) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
8.1.2 Timer 1 (16 Bits) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
8.1.3 Timer 2 (Eight Bits) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
8.1.4 Timer Clock Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Contents xi

8.1.5 Timer Non-PWM Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

8.1.6 Timer PWM Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
8.1.7 Too Much to Remember? Try AVRAssist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
8.2 Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
8.2.1 Setting External Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
8.2.2 Counter Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
8.3 Input Capture Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
9 ATmega328P Hardware—AC, ADC, and USART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
9.1 Analog Comparator (AC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
9.1.1 Reference Voltage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
9.1.2 Sampled Voltage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
9.1.3 Digital Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
9.1.4 Enable the Analog Comparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
9.1.5 Select Reference Voltage Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
9.1.6 Select Sampled Voltage Source Pin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
9.1.7 Comparator Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
9.1.8 Comparator Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
9.2 Analog-to-Digital Converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
9.2.1 ADC Setup and Initiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
9.2.2 ADC Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
9.3 USART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
9.3.1 Baud Rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
9.3.2 Double Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
9.3.3 Baud Rate Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
9.3.4 Baud Rate Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
9.3.5 What Is a Frame? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
9.3.6 Parity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
9.3.7 USART Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
9.3.8 Initializing the USART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
9.3.9 USART Completion and Error Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
9.3.10 USART Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

A Arduino Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

B ATmega328P Pinout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
C ATmega328P Power Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
D Predefined Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
E ADC Temperature Measuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
F Assembly Language—Briefly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
G Smallest Blink Sketch? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
xii Contents

H NormDuino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
I No ICSP? No Problem! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
J Breadboard 8 MHz Board Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
K AVRAssist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
About the Author

Norman Dunbar is a retired Oracle database administrator who

lives with his wife, Alison, and a cockapoo dog, Wesley, to keep
him out of trouble.
Norman has had a long-running relationship with electronics
since childhood and computers since the late 1970s, and the Ar-
duino was a perfect marriage of the two interests.
With a love of learning new things, examining and explaining the
Arduino Language and the hardware became a bit of a hobby, and
as his piles of notes expanded, Apress decided to publish his work
as Arduino Software Internals.
Since then, Norman has been diving into the slightly trickier
aspects of the Arduino—interrupts—with a view to documenting
them for his own ease of use. Once more, his notes became a book—
Arduino Interrupts—published by Apress in December 2023.
Because he never remembers exactly how much work is involved
and how hard it is to write a technical book, Norman is now writing
a third book about the Arduino, with a view to completing his
trilogy.
Norman’s motto continues to be don’t think, find out.

xiii
About the Technical Reviewer

Sai Yamanoor is an embedded engineer based in Oakland, CA. He

has over ten years of experience as an embedded systems expert,
working on hardware and software design. He is a coauthor of three
books on using Raspberry Pi to execute DIY projects, and he has
also presented a Personal Health Dashboard at Maker Faires across
the country. Sai is also working on projects to improve the quality of
life (QoL) for people with chronic health conditions. Check out his
projects at https://saiyamanoor.com.

xv
Acknowledgments

I would like to thank everyone involved in the production of this book—the people you almost never
hear about. Without them, there would be no book.
I’m grateful to the following people at Apress/Springer:
Miriam Haidara who convinced me to update Arduino Software Internals to cover changes for the
new version of the IDE and software. Jessica Vakili who has had the misfortune to have worked with
me on three books now, thanks! Also, Joseph Quatela, James Markham, and Nirmal Selvaraj who kept
answering my silly questions!
The people who turned my manuscript into a proper book, who did the indexing for me, the people
running the print machines, and the cover designers. You never get named or mentioned, but authors
do appreciate you—thanks.
Finally, to my wife Alison and Wesley the cockapoo, thanks for letting me write an update and
keeping me exercised!

xvii
Preface

If I have seen further it is by standing on ye sholders of Giants.

Sir Isaac Newton (1643–1727), in a letter to Robert Hooke, 15 February 1676

There are many books which discuss the abilities of the Arduino hardware and how best the maker
can use this to their benefit. I have many of them in my bookcase and digital versions on my phone
and tablet—in case I get bored with life and need something interesting to read. Many of these books
explain what the hardware does, and some even dig deeper into the hardware to explain how, in fairly
easy-to-understand terms, it does it.
There are no books which take a similar view of the Arduino software. There is now!
This book takes you on a journey (why do we always have to be on a journey these days?) into the
world of Arduino sketches and the various files involved in the compilation process. It will delve deep
into the supplied software and look at the specific parts of the Arduino Language which deal with the
underlying hardware, the ATmega328P (or ATmega328AU) microcontrollers—henceforth, referred
to as ATmega328P.
Once the Arduino Language has been explained, the book takes a short look at how you can
strip away the Arduino hand-holding and get down and dirty with the naked hardware. It’s not easy,
but equally it’s not too difficult. Don’t worry; this is still the C/C++ language; there’s no assembly
language required. Perhaps!

Rawdon, UK Norman Dunbar

xix
Preface to the Second Edition

Since the first edition of Arduino Software Internals was published in 2020, the Arduino environment
has moved onward with new microcontroller boards being added, numerous bugs being fixed, new
bugs introduced—albeit, not deliberately—and many improvements made.
One of the bigger changes has been to the IDE itself; it is now at release 2.1.0 and has changed
completely from the old 1.x releases. It now provides a much more modern experience with code
completion, IntelliSense, and much, much more. It still has drawbacks—when you open a new sketch,
you get a new IDE—but progress has indeed been made in lots of areas.
Another big change is the Arduino Command Line Interface. It has moved on from version 0.6
to version 0.30, and it has become a very usable tool. A couple of major improvements that come
immediately to mind are the ability to upload code with an ICSP device and the ability to burn
bootloaders. It has improved so much that the Arduino IDE has replaced the old preprocessing and
compilation subsystems with the “arduino-cli” under the covers. Sadly, it still cannot upload EEPROM
data.
PlatformIO, another alternative to the Arduino IDE, has itself improved and now, at the time of
writing—May 2023—supports over 1,500 boards, 50 platforms, and 24 different frameworks, not to
mention over 13,400 libraries!
The standard IDE for use with PlatformIO is Visual Studio Code (VSCode) rather than Atom or
the command line, although those are still available. Don’t worry if you don’t like or use VSCode;
PlatformIO Core—the command-line option—can still generate project files for an even larger number
of common IDEs such as Atom, CLion, Code::Blocks, Eclipse, Emacs, NetBeans, Qt Creator, Sublime
Text, Vim, Visual Studio, and VSCode.
The first edition of this book occasionally mentioned Windows, and at that time, I had limited
access to Windows 7. The current version, as of May 2023, is Windows 11, but unfortunately, I no
longer have access to any versions of Windows.
I hope you find the second edition as useful as, if not more than, the first edition.

xxi
Introduction
1

The Arduino is a great system for getting people into making with electronics and microcontrollers. I
was reintroduced to a long-lost hobby when I was gifted an Arduino Duemilanove (a.k.a. 2009) by my
wife’s late grandmother, and since then, I’ve had lots of fun learning and attempting to build things.
I’ve even built a number of Arduino clones based on just AVR microcontrollers and a few passive
components—it’s cheaper than fitting a new Arduino into a project!
Much has changed over the intervening years; LEDs used to cost about £10 each and came in one
color, red. These days, I can get a pack of 100 LEDs for about £2 in various different colors. Even
better, my old faithful Antex 15W soldering iron still worked, even after 35 years. Sadly, after the first
edition was published, it finally died. I bought another one, exactly the same!
The Arduino—and I’m concentrating on either the Uno version 3 or the Duemilanove here
as those are two which I’ve actually purchased (or been given)—is based around an Atmel
ATmega328 microcontroller. On the Uno, it’s the ATmega328PAU, while the Duemilanove uses the
ATmega328PPU.
Roughly, the only difference between the two is the Uno’s ATmega328PAU version is a surface
mount, while the ATmega328PPU version is a 28-pin through-hole device. They are, or should be,
identical to program, although the ATmega328PAU version does have two additional analog pins that
are not present on the ATmega328PPU.
Occasionally though, I may mention in passing the Mega 2560 R3—as I have a cheap Chinese
clone of one of these—which is based on the Atmel ATmega2560 microcontroller.
Some older Arduino boards had the ATmega168 microcontroller, which also was a 28-pin through-
hole version, but it only had 16 Kb of flash memory as opposed to the 32 Kb in the later 328 chips.
The EEPROM and RAM size is also half that of the ATmega328P devices.
The Arduino was designed for ease of use, and to this end, the software and the “Arduino
Language” hides an awful lot from the maker and developer. Hopefully, by the time you have finished
reading this book, you will understand more about what it does and why and, when necessary, how you
can bypass the Arduino Language (it’s just C or C++ after all) and use the bare-metal AVR-specific
C or C++ code instead. Doing this can lead to more space for your code, faster execution, and lower
power requirements—some projects can be run for months on a couple of batteries.

© Norman Dunbar 2024 1

N. Dunbar, Arduino Software Internals, Maker Innovations Series,
https://doi.org/10.1007/979-8-8688-0171-6_1
2 1 Introduction

1.1 Arduino Installation Paths

The version of the Arduino IDE described in this book is 2.1.0. The version of the underlying Arduino
Language is 1.8.6.
I used an installation on Linux Mint while writing this book as Linux is my operating system of
choice, plus I do not have access to Windows anymore. The IDE was installed by downloading the
zip file version, as opposed to the flatpak version, and extracted. The location I extracted into is

• /home/norman/arduino-2.1.0/arduino-ide

On first execution, the IDE will create two new hidden directories—if they don’t already exist:

• /home/norman/.arduino15 which will contain the appropriate Arduino Language files for
your chosen board(s)
• /home/norman/.arduinoIDE which holds installation log files and is now where the IDE
preferences are stored

When I compiled a sketch for my Uno board, I was prompted to install the AVR package
required by my Uno. I agreed, and AVR package version 1.8.6 was installed into /home/norman/
.arduino15, which just happens to be the same location used by the 1.x version of the IDE.
The range of preferences offered by the new IDE is not as large as previous versions. Well, it seems
that that is the case, but all is not as it seems. This shall be explained soon!
Within this book, there are references to various files provided by the Arduino software. Because of
the way I’ve installed my software and the fact that the installer versions of the download may install to
a different location, most paths used in this book will be relative to /home/norman/.arduino15.
Paths used will be as follows:
When executing the IDE, it will be found in /home/norman/arduino-2.1.0/
arduino-ide where the downloaded zip file was extracted. However, most of the interesting
files, those for the Arduino Language, are to be found elsewhere.

• $ARDBASE is /home/norman/.arduino15, the location where the IDE installed the AVR
packages for the Uno and other AVR boards.
• $ARDINST is /home/norman/.arduino15/packages/arduino/hardware/avr/
1.8.6, the location of the main Arduino files for AVR microcontrollers. This is where the various
cores, bootloaders, and so on can be found, beneath this directory.
• $ARDINC is /home/norman/.arduino15/packages/arduino/hardware/avr/1.
8.6/cores/arduino, 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
$ARDINST/cores/arduino.
• $TOOLS is where the AVR tools reside in the downloaded packages for the AVR boards. Here, you
will find avrdude and the AVR Library which underlies a lot of the Arduino Language itself. On
my system, this is /home/norman/.arduino15/packages/arduino/tools.
• $AVRINC is where the header files for the version of the AVR Library provided by the Arduino
IDE are located. In the new IDE, these are now dependent on the version of the compiler in use—
avr-g++ by default—so the path can be quite convoluted.
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
1.2 Coding Style 3

/home/norman/.arduino15/packages/arduino/tools/avr-gcc/xxxxx/avr/
include/avr.
Here, “xxxxx” is the avr-g++ compiler version and name, currently 7.3.0-atmel3.6.
1-arduino7, but this may change as new releases of the compiler are implemented by the IDE.

So, if you see a file referred to as $ARDINC/Arduino.h in the text, you will know that this
means the file

• /home/norman/.arduino15/packages/arduino/hardware/avr/1.8.6/cores/
arduino/Arduino.h on Linux.

You can see why I’m using abbreviations now, can’t you?
If you wish to examine the files on your system that I am discussing in the book, see Appendix A
for a couple of useful tips on how to avoid always having to type the full paths.

1.2 Coding Style

Code listings in the book will be displayed as follows:

#define ledPin LED_BUILTIN

#define relayPin 2
#define sensorPin 3
...

void loop() (1)

{
// Flash heartbeat LED.
digitalWrite(ledPin, HIGH);
delay(100);
digitalWrite(ledPin LOW); (2)
...
}

(1) This is a callout that attempts to bring your attention to something in the code which will be
described beneath the code listing in question.
(2) This is another callout; there can be more than one.

In the book’s main text, where you see words formatted like USCR0A or PORTB, then these are
examples of Arduino pin names, AVR microcontroller registers, bits within those registers, and/or
flags within the ATmega328P itself, as well as references to something listed in the data sheet for the
device. Where code listings are being explained, then variables from the code will be shown in this
style too.
Arduino pin numbers will be named Dn or An as appropriate. This is slightly different from the
normal usage of the digital pins, which normally just get a number; I prefer to be a little more formal
and give the digital pins their full title. <grin>
4 1 Introduction

Tip
Tips are exactly that. They give you a clue about something that may not be too well known in
the Arduino world, but which might be incredibly useful. (Or, maybe, just slightly useful!)

Note
This is a note. It brings your attention to something that may require a little more information.
It could be useful to pay attention to these notes. Maybe!

Warning
Warnings are there to highlight potential problems with something in the software or just
something that the data sheet needs you to take extra care over. There may be a possibility
of damage to your Arduino if you don’t pay particular attention. Occasionally, the data sheet
warns against doing something—so it’s best not to do what it says not to do!

1.2.1 Number Formats

Throughout this book, I need to refer to numbers in decimal, binary, or hexadecimal, from time to
time. To this end

Binary Binary numbers are written with a prefix of “0b” and a space every four bits, for
example, 0b0101 1011 0000 1101. All binary numbers will have this prefix, apart
from those which are single bit, that is, 0 and 1.
Hexadecimal Hexadecimal numbers are written with a prefix of “0x”. There are no spaces in
hexadecimal numbers, for example, 0x5B0E.
Decimal These numbers are written as you and I would normally write them, with no prefixes.
Commas will be used to separate the major groupings, for example, 23,310.

1.3 The Arduino Language

I should perhaps point out that there isn’t really such a thing as the Arduino Language. I may refer
to it frequently within the pages of this book, but technically, it doesn’t exist. What it is is simply an
abstraction of the C/C++ language, written in such a way as to make life easier for people learning to
make stuff with their Arduino. Which of the following is easier to understand?

digitalWrite(13, HIGH);

or
PORTB |= (1 << PORTB5);
1.4 Coming Up 5

The first is definitely the easiest to understand; however, the latter is by far the quicker of the
two as it just does what it says; it sets pin 5, on PORTB of the ATmega328P, to HIGH. The name,
digitalWrite(), appears to be a different language, but it isn’t; it’s that abstraction away from
plain AVR C/C++ which makes life easier for us all.

1.4 Coming Up

In Chapter 2, I explain how a sketch gets massaged into a proper C++ program and how the libraries
used in the sketch are incorporated into it. Following the brief overview of how compiling a sketch
operates, I then document the Arduino’s main() function, the various header files that it includes,
and the initialization carried out by the init() function. These initializations are part of every sketch
that you compile, so it helps if you know what the Arduino system is doing, hidden in the background,
just for you.
In Chapter 3, I explain about the features and facilities of the Arduino Language. This will include
all the commands such as pinMode(), digitalWrite(), and so on. I talk through all the
functions that relate to the Arduino, with particular emphasis on the code that applies to the standard
Arduino boards, those based on the ATmega328P family of AVR microcontrollers.
Chapter 4 looks into a number of the C++ classes (or objects) which are supplied with, and
used by, the Arduino Language. The classes of main interest here are the HardwareSerial
class which provides us with the Serial interface and its commands like Serial.begin() or
Serial.println(). However, the HardwareSerial class is not fully self-contained, so the
other, lesser known, supporting classes are also explained in this chapter.
Chapter 5 takes a brief look at how to cast off the bonds of the Arduino Language and delve into
the brazen world of AVR C++ itself, where you bypass the likes of pinMode() calls and talk to the
AVR microcontroller in something akin to its own language. Here, you will learn how you can set
the pinMode() for up to eight pins with a single instruction or how to digitalWrite() those
same eight pins, again with one instruction, and other efficient methods of communication with your
board.
Chapter 6 demonstrates a couple of alternatives to the Arduino IDE. Some people don’t get on
with it; I myself have a sort of love-hate relationship with it as I find versions 1.x of the editor a little
clumsy and slow for my liking. The new, improved versions 2.x of the IDE are much, much better,
however.
In this chapter, I will show you how you can write code for Arduino boards in both the Arduino
Language and plain AVR C/C++ code using the “PlatformIO” system and also give you a hefty
overview of the latest release of the arduino-cli utility used in versions 2.x of the IDE but available
for stand-alone use in Makefiles.
Chapter 7 is where I delve deeper into some features of the ATmega328P which, while not strictly
software, are fundamental to configuring the ATmega328P how you might like it and not as the
Arduino designers, however talented they may be, have decided.
In this chapter, I’ll be looking at the ATmega’s fuses, power reduction modes, sleep modes, and
similar features which determine how the ATmega328P works, but not necessarily what it does.
Chapters 8 and 9 are where I delve deeper into some more features of the ATmega328P which,
while not strictly software, are either important in understanding the Arduino Language or just useful
to know about. Hardware features such as the Analog Comparator (AC), Timer/counters—referred to
as timers henceforth—the Analog-to-Digital Converter (ADC), and the Universal Synchronous/Asyn-
chronous Receiver/Transmitter (USART) are covered in some detail.
6 1 Introduction

Finally, in the Appendixes, there are a number of topics that may be of interest or are kept together
in one place for reference. In here, you will find all the helpful reference material you might need,
such as pinout diagrams, and potentially useful (or unusual) code to upload to your Arduino.
There’s even an index!
Without any further ado, let’s dive in to what happens when you want to compile a sketch in the
Arduino IDE.
Arduino Compilation
2

This chapter is all about what happens when you compile an Arduino sketch and how the various
header files are used. Hopefully, by the time you have read (and understood) this part of the book,
you’ll have a much better idea of what happens during the compilation of an Arduino sketch. However,
before we dive into the gory details of a sketch’s compilation, we need to understand a bit about some
of the text files that live in and around the $ARDINST directory.
These files are used to set up the IDE’s menu options and to define the AVR microcontroller and
Arduino board to be used. Additionally, the IDE needs to know how to compile and upload sketches,
and with lots of different boards nowadays, not just those with AVR microcontrollers, these numerous
text files help the IDE configure the build tools and so on, for the specific board chosen from the
Boards menu in the IDE.
Once we have discussed the various text files, we can then get down and dirty in the compilation
process and also take a look at the hidden C++ files that the Arduino environment keeps well away
from us.

2.1 Settings.json

The file settings.json holds all the preferences for the Arduino IDE, and under versions
2.x of the IDE, it is found in /home/norman/.arduinoIDE which is a new hidden
directory, created on the first run of the version 2 IDE. On Windows, this would be
C:\Users\norman\.arduinoIDE.
You should be able to find the file after the first run of the IDE; if you have not yet done so, there
will not be a settings.json file to be found.
As you may have guessed, the file is in JSON format, which is still a text format, but has a different
layout to the preferences.txt file in previous versions of the IDE.
In the IDE, if you click File  Preferences, a dialog will be displayed showing the current
preferences. These have been read from settings.json. Just like the old preferences.txt
file, there are limited preferences that can be set on this dialog. However, there are a lot more
preferences than meets the eye!

© Norman Dunbar 2024 7

N. Dunbar, Arduino Software Internals, Maker Innovations Series,
https://doi.org/10.1007/979-8-8688-0171-6_2
8 2 Arduino Compilation

2.1.1 Finding Other Hidden Settings

The new IDE has a hidden preferences system similar to that in VSCode. You access it via the
CTRL+SHIFT+P key combination. This opens a new search bar in the editor and waits for you to
type something. Type “settings” without the quotes, which will give you a number of options. For
example:

• Open Settings (UI)

• Open User Settings
• Open Workspace Settings
• Open Workspace Settings (JSON)

The last option will allow you to edit the settings.json file directly in the IDE; this is very
useful and, at times, quicker than using CTRL+SHIFT+P. The others all appear to display the same
dialog in the IDE, and there are numerous settings available, too many to be honest.
A small example of using this option follows where we will search for the current tab size and
change it to “4,” but inserting spaces instead of a hard TAB character.

2.1.2 Setting Tab Stops

Now, you would think that an editor, for writing code, would at least allow you the ability to easily
adjust the width of the tab stops—not so the Arduino IDE!
All is not lost, as we do have that ability, but it involves editing the settings.json file;
however, we don’t have to edit it manually. These instructions only apply to version 2.x of the IDE:

• Open the IDE if not already open.

• Press CTRL+SHIFT+P.
• Type “settings” without quotes.
• Choose “Open Settings (UI).”

A new tab named “Preferences” will open in the IDE. There are two main options to the left side:

• User
• Workspace

The former will affect everything the current user does in the IDE; the latter will affect only the
current workspace or sketch.

• Click “User” and note that there are a number of categories of settings that can be changed.
• In the search box, type “tab size” without quotes. One of the displayed options is “Editor: Tab
Size.”
• Change the default of “2” to some other value that you prefer; I like four spaces, so I’ve configured
mine to be “4.”

Another useful setting to search for is “spaces.” This will allow you to configure the IDE to insert
spaces instead of actual tab characters. “Editor: Insert Spaces” is the appropriate setting.
 Another Random Document on
Scribd Without Any Related Topics
 Jacksonville, Fla., December 29, 1886.
Permission is hereby granted E. Wheaton and associates to
preach the gospel within the city limits at such places as they
may select; provided the streets and sidewalks are not
obstructed and the rights of private property are not disturbed
and there is no violation of City ordinances or statutes of the
State.
P. McQuaid, Mayor.

Galveston, Tex., Jan. 20, 1888.

To Whom It May Concern:
Permission is hereby granted to the bearer to hold religious
services on the streets anywhere within the corporate limits of
the city of Galveston, and the police authorities will lend such
protection as is necessary to enforce order at such meetings.
R. L. Fulton, Mayor of Galveston.

Office of Chief of Police,

Denver, Colo., June 23, 1888.
To any Police Officer:
This woman has permission from the Mayor to hold services on
the street.
 M. Henny, Chief of Police.

Sacramento, Cal., Aug. 24, 1888.

Permission is hereby granted E. Wheaton and associates to
preach the gospel within the city limits at such places as they
may select, provided the streets and sidewalks are not
obstructed and rights of private property are not disturbed, and
if not in conflict or violation of the city ordinances.
Eugene J. Gregory, Mayor.

FROM MISS JOSEPHINE COWGILL.

Some Years a Missionary in Jerusalem.

The following is contributed by a dear sister who has spent some
years as a missionary in Jerusalem, Palestine, and may be known to
many of our readers:
 MISS JOSEPHINE COWGILL.

Many years ago, while engaged in missionary work in the city of

New Orleans, La., I was one evening attracted by a large
gathering of people. In the midst was a woman kneeling on the
ground engaged in most earnest prayer. Many in the company
were of the worst class of people, yet they were quietly listening
and looking on with amazement. We were not accustomed to
any one praying on the streets in that manner. This was the first
time I had the privilege of meeting dear Sister E. R. Wheaton. I
can never forget the impressions made upon myself and others
by her prayers, exhortations and songs that evening. Standing
near me in that company was a woman who had charge of one
of the worst houses of prostitution in the city. Trembling and
weeping she said to me "I never heard anything like that
before. That woman makes me feel that I am an awful sinner,
and yet she loves me." That poor woman went to her house,
sent for a Bible and read it and spent the night in bitter
repenting for her sins. She was gloriously converted and then
called her household together and told them her experience and
how the Lord had pardoned her sins and made her happy in His
love. She then exhorted them to commence a new life; but if
they would not, then they must leave her house.
While in New Orleans, Sister Wheaton and those in company
with her were busily and successfully engaged in mission work
among prisoners and others of the worst class. Some years
afterward she again visited that city and the Lord greatly
blessed her work. One night, on a store-box in front of a saloon,
she preached to a large crowd. The saloonkeeper became very
uneasy and called a policeman to "take her away." He came, but
found it quite hard work to get her down and to another place.
The people wanted to hear her. She sang a song, the chorus of
which was, in part:
"If to Jesus you are true,
There's a glory waits for you,
In the beautiful, the glad forever."
Then with clasped hands she stood quietly gazing upward, with
tears rolling down her cheeks. Then with much feeling she said:
"I am homesick for heaven." I can never forget how those
words impressed me and others at that time.
Some years after I again met Sister Wheaton in Los Angeles,
California, where her work was like it had been in New Orleans.
At one time, when she had kindly offered me the privilege of
going with her to some other points, I made inquiry about how
I should take my trunk. She replied: "Sister Josephine, pilgrims
for God do not need a trunk. One valise is enough." Many times
I have thought of that reply and the good it did me. I have
never known of a more earnest and self-sacrificing Christian
worker than Sister Wheaton. The results of her labors as she
has gone forth "weeping and bearing precious seeds," cannot
be fully known until with rejoicing she comes "bringing sheaves
with her." In loving remembrance of her, I am,
 Yours in His blessed service.

Josephine Cowgill.
Haifo, Palestine.

MY FIRST STREET MEETING.

My first street meeting was in Washington, D. C., near the old

postoffice. I had spent the day in the jail, alms-house and hospitals.
I was then a stranger in the city. Some one asked me to go to a hall
where there was a little mission. We did so, and found they had
gone to the open air meeting. When we arrived the meeting was in
progress, one after another stepping out to testify or sing. No
opportunity was offered me to take any part in the meeting, as no
woman was allowed to testify. I looked to God in silent prayer to
open some way for me to speak to the people. At the close of their
service I spoke, saying, "The Lord has sent me with a message for
you dear people, and now the friends have closed their meeting and
we will not detain them, as they doubtless have other
engagements." I began to sing and God filled my soul with glory.
The needs of those poor hungry souls rose before me, as I sang and
prayed, and the message of love came welling up in my soul. I
spoke to them of righteousness, the coming Judgment and eternity.
I had held meetings in many of the principal cities of America, some
in Europe and other countries. But that night God anointed me for
street preaching and for work in slums, dives and saloons.
Closing the meeting, I thought of being alone on the street at night
with scarcely any money and not knowing my way back to my
lodging place. I said, "Oh, Lord, you know all about it." Walking
along I came to the mission and stepping in I took a seat near the
door. While I sat praying, a brother rose and told the circumstances
of the street meeting I had held, and that one of the worst men in
the city had been converted through its instrumentality. The man
had told the brother that God had saved him and he was going
home to write eight letters to his people, some of them in this and
some in the old country, to tell them what great things God had
done for him. God knew I was there and sent the message to
encourage me. After the service in the hall had closed a young lady
who proved to be the daughter of the landlady where I had been
staying, came to me and walked to her home with me. I could not
have found my way alone, not having their number, but God cared
for me.
Some extracts are given from reports of the work which were
published at different points during the first few years of my labors:

CONVERTED TO CHRIST.

THE CASE OF THE UNFORTUNATE WOMAN—CARD FROM MR. M.

Editor Hawk-Eye: Last evening at about seven o'clock Mrs.

Wheaton, the prison evangelist, and another lady of the
evangelists and myself held a meeting on the levee. Mrs.
Wheaton, who spoke on the future consequence of sin with
unusual earnestness, had the effect of breaking down Mrs. A.
into tears. Mrs. Wheaton went up to her and spoke to her. In a
few moments the unfortunate woman broke into ecstasies of joy
and commenced to leap around in a circle. For ten minutes she
kept up praising God and leaping, when suddenly she leaped
through the great crowd around, some now being horrified,
who, like many poor, unfortunate people, never saw a sudden
conversion. She ran up Jefferson street, where she was arrested
and locked up.
Had the woman been rich or popular she would have been
kindly treated, but being one of the unfortunate women of our
city she was locked up in an unclean, old filthy cell, with a bunk
for a bed. The police were informed that the woman was
converted and a lady offered to take her home last night. But
they kept her in that terrible cell with inmates in adjoining cells
 using obscene language. It is a sin and disgrace for the city
fathers to continue to have women locked up with men in the
same line of cells with such a horrifying stench and wooden
bunks. The city police are guilty of an outrageous act in
confining the woman in such a cell, when they ought to have
given her better quarters, as they had the opportunity. This
morning she was brought out before the police court; the
woman still testified that she had salvation before that court
and crowd of people. But good came out of it all as she
witnessed a grand confession to the police court and people
who never heard the gospel. She was, by the consent of
Captain S., taken to Mrs. H.'s and is doing well and is converted.
Last evening's Gazette stated that the woman went crazy by
attending the street meetings and would be examined before
the board of commissioners of insanity, which is every word of it
untrue. The woman is sane and was not before any board.
A. H. Mertz, in Burlington Hawk-Eye, Jan. 19, 1887.

A WONDERFUL CONVERSION.

In San Francisco a drunken girl came to my meeting on the street so

desperate and dangerous that even the police at times seemed
afraid of her. She seemed to be a veritable Magdalene. I was
impressed with the words, "Down in the human heart, crushed by
the tempter, feelings lie buried that grace can restore." How could it
be done? I dealt faithfully with her and went away, returning to the
city ten months later. She came again to my meetings, once very
drunk as she usually was. I talked to her about her need of salvation
and she was finally convicted. She waited at the close of the
meeting to speak with me, but at first would not yield to God. Finally
she sobered up and was wonderfully converted. I took her to my
room and cared for her, and as she was a desperate character, and
liable to do injury both to life and property, the Rescue Home at San
Francisco refused to take her, so I took all the risks myself and took
her to Helena, Montana, and left her at the Rescue Home at that
place.
The following is an account of work in Seattle soon after this as
reported by a paper of that city:

THE PRISON EVANGELIST.

MRS. ELIZABETH R. WHEATON CARRYING FORWARD HER MISSION

IN SEATTLE.

About three o'clock yesterday afternoon two women, one quite

elderly and the other about 25 years of age, whose dress and
demeanor bespoke them to be missionaries, walked into the
sheriff's office and asked Jailer Leckie if they might hold a short
religious service in the county jail. The urbane jailor replied that
he thought "a little prayin' wouldn't do them coves any harm,"
but they were eating and couldn't be interrupted for ten or
fifteen minutes.
"Then we'll wait," said Mrs. Wheaton, laying her black shawl
aside and taking a seat, in which she was followed by her sister
evangelist.
"Perhaps you would like to know who we are," said the elder of
the two women to a reporter who happened to be present.
"Here is my card," and she handed over a small piece of
pasteboard on which was printed with a rubber stamp,
"Elizabeth R. Wheaton, Prison Evangelist. Jesus is Coming Soon;
Prepare to Meet Thy God."
"That will tell who I am," continued the evangelist.... "Criminals
and fallen women are the ones I try to reach. I would rather try
to save a murderer or fallen woman than your smooth,
respectable hypocrites, every time. Mary and I have just come
through from san Francisco." * * *
 At this moment Jailer Leckie announced that the prisoners were
through eating, and the two women went below to pray with
them. The younger woman held back, saying that she was
afraid some of her old associates might be there, but she was
urged on by her protector and a few minutes later the words of
"Nearer My God to Thee," from two female voices, came
floating through the prison bars. The prisoners gave them
respectful hearing, and one or two seemed to be affected by the
earnest words of counsel that fell from the lips of the evangelist.
Later in the evening they held street services for the benefit of
the workingmen near the Armory and relief tents.

BECAME A PREACHER.

One of the worst women I ever knew was converted in the spring of
1885 on the streets of Kansas City, Mo., where I was holding
meetings. She came to the meeting to abuse and ridicule me. She
heard my voice, she said, two blocks away, and became convicted.
She came to where I was standing on a box preaching. I asked if
there was any one there who would seek God and live a Christian
life. I said if there was one such, let them come and kneel with me
by the box and I would pray for them. She knelt there and cried
mightily to God for mercy. But she went away unsaved and prayed
and wept day and night. She could neither eat nor sleep. She saw
herself a lost sinner. Her father had been a minister of the Gospel,
but had died when she was very young. She had drifted to this
wicked city in search of work, and you may know the rest. For it is
but the story of many a poor orphan girl in her struggle for bread.
She fell as thousands fall with none to pity or care. She was driven
from one sin to another, until at last disgraced and filled with shame,
she had tried twelve times to take her own life. Thus I found her a
miserable woman. She came again to the meeting, this time alone,
and was gloriously saved, and is still saved so far as I know. She
became a successful preacher of righteousness, for she knew how to
reach such as she had been. She became a terror to evil doers,
brave in danger, and hopeful before discouraging obstacles. She has
since told me she has saved many young girls' lives and characters
by taking them in and giving them food and shelter when every
other door except brothels and saloons was closed against them.
Bless God for the homes open to shelter and protect the unfortunate
girls.

THE BLIND ENCOURAGED.

One day while traveling in Montana, I went into a smoking car to

hold a little Gospel meeting, singing and distributing tracts, when I
found a blind lady there who seemed to be alone and neglected. I
spoke to her kindly about her soul and invited her to go with me into
the other car. I said, "I am always glad to do anything I can to help
a blind person. My grandmother was blind several years before her
death." She accepted it all gratefully and seemed very sorry to part
from me when we changed cars. I exhorted her to a life of Christian
service and to meet me in Heaven.
I never expected to meet her again, but some two years later I was
holding an open air meeting in California and a lady said, "Would
you allow me to testify?" and I said, "Certainly, if you are a Christian.
Would be glad to have you." When she began to speak she said:
"This lady don't know me, but I know her. We met once. Although I
have never seen her, as I am deprived of sight, yet I know her. I met
with her on the train one day," and she related the foregoing facts,
stating that my kindness had won her heart and she had never
forgotten my advice, and was now living a Christian life.

FORBIDDEN TO PREACH ON THE STREET.

One night when I attempted to hold a street meeting in F——,

California—where I had been holding services for a few nights—the
marshal said he had forbidden me to preach and sing on the streets.
A gentleman looked up the law books and returned saying that it
was not contrary to the laws of that city at that time to hold a gospel
meeting on the street and that I could proceed, but the marshal
came and forbade me, very unkindly and impolitely. At this crisis a
gentleman came up and said that a saloon keeper down the street
requested me to come and hold a meeting in front of his place. I
said: "A gentleman has requested that we come and hold a meeting
in front of his business place. We will go there, please," but the
marshal in a very ungentlemanly way said I was not to hold a
meeting on the street any place in that city.
I said we would go to a hall which had been opened for gospel
services. It was several blocks away and only a few of the immense
crowd would walk that distance. When I reached the place I sat
down behind the door and cried and thought, what shall I do? I was
sure the Lord wanted me to hold a meeting on the street. The blind
lady mentioned in the previous incident was in the congregation and
began to sing, "He is able to deliver thee," and I soon had the
victory. The same sister had attempted to sing on the street, as this
was her only means of supporting her old mother and sickly
husband, and the marshal came along and without any warning
pushed her off the street. A couple of strange gentlemen came and
kindly led her to a place of safety. I heard soon after this that this
man became suddenly insane and it took two men to hold him and
take him to the jail and from there to the insane asylum.

THOUGHT THEY SAW A GHOST.

Once, in a city, another lady and myself were walking along a very
lonesome street late at night. When passing a large dark building
she remarked that it was a very dangerous gambling den. My heart
burned within me. I was seized with an impulse to go in that place
of iniquity and warn those men of their souls' danger. No sooner
thought than done! I was soon in the room which proved to be
vacant, but I could see light through the cracks of a closed door
leading into the next room. I passed quietly across the room and
opened the door and stood confronting a number of rough looking
men who were seated at a long gambling table. Without a word I
crossed the room with noiseless footsteps and dropping my Bible on
the table and falling on my knees before them began to cry to God
in their behalf. The men seemed to take an unexpected view of the
situation, and rising simultaneously to their feet, they rushed wildly
from the room upsetting their chairs in their haste, and I was left
alone. The next day the report went out that a ghost had been seen
there the night before, and some of the men vowed they would
never touch a pack of cards again as long as they lived—that money
could not hire them to do it. Truly "The wicked flee when no man
pursueth."

HURT BY A SALOONKEEPER.

While I was at Springfield, Ill., I was led one Sabbath to go to the

park to hold a gospel meeting, taking two sisters with me. We had a
good meeting, and returning to the city I asked the street car
conductor if there was another park where I could hold services. He
directed me to a place in another suburb. We went there, and in a
grove I saw some tables and men and women sitting at them,
drinking. I began to sing a hymn, thinking we were in a public park,
when a man rushed out of a house toward me, saying, "You shan't
sing here." I said, "Please let me finish this verse." He replied, "No, I
won't allow any one to sing here." I knelt in prayer. He did not say I
should not pray. The sisters were looking at him, and said he hurried
toward me in great anger. The sisters prayed to God to spare me.
The man jerked me and pushed me over, when some of the men at
the tables called out to him, "Let go of that woman. You don't know
who she is. We know her." The men in the meantime running to us,
laid hold on the saloonkeeper and took him away. I was very much
hurt. I could not walk alone. The park proved to be a beer garden.
We went to the nearest house and asked permission to rest till I
should gain strength to return to the city. The people where we
stopped were very indignant, and said the man had no license to sell
liquor on Sunday, and was violating the city ordinance. There were
no arrests. The whisky men must have their own way in this land of
American liberty. They can ruin lives, break up homes, blight the
prospects of the best people on earth and fill the prisons,
almshouses, criminal insane asylums, brothels, graves of paupers,
and doom souls by the multitude, and who cares? Who votes to put
down the saloons? Who tries to save mothers' girls as well as
mothers' boys, husbands and wives? Even the parents are overtaken
by the demon of strong drink and sink into the most depraved
conditions in order to satisfy their craving for alcohol. O, the
awfulness of it all! Sisters, brothers, are you and I clear? Are we
doing our best to stop this horrible traffic in whisky and girls, for one
of these places can scarcely exist without the other. How many girls
and boys are sacrificed yearly to fill the saloonkeepers' coffers and
fill up hell? Think of these things.

WARNED TO LEAVE THE CITY.

Upon entering a town in Mississippi I inquired of a woman if she

could direct me to a hotel, and she told me her sister and her
husband kept one and I would be made comfortable with them.
We went to the hotel and left our luggage and went at once to hold
an open air meeting. The singing attracted a considerable crowd,
and at the close of the service many came to shake hands with me
and thank me for the meeting, among whom were a number of
colored people, who thanked the Lord in their characteristic way and
asked me to preach again which I agreed to do that night.
As we turned our steps toward our hotel, we noticed a colored man
walking a short distance ahead of us who, when we were out of
hearing of the crowd, turned and said to us: "You women don't
intend to hold another meeting on the street to-night?" and I said,
"Certainly, I shall obey God." He said, "You have shaken hands with
the colored people and the white people are angry, and they will
mob you. I came along here for the purpose of warning you. If they
saw me talking with you my life would be in danger." I told him I
was not afraid, thanked him and told him I would do as the Lord led.
On reaching our hotel the landlord asked if I intended to hold
another meeting on the street that night, and I told him I did. He
said that the townspeople had forbidden me to hold another service
and that I would have to leave his hotel at once, because I had
shaken hands with the colored people. We told him we had made
the appointment and we should keep our word. He went to his wife
and told her to go and tell those women to leave the house and take
the train, as we had associated with the colored people and the
white people would not allow us to remain in town. She replied that
we had paid our money and our money was as good as anybody's,
and that we were respectable, honest women and she was going to
treat us as such.
When we went down the street we heard a noise as of a mob, and
we went praying the Lord to show us what to do, and He showed us
our life was in danger and to step one side into the colored people's
church where God's presence was revealed in mighty power and
souls were convicted and converted.
In the morning two colored women called upon me, saying they had
come to warn me and assist me to the train. One of them said that
two nights before she had a terrible dream about a woman coming
to preach on the streets and was so impressed that she sent her
husband four miles to see if there was anything in it. This was the
man that warned us that night. When he went home and told her
what he had seen and heard, she dreamed again and the Lord told
her to come and help us out of town, as the people would take my
life. They carried our luggage and showed us to the train and got us
safely on board, and with a "God bless you, Honey, we's prayin' for
you," they were gone, and we went on our way with thankful hearts
for our Lord's protecting care.

IN JAIL.
I have several times been arrested for holding services in the open
air, but have been taken to prison but twice—once in Glasgow,
Scotland, as related elsewhere, and once in Belleville, Illinois.
In 1889, Sister Anna Kinne wrote me from Belleville that they were
holding meetings at that place, but had seen but little stir, that it
seemed to be a hard field, and that she believed the Lord wanted
me to come and help them in the meetings. I was, at the time, in
Mississippi, but after praying over the matter I felt that I should go
to Belleville in answer to her request.
The first Sabbath after reaching there I tried to hold services in the
open air, but was stopped by policemen. I tried again with the same
results. Then I went to the mayor, but was refused permission to
hold any such meetings. When I asked him if he would take the
responsibility on the day of judgment, he said, "Yes." I then went to
the jail and held services, and the sheriff kindly inquired about my
work and showed considerable interest, and took down some notes.
I then asked him for permission to hold meetings on the court house
steps. This was readily granted, and I took Sister Kinne with me. The
marshal of the town had bitterly opposed my work, and while we
were singing he very rudely and unceremoniously came and took me
by the arm and dragged me down from the steps.
I told him that the sheriff had given me permission to hold services,
but he was very angry and refused to let me go on.
I said to those who had gathered, "We will have no open air
meeting, but come to Buchanan Hall to-night, and we will have a
meeting there."
I think it was the following night that I was impressed just before
the opening of our services, to sing a hymn, standing in the mission
door. I spoke to Sister Kinne of this and she said, "God bless you,
Sister Wheaton, I will pray for you."
I went quietly down to the door and was standing there singing an
old-time hymn, when out of the darkness there came two
policemen. Without saying a word they took hold of me and dragged
me along the street. I had no bonnet on, and my shawl was
dragging along in the mud. I said, "Please let me get my shawl, and
will you please let me ask one of the ladies at the mission to go with
me?" But they refused and seemed glad to think that I was being
disgraced. As I met two or three Christian people, one of them
spoke kindly to me and I replied that I was suffering for Jesus' sake.
"You seem to be well acquainted with the men," one of the
policemen said. "No," I said, "only with a few Christians."
When we arrived at police headquarters they gave in the report that
I was on the street holding a meeting and was having a row, etc.,
which was, of course, utterly false.
I was, of course, surprised at the treatment I was receiving. I
opened my Bible, which I still held, and began reading in silence.
The officer said, "Are you making all of this ado and trouble?" I
replied, "I was standing in our mission door singing." He said, "Will
you give bail for your good behavior?" I said, "I have no money for
bail." Then he asked me if I had no friends. I told him I was a
stranger in the city. "Then," he said, "I will have to send you to jail,
or what will you do?" I said I did not know. He then told another
policeman to take me to the jail across the square, and only a few
blocks away. This policeman said to some boys who were standing
outside, "You boys stay here, we do not want a mob." But the
marshal said, "Go along boys. She wants notoriety—give it to her."
And so I went to the jail with a mob crying after me.
Arriving at the jail the kind jailor was shocked to see me in the
officer's charge, and said, "You are not a prisoner?" I said, "Yes, I
was singing in our mission door, but they arrested me." His wife
came in and kindly said, "Come into the parlor, and I will make ready
for you the spare bedroom." I was, of course, surprised and deeply
touched. "No, indeed," I said, "I am a prisoner. Take me into the cell
with the other women." Her little daughter came in and knelt down
by my side and kissed my hand, saying how very sorry she was for
me. It was on a Christmas eve, and the child was going to the
Christmas tree.
Soon the sheriff came in in a hurry and said, "You are a free
woman!" He, finding I had been arrested, had notified friends who
had given bail and secured my release. Not understanding the
sheriff, I said, "No, I am here in disgrace, and I want you to put me
in the woman's cell." But he insisted that I was free. Then I said,
"They have put me here in disgrace, and I want some one to come
and take me to our mission, as it is dark." They then sent for
someone to come for me, and such a shout as went up when I again
entered the mission hall. One good old Christian friend said, "I told
you that if she was a woman of God, and I knew she was, she would
return to the hall before the meeting was over."
It seems that a reporter who was at the police station at the time of
my arrest and heard the abuse of the officers had hurried to the
sheriff's office, and he, as I have said, had secured my release.
We give here a verbatim copy of the paper signed by friends, the
original of which I still have in my possession. Somehow the case
was dismissed, and I was never brought to trial:

VERBATIM COPY OF A RECOGNIZANCE.

(12th, 24th, 1899.)

State of Illinois, St. Clair County, ss.

This day personaly appeared before the undersigned, William
Bornmann, one of the Justices of the Peace in and for said
County, Mrs. E. R. Wheaton, James West and Wm. Meyer, and
jointly and severally acknowledged themselves to owe and be
indebted unto the People of the State of Illinois, in the sum of
Twenty-five Dollars, to be levied on their goods and chattels,
lands and tenements, if default be made in the premises and
conditions below, to-wit:
 Whereas, The above bounden, Elizabeth R. Wheaton, was, on
the 24th day of December, A. D. 1889, arrested for violation of
the city ordinance, was adjudged and required by said Justice of
the Peace to give bonds, as required by the statute in such
cases, made and provided, for her appearance to answer to said
charge. Now the conditions of this recognizance is such that if
the above bounden, Elizabeth R. Wheaton, shall personally
appear and be before me, in Belleville, on the 27th day of
December, A. D. 1889, at 9 a. m., and from day to day, and
from term to term, and from day to day of each term hereafter,
until discharged by order of said Court, then and there to
answer to the said People of the State of Illinois on said charge
of violation of the city ordinance and then and there answer and
abide the order and judgment of said Court, and thence not
depart the same without lawful permission, then and in that
case this recognizance is to become void; otherwise to be and
remain in full force and virtue.
As witness our hands and seals, this 24th day of December, A.
D. 1889.
Taken, entered into, acknowledged and approved before me,
this 24th day of December, 1899.
Wm. Bornmann, J. P.
Wilhelm Meyer, [L. S.]
Jas. A. West, [L. S.]

This occurrence caused a great deal of excitement at the time. Some

time after I met one of the editors of one of the principal papers of
the town, and he stated that a serious calamity had overtaken all
those who were active in the opposing and persecuting me, and
mentioned some who had died and others upon whom God's
judgments seemed to have fallen.
The following was taken from a paper published at Belleville:
Mrs. Elizabeth R. Wheaton, a well known prison evangelist who
has labored in nearly all of the principal prisons of the United
States, was arrested Tuesday evening by Policemen S. and S.,
while she was engaged in conducting a song service, standing
in the door at the entrance to Buchanan Hall, where a series of
meetings are being held by two other evangelists, Mr. and Mrs.
S. D. Kinne. The officers, on arriving on the scene, ordered Mrs.
Wheaton to stop singing, but as she paid no attention to their
command, she was at once arrested and hurried off to the
police station, where she was questioned by the captain of
police and the city marshal, and a little later she was removed
to the county jail, but through the courtesy of the jailor she was
not locked up in a cell. A complaint of disturbing the peace was
made against her before Justice B., and a hearing was fixed for
tomorrow before him, and a bond for her appearance was duly
executed; but while these formal proceedings were being
attended to Sheriff R., having heard of Mrs. Wheaton's
incarceration in the county jail, repaired to the institution,
immediately ordered her release, as there was no authority for
holding her there, and when the officer from Justice B.'s court
arrived with the bail bond for Mrs. Wheaton's signature, he was
chagrined to find that the lady had been released by order of
the sheriff. No further attempt was made to arrest her, and it is
probable that the matter will be dropped. Mrs. Wheaton is an
elderly lady and is deeply devoted to Christian work, especially
among the unfortunates confined in jails and prisons, and she
has a large number of testimonials as to her character and work
from prison officials, railway managers and others in all parts of
the country. Many prominent citizens expressed themselves
yesterday as deeply regretting the action of the officers in
arresting Mrs. Wheaton. The same lady, by written permission
of Sheriff R., attempted to hold religious services from the court
house steps on Sunday evening last, but she was forced to
desist by the city marshal. Mrs. Wheaton applied to Mayor B.
recently for permission to hold open-air religious meetings on
the streets, but was denied the privilege on the ground that
considerable disorder had been occasioned some months ago by
the holding of such meetings by members of the Salvation
Army, who held forth in Belleville for a time. The action of the
mayor in refusing to allow the evangelist to hold open-air
meetings, and the arrest of Mrs. Wheaton while engaged in
conducting a song service in the door of Buchanan Hall, where
the revival services are held, is causing a great deal of severe
criticism, owing to the toleration of the parading of the principal
streets by brass bands on Sundays, as well as other days, to
draw audiences for minstrel shows, etc., the gathering of
crowds on the public square by street fakirs, patent medicine
peddlers, quack doctors and others, who deal out rough jokes,
etc., in tones loud enough to be heard blocks away.
Belleville, Dec. 26, 1888.
 CHAPTER XVIII.
Rescue Work.
A Mother's Plea for Her Fallen Daughter.

So tenderly reared in the pure country air,

So innocent, gracious and true,
A sweet loving daughter, so gentle and fair.
Of the great wicked world naught she knew,
She roamed on the hillside and plucked the sweet flowers,
Nor far from my sight did she stray,
Till a shy cunning charmer invaded her bowers,
And stole my loved treasure away.

With words fair and lovely he won her young heart,

Then wooed her far from the home nest,
Then hastily pressed to the city's great mart,
My darling he tore from my breast;
So simple, confiding, ne'er dreaming of harm.
She laid her young life at his feet,
And the foul, venomed viper pierced her heart with a thorn,
And left her to die in the street.

All wounded and bleeding and covered with shame,

And knowing not wither to go,
In the haunts of the vilest she cringed her away,
To hide her disgrace and her woe;
Could I know she had gone from this cold, cruel world,
My grief would be easy to bear,
But to satiate vile passions her life-blood is sold,
And my broken heart pleads in my prayer.
Oh, bring back my darling, a poor bruised thing,
The victim of Satan's deceit,
O tell her I love her, though cursed by the fiend
That crushed her to hell 'neath his feet.
O pity my daughter, my poor fallen one,
Ye who have daughters so fair,
And shield not the monster who spoiled my loved one
And drove my poor heart to despair.
—Mary Weems Chapman.
Chicago, Ill.
For some years I have been quite intimately associated with friends
who have, perhaps, the largest Rescue Home in the world. I am told
that they have taken in more girls than any other Home of the kind.
Over 1,250 girls have there been confined and never have they lost
one of these young mothers by death. But, oh, it is a sad sight to
see them, day after day carrying their load of sorrow in their hearts.
Often when I am there, as I manifest toward them my love and
sympathy, they tell me their story of woe sad as was the cry of Eve
when banished from the presence of God. She yielded to Satan's
devices because she believed the voice of Satan rather than the
voice of God. She became an outcast—and so our sisters are still
being deceived by the devil in human form and become outcasts
from all that is good. Some of them have been won by a mess of
pottage, a mere bauble or a gewgaw. Others have the promise of
love—that which every human heart craves. These believe, trust,
yield and are ruined and some of them are so young! so ignorant!
Then there are some who have been basely betrayed or brutally
forced and then left to bear alone their shame and disgrace—for,
alas! the "traffic in girls" is not an imaginary thing, but an awful
reality.
O that the good people of our fair land would awaken and see that
justice is done in behalf of the helpless and innocent! Prevention is
better than cure. Let us guard the children and put down every
influence that would tend to demoralize either our boys or girls! But
in the meantime, let us do all within our power to lift up the fallen
and win back those who have gone astray and share the burden and
sorrow of those who suffer through no fault of their own.
Those who have been daring in sin often make the most gifted,
consecrated and valiant workers for God and souls when truly and
fully saved. I bless the Lord for the privilege of seeking and finding
some of these "diamonds in the rough." I have known many
Christian workers who had once been criminals or fallen, but who
had been rescued by some one who had a knowledge of human
nature and a heart filled with the love of God who told them of the
love of Christ and His wonderful power to save. O when we all meet
in the great Hereafter what a time of rejoicing there will be among
the rescuers and the rescued.

DRUNKEN WOMEN AND MEN.

I find hundreds of men and women, many young women, in

drunkenness and crime, and the most open daring sins. In one of
the largest drinking dens in the world I asked the proprietor if I
might sing a hymn, and he gave his consent. I was obliged to go
down stairs and through many rooms and hallways and then up a
dark stairway to the platform where the orchestra was playing.
When they ceased I sang a hymn which touched their hearts and
they cheered the singing. I offered a prayer and they all seemed to
appreciate it. There were hundreds of men only, drinking, miners
and others. Then I went where there were both men and women
drinking, and sang and prayed with them. At near midnight, while I
was engaged in prayer, one of the poor, unfortunate girls clasped my
hand and put a piece of silver in it, and stood holding my hand till I
rose. She cried and spoke of her desire to be good. She was
reminded of her old home and her mother. The proprietor then told
me I must leave, as he found he would lose her from his den. He
said he was once a Christian himself, and on coming west, saw the
money to be made in that kind of business, and fell, and went deep
in sin, leading others down with himself.

ASSAULTED IN A DIVE.

While in San Pedro, California, I went, one night, into a saloon to

invite the men to a gospel meeting at the mission on the same
block, and the keeper sprang up from his gambling table, where he
was engaged with several others in a game of some kind, and
rushing towards me, violently grabbed me by the arms, and then
with both hands clutching me, rushed me to the door, using vile and
insulting epithets to me as he went. At the door a lady said, "This is
a public house; you dare not throw people out who have done you
no harm." He finally released his Satanic grasp upon me. I had only
spoken a few kindly words to two young men standing at the bar in
the act of raising their glasses to their lips. I had just said, "Don't
drink it, boys, please don't," when the assault was made. As the
saloonist rushed at me, I said, "Don't touch me, please; I will go
out." But he seemed fiendishly happy in injuring and insulting a
helpless old woman, who only wished to do them all good, and see
them saved in Heaven at last. The only excuse he ever made was
that he thought I was Carrie Nation. Commenting on this
occurrence, a Los Angeles paper contained the following item:

San Pedro, March 29.—"Mother" Wheaton, a well known prison

evangelist, was roughly assaulted by John Wilkins, a Front
street saloonkeeper, shortly after seven o'clock last evening.
Mrs. Wheaton was preaching to a large gathering in front of
Wilkins' joint, and hearing loud cursing within, the aged
reformer entered, intending to invite the blasphemers to Peniel
Mission, where services are held every evening. She had
scarcely passed inside the doors of the dive, when Wilkins
rushed forward, seized her and thrust her backward. At the
same time he applied vile epithets to her, shouting angrily: "Get
out of here, woman, and be quick about it!"
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebookname.com