# kai-morich/simpleusbterminal architecture

> Architecture diagram of the GitHub repository kai-morich/simpleusbterminal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kai-morich/simpleusbterminal
- Repository: https://github.com/kai-morich/simpleusbterminal

## Overview

##### Project Type and Purpose
- This is a single-module Android application (“SimpleUsbTerminal”) whose sole purpose is to act as a line-oriented terminal/console for USB-to-serial devices.
- It provides UI screens to list devices and exchange data, a background service to maintain connectivity and buffer data, and leverages an external library for low-level USB serial communication.

##### File Structure Overview
- Top-level: Gradle wrapper files, settings.gradle, build.gradle → standard Android build configuration.
- app/
- build.gradle, proguard-rules.pro → module build and obfuscation config
- src/main/java/...simple_usb_terminal/
– MainActivity.java → hosts UI fragments
– DevicesFragment.java → enumerates and requests permission for USB devices
– TerminalFragment.java → displays incoming data and sends user input
– SerialService.java → Android Service that owns SerialSocket, buffers I/O
– SerialSocket.java, SerialListener.java → wrapper around usb-serial-for-android library to read/write bytes
– CustomProber.java → detects supported USB-serial chipsets
– Constants.java, TextUtil.java → helpers
- src/main/res/… → layouts (activity_main, device_list, terminal), menus, drawables, usb_device_filter.xml

##### README Insights
- Describes supported chipsets, key features (permission handling, foreground service, break signal, control lines, flow control).
- Credits usb-serial-for-android library for actual USB protocol implementation.

a. Main Components to show:
- Android UI Layer
- MainActivity
- DevicesFragment
- TerminalFragment
- Android Service Layer
- SerialService (foreground service)
- USB Communication Layer
- SerialSocket & SerialListener (wrapping usb-serial-for-android)
- CustomProber (device detection)
- External Dependencies
- usb-serial-for-android library
- Hardware/Platform
- Android OS USB Host API
- External USB-to-serial device (FTDI, PL2303, CDC, etc.)

b. Relationships and Interactions:
- UI fragments send user actions (e.g., “Open device”, “Send data”) to MainActivity
- MainActivity binds/communicates with SerialService (startService + bindService)
- SerialService uses CustomProber to detect and open a connection via usb-serial-for-android
- SerialSocket dispatches incoming bytes to SerialListener → forwards to TerminalFragment via Service callbacks or local broadcast
- User input from TerminalFragment → Service → SerialSocket.write() → USB Host API → Device
- Service remains in foreground to persist through configuration changes/background

c. Architectural Patterns and Principles:
- Separation of concerns: UI vs Service vs I/O
- Observer pattern: SerialListener callbacks feed data into UI
- Layered design: Presentation (Fragments/Activity) → Service (business logic) → Adapter (SerialSocket) → Hardware API

d. Key Technologies/Frameworks:
- Android SDK (Activities, Fragments, Services, USB Host)
- usb-serial-for-android library for low-level protocol
- Gradle build system

##### Final Recommendations
- Be thorough: include every Java class that has a distinct responsibility (e.g., CustomProber, SerialListener)
- Both control flows (permission requests, service binding) and data flows (serial data in/out)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        MA["MainActivity"]:::ui
        DF["DevicesFragment"]:::ui
        TF["TerminalFragment"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        SSvc["SerialService"]:::service
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        CProber["CustomProber"]:::adapter
        SSocket["SerialSocket"]:::adapter
        SListener["SerialListener"]:::adapter
    end

    %% External Dependency
    subgraph "External Dependency"
        USBLib["usb-serial-for-android"]:::external
    end

    %% Platform Layer
    subgraph "Android Platform"
        USBAPI["Android OS USB Host API"]:::platform
    end

    %% Hardware Layer
    Device["USB-to-Serial Device"]:::hardware

    %% Helpers & Config
    Constants["Constants"]:::helper
    TextUtil["TextUtil"]:::helper
    Manifest["AndroidManifest.xml"]:::config

    %% UI Resources
    subgraph "UI Layouts & Resources"
        AMain["activity_main.xml"]:::config
        DHeader["device_list_header.xml"]:::config
        DItem["device_list_item.xml"]:::config
        FTLayout["fragment_terminal.xml"]:::config
        MenuD["menu_devices.xml"]:::config
        MenuT["menu_terminal.xml"]:::config
        USBFilter["usb_device_filter.xml"]:::config
        IconSend["ic_send_white_24dp.xml"]:::config
        IconDel["ic_delete_white_24dp.xml"]:::config
        IconBlk["ic_block_white_24dp.xml"]:::config
    end

    %% Relationships
    DF --> MA
    TF --> MA
    MA -->|"startService()/bindService()"| SSvc
    SSvc -->|"detect()/probe()"| CProber
    CProber --> USBLib
    SSvc --> SSocket
    SSocket --> USBLib
    SSocket --> SListener
    SListener -->|"onReceived(bytes)"| SSvc
    SSvc -->|"forward data"| TF
    TF -->|"send(data)"| SSvc
    SSvc -->|"write(data)"| SSocket
    SSocket -->|"io(data)"| USBAPI
    USBAPI --> Device
    Device --> USBAPI
    USBAPI -->|"incoming(bytes)"| SListener
    Constants -.-> SSvc
    TextUtil -.-> TF

    %% Click Events
    click MA "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/MainActivity.java"
    click DF "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/DevicesFragment.java"
    click TF "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/TerminalFragment.java"
    click SSvc "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/SerialService.java"
    click SSocket "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/SerialSocket.java"
    click SListener "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/SerialListener.java"
    click CProber "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/CustomProber.java"
    click Constants "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/Constants.java"
    click TextUtil "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/java/de/kai_morich/simple_usb_terminal/TextUtil.java"
    click Manifest "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/AndroidManifest.xml"
    click AMain "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/layout/activity_main.xml"
    click DHeader "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/layout/device_list_header.xml"
    click DItem "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/layout/device_list_item.xml"
    click FTLayout "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/layout/fragment_terminal.xml"
    click MenuD "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/menu/menu_devices.xml"
    click MenuT "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/menu/menu_terminal.xml"
    click USBFilter "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/xml/usb_device_filter.xml"
    click IconSend "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/drawable/ic_send_white_24dp.xml"
    click IconDel "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/drawable/ic_delete_white_24dp.xml"
    click IconBlk "https://github.com/kai-morich/simpleusbterminal/blob/master/app/src/main/res/drawable/ic_block_white_24dp.xml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0052CC,color:#000
    classDef service fill:#DFFFD0,stroke:#008000,color:#000
    classDef adapter fill:#FFE8D0,stroke:#CC5200,color:#000
    classDef external fill:#E8D0FF,stroke:#8000CC,color:#000
    classDef platform fill:#F0F0F0,stroke:#666,color:#000
    classDef hardware fill:#FFD0D0,stroke:#CC0000,color:#000
    classDef helper fill:#FFF0D0,stroke:#CCCC00,color:#000
    classDef config fill:#F8F8F8,stroke:#999,color:#000
```
