> For the complete documentation index, see [llms.txt](https://mujoseph.gitbook.io/mujoseph-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mujoseph.gitbook.io/mujoseph-docs/emma-mk1-drsstc/emma-mk1-drsstc-web-controller-software-overview.md).

# Emma Mk1 DRSSTC Web Controller Software Overview

The *Emma Mk1 DRSSTC Web Controller* Python script runs on the [Raspberry Pi 4B](/mujoseph-docs/emma-mk1-drsstc/hardware-overview/raspberry-pi.md). The script hosts a Flask web portal that controls the [*DRSSTC\_Driver*](/mujoseph-docs/emma-mk1-drsstc/drsstc_driver-firmware-overview.md) through a [UART interface](/mujoseph-docs/emma-mk1-drsstc/hardware-overview/electrical-design/pcb-design/motherboard.md#wireless-control-interface).

## Repository

Source code for the *Emma Mk1 DRSSTC Web Controller* can be found [here](https://github.com/muJoseph/Emma-Mk1-DRSSTC-Web-Controller).

## Overview

The `drsstc_mb_controller_web.py` script creates three `OsalProcess` objects from the `main` thread:

* `osal_timer_process` : Serves as a timer service for the other two tasks. Provides basic scheduler functionality to create periodic and/or delayed events within the consuming `OsalProcess` object(s). Operates within a worker thread.
* `mujoe_osal` : Manages the Raspberry Pi UART peripheral. Builds/sends command frames to and receives/parses frames from the *Emma Mk1* [*Motherboard*](/mujoseph-docs/emma-mk1-drsstc/hardware-overview/electrical-design/pcb-design/motherboard.md) *PCB*. Operates within a worker thread.
* `web_portal_osal` : Manages the [Flask](https://pypi.org/project/Flask/) web portal. Operates within a worker thread.

`OsalProcess` is simply a wrapper for Python's native [`multiprocessing.Process`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Process)  and [`multiprocessing.Queue`](https://docs.python.org/3/library/multiprocessing.html#multiprocessing.Queue) classes. Each `OsalProcess` stands up a `multiprocessing.Process` within a worker thread, and data is exchanged with said process using a TX and RX `multiprocessing.Queue`. 

The `main` thread serves as a central dispatch: it consumes all emitted messages from the `mujoe_osal` and `web_portal_osal` objects and forwards the message to its destination if neccessary. 

The figure below shows the high-level architecture of the *Emma Mk1 DRSSTC Web Controller* software, as well as the companion *DRSSTC\_Driver* firmware.

{% hint style="info" %}
All layers above the OSAL processes (the web portal and the code-behind for interfacing with the OSAL threads) was written with AI.
{% endhint %}

{% code expandable="true" %}

```mermaid
flowchart TB
    subgraph RPI["Raspberry Pi — Python"]
        Browser["Operator browser"]
        Flask["Flask routes and HTML portal"]
        WebOSAL["DrsstcWebPortalAppOsal<br/>web worker process"]
        Main["drsstc_mb_controller_web.py<br/>validation and orchestration"]
        SerialOSAL["MujoeSerialCommOsal<br/>serial worker process"]
        PyProtocol["MujoeSerialCommRpi<br/>frames, CRC, response parser"]
        PySerial["pyserial + Linux serial device<br/>/dev/serial0, 115200 8N1"]

        Browser <--> Flask
        Flask <--> WebOSAL
        WebOSAL <-->|multiprocessing emit queue| Main
        Main <-->|OSAL queues and events| SerialOSAL
        SerialOSAL <--> PyProtocol
        PyProtocol <--> PySerial
    end

    UART["3.3 V UART<br/>TX, RX, and common ground"]
    PySerial <--> UART

    subgraph MCU["Emma Mk1 controller — STM32 / FreeRTOS"]
        STMUSART["USART1 + DMA driver<br/>PC4 TX, PC5 RX"]
        CommTask["commTask<br/>CMSIS-RTOS message queue"]
        CProtocol["mujoe_ser_comm<br/>frame parser, CRC, command dispatch"]
        DRSSTCDispatch["mujoe_ser_comm_drsstc<br/>command handlers"]
        ResTask["resDriveTask<br/>validation and burst control"]
        Hardware["Resonant-drive, HRTIM, OCD,<br/>HV bus, buzzer, and LEDs"]

        STMUSART <--> CommTask
        CommTask <--> CProtocol
        CProtocol <--> DRSSTCDispatch
        DRSSTCDispatch <--> ResTask
        ResTask <--> Hardware
    end

    UART <--> STMUSART
```

{% endcode %}

## Program Flow Example

When the host initiates a resonant burst via the web portal:

1. `web_portal_osal` object emits a message notifying the `main` thread of the GUI button press (and also passes command arguments, such as PRF period, on-time, etc.).
2. &#x20;The `main` thread then sends the "start resonant burst" message to the `mujoe_osal` object.&#x20;
3. The mujoe\_osal object builds the UART command frame, sends it, awaits the response UART frame from the [*Motherboard*](/mujoseph-docs/emma-mk1-drsstc/hardware-overview/electrical-design/pcb-design/motherboard.md) *PCB,* and alerts the `main` thread via another emitted message of the command response.
4. The `main` thread then notifies `web_portal_osal`, which in turn updates the GUI.

## Video Demo&#x20;

The video below demonstrates the following:

* Set the [OCD current limit and comparator hysteresis](/mujoseph-docs/emma-mk1-drsstc/drsstc_driver-firmware-overview/serial-interface.md#set-ocd-parameters-command)
* Control the [high-voltage bus state](/mujoseph-docs/emma-mk1-drsstc/drsstc_driver-firmware-overview/serial-interface.md#control-high-voltage-bus-command)
* [Start a finite burst](/mujoseph-docs/emma-mk1-drsstc/drsstc_driver-firmware-overview/serial-interface.md#start-burst-command)
* Dump the [resonant capture buffer](/mujoseph-docs/emma-mk1-drsstc/drsstc_driver-firmware-overview/serial-interface.md#dump-resonant-period-capture-buffer-command) to a CSV

{% embed url="<https://youtu.be/z07r5cOWDMk?si=NhIUJe-ECAXNKbZz>" %}
Demo of the *Emma Mk1 DRSSTC Web Controller* software
{% endembed %}