Endless Ebook, One Click Away – Start Downloading at ebookname.

com

Arduino Software Internals A Complete Guide to How

Your Arduino Language and Hardware Work Together
2nd Edition Norman Dunbar

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

OR CLICK HERE

DOWLOAD EBOOK

Browse and Get More Ebook Downloads Instantly at https://ebookname.com

Click here to visit ebookname.com and download ebook now
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
Another Random Scribd Document
with Unrelated Content
The Project Gutenberg eBook of The Fairy and
the Witch
This ebook is for the use of anyone anywhere in the United States
and most other parts of the world at no cost and with almost no
restrictions whatsoever. You may copy it, give it away or re-use it
under the terms of the Project Gutenberg License included with this
ebook or online at www.gutenberg.org. If you are not located in the
United States, you will have to check the laws of the country where
you are located before using this eBook.

Title: The Fairy and the Witch

Author: A. D. Nelson

Release date: September 13, 2020 [eBook #63192]

Most recently updated: October 18, 2024

Language: English

Credits: E-text prepared by Mary Glenn Krause, David E. Brown, and

the Online Distributed Proofreading Team
(http://www.pgdp.net) from page images generously made
available by Internet Archive (https://archive.org)

*** START OF THE PROJECT GUTENBERG EBOOK THE FAIRY AND

THE WITCH ***
The Project Gutenberg eBook, The Fairy and the Witch, by A. D.
Nelson

Note: Images of the original pages are available through Internet

Archive. See https://archive.org/details/fairywitch00nels
 The Fairy
and The Witch
BY
A. D. NELSON.

PRICE 15 CENTS

Eldridge Entertainment House

Franklin, Ohio
 —HERE ARE—
SOME OF OUR VERY NEW TITLES
It is always a satisfaction to be the first to get hold of
new and novel entertainments, and here is YOUR
chance:
PLAYS FOR FEMALE CHARACTERS
Aunt Deborah’s First Luncheon 25c
When Shakespeare Struck The Town 25c
Ye Tea Party of Ye Olden Time 25c

TWO CLEVER MUSICAL PLAYS FOR CHILDREN

Under The Sugar Plum Tree 40c
In Little Folks Town 40c
TWO NEW MOCK TRIALS
Father Time’s Christmas Trial 15c
Will Soakum’s Matrimonial Bureau 25c

THREE SPLENDID BOOKS

Dramatic Stories, Myths and Legends
{
Paper 35c;
For Children—The Stage or School Room Boards 50c

Good Stunts for Commencement Week 50c

Novelties That Will Enliven This Festive
Occasion

What to Say for Closing Day 30c

Good Dialogs, Exercises, Etc. for Closing Day.
 SEND ORDERS TO
ELDRIDGE ENTERTAINMENT HOUSE
Franklin, Ohio
THE FAIRY AND THE WITCH

An allegorical sketch for Hallowe’en, in which is

related the fall of Black Witch and the
rise of White Fairy.

By A. D. NELSON.

Copyright, 1915, Eldridge Entertainment House.

Eldridge Entertainment House.

FRANKLIN, OHIO.
 PROPERTIES.
One black kettle or cauldron, of iron.
One tripod constructed of rough sticks about 2 inches
in diameter and fastened at top by wire, chain or rope
from which kettle is hung.
One wand for White Fairy.
One Black Rod for the Witch, to be so constructed that
it will break into two pieces at will.
One contrivance for making a light appear in witch’s
kettle at will.
An organ or piano for music, off stage, if desired
where indicated in lines of play.
 CHARACTERS.
White Fairy—an older child, female.
Black Witch—adult, female, or an additional
effectiveness can be made in the denouement if this
be impersonated by a male, speaking in a shrill high-
pitched falsetto.
Mirth—First Fairy Messenger, child, male or female.
Jollity—Second Fairy Messenger, child, male or female.
Erebus—Imp of Blackness, child, male or female.
Noctis—Black Fury of Night, child, male or female.
The Children—in any number.
 COSTUMES.
Conventional costume for White Fairy; also
conventional witch costume for Black Witch with
addition of black mask and hood for face and back of
head to conceal identity. The witch costume to be so
constructed that it can be easily removed.
Fairy Messengers clad in white or some diaphanous
drapery of light blue or pink.
Erebus and Noctis costumes, black, armless inverted
sacks running from a point above head to a fullness at
shoes with eye-holes, etc., cut in proper place.
Children costumes, as they may be dressed.
 The Fairy and The Witch.
(Scene: A clearing in the forest, with
Witch’s kettle suspended on tripod near
the Right Front of Stage. No scenery is
necessary but an added effectiveness
can be secured if play is given out of
doors.)
(Enter White Fairy from back of stage, to
accompaniment of light, lilting music if desired. White
Fairy in pantomime casts spell over region by tripping
lightly to right of stage and waving wand, thence over
kettle, thence to front, thence to left. Exit White Fairy
at rear, music ceases.)
(Enter Black Witch from left, plods toward kettle
chuckling fiendishly. Bends over kettle, presumably
examining it, then moves towards left across front of
stage during reading of lines.)
Black Witch (boastfully) Mistress of this black night am I. Witch and
wizard of all the powers of night and darkness I am. Supreme above
all good in the Spirit World, tonight on mundane earth. I come to
work my spell and my skill in arts malign display. Not all the holy
saints, who tomorrow rule the day, can wrest from me my power of
night—Hallowe’en! (in derision) A hallowed evening! Oh, ho, ho! Ah,
ha, ha!! From that proud eminence brought low by me and now
decreed to devilish deeds and dark! Thus shall it ever be. (Calling
toward left, off stage.) Come now my hosts of somber reputation.
Make merry! With fell design make we night hideous. Come Owl and
hoot for me! (Listens, no response, calls louder.) Come Owl! Hoot
Owl! (Owl hoots off stage, left. Aside, chuckling.) Didst hear the old
fool hoot? (Calling owl) Come nearer Owl, perch thou upon my
shoulder. (Owl hoots again very faintly. Pleading) Come Owl, Owl
come! (No response. Grows slightly alarmed. Muses) What portends
this? Am I now to lose my power as Jove hath so long menaced?
Owl has fled and will not come to me. (Pauses, resumes hopefully)
Ah, well, in my train come others who will heed and answer me. This
night Black Witch must have her way!
(During next lines while calling upon her hosts the
Witch moves to and fro calling toward different
sections of the region as taste may dictate except as
indicated with the lines.)
Black Witch Black Cat, most common beast of evil augury, what
sayest thou? Come forth Black Cat. Let thy penetrating howl echo
through the wood. Roost thou upon my back. Come Black Cat, oh!
Black Cat come! (Pauses, looks expectantly toward tree, no
response. Then muses a trifle sadly.) Ah! ’tis indeed a night of evil
omen when my own Black Cat forsaketh me. (Turning hopefully)
Raven! Thou bird of sable plumage, bleak and drear, hear thy
mistress call. Sound thy raucous note athwart the evening air. Come
Raven! bear me company. (Pauses, no response. Despairingly)
Raven too is gone and will not heed my voice. (Brightening) Oh!
well, not yet do we despair, with ill intent and fury unabated call we
yet others! (From front center of stage directly facing audience.)
Come snake! sleek-bellied serpent, curse of women, cursed by men,
come forth my own beloved. (Drags point of cane, wiggling, along
ground from stage front towards self.) Start from thy hole, oh! snake
of mine. Let thy rattling hisses be heard among the leaves. Coil
clammily around me! (Pauses, no response, resumes furiously)
Seven curses be upon thee, pampered pet of Eve, and thou wilt not
come! (Turns away in despair and next calls with rather hopeless
air.) Jackal, night prowler of the forest, hast thou joined this motley
crew of renegades? (Pleadingly) Heed my voice, oh! Jackal! Prithee
leave thy secret lair; come forth! Strike thy eerie call weird and
dominant! Soft-footed creep through the forest aisles reposing at my
feet. (Pauses, no response, resumes furiously.) Keep to thy den
accursed beast forever! Rot and die!
Black Witch (Musing sadly) Even yet, methinks, I must rely upon my
frisky imps of darkness to aid in this foul festival! (Again brightens
hopefully, exclaims) But no! But no!
(At this line Black Witch should be near front of stage
at point directly in front of place where Mirth will enter.
During next lines Black Witch raises arms aloft in
supplication and backs toward place of Mirth’s
entrance.)
Black Witch (Moving backwards, hands aloft in earnest supplication.)
Come, Wind of night! oh, Night Wind come! Thy blasting fury loose
upon this world! (Pauses, drops arms, no response, again muses
sadly.) Ah! Wind of Night, on which I’ve drifted through the sky
these thousand years, hast thou too deserted me? (Again raises
arms aloft and cries in desperation) Will none come forth to do my
will?
(Enter Mirth, silently, directly behind Black Witch.
Remains behind B. W. and out of her sight, dogging
her footsteps, poking fun at her, making grimaces,
etc.)
Black Witch (Moving towards kettle soliloquizing brokenly) Ah,
mighty Jove, hast thou delivered me unto mine enemies on this dark
night of all dark nights?—Some one has cast a spell upon the place
and for the moment I am powerless—Aye! for the moment! (looks at
her rod as if conscious of it for the first time) But I have still my
trusty rod of black, and it will yet dispel this impotence oppressive—
Though my voice fail this rod will fail me not!
(Makes passes over kettle with rod and turning slightly
catches sight of Mirth.)
Black Witch (Rather amused as if White Fairy were a foe of small
consequence.) Ah, ha! White Fairy is now revealed as Jove’s agent
to work my ruin and she hath sent Mirth, her messenger, to haunt
my footsteps and bedevil me! (chuckles, then calls) Come Erebus,
Imp of Blackness, come! Make haste and drive this Mirth away.
 (Erebus groans, off stage, left)
(Enter Erebus from left, treading slowly and heavily)
Black Witch What ails thee, Imp of Blackness?
Erebus (Yawning) I sleep and cannot wake. My feet drag like lead
behind me. (groans) My eyes will not open and my body wilts in
sleep.
Black Witch (Musing) It is the dread fairy spell! (severely to Erebus)
Cease thy deep grumblings and drive Mirth away from here.
(Erebus takes after Mirth. Mirth tripping lightly, Erebus
dragging himself along heavily.)
(Exeunt Erebus and Mirth to back of stage.)
Black Witch (Calling, toward left) Come also Noctis, Black Fury of the
night, come too! Speed thee hence. Lend thy brother aid.
(Enter Noctis, moaning and yawning, also treading
heavily as if in a stupor.)
Noctis (Lifelessly) Did call me, mother Witch?
Black Witch (Sharply) I did, and art thou also sodden with a heavy
stupor?
Noctis (Trembling) I am, dread mother Witch. My eyes refuse to
open and my feet will not obey my will.
Black Witch (Impatiently) Cease thy grumblings and be thankful that
you live.
(Enter Erebus from back moving with crestfallen air
towards witch.)
Black Witch Even now methinks almighty Jove hath delivered this
region to White Fairy and our course is run. (turns to Erebus) Did
Mirth escape thee? (Erebus bows head) Sodden Imp! (to both) But
come, let us brew our witch’s brew. Gather around and with mighty
magic incantation will we boil a brew to blight the world.
 (Enter Mirth and Jollity from back as Black Witch,
Erebus and Noctis move toward kettle. Mirth and Jollity
dog footsteps of the three, remaining out of sight
poking fun at Witch, etc. Black Witch, Erebus and
Noctis begin to spread out around kettle while Black
Witch makes few passes with wand. She catches sight
of Mirth and Jollity and screeches.)
Black Witch (Screeching) Erebus and Noctis! fly after these unholy
imps of light!
(Erebus and Noctis pursue Mirth and Jollity, the fairy
messengers tripping lightly, Erebus and Noctis
following heavily. Exeunt, the four, to back of stage.)
Black Witch (following a few steps) Fly, fly! Let not your footsteps
laggard be. Capture them and, returning hence, let their bones and
flesh serve but to fill the pot. (Turns toward kettle, chuckling with
glee.) Oh, ho, ho! Ah, ha, ha! Two fairy messengers to grace the
witch’s brew. Fine will be the scent as their bones are burned and
flesh is boiled into the stew! (Turning) Erebus and Noctis, fail me
not!
(Enter Erebus and Noctis returning from chase empty
handed, from back of stage.)
Black Witch Didst let them escape thee, dull imps?
Erebus and Noctis (heads hanging) Aye, dread mother.
Black Witch (Beating Erebus and Noctis about shoulders with rod)
Stupid dullards! Worthless laggards! See that ye fail me not again!
(Indignant) Come with me and gather ’round the cauldron.
(They move over to kettle and take positions around it.
Black Witch makes passes with rod and at signal from
Black Witch all three chant chorus of incantation song.
The solo stanzas of this song, also the chorus are to be
droned out in a slow, sing-song chant, no particular
tune or melody desired. Make it as weirdly unmusical
 and inharmonious as possible, but let the words “get
across” distinctly.)
Chorus (Black Witch, Erebus and Noctis, while moving around the
kettle circling slowly.)
We’re watching the pot and it’s going to
boil;
The air will get hot and this region will
spoil,
But that matters not for we brew
witches’ oil.
(Stop circling. Black Witch waves rod. She reaches
over and fingers the head of Erebus, tosses hand
toward cauldron. Repeats process with Noctis. The
three immediately resume circling around kettle while
Black Witch sings first stanza in solo.)
Black Witch (solo chant)
1 A louse and a lizard
And two babies fair;
The brains of a pole-cat,
Some coyote’s hair;
Animals, reptiles
And birds of the air,
We take of their entrails
And stir them with care.
Chorus (the three, still circling)
We’re watching the pot and it’s going to boil,
The air will get hot and this region will spoil,
But that matters not for we brew witches’ oil.
(All cease circling at conclusion of this chorus. Black
Witch to be behind kettle facing audience. Erebus and
Noctis on each side. While Black Witch sings next
 stanza the three sway back and forth but do not circle
around.)
Black Witch (solo chants)
2 To those must be added
The element, strife;
Some envy and malice—
The ills of our life—
Vengeance and jealousy,
Backbiting, lies,
All put in the kettle
With things we despise!
(The three immediately begin circling again and chant
chorus.)
All We’re watching the pot and it’s going to boil,
The air will get hot and this region——
Black Witch (Interrupting hysterically and shaking rod menacingly
towards Erebus and Noctis in turn.) Curses upon thee, torpid imps!
Canst not chant with thy wonted vim? Let thy voices swell to the far
gods, else will sovereign Jove hear us not. Raise thy voices. I
command thee!
(The three resume circling and re-commence the
chorus, Erebus and Noctis chanting louder.)
All We’re watching the pot and it’s going to boil,
The air will get hot and this region will spoil,
But that matters not for we——
Black Witch (Interrupting by beating the kettle with rod and
screaming furiously) Curses upon thee, dead! black! pot!!
(Enter White Fairy at back of stage at word “pot”. Fairy
raises wand. Light appears inside of kettle as Black
Witch beats it, to be so timed that the glow appears at
instant White Fairy raises wand.)
Black Witch (screaming triumphantly) Ha! ha! it comes! Light comes
—light make fire—come fire—fire come!
White Fairy (coming forward and interrupting) Stop! I command
thee, stop!
(Erebus and Noctis shiver, moan and fall prone on the
ground, remaining there until told to fly by Black
Witch.)
Fairy (From position a trifle to the left and back of kettle, gazing
steadily at Witch, ignoring imps.) This night thou art delivered unto
me.
Black Witch (moving toward Fairy) Not so, not so, loathed Fairy.
Though ages old I still am young and thou shalt not prevail.
Fairy (calmly) Thy power is gone——
Black Witch (Interrupting in derision) Not yet, dear Fairy! (continues
with air of triumph) See yonder glow in my black pot? With my rod I
brought it and it will burn and brighten until thee and thine
consumed and parched be, and the whole world blighted. This rod,
my power, though it weakened be, is potent still and thou canst do
naught against me——
Fairy (Interrupting with cool hauteur) That light is mine. I caused it
there. Forever it will glow—a fairy gleam to light and bless the world.
Thy power is gone, thy rod is dead.
(Black Witch begins to laugh scornfully, moves over
and gazes into pot, is startled and laugh is choked
down.)
Black Witch (murmuring hopelessly) ’Tis true. ’Tis true.
(Black Witch grows afraid, moves away from kettle
towards left across front of stage, muttering. Fairy
maintains her original position but turns around slowly
following movements of Black Witch with her eye.
 Fairy makes passes with wand toward Black Witch.
Black Witch trembles and becomes furiously enraged.)
Black Witch (hysterically) Begone, foul fairy, ere I smite thee dead!
Fairy (Calmly) Do thy worst. Thy worst is less than none.
(Black Witch grows desperate, approaches White Fairy
and raises rod to strike her. At this moment B. W.
should be to left of Fairy.)
Black Witch With mine omnipotent rod I kill thee!
(Fairy smiles, holds forth her wand. Arms of Black
Witch become rigid in mid-air.)
Black Witch (screaming) Fly Erebus and Noctis, Imps of Blackness,
for your lives make haste! Away! Away!
(Exeunt Erebus and Noctis to back passing to the right
and behind Witch and Fairy.)
White Fairy (still smiling) Break rod, rod break!
(Touches rod with wand, rod breaks.)
White Fairy (slightly toward audience) And thus shall broken be her
power forevermore.
(White Fairy waves her wand toward Black Witch,
Black Witch trembles, groans, broken piece of rod falls
from her hand.)
Black Witch (muttering) ’Tis true. ’Tis true. Jove hath forsaken me
and aids this young sprite to do me harm—— (words trail off into
silence as White Fairy continues to wave wand.)
White Fairy (Low and rather sadly) Thy lips are silent now forever.
Now thou must sleep—sleep witch, no longer witch.
(White Fairy continues to wave wand slowly. Black
Witch nods head drowsily, wilts into sleep and falls to
ground.)
White Fairy Thou hast fallen. A deeper sleep is thine than fell upon
the Imps of Blackness. Sleep forever—wake no more!
(Black Witch exhales one last breath. Dies.)
White Fairy (solemnly) Thine is a sleep eternal. Thou art dead.
(White Fairy gives one last pitiful look at dead Witch,
then turns away smiling.)
White Fairy (calling) Come Mirth and Jollity! Come, children, come.
(Mirth and Jollity and children, come tripping in with
exclamations of childish delight, etc., until they spy the
dead Witch; then their cries are hushed, their tripping
ceases and they move furtively on tip-toe over to
White Fairy glancing at her for explanations.)
White Fairy Black Witch is dead. Her power is gone, and Hallowe’en
shall always be a hallowed evening—holy night! redeemed from evil
by the power of light. Let men rejoice and women sing. Let children
play and dance. This night, henceforth, is sacred to the joys of
children.
(Children clap hands in applause.)
White Fairy Come! let us dance.
(Music starts up. Any lively dance song for children
such as can be found in any school music book will be
suitable here. All clasp hands and begin to circle
around kettle, singing and dancing. Music breaks off
and all stop singing abruptly in middle of first stanza.
Children all glance towards dead Witch then towards
Fairy.)
White Fairy What is it, children?
Mirth Good Fairy, we want no one to die.
White Fairy (touching Mirth with wand) Bless you, dear messenger
of mine, but the witch is evil and cannot live.
Jollity Can’t you give the witch her life but keep her evil power away
from her?
Children (in unison) Please good Fairy, restore the Witch’s life! Please
oh! please.
White Fairy (pondering) Your pleas move me. I will restore the
witch’s life. In Spirit world she can no longer live. A mortal, she must
dwell upon the earth.
(Children cluster in “background” as Fairy goes toward
Witch.)
White Fairy (touching Witch with wand) Insensate clay awake!
Moved by the tears of children, whom thou hast terrified and
wronged, I give thee life. Thou canst no longer dwell with spirits.
Wake in mortal form!
(Witch begins to show signs of life as White Fairy
continues to wave wand.)
White Fairy (Resuming) Too long hast thou disgraced thy sex in
Spirit World, in mortal life thou shalt assume the guise of man.
(During preceding lines Witch must unfasten necessary
strings, hooks, etc., to allow entire costume to fall off
as she rises. Fairy reads next line upon receiving signal
from Witch that all is ready.)
White Fairy (stepping back and raising wand) Rise mortal man.
(Mortal rises, children cheer.)
White Fairy (Continuing) Be grateful for thy life.
Note—If part of Witch is played by female omit this
line and change words to feminine gender in following
lines where necessary. In the original production the
Witch was effectively impersonated by a young man
thus bringing out a stronger anti-climax upon
restoration to life.
Mortal (bowing) I am grateful.
(Fairy disposes of wand by hanging it on her dress.)
White Fairy Thy life is due these children. See thou be good to them
else will thy life be forfeited to me again. Love them, I command
thee.
Mortal (bowing low and gently kissing Fairy’s hand) I will love them
and obey thee, most gracious majesty.
(White Fairy and Mortal clasp hands and turn toward
audience.)
White Fairy Thus ever shall the powers of night and darkness be
dispelled.
Mortal And good will triumph over evil everywhere.
(They bow to audience and to each other.)
White Fairy Will dance with us, my Lord?
Mortal Your majesty doth honor me.
(All join hands circling around kettle and sing dance
song. Organ glides into march at end. All march off,
Fairy and Mortal in lead, then Mirth and Jollity,
followed by children. Exunt all.)
CURTAIN.
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