# atmega328p-nano

Adopt this skill: https://proskills.md/skills/other/alexex1993-mcu-skills-skills-avr-atmega328p-nano

Page: https://proskills.md/skills/other/alexex1993-mcu-skills-skills-avr-atmega328p-nano
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/avr/atmega328p-nano/SKILL.md
size: 8093
upstream: https://github.com/alexex1993/mcu-skills/blob/main/skills/avr/atmega328p-nano/SKILL.md

```text
---
name: atmega328p-nano
description: Firmware development for the Arduino Nano (A000005, ATmega328P @ 16 MHz, 5 V) — its 30 KB usable flash, 2 KB SRAM, 1 KB EEPROM, 8-channel 10-bit ADC, six 8-bit PWM pins across three timers, UART shared with the USB-serial chip, I2C on A4/A5, SPI on D10–D13, sleep modes, and the Arduino AVR core + PlatformIO setup around them. Use when working on this board or any ATmega328P Nano clone (FTDI or CH340 USB): project setup, platformio.ini, old-vs-new bootloader uploads, pin mapping, A6/A7 restrictions, timer/Servo/tone conflicts, the 2 KB SRAM budget, analog references, powering from VIN, ICSP recovery, or debugging why something on the board does not work.
---

# 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.

1. **`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)`.
2. **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).
3. **`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).
4. **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.
5. **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.
6. **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).
7. **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.
8. **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.
9. **`analogReference(EXTERNAL)` before any voltage touches AREF**, and AREF
   ≤ 5 V always. Driving AREF while an internal reference is selected burns
   the pin.
10. **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).
11. **`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.
12. **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.
13. **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 char
```

## File: README.md
upstream: https://github.com/alexex1993/mcu-skills/blob/main/README.md

````text
# mcu-skills — Claude Code and Codex Skills for Microcontrollers (MCU)

**Claude Code and Codex skills for MCU firmware development** on STM32, ESP32, ESP8266, RP2040 / RP2350,
nRF52 and AVR boards. These are [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills)
(`SKILL.md`) for embedded development — one skill per board, holding the board-specific knowledge
that is otherwise scattered across a datasheet, a reference manual, a schematic and a weekend of
debugging.

A good MCU skill answers, without the model guessing: which pin does what, which clock tree
actually works, which HAL call silently does nothing, and how to get a build onto the chip.

## Skills in this repo

