SDD

Software Design Document (SDD)

Version History

Version	Date	Status
1.0	02/04/2024	Approved
1.1	08/04/2024	Approved
1.2	16/04/2024	Approved
2.0	06/09/2024	Approved
3.0	-	Approved
4.0	-	Approved
5.0	-	Approved
6.0	03/09/2025	Pending Approval

Reference

System Requirement Specification SRS.

1. Introduction

Purpose

This document outlines the design and architecture of Obo Blocks, a Scratch Blocks to Python code converter with code evaluation using Pydiode. Obo Blocks aims to facilitate the transition from visual programming to text-based programming for students and teachers at Roboticgen Academy

Scope

Obo Blocks will allow users to convert programs written in Scratch Blocks, a visual programming language, into Python code. Additionally, it will provide code interpretation capabilities with limited number of libraries using Pydiode while supporting micropython extension, enabling users to edit the generated Python code snippets, run their Python code directly within the web interface while allowing users to upload generated code to ESP32 Development Board (MagicBit). Also enables to upload custom files and packages. The target users include students and teachers affiliated with Roboticgen Academy.

2. System Overview

The system is for students who have no prior knowledge of Python-related programming to program ESP32 using Scratch Blocks. The enhanced version integrates advanced file management, custom library uploads, and improved code editing features.

3. Architectural Style

The Monolithic Architecture will be used for the system

4. Components

• Blockly Workspace: Responsible for providing the interface for building programs using Scratch Blocks

graph LR
  subgraph Workspace
    TB[Toolbox]
    CV[Canvas]
  end

Loading

• Code Converter: Responsible for converting Scratch Blocks programs into Python code.

graph LR
  subgraph "Code Converter"
    BV[Block Validator]
    AF[Argument Filter]
    PCG[Python Code Generator]
    EL[Event Listener]
    MR[(Mapping Registry)]
  end

  BV --> AF --> PCG
  EL --> PCG
  MR -. lookups .-> PCG

Loading

• Code Interpreter: Utilizes Pydiode for executing Python code within the browser environment.

graph LR
  subgraph "Code Interpreter"
    JB[JavaScript Bridge]
    PY[Pyodide Runtime - CPython WASM]
    MC[WASM mpy-cross - compile/validate .mpy]
    SB[Sandbox / Permissions]
  end

  JB --> PY
  JB --> MC
  PY --> SB
  MC --> SB

Loading

• Code Uploader: Responsible for uploading generated code to ESP32 Development Board (MagicBit).

graph LR
  subgraph "Code Uploader"
    FG[File Generator - .py/.mpy]
    DW[Data Writer]
    DR[Data Reader]
    VF[Verifier]
  end

  subgraph Connectivity
    WS[WebSerial - USB]
    WR[WiFi WebREPL]
    BLE[Bluetooth LE]
    P2P[WebRTC P2P]
  end

  subgraph "ViperIDE Modules"
    FM[File Manager]
    PM[Package Manager]
    VM[Virtual Device - MicroPython VM]
  end

  ESP[ESP32 / MagicBit]

  FG --> DW
  DR --> VF
  FM -.manage .-> FG
  PM -.packages .-> FG
  VM -.simulate .-> VF

  DW --> WS --> ESP
  DW --> WR --> ESP
  DW --> BLE --> ESP
  DW --> P2P --> ESP

Loading

• Error Handler: Handles errors and provides informative messages to users.

graph LR
  subgraph "Error Handler"
    LN[Listener]
    EX[Exception Handler]
    UO[User Output - console log]
  end

  LN --> EX --> UO

Loading

Component Communication

graph LR
  WS[Blockly Workspace]
  CC[Code Converter]
  CI[Code Interpreter - Pyodide + WASM mpy-cross]
  CU[Code Uploader - File Manager and Package Manager Integrations]
  EH[Error Handler]
  ESP[ESP32 / MagicBit]

  WS --> CC --> CI --> CU --> ESP
  CI -- stdout/stderr --> WS
  CU -- status --> WS

  WS -. ui errors .-> EH
  CC -. conversion errors .-> EH
  CI -. runtime errors .-> EH
  CU -. I/O errors .-> EH

Loading

Sequence Diagram

sequenceDiagram
    actor U as User
    participant W as Workspace
    participant FM as File Manager
    participant PM as Package Manager
    participant IU as Interpreter & Uploader
    participant MC as WASM mpy-cross
    participant D as ESP32 Device

    U ->> W: Build Scratch Blocks
    W ->> IU: Convert blocks → Python (.py)

    U ->> FM: Manage files (upload/edit/delete)
    FM ->> IU: Provide .py/.mpy files for execution/upload

    U ->> PM: Install/Update packages
    PM ->> IU: Provide dependencies / libraries
    PM ->> MC: Compile custom packages if needed
    MC -->> PM: Compiled .mpy / validation

    IU ->> MC: Compile/validate Python code
    MC -->> IU: .mpy bytecode / diagnostics

    IU ->> D: Upload .py/.mpy<br/>(WebSerial/WebREPL/BLE/WebRTC)
    IU -->> W: Messages + stdout/stderr

    D -->> IU: Status codes / read-back
    IU -->> W: Verification result

Loading

5. Interfaces

User Interface

• Blockly Workspace: Drag-and-drop blocks
• Python Editor: Syntax highlighting, auto-complete
• Output Console: Execution results, error logs
• File Manager: Tree view, drag-and-drop, file operations
• Package Manager: Install/update/remove libraries
• Virtual Device Emulator: In-browser MicroPython execution

Hardware Interfaces

ESP32 (MagicBit) via:

• WebSerial (USB)
• WiFi (WebREPL)
• Bluetooth LE
• WebRTC P2P

APIs / Services

• Pyodide: Browser CPython runtime
• WASM mpy-cross: MicroPython bytecode compiler
• Blockly: Block-based editor
• CodeMirror: Text editor
• Web APIs: WebSerial, WebBluetooth, WebRTC

6. Technology Stack

• Frontend: React
• Editor: CodeMirror 6, Highlight.js
• Runtime: Pyodide (WASM), WASM mpy-cross
• Protocols: WebSerial, WebBluetooth, WebRTC, WebSocket
• Dev Tools: VS Code, GitHub
• Deployment: Vercel (development), AWS (production)

7. Dependencies

• Blocky
• Python
• Pydiode
• Highlightjs
• CodeMirror 6
• Xterm.js
• Web Serial Polyfill
• PeerJS