# dronecan/pydronecan architecture

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

- Interactive diagram: https://gitdiagram.com/dronecan/pydronecan
- Repository: https://github.com/dronecan/pydronecan

## Overview

##### Project Type and Purpose
- This is a network-protocol library implementing the DroneCAN v1 protocol in pure Python.
- It provides:
- A data‐type definition subsystem (DSDL)
- A transport and framing layer
- A node abstraction for network operations
- Driver interfaces to various CAN back ends
- Higher-level “app” utilities and example/CLI tools

##### File Structure (Map to Components)
- Top‐level package “dronecan” splits into submodules:
- dsdl — parsing and handling of data‐structure definitions
- transport — message framing, priority scheduling, transfer reassembly
- node — API for creating/managing network nodes, service and message clients/servers
- driver — back‐end adapters (SocketCAN, python‐can, SLCAN, MAVLink tunnel, file, multicast)
- app — example application utilities (dynamic node ID allocator, file server, monitors, collectors)
- introspect, utility, version — supporting services and metadata
- Separate “examples” and “tools” directories show how end users wire up the library in scripts.

##### README Insights
- Confirms it’s a lightweight CAN-bus protocol stack for robotics/aerospace.
- No external Python dependencies on Python 3; optional ones for Python 2.7.

##### Main Components & Their Relationships
A. DSDL Subsystem (dronecan.dsdl)
- Generates Python classes for DroneCAN message and service types.
- Feeds into the transport layer as typed payloads.
B. Core Protocol Stack
1. Application Layer (dronecan.app + user scripts)
- Uses the Node API to send/receive transfers.
2. Node Abstraction (dronecan.node)
- Exposes service‐request/response and publish/subscribe primitives.
3. Transport Layer (dronecan.transport)
- Implements multiplexing, CRC, frame sequencing.
4. Driver Layer (dronecan.driver.*)
- Concrete CAN I/O: SocketCAN, python‐can, SLCAN, file replay, multicast, MAVLink tunneling.
C. External CAN Bus
- Physical medium or virtualized interfaces (e.g. SocketCAN).
D. Examples & CLI Tools
- Live demos, diagnostics and bridging scripts that instantiate the above layers.

##### Architectural Patterns & Design Principles
- Strict layering: each layer only depends on the one immediately below plus the DSDL data types.
- Plug-in driver architecture: new back ends conform to a common driver interface.
- Separation of concerns: parsing DS definitions is orthogonal to transport logic.
- Node‐centric API: easy to create services or publishers without dealing directly with frames.

1. Applications / CLI & Examples
2. Node API
3. Transport Layer
4. Driver Plugins
5. CAN Bus (physical or virtual)
6. DSDL Repository (off-to-side, feeding into transport via code generation)
- App → Node → Transport → Driver → CAN Bus
- CAN Bus → Driver → Transport → Node → App
- DSDL → Transport (code‐gen path)
- Blue rectangles for core modules (node, transport)
- Green for application utilities (dronecan.app, examples, tools)
- Gray for drivers (each submodule)
- Orange for external systems (CAN Bus, Python runtime)
e. Technologies:
- “Pure-Python runtime” on the background

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Applications & CLI Tools Layer
    subgraph "Applications & Tools"
        direction TB
        App["dronecan.app\n(dynamic_node_id, file_server,\nlog_message_monitor,\nmessage_collector,\nnode_monitor)"]:::app
        Examples["examples/\n(end-user scripts)"]:::app
        Tools["tools/\n(dronecan_bridge,\ndronecan_msgid_decode,\ndronecan_tcplink)"]:::app
    end

    %% Node API Layer
    subgraph "Node API"
        direction TB
        Node["dronecan.node\n(Node abstraction,\nservice/messaging API)"]:::core
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        Transport["dronecan.transport\n(multiplexing, CRC,\nframe sequencing)"]:::core
    end

    %% Driver Plugins Layer
    subgraph "Driver Plugins"
        direction TB
        Drivers["dronecan.driver/\n(common, socketcan,\npython_can, slcan,\nmavcan, mcast,\nfile, timestamp_estimator)"]:::driver
    end

    %% CAN Bus External
    CAN["CAN Bus\n(physical or virtual)"]:::external

    %% DSDL Subsystem (offline code-gen)
    DSDL["dronecan.dsdl/\n(custom DSDL parser,\ncode generator)"]:::dsdl

    %% Data Flow
    App -->|uses| Node
    Examples -->|uses| Node
    Tools -->|uses| Node
    Node -->|sends/receives| Transport
    Transport -->|frames/unframes| Drivers
    Drivers -->|I/O| CAN
    CAN -->|raw frames| Drivers
    Drivers -->|raw frames| Transport
    Transport -->|transfers| Node
    Node -->|data objects| App
    DSDL -.->|code-gen| Transport

    %% Click Events
    click App "https://github.com/dronecan/pydronecan/tree/master/dronecan/app/"
    click Examples "https://github.com/dronecan/pydronecan/tree/master/examples/"
    click Tools "https://github.com/dronecan/pydronecan/tree/master/tools/"
    click Node "https://github.com/dronecan/pydronecan/blob/master/dronecan/node.py"
    click Transport "https://github.com/dronecan/pydronecan/blob/master/dronecan/transport.py"
    click Drivers "https://github.com/dronecan/pydronecan/tree/master/dronecan/driver/"
    click DSDL "https://github.com/dronecan/pydronecan/tree/master/dronecan/dsdl/"

    %% Styles
    classDef app fill:#ccffcc,stroke:#2f6627,color:#000;
    classDef core fill:#cce5ff,stroke:#1f4e79,color:#000;
    classDef driver fill:#eeeeee,stroke:#444444,color:#000;
    classDef external fill:#ffe5cc,stroke:#b36b00,color:#000;
    classDef dsdl stroke-dasharray: 5 5,fill:#fafafa,stroke:#777777,color:#000;
```
