docs: Add getting started guide and updated emulator instructions

Author: MikeHLee

simulation/README.md

@@ -11,7 +11,112 @@ Unified simulation framework for Oasis firmware with MCU emulation and MCP inter
 - **MCP Server**: AI-accessible API for simulation control
 - **Fault Injection**: Test edge cases with disconnect, stuck, offset, and noise faults
 
-## Quick Start
+## Getting Started: Build Your First Device
+
+### 1. Install the Simulation Framework
+
+```bash
+cd oasis-firmware/oasis-rpi/simulation
+pip install -e .[all]
+```
+
+### 2. Create a Device Configuration
+
+Create `my_device.yaml` in your project directory:
+
+```yaml
+device:
+  id: my-first-device
+  name: Simple Temperature Monitor
+  board:
+    platform: mcu
+    model: esp32_devkit
+
+sensors:
+  - name: temp_sensor
+    type: dht22
+    pins:
+      data: 4
+    sampling:
+      interval_ms: 5000
+
+actuators:
+  - name: warning_led
+    type: relay
+    pins:
+      output: 16
+    default:
+      state: off
+
+control_loops:
+  - name: temp_warning
+    type: threshold
+    input:
+      sensor: temp_sensor
+      measurement: temperature
+    output:
+      actuator: warning_led
+    threshold:
+      setpoint: 30.0
+      hysteresis: 2.0
+      direction: heat
+```
+
+### 3. Run a Simulation
+
+```python
+from behavioral import BehavioralRuntime
+from pathlib import Path
+
+# Initialize runtime
+runtime = BehavioralRuntime()
+runtime.load_component_library(Path('components'))
+
+# Add components
+runtime.add_component('temp1', 'dht22')
+runtime.add_component('led1', 'relay')
+
+# Set physical input (simulated environment)
+runtime.set_physical_input('temp1', 'temp_actual', 25.0)
+runtime.set_physical_input('temp1', 'humidity_actual', 60.0)
+
+# Run simulation loop
+for _ in range(100):
+    runtime.step(0.1)  # 100ms steps
+    state = runtime.get_state()
+    print(f"Time: {state['sim_time_ms']}ms")
+```
+
+### 4. Using the MCP Server (AI-Assisted Development)
+
+Start the MCP server for AI assistant integration:
+
+```bash
+oasis-sim  # Runs stdio MCP server
+```
+
+Then use your AI assistant to:
+- Add components: "Add a DHT22 sensor called sensor1"
+- Run simulation: "Step the simulation forward 1 second"
+- Inject faults: "Disconnect sensor1 to test fault handling"
+- Generate components: "Parse this datasheet and create a component YAML"
+
+## Desktop UI (Rust + egui)
+
+The desktop application provides a visual interface for simulation:
+
+```bash
+cd oasis-firmware/oasis-rpi/desktop
+cargo run --release
+```
+
+### UI Features
+- **Device Editor**: Visual drag-and-drop component placement
+- **Wiring View**: See signal connections between components
+- **Simulation Panel**: Real-time waveform visualization
+- **Fault Injection**: Click to inject faults and test resilience
+
+## Quick Start (CLI)
 
 ```bash
 # Install (basic)
@@ -34,47 +139,60 @@ oasis-datasheet generate sensor.pdf -o components/sensors/new.yaml
 
 ## Emulator Prerequisites
 
-### ESP32 (Easiest - Wokwi)
+### ESP32 (Wokwi CLI) - Recommended
 ```bash
-# Wokwi CLI (cloud-based, no local install needed)
-source ~/.nvm/nvm.sh && nvm use 20
-npm install -g wokwi-cli
-```
+# macOS ARM64
+curl -L -o /usr/local/bin/wokwi-cli \
+  https://github.com/wokwi/wokwi-cli/releases/download/v0.26.1/wokwi-cli-macos-arm64
+chmod +x /usr/local/bin/wokwi-cli
 
-### ESP32 (Local - QEMU)
-```bash
-# Build Espressif QEMU
-git clone https://github.com/espressif/qemu.git
-cd qemu
-./configure --target-list=xtensa-softmmu
-make -j$(nproc)
-sudo make install
+# macOS x64
+curl -L -o /usr/local/bin/wokwi-cli \
+  https://github.com/wokwi/wokwi-cli/releases/download/v0.26.1/wokwi-cli-macos-x64
+chmod +x /usr/local/bin/wokwi-cli
+
+# Linux
+curl -L -o /usr/local/bin/wokwi-cli \
+  https://github.com/wokwi/wokwi-cli/releases/download/v0.26.1/wokwi-cli-linux-x64
+chmod +x /usr/local/bin/wokwi-cli
+
+# Verify
+wokwi-cli --version
 ```
 
 ### Arduino (simavr)
 ```bash
 # macOS - build from source
+brew tap osx-cross/avr
 brew install avr-gcc libelf
 git clone https://github.com/buserror/simavr.git
-cd simavr && make && sudo make install
+cd simavr && make && sudo make install PREFIX=/usr/local
 
 # Ubuntu/Debian
-sudo apt install simavr
+sudo apt install simavr avr-libc
+
+# Verify
+simavr --help
 ```
 
 ### STM32 (Renode)
 ```bash
-# macOS - download from releases
-curl -LO https://github.com/renode/renode/releases/download/v1.15.0/renode-1.15.0.macos-x64.dmg
+# macOS ARM64
+curl -LO https://github.com/renode/renode/releases/download/v1.16.1/renode-1.16.1-dotnet.osx-arm64-portable.dmg
+hdiutil attach renode-1.16.1-dotnet.osx-arm64-portable.dmg
+cp -R "/Volumes/Renode_1.16.1/Renode.app" /Applications/
+ln -sf /Applications/Renode.app/Contents/MacOS/Renode /usr/local/bin/renode
+hdiutil detach "/Volumes/Renode_1.16.1"
+
+# macOS x64
+curl -LO https://github.com/renode/renode/releases/download/v1.16.1/renode_1.16.1.dmg
 # Mount and copy to /Applications
 
 # Ubuntu/Debian
 sudo apt install renode
 
-# Or portable version
-wget https://github.com/renode/renode/releases/download/v1.15.0/renode-1.15.0.linux-portable.tar.gz
-tar xzf renode-1.15.0.linux-portable.tar.gz
-export PATH=$PATH:$(pwd)/renode_1.15.0_portable
+# Verify
+renode --version
 ```
 
 ## MCP Tools