Avr8Sharp 1.1.0-beta8

Avr8Sharp

Avr8Sharp is a high-performance emulator for the AVR 8-bit microcontroller family, written entirely in modern C# (.NET 10). It runs real, unmodified Arduino and AVR firmware — and is designed as a deterministic firmware testkit for validating the output of the PyMCU compiler in CI.

It is a C# port and re-imagination of avr8js by Uri Shaked, with accuracy fixes and .NET-specific optimizations.

dotnet add package Avr8Sharp
dotnet add package Avr8Sharp.TestKit   # fluent harness for firmware tests

using Avr8Sharp.TestKit.Boards;

var uno = new ArduinoUnoSimulation()
    .WithHex(File.ReadAllText("sketch.hex"));

uno.RunMilliseconds(500);

uno.PortB.Should().HavePinHigh(5);    // LED_BUILTIN
uno.Serial.Should().Contain("Hello");

Supported chips

Any AVR 8-bit device can be modelled via AvrTestSimulation.Create() with custom peripheral configs.

Features

• Full AVR Enhanced instruction set — all ATmega328P / ATmega2560 instructions
• Datasheet-accurate flags — half-carry, overflow, sign, and carry verified against Microchip datasheets; accuracy bugs from avr8js corrected
• Board presets — Uno, Mega 2560, ATtiny85 with all peripherals wired up
• Peripherals — GPIO, USART, Timers (8/16-bit), SPI, TWI (I²C), ADC, EEPROM, USI, Watchdog
• Fluent TestKit — RunUntilSerial, RunToBreak, RunUntilMs with bounded, never-hanging runs
• FluentAssertions extensions — CPU, GPIO, memory, and serial probe assertions
• Inline assembly — load and run short assembly snippets without an external toolchain
• AOT-friendly — trimmable and NativeAOT-compatible

Getting Started

git clone https://github.com/PyMCU/avr8sharp.git
cd avr8sharp
dotnet restore
dotnet build

Run the tests:

dotnet test

TestKit

using Avr8Sharp.TestKit.Boards;

var uno = new ArduinoUnoSimulation()
    .WithHex(File.ReadAllText("blink.hex"));

// Blocks until "PASS" appears on Serial, or throws TimeoutException after 5 s
uno.RunUntilSerial(uno.Serial, "PASS", maxMs: 5000);

uno.Serial.Should().Contain("PASS");
uno.PortB.Should().HavePinHigh(5);

Validating firmware in CI

[Test]
public void Firmware_output_matches_expected()
{
    var mega = new ArduinoMegaSimulation()
        .WithHex(File.ReadAllText("firmware.hex"));

    mega.RunUntilSerial(mega.Serial0, "done", maxMs: 3000);

    mega.Serial0.Should().Contain("done");
    // Cycle-count regression guard — deterministic across machines
    Assert.That(mega.Cpu.Cycles, Is.LessThanOrEqualTo(1_000_000));
}

Solution structure

Architecture notes

• Instruction decoder: 65 536-entry flat LUT of delegate* function pointers — O(1) dispatch with no opcode branch (NativeLutDecoder)
• SREG lazy evaluation: arithmetic flags written to a split field (_sregArith); I/T flags always accurate in _ram[95] — avoids redundant flag computation
• ProcessClockEvents O(1): circular deque with _clockHead pointer; no array shift on timer reprogramming
• MmioController inline chains: up to 4 write hooks per address stored inline in a value struct — no closure allocations

Roadmap

Core / CPU

• Full AVR Enhanced instruction set (ATmega328P / ATmega2560)
• ATtiny85 Reduced Core
• Interrupts, SREG, SP, cycle-accurate timing
• Accuracy fixes: half-carry in ADC, CPI, NEG, SBIW, SUBI
• SPM (self-programming flash)

Peripherals

• GPIO with pin-change and external interrupts
• USART (multiple channels on Mega)
• Timers 0–5 (8-bit and 16-bit)
• SPI
• TWI / I²C (master mode)
• ADC
• EEPROM (read/write/erase)
• USI
• Watchdog
• ATtiny85 TC1 CTC and PWM modes
• TWI slave mode

Ecosystem

• Board presets: Uno, Mega 2560, ATtiny85
• FluentAssertions extensions
• Inline AVR assembler
• DocFX API reference

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/my-feature).
3. Ensure all tests pass (dotnet test).
4. Commit following Conventional Commits.
5. Open a Pull Request against main.

License

The entire project — the simulator core included — is licensed under the Business Source License 1.1 (BUSL-1.1); see LICENSE and LICENSE-BUSL.txt for the full text and parameters.

Non-commercial, personal, hobby, educational, academic, evaluation and open-source use is free of charge. Commercial Use requires a separate commercial license — see the Additional Use Grant in LICENSE-BUSL.txt for what counts as Commercial Use.

On the Change Date (2030-07-11), the project converts automatically to the MIT License (the Change License). Each published version gets its own Change Date, four years after its release.

Based on the original work from avr8js © 2019–present Uri Shaked, distributed under the MIT License; that notice is retained in LICENSE and NOTICE.txt, which lists the third-party attribution that must accompany every redistribution.
C# Port © 2025–present Iván Montiel Cardona.