# upstreamdata/pyasic architecture

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

- Interactive diagram: https://gitdiagram.com/upstreamdata/pyasic
- Repository: https://github.com/upstreamdata/pyasic

## Overview

##### Main components
- Core Manager: At the heart of the system is the “pyasic core” which ties together network scanning, miner creation (via a factory), and control functions.
- Network Module: Represented by classes like MinerNetwork which manage asynchronous scanning of IP subnets for ASICs.
- Miner Factory: The abstraction offering methods like get_miner() (and underlying MinerFactory) that instantiates the correct miner type.
- Miner Modules: Organized under the “pyasic/miners” directory, these modules encapsulate support for various ASIC models and their vendor-specific implementations. They include subdirectories for different manufacturers (antminer, auradine, avalonminer, etc.) and backends (cgminer, bmminer, etc.).
- Communication Adapters: Modules implementing different protocols such as RPC (pyasic/rpc), SSH (pyasic/ssh), and Web (pyasic/web) that allow control commands and data gathering to be sent to the ASIC miners.
- Data & Configuration: Helper dataclasses (MinerData, MinerConfig) and associated utilities found across pyasic/config and pyasic/data that consistently represent miner status, configuration, errors, and operational metrics.
- Device & Algorithm Layers: Components within pyasic/device manage low-level interactions with the ASIC hardware and also contain mathematical/algorithmic logic (e.g., various hashing algorithm implementations).
- Settings & Logger: Global settings (pyasic/settings) to manage default credentials and timeouts plus logging facilities (pyasic/logger) to record operations.

##### Relationships and data flows
- User or Automated Service → Pyasic Interface:
- The library is typically invoked by a user script or service (as seen in the examples in the README) via command-line or API calls.
- Network Scanning → Miner Creation:
- The MinerNetwork class collects active ASICs on a given subnet and passes their IP addresses to the MinerFactory (via get_miner()).
- MinerFactory → Specific Miner Implementations:
- Based on IP probe responses, the factory selects the correct miner subclass (organized by type, model, and vendor) and returns a fully instantiated miner object.
- Miner Instance Operations:
- The miner object (which implements a common interface defined in BaseMiner) exposes asynchronous methods such as get_data(), get_config(), send_config(), and control functions (e.g., reboot, fault_light_on/off).
- Communication Adapters:
- Depending on the miner’s type, control commands and data are sent through appropriate channels (RPC, SSH, or HTTP/web protocols).
- Data Aggregation:
- Retrieved MinerData instances (and MinerConfig details) are used to aggregate metrics and provide a consistent interface to the client.

##### Important architectural patterns
- Asynchronous Programming:
- The project uses Python’s asyncio to perform non-blocking network calls and parallel data gathering from multiple ASICs.
- Factory and Abstraction:
- A factory pattern is used to create miner objects based on network discovery. All miner classes implement a common interface ensuring uniform control regardless of vendor differences.
- Modular Design and Separation of Concerns:
- Different directories clearly separate configuration, data processing, device handling, algorithms, networking, communication protocols, and documentation. This makes it straightforward to extend support for new ASIC models.
- Use of Data Classes & Helper Functions:
- Consistent data structures (via MinerData and MinerConfig) ensure that data collected from varied devices is normalized.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        UI("User / Client Interface"):::user
    end

    subgraph "Core Layer"
        CORE("pyasic Core"):::core
        NET("MinerNetwork"):::network
        FACTORY("Miner Factory"):::factory
        MODULES("Miner Modules"):::miner
    end

    subgraph "Communication Layer"
        RPC("RPC Adapter"):::adapter
        SSH("SSH Adapter"):::adapter
        WEB("Web Adapter"):::adapter
        ASIC("ASIC Miners"):::external
    end

    subgraph "Support Modules"
        CONFIG("Configuration"):::data
        DATA("Data"):::data
        DEVICE("Device & Algorithm Layer"):::device
        SETTING("Settings"):::settings
        LOGGER("Logger"):::logger
    end

    %% Data Flow and Relationships
    UI --> CORE
    CORE --> NET
    NET --> FACTORY
    FACTORY --> MODULES
    MODULES --> RPC
    MODULES --> SSH
    MODULES --> WEB
    RPC --> ASIC
    SSH --> ASIC
    WEB --> ASIC
    MODULES --> CONFIG
    MODULES --> DATA
    MODULES --> DEVICE
    SETTING --> CORE
    LOGGER --> CORE

    %% Styles
    classDef user fill:#a2d9ce,stroke:#000,stroke-width:1px;
    classDef core fill:#f7dc6f,stroke:#000,stroke-width:1px;
    classDef network fill:#aed6f1,stroke:#000,stroke-width:1px;
    classDef factory fill:#d7bde2,stroke:#000,stroke-width:1px;
    classDef miner fill:#f5b7b1,stroke:#000,stroke-width:1px;
    classDef adapter fill:#f1948a,stroke:#000,stroke-width:1px;
    classDef external fill:#d5f5e3,stroke:#000,stroke-width:1px,stroke-dasharray: 5;
    classDef data fill:#fcf3cf,stroke:#000,stroke-width:1px;
    classDef device fill:#fad7a0,stroke:#000,stroke-width:1px;
    classDef settings fill:#d6eaf8,stroke:#000,stroke-width:1px;
    classDef logger fill:#e8daef,stroke:#000,stroke-width:1px;

    %% Click Events
    click CORE "https://github.com/upstreamdata/pyasic/blob/master/pyasic/__init__.py"
    click NET "https://github.com/upstreamdata/pyasic/tree/master/pyasic/network/"
    click FACTORY "https://github.com/upstreamdata/pyasic/blob/master/pyasic/miners/factory.py"
    click MODULES "https://github.com/upstreamdata/pyasic/tree/master/pyasic/miners/"
    click RPC "https://github.com/upstreamdata/pyasic/tree/master/pyasic/rpc/"
    click SSH "https://github.com/upstreamdata/pyasic/tree/master/pyasic/ssh/"
    click WEB "https://github.com/upstreamdata/pyasic/tree/master/pyasic/web/"
    click CONFIG "https://github.com/upstreamdata/pyasic/tree/master/pyasic/config/"
    click DATA "https://github.com/upstreamdata/pyasic/tree/master/pyasic/data/"
    click DEVICE "https://github.com/upstreamdata/pyasic/tree/master/pyasic/device/"
    click SETTING "https://github.com/upstreamdata/pyasic/tree/master/pyasic/settings/"
    click LOGGER "https://github.com/upstreamdata/pyasic/tree/master/pyasic/logger/"
```
