# oizom-iot/sds011 architecture

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

- Interactive diagram: https://gitdiagram.com/oizom-iot/sds011
- Repository: https://github.com/oizom-iot/sds011

## Overview

##### Project Type and Purpose
- This project is a Python module that acts as a client for the SDS011 fine dust sensor. Its purpose is to interface with the sensor using a serial port and to offer various interaction modes: a console-based test, a PyQt5 GUI for basic plotting, socket output for real‐time data streaming, and database logging using SQLite.
- The README makes clear that the module offers multiple operational modes (normal measurement, socket-based delivery, and database logging) and includes example applications to demonstrate its features.

##### File Structure
- Top-Level Files and Directories:
- Files like .gitignore, LICENSE, README.md, and setup.py indicate that this is a distributable Python package.
- The main code resides in the sds011 directory (with an __init__.py to mark it as a package) and includes the core module “sds011.py” that likely implements the SDS011 class.
- Examples:
- The 'examples' subdirectory within sds011 shows scripts for a console test and a PyQt5 application (sds011_pyqt5app.pyw), hinting at both headless and GUI-based usage.
- Utilities:
- The utils folder contains specific modules for handling database (databasehandler.py) and socket (sockethandler.py) functionalities. These support the extended features described in the README.

##### Main Components
a. Sensor and External Interfaces:
- External Sensor Device: Represent the physical SDS011 sensor.
- Serial Port: This is your physical communication channel (e.g., “/dev/ttyUSB0” or COM port) between the sensor and the client.
b. Core Module: SDS011 Module:
- Main Sensor Client (sds011.py): This component encapsulates communication protocols with the sensor, interprets measurements, and provides the API (set_working_period, read_measurement, etc.).
c. Adapters / Utility Components:
- Socket Handler (sockethandler.py): Handles opening a local socket (default port 9999) for streaming sensor data.
- Database Handler (databasehandler.py): Manages SQLite database interactions when logging measurements.
d. User Interface / Example Applications:
- Console Example (sds011_console_test.py): A simple script demonstrating basic sensor readings.
- PyQt5 GUI (sds011_pyqt5app.pyw): A graphical application that displays sensor information and plots data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["SDS011 Sensor"]:::external
    B["Serial Interface"]:::external
    C["SDS011 Client (sds011.py)"]:::core
    D["Socket Adapter (sockethandler.py)"]:::adapter
    E["Database Adapter (databasehandler.py)"]:::adapter
    F["Console Example (sds011_console_test.py)"]:::example
    G["PyQt5 GUI (sds011_pyqt5app.pyw)"]:::example

    A -->|"sends_data"| B
    B -->|"transmits"| C
    C -->|"streams_via_socket"| D
    C -->|"logs_to_database"| E
    C -->|"provides_API"| F
    F -->|"launches_GUI"| G

    classDef external fill:#FDB813,stroke:#333,stroke-width:2px;
    classDef core fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef adapter fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef example fill:#D1C4E9,stroke:#333,stroke-width:2px;

    click C "https://github.com/oizom-iot/sds011/blob/master/sds011/sds011.py"
    click D "https://github.com/oizom-iot/sds011/blob/master/sds011/utils/sockethandler.py"
    click E "https://github.com/oizom-iot/sds011/blob/master/sds011/utils/databasehandler.py"
    click F "https://github.com/oizom-iot/sds011/blob/master/sds011/examples/sds011_console_test.py"
    click G "https://github.com/oizom-iot/sds011/blob/master/sds011/examples/sds011_pyqt5app.pyw"
```
