From 13195a8e4f8ad244daf07fad0b963fe121f67fc4 Mon Sep 17 00:00:00 2001 From: Julian Rendell Date: Thu, 25 Feb 2021 14:51:09 -0800 Subject: clarifying the scope of library Attempt to clarify the scope of this library and what else is needed to make a complete application.--- README.md | 36 +++++++++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index edbeeec..0eb769e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # AVR8js -JavaScript implementation of the AVR 8-bit architecture +This is a JavaScript library that implementats the AVR 8-bit architecture. + +It's the heart- but not the whole body- of the Arduino simulator at [https://wokwi.com](https://wokwi.com). [![Build Status](https://travis-ci.org/wokwi/avr8js.png?branch=master)](https://travis-ci.org/wokwi/avr8js) [![NPM Version](https://img.shields.io/npm/v/avr8js)](https://www.npmjs.com/package/avr8js) @@ -8,12 +10,25 @@ JavaScript implementation of the AVR 8-bit architecture ![Types: TypeScript](https://img.shields.io/npm/types/avr8js) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/wokwi/avr8js) -## Running the demo project +## Example Applications Using `AVR8js` -The demo project allows you to edit Arduino code, compile it, and run it in the simulator. -It also simulates 2 LEDs connected to pins 12 and 13 (PB4 and PB5). +* [WokWi Arduino Simulator](https://wokwi.com) - simulated Arduino UNO with a choice of hardware that can be wired up dynamically in your browser! +* [WokWi Playgrounds](https://github.com/wokwi/wokwi-playgrounds) - pre-configured Arduino circuits with notes and goals. A starting point for an online lesson system. +* [avr8js-electron playground](https://github.com/arcostasi/avr8js-electron-playground) - a Downloadable Electron Arduino simulator app +* [AVR8js-Falstad](https://markmegarry.github.io/AVR8js-Falstad/) - combining the Falstad circuit simulator with AVR8js! +* [The Engineering Physics Department of Dawson College's Arduino Course](https://tawjaw.github.io/Arduino-Robot-Virtual-Lab/) - an introduction to Arduino with a focus on robotics -To run the demo project, check out this repository, run `npm install` and then `npm start`. +## How to Use This Library + +This library only implements the AVR CPU core. +You have to supply it pre-compiled machine code to run, and implement functional simulations of any external hardware. You will probably also want to add audio/visual representations of external hardware being simulated. + +A rough conceptual diagram: + +``` +Pre-Compiled machine code --> AVR8js <--> Glue code <--> external hardware functional simulation <--> simulation state display for the user +``` +You may be interested in exploring the [wokwi-elements](https://github.com/wokwi/wokwi-elements) collection of web-components for visual representations of many common hardware components. (Note: these are visual only elements- you will need to add the appropriate functional simulation and glue code.) ### Walkthrough Video Tutorial @@ -23,6 +38,8 @@ A step-by-step video tutorial showing how to build a simple Arduino simulator us ### Unofficial examples +These examples show working examples of using `avr8js` in an application. Many of them also demonstrate how to use the `wokwi-elements` and include working examples of functional simulations of the components, and how to hook them up to `avr8js`. + * [Minimal Example](https://stackblitz.com/edit/avr8js-minimal?file=main.ts) * [6 LEDs](https://stackblitz.com/edit/avr8js-6leds?file=index.ts) * [LED PWM](https://stackblitz.com/edit/avr8js-pwm?file=index.ts) @@ -34,6 +51,15 @@ A step-by-step video tutorial showing how to build a simple Arduino simulator us * [Assembly Code](https://stackblitz.com/edit/avr8js-asm?file=index.ts) * [EEPROM persistence](https://stackblitz.com/edit/avr8js-eeprom-localstorage?file=eeprom-localstorage-backend.ts) +Note: they are all hosted outside of this repo. + +## Running the demo project + +The demo project allows you to edit Arduino code, compile it, and run it in the simulator. +It also simulates 2 LEDs connected to pins 12 and 13 (PB4 and PB5). + +To run the demo project, check out this repository, run `npm install` and then `npm start`. + ## Which chips can be simulated? The library focuses on simulating the *ATmega328p*, which is the MCU used by the Arduino Uno. -- cgit v1.2.3