| Skill | Board | MCU | Image |
|---|---|---|---|
| [`stm32h750-weact`](skills/stm32/stm32h750-weact) | WeAct Studio MiniSTM32H7xx core board | STM32H750VBT6 (Cortex-M7) | <img src="https://github.com/user-attachments/assets/096199da-56a0-4aa2-9711-bba7d59dc035" width="120"> |
| [`stm32f411-blackpill`](skills/stm32/stm32f411-blackpill) | WeAct Studio "Black Pill" V3.x (and clones) | STM32F411CEU6 (Cortex-M4F) | <img src="https://github.com/user-attachments/assets/430196ed-a5b6-4651-b5eb-ee44fcd09235" width="120"> |
| [`stm32f401rc-blackpill`](skills/stm32/stm32f401rc-blackpill) | 40-pin "Black Pill" clone with the WeAct HID bootloader | STM32F401RCT6 (Cortex-M4F) |  |
| [`esp32c6-lcd147`](skills/esp32/esp32c6-lcd147) | Waveshare ESP32-C6-LCD-1.47 | ESP32-C6FH4 (RISC-V) | <img src="https://github.com/user-attachments/assets/fa79311c-b137-4550-b5be-d545019ebe28" width="120"> |
| [`esp32c6-touch-lcd147`](skills/esp32/esp32c6-touch-lcd147) | Waveshare ESP32-C6-Touch-LCD-1.47 | ESP32-C6FH8 (RISC-V) | <img src="https://github.com/user-attachments/assets/3109f034-63e3-4451-9a23-72eecf480da3" width="120"> |
| [`esp32c3-oled042`](skills/esp32/esp32c3-oled042) | ESP32-C3 0.42" OLED (ABRobot / 01Space) | ESP32-C3FH4 (RISC-V) | <img src="https://github.com/user-attachments/assets/06dbaf31-eb85-431a-8bfb-ae2e00d3e5cd" width="120"> |
| [`esp32-wroom-30pin`](skills/esp32/esp32-wroom-30pin) | 30-pin ESP32 devkit (DOIT V1 / CH340 Type-C) | ESP32-D0WDQ6 (Xtensa LX6) | <img src="https://github.com/user-attachments/assets/57fb4456-8897-47a7-a4ee-1edd831bc15b" width="120"> |
| [`esp32-wroom-36pin`](skills/esp32/esp32-wroom-36pin) | 36-pin ESP32 devkit (original DOIT DevKit V1) | ESP32-D0WDQ6 (Xtensa LX6) |  |
| [`esp32-wroom-38pin`](skills/esp32/esp32-wroom-38pin) | 38-pin ESP32 devkit (DevKitC V4 / NodeMCU-32S) | ESP32-D0WDQ6 (Xtensa LX6) | <img src="https://github.com/user-attachments/assets/b4b6fa6f-41f5-4d30-a3bc-1f3bb096aa9d" width="120"> |
| [`esp32s3-cam-40pin`](skills/esp32/esp32s3-cam-40pin) | 40-pin ESP32-S3 CAM board (Freenove FNK0085 / clones) | ESP32-S3-WROOM-1 N8R8/N16R8 (Xtensa LX7) | <img src="https://github.com/user-attachments/assets/6ce188ac-881b-44df-a7de-2650b5d04740" width="120"> |
| [`esp32s3-rlcd42`](skills/esp32/esp32s3-rlcd42) | Waveshare ESP32-S3-RLCD-4.2 (SKU 33298 / 33507) | ESP32-S3-WROOM-1-N16R8 (Xtensa LX7) | <img src="https://github.com/user-attachments/assets/9b55c6b2-3135-44ad-824b-a05659bd6f0f" width="120"> |
| [`esp32p4-jc-m3-dev`](skills/esp32/esp32p4-jc-m3-dev) | Guition JC-ESP32P4-M3-DEV | ESP32-P4NRW32 (2× RISC-V) + ESP32-C6 | <img src="https://github.com/user-attachments/assets/90a0671f-0f89-4a55-a69e-0ac45e5c1142" width="120"> |
| [`esp32p4-jc4880p443`](skills/esp32/esp32p4-jc4880p443) | Guition JC4880P443C_I_W, 4.3" 480×800 touch display | ESP32-P4NRW32 (2× RISC-V) + ESP32-C6 |  |
| [`esp8266-nodemcu-30pin`](skills/esp8266/esp8266-nodemcu-30pin) | 30-pin NodeMCU devkit (DevKit V1.0 / Amica, LoLin V3) | ESP8266EX (ESP-12E/F, Tensilica L106) | <img src="https://github.com/user-attachments/assets/8b4c1691-a1ab-4c1f-9c16-42703e76c160" width="120"> |
| [`nrf52840-promicro`](skills/nrf/nrf52840-promicro) | ProMicro nRF52840 V1940 (nice!nano v2 clone / SuperMini) | nRF52840 QIAA (Cortex-M4F) | <img src="https://github.com/user-attachments/assets/eb74eab1-516c-4b16-b564-58ca096222fc" width="120"> |
| [`atmega328p-nano`](skills/avr/atmega328p-nano) | Arduino Nano (A000005) | ATmega328P (AVR 8-bit) | <img src="https://github.com/user-attachments/assets/e37f4c59-3746-4603-9f78-65207a957386" width="120"> |
| [`atmega32u4-beetle`](skills/avr/atmega32u4-beetle) | Beetle / CJMCU "Mini Arduino Leonardo" | ATmega32U4 (AVR 8-bit, native USB) | <img src="https://github.com/user-attachments/assets/35a02767-cf7f-43d3-9ee7-3ae55491f574" width="120"> |
| [`lgt8f328p-minievb`](skills/avr/lgt8f328p-minievb) | LGT8F328P-LQFP32 MiniEVB, Nano-style 30-pin (silkscreen `LGTBF32BP`) | LGT8F328P (Logic Green LGT8XM, AVR-compatible) | <img src="https://github.com/user-attachments/assets/88178e6d-4657-428b-af61-8f85fe6579d0" width="120"> |
| [`rp2040-pico`](skills/rp2/rp2040-pico) | Raspberry Pi Pico (SC0915, and Pico H) | RP2040 (2× Cortex-M0+) | <img src="https://github.com/user-attachments/assets/30a66b6a-8052-4b60-8900-98b393099929" width="120"> |
| [`rp2350a-weact`](skills/rp2/rp2350a-weact) | WeAct Studio RP2350A Core Board (V1.0 and V2.0) | RP2350A (2× Cortex-M33) | <img src="https://github.com/user-attachments/assets/b3b84cc3-8e8a-45be-bb49-882ce5f7499c" width="120"> |
| [`beu1000-evuba`](skills/baikal/beu1000-evuba) | Baikal Electronics EVU-BA-2.1 | BE-U1000 (3× RISC-V: 2× BR-350, BM-310) |  |

