Arduino Nano (ATmega328P)
Board-specific firmware knowledge. The Nano is simple enough that every
failure mode is silent — the sketch compiles, uploads, runs, and does
something subtly wrong — so read the reference file rather than guessing.
reference/board-hardware.md — the complete board reference: corrected pin
map (the official manual's own tables contain errors), power tree, clock,
memory map, connector/LED inventory plus a development guide (Part II:
§8 toolchain, §10 peripheral cookbook, §11 gotchas, §12 flashing, §13
symptom → cause → fix table).reference/recipes.md — copy-paste code: platformio.ini, board.h,
non-blocking timing, serial + free RAM, EEPROM with update semantics, ADC
and references, interrupts, the timer/PWM map, Servo vs tone(),
power-down sleep, PROGMEM tables.template/ — a project that builds clean, in two variants, plus a
scaffold script. See template/README.md.
Orientation
| |
|---|
| MCU | ATmega328P, 8-bit AVR @ 16 MHz (crystal — fixed, no PLL), Harvard architecture |
| Memory | 32 KB flash (30,720 B usable — 2 KB bootloader reserve), 2 KB SRAM, 1 KB EEPROM. No DMA, no MPU |
| LED / button | L = D13 (LED_BUILTIN), on = HIGH · RESET button, active-low |
| ADC | 8 × 10-bit, 0–5 V, ~100 µs per analogRead(); A6/A7 are analog-input only |
| PWM | 6 × 8-bit: D3, D11 (~490 Hz, Timer2), D9, D10 (~490 Hz, Timer1), D5, D6 (~980 Hz, Timer0) |
| UART | D0/D1 — shared with the USB-serial chip, not free pins |
| I2C / SPI | A4=SDA, A5=SCL · D10=SS, D11=MOSI, D12=MISO, D13=SCK (+ICSP header) |
| Power | 5 V logic. USB Mini-B, VIN 7–12 V via LDO, +5V pin (bypasses regulator). 3V3 pin 50 mA max |
| Debug | No SWD/JTAG — only the 6-pin ICSP header (pin 1 at the outer edge; some diagrams rotate it 180°) |
| Toolchain | PlatformIO 6.1 + atmelavr 5.3.0 + Arduino AVR core, board = nanoatmega328new (Optiboot) / nanoatmega328 (old bootloader) |
Rules that prevent the expensive mistakes
Each of these produces a failure that looks like something else.
upload_speed = 57600 on old-bootloader boards. Genuine Nanos sold
before Jan 2018 and most clones run the old ATmegaBOOT at 57600 baud, not
Optiboot's 115200. The wrong choice fails uploads with not in sync /
stk500_recv — which reads like a driver or cable problem, not a
firmware-era problem. In the Arduino IDE the equivalent is
Tools → Processor → ATmega328P (Old Bootloader).- The 2 KB SRAM is the wall, not the 30 KB flash. Every
Serial.print
string literal, const array and String copy lands in SRAM by default.
The failure is a heap/stack collision that corrupts variables or crashes
after minutes-to-days — nothing prints "out of memory". F() on every
literal, PROGMEM for tables, static buffers instead of String, and
watch free RAM (recipe 4).
digitalWrite(A6) / digitalRead(A7) compile and silently misbehave.
A6/A7 feed the ADC mux only — there is no port register behind them. They
are analog-input-only; any digital use needs the signal moved to a real
pin. A0–A5 are full digital pins (aliases 14–19).- D0/D1 are wired to the FTDI/CH340 chip, not to free GPIO. Using them
while
Serial is open produces garbage in both directions, and anything
external wired to them blocks uploads. The TX/RX LEDs show USB-serial
traffic only — they say nothing about D1 driven manually.
- Never write
TCCR0A/TCCR0B. Timer0 is millis(), micros() and
delay() and the ~980 Hz PWM on D5/D6. "Just changing the PWM
frequency" on those pins makes delay() lie and baud-rate-timed software
(SoftwareSerial, DHT, NeoPixel) glitch, with no error anywhere.
- Every PWM pin is rented from a library.
Servo takes Timer1 — D9/D10
analogWrite() dead while attached. tone() takes Timer2 — D3/D11 dead
while playing. Servo + tone coexist (different timers) but neither
survives touching Timer0. Also: PlatformIO's AVR core bundles only
EEPROM/HID/SoftwareSerial/SPI/Wire — #include <Servo.h> is a compile
error until lib_deps = arduino-libraries/Servo is added (the Arduino
IDE bundles it).
- D13 is the LED and the SPI clock. The LED + series resistor load the
line, which matters when D13 is an input or SCK: a flaky SPI bus that
blinks L with the clock is this, not your wiring.
- All GPIO are 5 V push-pull. Into a 3.3 V-only peripheral that is
damage, not a logic level. The 3V3 pin is an output limited to 50 mA —
powering a sensor is fine, a radio module is not.
analogReference(EXTERNAL) before any voltage touches AREF, and AREF
≤ 5 V always. Driving AREF while an internal reference is selected burns
the pin.- The +5V pin bypasses the regulator. Feeding it from anything above
5.0 V — or from a "5 V" supply that drifts — goes straight into the MCU.
Unregulated input belongs on VIN, which needs ≥ 7 V to clear the LDO
dropout (7–12 V recommended).
wdt_disable() first in setup() (and clear MCUSR). A sketch that
leaves the watchdog enabled boot-loops boards with the old ATmegaBOOT
bootloader — it does not clear the WDT on entry — and the loop survives
re-uploading; only ICSP recovery or Optiboot fixes it.- Unconnected inputs are not zero — they float. Pull-ups (20–50 kΩ)
are off by default:
INPUT_PULLUP or an external resistor, or the pin
reads random noise.
- USB + VIN together = auto power selection, highest voltage wins. A
9 V VIN while debugging over USB back-feeds the USB port. Power
actuators from VIN, the debug session from USB, grounds common — or
accept VIN < 5 V.
When the task is memory
2,048 B covers globals, heap and stack together, and there is no MPU: the
heap grows up, the stack grows down, and their collision is whatever random
corruption results. The arithmetic that matters:
- A
Serial.println("temperature sensor ready") costs 26 B of SRAM forever;
in F() it costs 0. A 256-entry uint16_t table is an eighth of the
chip — PROGMEM it (recipe 11).
- The Arduino core + a Blink already use ~600 B flash and single-digit bytes
of RAM;
Serial adds ~1.5 KB flash. The template's full variant —
heartbeat + serial report + ADC + EEPROM counter — totals 2,874 B flash,
201 B RAM. Budget accordingly: a 1 KB receive buffer is half the machine.
String fragments the small heap; static char[] buffers do not. On this
part, prefer snprintf() into a fixed buffer.- Instrument, don't estimate: the
free_ram() probe in recipe 4 costs 20 B
flash. Below ~200 B free, stop adding features and restructure.
When the task is timing
The three timers are the whole scheduling story, and all of them are spoken
for:
| Timer | Owned by | PWM pins | Free to reconfigure? |
|---|
| Timer0 | millis()/micros()/delay() | D5, D6 (~980 Hz) | never |
| Timer1 | Servo library | D9, D10 (~490 Hz) | if Servo is not used (recipe 8 has the fast-PWM setup) |
| Timer2 | tone() | D3, D11 (~490 Hz) | if tone is not used |
Consequences worth internalizing: an ISR or noInterrupts() section longer
than ~100 µs starts eating UART characters and skewing millis()-based
intervals; delayMicroseconds() is cycle-counted and stays exact; and
anything bit-banged (DHT, one-wire, SoftwareSerial) degrades when interrupts
are blocked — including by long Servo pulses. The non-blocking
millis() pattern (recipe 3) is the default shape of every loop on this
board.
Starting a new project
Do not hand-assemble one. template/ builds clean; scaffold from it:
~/.claude/skills/atmega328p-nano/template/variants/new-project.sh <target-dir> [--full|--minimal]
cd <target-dir> && pio run
--minimal — the classic Blink on the "L" LED, hardware-verified. 924 B
flash, 9 B RAM. Flash this first on an unfamiliar board: if it does
not blink, the problem is the toolchain, the COM port or the bootloader
era (rule 1), not the code.--full (default) — non-blocking heartbeat, serial report with F()
strings, free-RAM watch, ADC sample on A0, EEPROM boot counter. 2,874 B
flash, 201 B RAM.
Both build as-is with platform-atmelavr 5.3.0 (verified). Nothing is
generated and no paths are embedded, so copying the tree by hand works
identically. template/README.md maps files to subsystems.
When the user already has a project, prefer bringing it in line with the
template's platformio.ini and include/board.h over rewriting their code.
Flashing
Over the Mini-B USB cable, nothing to press — the DTR auto-reset opens the
bootloader (Optiboot listens ~1 s at 115200, old ATmegaBOOT ~1–2 s at
57600):
pio run -t upload -t monitor
The board enumerates as a COM port: FTDI VCP on genuine boards, CH340 on
most clones (needs the WCH driver — its absence is why a clone "does not
appear on any port").
Upload failure checklist, in order: wrong bootloader era (rule 1), wrong
COM port / missing CH340 driver, something wired to D0/D1 (disconnect), and
only then assume the sketch. A sketch that crashes instantly or blocks
interrupts can be replaced by timing a RESET press during upload.
The recovery route is the 6-pin ICSP header with a second Arduino running
11.ArduinoISP, a USBasp, or avrdude — it bypasses the bootloader
entirely, so no bad firmware permanently bricks this board. Burn Bootloader over ICSP also restores the fuse set (LOW=0xFF, HIGH=0xDA,
EXT=0xFD — PlatformIO's own board definition; avrdude reads back the
equivalent 0x05 on some tools since only the low 3 BODLEVEL bits are
implemented) — the fix for clones with mis-set clock fuses and for WDT
boot-loops. ICSP is also how to upload bootloader-less and reclaim the
reserved 2 KB.
Reporting
Say what is verified on hardware and what is derived. In this skill the
Blink (the template's --minimal variant) ran on an Arduino Nano
A000005 v3.x with the Optiboot bootloader, and the pin map it relies on is
the corrected physical pinout of §2 — the official A000005 manual's own pin
tables contain errors (they omit RESET/GND and AREF, mislabel 3V3, and
invent "Serial Wire Debug" pins), so quote this skill's tables, not
Arduino's. Everything marked ⚠︎ compile-checked only in
reference/recipes.md — ADC references, interrupts, Timer1 PWM, Servo/
tone, sleep, PROGMEM — compiles against the Arduino AVR core but was not
run on hardware by the author. The VIN range is reported inconsistently by
the sources (7–15 V, 7–12 V, 6–20 V); this skill states 7–12 V recommended
as the conservative intersection.