docs: add more info to the README and separate architecture docs

Signed-off-by: deadprogram <[email protected]>
hybridgroup · Feb 22, 2024 · 87b2603 · 87b2603
1 parent 750d331
commit 87b2603
Show file tree

Hide file tree

Showing 2 changed files with 110 additions and 64 deletions.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -0,0 +1,66 @@
+# Architecture
+
+```mermaid
+flowchart TD
+    subgraph Application
+        App
+    end
+    App-->Engine
+    subgraph Modules
+        WASM1
+        WASM2
+    end
+    subgraph Engine
+        FileStore
+        Interpreter
+        Devices
+    end
+    FileStore-->Modules
+    Interpreter-->Modules
+    Interpreter-->Devices
+    Devices--->Machine
+    Devices--->Hardware
+    Devices--->Network
+    subgraph Hardware
+        Sensor
+        Displayer
+        LEDSetter
+    end
+    subgraph Network
+        Net
+        Bluetooth
+    end
+    subgraph Machine
+        GPIO
+        ADC
+        I2C
+        SPI
+    end
+    Displayer-->SPI
+    Sensor-->GPIO
+    Sensor-->I2C
+```
+
+## Application
+
+The host application that the developer who uses Mechanoid is creating.
+
+## Modules
+
+The WASM modules that developers who are creating code for this Application are writing.
+
+## Engine
+
+The capabilities that the Application uses/exposes for Modules.
+
+## Devices
+
+Wrappers around specific devices such as displays or sensors that can be used by the Application and/or Modules.
+
+## Network
+
+Wrappers around specific networking capabilities such as WiFi or Bluetooth that can be used by the Application and/or Modules.
+
+## Machine
+
+Wrappers around low-level hardware interfaces such as GPIO or I2C that can be used by the Application and/or Modules.
diff --git a/README.md b/README.md
@@ -2,19 +2,37 @@
 
 Mechanoid is a framework for developing applications using WebAssembly for embedded microcontrollers written using TinyGo.
 
-## How to use
+## Simple
 
+### WebAssembly guest program
+
+```go
+//go:build tinygo
+
+package main
+
+//go:wasmimport hosted pong
+func pong()
+
+//go:export ping
+func ping() {
+	pong()
+}
+
+func main() {}
 ```
-mecha new simple
-...
 
-(generates new application skeleton)
+Compile this program to WASM using TinyGo:
 
 ```
+$ tinygo build -size short -o ./modules/ping/ping.wasm -target ./modules/ping/wasm-unknown.json -no-debug ./modules/ping
+   code    data     bss |   flash     ram
+      9       0       0 |       9       0
+```
 
-### Simple
+### Mechanoid host application
 
-Loads an embedded WASM module and then runs it by calling the exported `Ping()` function:
+The Mechanoid host application that runs on the hardware, loads this WASM module and then runs it by calling the exported `Ping()` function:
 
 ```go
 package main
@@ -105,72 +123,34 @@ pong
 More examples are available here:
 https://github.com/hybridgroup/mechanoid-examples
 
-## Architecture
-
-```mermaid
-flowchart TD
-    subgraph Application
-        App
-    end
-    App-->Engine
-    subgraph Modules
-        WASM1
-        WASM2
-    end
-    subgraph Engine
-        FileStore
-        Interpreter
-        Devices
-    end
-    FileStore-->Modules
-    Interpreter-->Modules
-    Interpreter-->Devices
-    Devices--->Machine
-    Devices--->Hardware
-    Devices--->Network
-    subgraph Hardware
-        Sensor
-        Displayer
-        LEDSetter
-    end
-    subgraph Network
-        Net
-        Bluetooth
-    end
-    subgraph Machine
-        GPIO
-        ADC
-        I2C
-        SPI
-    end
-    Displayer-->SPI
-    Sensor-->GPIO
-    Sensor-->I2C
-```
-
-#### Application
-
-The host application that the developer who uses Mechanoid is creating.
+## Getting started
 
-#### Modules
+- Install the Mechanoid command line tool
+- Create a new project
+- Make something amazing!
 
-The WASM modules that developers who are creating code for this Application are writing.
+## `mecha` command line tool
 
-#### Engine
-
-The capabilities that the Application uses/exposes for Modules.
-
-#### Devices
+```
+NAME:
+   mecha - Mechanoid WASM embedded development tools
 
-Wrappers around specific devices such as displays or sensors that can be used by the Application and/or Modules.
+USAGE:
+   mecha [global options] command [command options] 
 
-#### Network
+COMMANDS:
+   new      create a new Mechanoid project
+   flash    flash a Mechanoid project to a device
+   test     run tests for a Mechanoid project
+   help, h  Shows a list of commands or help for one command
 
-Wrappers around specific networking capabilities such as WiFi or Bluetooth that can be used by the Application and/or Modules.
+GLOBAL OPTIONS:
+   --help, -h  show help
+```
 
-#### Machine
+## How it works
 
-Wrappers around low-level hardware interfaces such as GPIO or I2C that can be used by the Application and/or Modules.
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for more information.
 
 ## Goals