@Mega Visualizer | DEMO: (https://shubin123.github.io/avr_visual/)

A browser-based AVR assembler and visual debugger for the ATmega2560 (Arduino Mega 2560), built around a real HD44780 LCD and the 6-LED module used in the course examples under examples/. Write AVR assembly, assemble it, and watch it run against a real instruction-accurate CPU core — with a live register file, SREG flags, stack, memory map, disassembly, and the actual board/LCD/LED state updating as the program executes.

Running it

Prerequisites

• Node.js: Version 22.12.0 or higher is required. A .nvmrc file is provided, and you can switch to the correct version using nvm use.
• Private Examples: This project references files from a private /examples directory. To ensure the application builds successfully out of the box on a fresh clone, the build/dev process automatically generates stubs for any missing examples (e.g. if the directory is ignored/not cloned). If you have the actual course assembly files, simply place them in /examples and they will be used instead.

nvm use          # optional: select correct Node version via NVM
npm install
npm run dev      # starts the Vite dev server
npm test         # runs the assembler/encoder/emulator test suite
npm run build    # type-checks and produces a production build (without asset hashing)

Architecture

• src/isa/instructions.ts — the AVR instruction encoder. Every opcode bit pattern is transcribed directly from the official Microchip AVR Instruction Set Manual (DS40002198) and packed generically from a bit-template string, so the mapping from mnemonic to machine code is auditable against the manual rather than hand-derived.
• src/isa/expr.ts, src/isa/preprocess.ts, src/isa/assembler.ts — a from-scratch two-pass AVR assembler: a C-style preprocessor (#define/#ifdef/#ifndef/.include), an expression evaluator (floating point, low()/high()/int(), etc. — needed for course code like multi_timer.asm's timer-constant math), and the pass 1 (symbol table)/pass 2 (encode) assembler itself.
• src/mega2560/ — the ATmega2560 device model. m2560def.inc is the actual Microchip device header (the same one referenced by .include "m2560def.inc" in course code), bundled so it works with no upload step; sfr-map.generated.ts and register-names.generated.ts are mechanically generated from it (not hand-transcribed) to avoid address transcription errors; device.ts builds the avr8js peripheral configs (GPIO ports A-L, timers 0-5, ADC) from those addresses.
• src/emulator/ — wraps the avr8js CPU core (the same engine behind Wokwi's Arduino simulator) with the ATmega2560 peripheral set, plus a from-scratch HD44780 controller simulation that watches GPIO pin state directly (so it works with anyone's LCD driver code, not just one specific library).
• src/ui/ — the React UI: a CodeMirror-based editor with AVR-asm syntax highlighting, the debugger panels (registers, SREG, stack, memory map, disassembly with breakpoints), and the hardware panel using @wokwi/elements for the LED/LCD/ pushbutton visuals.

Default hardware wiring

The board matches the classic LCD keypad shield used in the course material:

• LCD (4-bit interface): RS=D8, E=D9, D4-D7=D4-D7 (see src/emulator/hd44780.ts)
• Buttons: a single analog pin (ADC0) with the shield's usual resistor-ladder ranges (see src/emulator/emulator.ts)
• LEDs: the six-LED module from examples/a2-signaling.asm — PORTL7/5/3/1 and PORTB3/1 (see src/ui/HardwarePanel.tsx)

Known limitations

• External/pin-change interrupts (INT0-7, PCINT) are not modeled — the ATmega2560's pin-to-interrupt mapping differs substantially from the ATmega328p configs avr8js ships, and neither reference program needs them (only timer and ADC interrupts are used). Timer and ADC interrupts work.
• USART, SPI, and TWI peripherals are not wired up.
• LPM/ELPM/JMP/CALL address the full 22-bit space, but RAMPZ-based access beyond the first 64K words of flash isn't modeled.
• PWM/timer compare-output pin overrides use best-effort Arduino Mega pin mappings; timing/counting/interrupt behavior is verified, waveform output on physical pins is not the focus of this tool.

Acknowledgments

The instruction encoder, assembler, and UI here are original to this project, but the CPU this tool actually runs code on is not — at its core, Mega Visualizer is a harness around a handful of other people's work:

• avr8js (Uri Shaked / Wokwi) is the instruction-accurate AVR8 CPU core that every assembled program actually executes on — the same engine behind Wokwi's Arduino simulator. This project's assembler, debugger, and hardware panel are all built to feed it a program image and observe its GPIO/peripheral state; without it there is no emulator here, only an assembler.
• @wokwi/elements (also Wokwi) supplies the LED, LCD1602, and pushbutton web components the hardware panel renders.
• CodeMirror 6 powers the code editor, syntax highlighting, and (via its gutter API) the breakpoint UI.
• React, Zustand, and Vite are the UI framework, state store, and build tooling. react-grid-layout provides the draggable/resizable panel dashboard.
• The Microchip AVR Instruction Set Manual (DS40002198) and the ATmega2560 device header (src/mega2560/m2560def.inc, bundled verbatim) are the primary sources the instruction encoder and register/SFR addresses are checked against.