Oxidized interface for simavr.

The main purpose of this crate is to serve as a building block for the avr-tester crate, providing a safe and curated access to simavr.

See: [AvrSimulator::new()].

avr-tester  

Framework for testing AVR binaries, powered by simavr.

tl;dr get your microcontroller's firmware black-box-tested in seconds!

Getting started

Create a crate dedicated to your firmware's tests:

$ cargo new firmware-tests --lib

... add avr-tester as its dependency:

# firmware-tests/Cargo.toml

[dependencies]
avr-tester = "0.3"

... and start writing tests:

// firmware-tests/src/lib.rs

use avr_tester::*;

fn avr() -> AvrTester {
    AvrTester::atmega328p()
        .with_clock_of_16_mhz()
        .load("../../firmware/target/atmega328p/release/firmware.elf")
}

// Assuming `firmware` implements a ROT-13 encoder:

#[test]
fn short_text() {
    let mut avr = avr();

    // Let's give our firmware a moment to initialize:
    avr.run_for_ms(1);

    // Now, let's send the string:
    avr.uart0().write("Hello, World!");

    // ... give the AVR a moment to retrieve it & send back, encoded:
    avr.run_for_ms(1);

    // ... and, finally, let's assert the outcome:
    assert_eq!("Uryyb, Jbeyq!", avr.uart0().read::<String>());
}

#[test]
fn long_text() {
    let mut avr = avr();

    avr.run_for_ms(1);
    avr.uart0().write("Lorem ipsum dolor sit amet, consectetur adipiscing elit");
    avr.run_for_ms(10);

    assert_eq!(
        "Yberz vcfhz qbybe fvg nzrg, pbafrpgrghe nqvcvfpvat ryvg",
        avr.uart0().read::<String>(),
    );
}

... having the tests ready, just run cargo test inside firmware-tests :-)

Since AvrTester emulates an actual AVR, you don't have to modify your firmware at all - it can use timers, GPIOs etc. and everything should just work ™.

In fact, your project doesn't even have to be written in Rust - you can create Rust tests for a firmware written in C, Zig and anything else!

Features

• Analog pins,
• Custom components,
• Digital pins,
• SPIs,
• TWIs (aka I2C),
• Timeouts,
• UARTs.

See more: <./avr-tester/tests/examples>.

Supported platforms

See: simavr-ffi.

Roadmap

Following features are supported by simavr, but haven't been yet exposed in AvrTester:

• Interrupts,
• EEPROM,
• Watchdog,
• USB.

Your firmware can use those features, you just won't be able to test them.

Caveats

• Triggering AVR's sleep mode will cause the Rust code to panic, because the only way to wake an AVR is to trigger an interrupt and those are not yet supported.

Contributing

Pull requests are very much welcome!

Tests

Use just test to test AvrTester (so meta!) -- note that you might need some additional dependencies:

... using Nix (Linux / Mac)

$ nix develop
# and then `just test`

... on Ubuntu

$ sudo apt install avr-libc gcc-avr
# and then `just test`

License

Copyright (c) 2022 Patryk Wychowaniec pwychowaniec@pm.me.
Licensed under the MIT license.