@@ -97,10 +65,11 @@ const {frontmatter: fm} = useData()
WARDuino and the related projects documented here, are being developed as part of active research projects. - The principle investigators at Ghent University and the VUB, maintain this documentation website and the associated software. + The principle investigators at Ghent University and the VUB, maintain this documentation website and the + associated software. You can find out more about the research on the published articles page.
@@ -365,7 +338,7 @@ const {frontmatter: fm} = useData() .icon { box-sizing: border-box; margin-right: 8px; - margin-top: 5px; + vertical-align: text-bottom; } .icon > span { @@ -384,12 +357,14 @@ h4.center { p.center { max-width: 688px; - margin: 0 auto; + margin: 0 auto; } @media (max-width: 640px) { - max-width: 100%; + p.center { + max-width: 100%; + } } .divider { @@ -422,4 +397,9 @@ p { line-height: 24px; font-weight: 400; } + +a > span { + font-size: inherit; + font-weight: inherit; +} diff --git a/warduino/.vitepress/config.ts b/warduino/.vitepress/config.ts index f14dee5..5a76e05 100644 --- a/warduino/.vitepress/config.ts +++ b/warduino/.vitepress/config.ts @@ -59,22 +59,38 @@ export default defineConfig({ { text: 'MQTT Smartlamp', link: '/guide/examples/smartlamp' }, ] }, - { text: 'VS Code Plugin', link: '/guide/plugin' }, + { text: 'VS Code Plugin', + collapsed: true, + items: [ + { text: 'Installation', link: '/guide/plugin/' }, + { text: 'Getting Started', link: '/guide/plugin/get-started' }, + { text: 'Debugging Hardware', link: '/guide/plugin/tutorial' }, + ] + }, { text: 'Testing on Hardware', link: '/guide/latch' } ] }, { - text: 'WARDuino Reference', + text: "Developer's Guide", collapsed: true, items: [ - { text: 'Overview', link: '/reference/' }, + { text: 'Contributing', link: '/reference/contributing' }, { text: 'Development', link: '/reference/development' }, + { text: 'Platform Support', link: '/reference/platforms' }, + ] + }, + + { + text: 'Technical Reference', + collapsed: true, + items: [ + { text: 'Overview', link: '/reference/' }, + { text: 'Architecture', link: '/reference/architecture' }, { text: 'Primitives', link: '/reference/primitives' }, - { text: 'Remote Debugger', link: '/reference/debugger' }, { text: 'Debug Protocol', link: '/reference/debug-protocol' }, { - text: 'EDWARD Reference', + text: 'EDWARD', collapsed: true, items: [ { text: 'Overview', link: '/reference/edward/' }, @@ -87,21 +103,20 @@ export default defineConfig({ }, ] }, - { text: 'Platform Support', link: '/reference/platforms' } - ] - }, - - { - text: 'Latch Reference', - collapsed: true, - items: [ - { text: 'Overview', link: '/latch/' }, - { text: 'Latch API', link: '/latch/api' } + { + text: 'Latch', + collapsed: true, + items: [ + { text: 'Overview', link: '/latch/' }, + { text: 'Latch API', link: '/latch/api' }, + ] + }, + { text: 'VS Code Plugin', link: '/reference/plugin' } ] }, { - text: 'Research Articles', + text: 'Published Articles', collapsed: true, items: [ { text: 'Overview', link: '/articles/' }, diff --git a/warduino/articles/index.md b/warduino/articles/index.md index d374d18..2b9794f 100644 --- a/warduino/articles/index.md +++ b/warduino/articles/index.md @@ -2,7 +2,7 @@ import citation from '../.vitepress/components/citation.vue' -# Research Articles +# Published Articles ## EDWARD (2022) diff --git a/warduino/guide/examples/smartlamp.md b/warduino/guide/examples/smartlamp.md index 6aaff10..55af646 100644 --- a/warduino/guide/examples/smartlamp.md +++ b/warduino/guide/examples/smartlamp.md @@ -1,3 +1,6 @@ +--- +next: VS Code Plugin +--- # Smartlamp App with MQTT diff --git a/warduino/guide/latch.md b/warduino/guide/latch.md index 031af8b..5359c4b 100644 --- a/warduino/guide/latch.md +++ b/warduino/guide/latch.md @@ -1,14 +1,16 @@ --- title: Latch -next: WARDuino Reference +next: Developer's Guide --- # Testing: Latch framework **Latch (Large-scale Automated Testing on Constraint Hardware)** is a novel testing framework for running large scale unit and integration tests in constrained environments. ::: tip Open source - You can find the open source code on [github](https://github.com/TOPLLab/latch). - ::: +## Getting Started + + + diff --git a/warduino/guide/plugin/get-started.md b/warduino/guide/plugin/get-started.md new file mode 100644 index 0000000..10cdfa3 --- /dev/null +++ b/warduino/guide/plugin/get-started.md @@ -0,0 +1,47 @@ +# Getting Started + +## Launch the Plugin {#launch} + +Open your local plugin repository (see [install step](./index.md)), and click on `Run Extension` under the _Run and Debug_ tab. +This will launch the plugin in a new VS Code window. + +In this new window, open your project folder. +If you don't have a project yet, you can use the [AssemblyScript template](https://github.com/TOPLLab/as-warduino-template) for WARDuino to get started quickly. + +## Project Configuration {#vscode-config} + +::: tip Add `launch.json` file +If you use any of our templates, you can skip this configuration step. +The template contains the correct launch file. +::: + +To use the WARDuino plugin to debug your project, you need to create a `launch.json` file in the `.vscode` subfolder of your project root directory [\[1\]](https://code.visualstudio.com/docs/editor/debugging). +The file should look like this: + +```json +{ + "version": "0.4.1", + "configurations": [ + { + "type": "WARDuinoDBG", + "request": "launch", + "name": "Debug WARDuino", + "program": "${workspaceFolder}/src/main.ts", + "stopOnEntry": true, + "trace": false + } + ] +} +``` + +The `program` key within the JSON file specifies the application's entry file that needs to be debugged. + +Depending on the file extension pointed by the `program` entry, the plugin will load the required WebAssembly compiler and create source mappers accordingly. + +## Start Debugging + +By default, the plugin will debug using a local running instance of WARDuino (emulator). +This means you don't need any further configuration. +Navigate to the _Run and Debug_ tab, and click on `Debug WARDuino`. + +The next tutorial goes through the steps needed to debug on real hardware. diff --git a/warduino/guide/plugin/index.md b/warduino/guide/plugin/index.md new file mode 100755 index 0000000..84f3be0 --- /dev/null +++ b/warduino/guide/plugin/index.md @@ -0,0 +1,51 @@ +# VS Code Plugin + +::: tip WARDuino VS Code 0.4.1 + +This page describes the VS Code plugin [version 0.4.1](https://github.com/TOPLLab/WARDuino-VSCode/releases/tag/v0.4.1), which works with WARDuino [version 0.4.2](https://github.com/TOPLLab/WARDuino/releases/tag/v0.4.2). + +::: + +::: warning Unstable prerelease + +The plugin is still in experimental phase. +The following describes the current state of the VS Code plugin, which is not yet fully stable. +Consequently, the plugin may crash unexpectedly or become unresponsive. + +::: + +The WARDuino plugin is a VS Code extension designed for debugging applications running on the WARDuino VM. The plugin offers two debugging techniques: + +1. [remote debugging](/reference/architecture.md#classic) and +2. [event-based out-of-place debugging](/reference/edward/index). + +Noteworthy functionality of the plugin: + +- On-demand switching from [remote debugging](/reference/architecture.md#classic) to [event-based out-of-place debugging](/reference/edward/index). +- Access to classic debug operations: add a breakpoint, remove a breakpoint, step, step-over, run, and more. +- Access to advanced debug operations: step back debug operations to view past state. (experimental) +- A view on the whole debugging history to easily jump back to a previous state. (experimental) +- Upload new source code on the device once a fault has been fixed. +- Debug on a board +- Debug on an emulator. +- Control over interrupts (e.g., button press, incoming MQTT message) and the handling of it. + +## Manual Installation {#installation} + +::: warning Soon to be released! + +The VS Code plugin has not been published yet. Look out for it in the VS Code Marketplace! +::: + +Before installing the plugin, make sure that you followed the [installation guide](/guide/get-started.md#installation) for the needed development software. + +Once the installation is completed follow these steps: + +- Install VS Code (version 1.63.2 or higher) + +- (Optional) In case you plan to debug Textual WebAssembly source files make sure to install this [VS Code WebAssembly Syntax Highlight plugin](https://github.com/AlanCezarAraujo/vscode-webassembly-syntax-highlight). + +- Change the VS Code settings to enable allow `Allow Breakpoints Everywhere`. + For this, navigate to the VS Code settings and search for `Allow Breakpoints Everywhere` in the search bar. +- Download the [WARDuino VS Code plugin](https://github.com/TOPLLab/WARDuino-VSCode) repo and execute the installation bash script named `install.sh`. + This script downloads and builds the essential libraries such as the WARDuino VM. diff --git a/warduino/guide/plugin/tutorial.md b/warduino/guide/plugin/tutorial.md new file mode 100644 index 0000000..6f98acb --- /dev/null +++ b/warduino/guide/plugin/tutorial.md @@ -0,0 +1,42 @@ +# Debugging on Hardware + +You can access the settings for the WARDuino debugger, by opening the settings window of VS Code and typing _"warduino"_ in the search input area. +To enable debugging on the physical board set the `WARDuino: Debug Mode` configuration value to `embedded`. + +Now the plugin needs to know to what device to connect to. +Set the right address for the serial port in the `WARDuino: Port` field, and the FQBN of the target hardware in `WARDuino: Device`. + +If you are using the Arduino toolchain (see [arduino setup instructions](/guide/get-started.html#arduino-toolchain-setup)), +you can find the FQBN value for your hardware with the `arduino-cli`. + +```bash +arduino-cli board listall +``` + +After updating these settings, you can start the debugger by navigating to the _Run and Debug_ tab, and clicking on `Debug WARDuino`. + +The plugin will first compile and flash your software, before starting a debugging session. +Due to these initial steps, it may take a while before the debugger is connected. +A popup notification will appear once the debugger is connected, and you can see the status of the plugin on the bottom right of your VS Code window at any time. + +::: tip menu_book Find out more +Go to the technical reference for more information. + +[-> debugging concurrency tutorial](/reference/edward/concurrency.md) + +[-> debug protocol API](/reference/debug-protocol.md) + +[-> plugin technical reference](/reference/plugin.md) + +[-> supported platforms](/reference/platforms.md) +::: + + \ No newline at end of file diff --git a/warduino/latch/api.md b/warduino/latch/api.md index 32dc2f2..977b3a7 100644 --- a/warduino/latch/api.md +++ b/warduino/latch/api.md @@ -1,7 +1,6 @@ --- title: Latch API description: "The Latch API" -next: Research Articles --- # Latch API diff --git a/warduino/latch/index.md b/warduino/latch/index.md index 9c2fb70..b01b782 100755 --- a/warduino/latch/index.md +++ b/warduino/latch/index.md @@ -39,7 +39,7 @@ During developement, we found that the framework implements a few novel testing We use the framework to test three core aspects of WARDuino: 1. The virtual machine folllows the WebAssembly specication. -2. The debugger implements the [API](/reference/debugger) correctly. +2. The debugger implements the [API](/reference/debug-protocol) correctly. 3. The [built-in modules](/reference/primitives) work correctly. The test suites written in latch can be found in the [GitHub repository](https://github.com/TOPLLab/WARDuino/tree/main/tests/latch). diff --git a/warduino/latch/tutorial.md b/warduino/latch/tutorial.md new file mode 100644 index 0000000..42c6817 --- /dev/null +++ b/warduino/latch/tutorial.md @@ -0,0 +1,4 @@ +--- +next: Published Articles +--- +# Automating Manual Tests diff --git a/warduino/reference/debugger.md b/warduino/reference/architecture.md similarity index 65% rename from warduino/reference/debugger.md rename to warduino/reference/architecture.md index e501f6f..0dd7512 100644 --- a/warduino/reference/debugger.md +++ b/warduino/reference/architecture.md @@ -1,5 +1,8 @@ -# Classic Remote Debugger +# WARDuino Architecture + +This page gives an overview of the core components of the WARDuino virtual machine + +## Classic Remote Debugger {#classic} WARDuino facilitates remote debugging by allowing debug messages to be sent over a variety of carriers, such as USB (wired) or Wi-Fi (wireless) communication. In theory any communication channel that reliably signals at least one readable pin on the device can be used. - diff --git a/warduino/reference/contributing.md b/warduino/reference/contributing.md new file mode 100644 index 0000000..1fa07c8 --- /dev/null +++ b/warduino/reference/contributing.md @@ -0,0 +1,22 @@ +# Contributing + +If you want to help with development, issues on the [roadmap](https://github.com/orgs/TOPLLab/projects/1) with low priority are a good starting point. + + \ No newline at end of file diff --git a/warduino/reference/development.md b/warduino/reference/development.md index 62dde05..20a2c00 100644 --- a/warduino/reference/development.md +++ b/warduino/reference/development.md @@ -5,6 +5,7 @@ import illustration from '../.vitepress/components/illustration.vue' # Developing WARDuino This guide is for people who want to help with development. +We highly recommend you first read more on the [architecture](architecture.md) of the virtual machine in the technical reference. ## A Tale of three Versions diff --git a/warduino/reference/edward/concurrency.md b/warduino/reference/edward/concurrency.md index daf9023..56cdac3 100644 --- a/warduino/reference/edward/concurrency.md +++ b/warduino/reference/edward/concurrency.md @@ -1,6 +1,6 @@ # Debugging Concurrency -The EDWARD debugger is can help debug concurrency issues better than the classic [remote debugger](/reference/debugger.md) of WARDuino. Here we will illustrate how with a representative example. +The EDWARD debugger can help debug concurrency issues better than the classic [remote debugger](/reference/architecture.md#classic) of WARDuino. Here we will illustrate how with a representative example. ## The Application @@ -26,7 +26,7 @@ export function main(): void { The callbacks will change a delta variable, which the program uses to update the LED brightness accordingly in steps of `5` procent. -After subscribing, the code will continually checking the connection to the MQTT broker and the local Wi-Fi network, as well as update the LED brightness. +After subscribing, the code will continually check the connection to the MQTT broker and the local Wi-Fi network, as well as update the LED brightness. ```ts // ... diff --git a/warduino/reference/index.md b/warduino/reference/index.md index 0caa71a..1eda9b7 100755 --- a/warduino/reference/index.md +++ b/warduino/reference/index.md @@ -2,11 +2,19 @@ import citation from '../.vitepress/components/citation.vue' -# WARDuino +# Technical Reference -The WARDuino virtual machine is a WebAssembly runtime for microcontrollers, which runs both under the Arduino and ESP-IDF toolchains. - -Here you will find a full reference on the virtual machine and its core components. +The reference documentation present here goes into the technical details of WARDuino, EDWARD, the VS Code plugin and Latch. If you are looking to just get started with programming, [the Programmer's Guide](/guide/get-started) explains how to use WARDuino to write software using AssemblyScript or Rust. -