## Install

### Codex

Clone the repository, then install all board skills with one command:

```sh
git clone https://github.com/alexex1993/mcu-skills.git
cd mcu-skills
./scripts/install.sh --codex --all
```

On Windows, run the PowerShell installer from the clone:

```powershell
.\scripts\install.ps1 --codex --all
```

This installs into `~/.agents/skills`, the user skill directory documented in
[OpenAI's skills guide](https://learn.chatgpt.com/docs/build-skills). Each board is installed
as a separate skill, with its references, templates and assets. The default is a symlink
(a directory junction on Windows), so `git pull` updates installed skills. Keep the clone in
place while using links. Use `--copy` for an independent copy instead.

The same options work with both installers:

```sh
./scripts/install.sh --codex --list
./scripts/install.sh --codex rp2040-pico                # just one board
./scripts/install.sh --codex --all --copy               # standalone copies
./scripts/install.sh --codex --all --copy --yes         # replace existing installs without prompts
./scripts/install.sh --codex --uninstall rp2040-pico
```

`--list` always shows both Claude and Codex installations in separate columns, including
installation paths and link targets. The directory overrides below also apply to this view.

Existing installations require confirmation before replacement unless `--yes` is supplied.
Replacing a copy discards local edits in that installed skill. Updating an already-correct
link is a no-op. To update copies, pull the repository and rerun the copy command.

For a project-scoped install, set `CODEX_SKILLS_DIR` to that project's `.agents/skills`:

```sh
CODEX_SKILLS_DIR=/path/to/project/.agents/skills ./scripts/install.sh --codex --all --copy
```

```powershell
$env:CODEX_SKILLS_DIR = 'C:\path\to\project\.agents\skills'
.\scripts\install.ps1 --codex --all --copy
```

`CODEX_SKILLS_DIR` is an override provided by these scripts; it can also point to
`$CODEX_HOME/skills` if that is where you keep your Codex skills. It is independent of
`CLAUDE_SKILLS_DIR`.

Codex discovers skills automatically. In the CLI or IDE extension, use `/skills` to browse
them or mention one explicitly, for example `$rp2040-pico`. If newly installed skills do not
appear, restart Codex.

### As a Claude Code plugin

The repo is a plugin marketplace with one plugin per board. Inside Claude Code:

```
/plugin marketplace add alexex1993/mcu-skills
/plugin install stm32h750-weact@mcu-skills
```

Plugin names match the skill names in the table above. Or install from a clone with the
scripts below.

### Claude Co
````
