# aphyt/omron_fins architecture

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

- Interactive diagram: https://gitdiagram.com/aphyt/omron_fins
- Repository: https://github.com/aphyt/omron_fins

## Overview

1. This repository is a small Python 3 library for speaking Omron’s FINS protocol to PLCs. It is not an application in itself; the main deliverable is the `fins` package, which exposes transport-specific connection classes and protocol helpers.

2. The architecture is split into a protocol/core layer and transport adapters. The core appears to live in `fins/fins_common.py`, which likely defines FINS frame construction, parsing, constants/enums such as PLC memory areas, and shared request/response handling used by all transports.

3. Three transport modules implement the wire-level boundary:
   - `fins/tcp.py` for FINS over TCP
   - `fins/udp.py` for FINS over UDP
   - `fins/usb.py` for USB-based communication
   The README emphasizes UDP as the most practical path and notes that USB requires a custom LibUSBK-style driver rather than Omron’s CX-One driver.

4. The public usage model is connection-centric. Client code instantiates a connection object, calls `connect(host)` or equivalent, sets PLC node addressing fields such as `dest_node_add` and `srce_node_add`, and then issues protocol operations like memory reads/writes or program transfer. This makes the transport an implementation detail behind one object per session.

5. The main data flow is: user program → `fins` connection object → protocol frame assembly in common code → transport send/receive → PLC response parsing → raw bytes or higher-level result returned to the caller. The library therefore sits directly between application logic and the PLC, with no intermediate server or daemon.

6. The most important functional use cases are PLC memory access and program file transfer. The README highlights reading and writing memory areas such as CIO bits/words, and transferring a PLC program to/from a hex file. That suggests the core API centers on memory-area operations plus file-backed program download/upload.

7. The `examples/` directory is part of the architecture documentation, not just demos. It contains separate scripts for TCP/UDP send/get flows, which illustrates how the same protocol operations are reused across transports. The examples are useful for understanding the expected lifecycle and the minimal state a client must configure before issuing FINS calls.

8. The `docs/` directory provides standalone project documentation, reinforcing that the package is meant to be embedded in other Python systems rather than deployed as a service. There is no evidence of a database, web server, message bus, or background worker architecture.

9. Packaging is handled in `setup.py`, so the repository is distributed as a Python package. `fins/__init__.py` serves as the package boundary for public imports, while the lower-level modules remain separated by transport and shared protocol logic.

10. The main external dependency is the PLC itself and the FINS network path to it. For Ethernet-based CP/CS/CJ processors, UDP/TCP provide the normal integration boundary; USB is explicitly experimental and depends on the user supplying compatible drivers and hardware identifiers. This means the repo’s architecture is centered on device communication, not on internal service composition.

11. For an architecture diagram, the key components are: client application, protocol core, transport layer(s), and Omron PLC endpoint. The important arrows are request/response byte streams, with protocol state such as node addressing and memory-area selection flowing from the client into the connection object and returned data flowing back as raw bytes or file contents.

Main entry points: [`fins/__init__.py`](https://github.com/aphyt/omron_fins/blob/master/fins/__init__.py) (fins package), [`examples/README.md`](https://github.com/aphyt/omron_fins/blob/master/examples/README.md) (Examples), [`fins/fins_common.py`](https://github.com/aphyt/omron_fins/blob/master/fins/fins_common.py) (Common core), [`fins/tcp.py`](https://github.com/aphyt/omron_fins/blob/master/fins/tcp.py) (TCP transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Public package"]
  node_n2["fins package<br/>public API<br/>[__init__.py]"]
  node_n14["Packaging<br/>build metadata<br/>[setup.py]"]
end

subgraph group_g2["Protocol core"]
  node_n3["Common core<br/>protocol core<br/>[fins_common.py]"]
end

subgraph group_g3["Transport adapters"]
  node_n4["TCP transport<br/>adapter<br/>[tcp.py]"]
  node_n5["UDP transport<br/>adapter<br/>[udp.py]"]
  node_n6["USB transport<br/>adapter<br/>[usb.py]"]
end

subgraph group_g4["Usage artifacts"]
  node_n7["Examples<br/>usage scripts<br/>[README.md]"]
  node_n8["TCP get<br/>example"]
  node_n9["TCP send<br/>example"]
  node_n10["UDP get<br/>example"]
  node_n11["UDP send<br/>example"]
  node_n12["README<br/>project guide<br/>[README.md]"]
  node_n13["Docs<br/>[README.md]"]
end

subgraph group_g5["External endpoint"]
  node_n1(("Client app<br/>caller"))
  node_n15[("Omron PLC<br/>device")]
end

node_n1 -->|"imports"| node_n2
node_n2 -->|"shared logic"| node_n3
node_n2 -->|"TCP class"| node_n4
node_n2 -->|"UDP class"| node_n5
node_n2 -->|"USB class"| node_n6
node_n4 -->|"frames"| node_n3
node_n5 -->|"frames"| node_n3
node_n6 -->|"frames"| node_n3
node_n4 -->|"FINS/TCP"| node_n15
node_n5 -->|"FINS/UDP"| node_n15
node_n6 -->|"USB link"| node_n15
node_n1 -.->|"learns from"| node_n7
node_n7 -->|"contains"| node_n8
node_n7 -->|"contains"| node_n9
node_n7 -->|"contains"| node_n10
node_n7 -->|"contains"| node_n11
node_n12 -.->|"documents"| node_n2
node_n13 -.->|"documents"| node_n2
node_n14 -->|"packages"| node_n2
node_n1 -->|"reads/writes"| node_n15

click node_n2 "https://github.com/aphyt/omron_fins/blob/master/fins/__init__.py"
click node_n3 "https://github.com/aphyt/omron_fins/blob/master/fins/fins_common.py"
click node_n4 "https://github.com/aphyt/omron_fins/blob/master/fins/tcp.py"
click node_n5 "https://github.com/aphyt/omron_fins/blob/master/fins/udp.py"
click node_n6 "https://github.com/aphyt/omron_fins/blob/master/fins/usb.py"
click node_n7 "https://github.com/aphyt/omron_fins/blob/master/examples/README.md"
click node_n8 "https://github.com/aphyt/omron_fins/blob/master/examples/example_tcp_get_program.py"
click node_n9 "https://github.com/aphyt/omron_fins/blob/master/examples/example_tcp_send_program.py"
click node_n10 "https://github.com/aphyt/omron_fins/blob/master/examples/example_udp_get_program.py"
click node_n11 "https://github.com/aphyt/omron_fins/blob/master/examples/example_udp_send_program.py"
click node_n12 "https://github.com/aphyt/omron_fins/blob/master/README.md"
click node_n13 "https://github.com/aphyt/omron_fins/blob/master/docs/README.md"
click node_n14 "https://github.com/aphyt/omron_fins/blob/master/setup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n2,node_n14 toneBlue
class node_n3 toneAmber
class node_n4,node_n5,node_n6 toneMint
class node_n7,node_n8,node_n9,node_n10,node_n11,node_n12,node_n13 toneRose
class node_n1,node_n15 toneIndigo
```

## Components

### Public package

Import and session boundary exposed to client code.

- [fins package](https://github.com/aphyt/omron_fins/blob/master/fins/__init__.py): public API · Package boundary for imports and connection classes. · `fins/__init__.py`
- [Packaging](https://github.com/aphyt/omron_fins/blob/master/setup.py): build metadata · Python packaging and distribution entry point. · `setup.py`

### Protocol core

Shared FINS framing, parsing, and PLC addressing logic.

- [Common core](https://github.com/aphyt/omron_fins/blob/master/fins/fins_common.py): protocol core · Shared frame building, parsing, constants, and request/response handling. · `fins/fins_common.py`

### Transport adapters

Wire-level implementations for Ethernet and USB.

- [TCP transport](https://github.com/aphyt/omron_fins/blob/master/fins/tcp.py): adapter · FINS over TCP connection implementation. · `fins/tcp.py`
- [UDP transport](https://github.com/aphyt/omron_fins/blob/master/fins/udp.py): adapter · FINS over UDP connection implementation. · `fins/udp.py`
- [USB transport](https://github.com/aphyt/omron_fins/blob/master/fins/usb.py): adapter · USB-based FINS communication path. · `fins/usb.py`

### Usage artifacts

Repository documentation and runnable examples.

- [Examples](https://github.com/aphyt/omron_fins/blob/master/examples/README.md): usage scripts · Repository examples showing transport-specific send/get flows. · `examples/README.md`
- [TCP get](https://github.com/aphyt/omron_fins/blob/master/examples/example_tcp_get_program.py): example · Example for retrieving PLC data over TCP. · `examples/example_tcp_get_program.py`
- [TCP send](https://github.com/aphyt/omron_fins/blob/master/examples/example_tcp_send_program.py): example · Example for sending PLC data over TCP. · `examples/example_tcp_send_program.py`
- [UDP get](https://github.com/aphyt/omron_fins/blob/master/examples/example_udp_get_program.py): example · Example for retrieving PLC data over UDP. · `examples/example_udp_get_program.py`
- [UDP send](https://github.com/aphyt/omron_fins/blob/master/examples/example_udp_send_program.py): example · Example for sending PLC data over UDP. · `examples/example_udp_send_program.py`
- [README](https://github.com/aphyt/omron_fins/blob/master/README.md): project guide · Top-level overview of supported transports and usage. · `README.md`
- [Docs](https://github.com/aphyt/omron_fins/blob/master/docs/README.md): project docs · Standalone documentation for the library. · `docs/README.md`

### External endpoint

The PLC and network path the library communicates with.

- **Client app**: caller · User code that creates a connection and issues FINS operations.
- **Omron PLC**: device · External PLC endpoint speaking FINS over TCP, UDP, or USB.

## Connections

- Client app → fins package: imports · Client code uses the public package surface.
- fins package → Common core: shared logic · Public connection classes rely on the common FINS core.
- fins package → TCP transport: TCP class · Package exposes the TCP connection implementation.
- fins package → UDP transport: UDP class · Package exposes the UDP connection implementation.
- fins package → USB transport: USB class · Package exposes the USB connection implementation.
- TCP transport → Common core: frames · TCP transport uses shared frame assembly and parsing.
- UDP transport → Common core: frames · UDP transport uses shared frame assembly and parsing.
- USB transport → Common core: frames · USB transport uses shared frame assembly and parsing.
- TCP transport → Omron PLC: FINS/TCP · TCP transport sends requests to the PLC and receives responses.
- UDP transport → Omron PLC: FINS/UDP · UDP transport sends requests to the PLC and receives responses.
- USB transport → Omron PLC: USB link · USB transport communicates with the PLC over a driver-backed device path.
- Client app → Examples: learns from · Examples show the minimal connection lifecycle and API usage.
- Examples → TCP get: contains · TCP retrieval example.
- Examples → TCP send: contains · TCP send example.
- Examples → UDP get: contains · UDP retrieval example.
- Examples → UDP send: contains · UDP send example.
- README → fins package: documents · README describes the package entry points and usage model.
- Docs → fins package: documents · Docs explain the library for embedded use.
- Packaging → fins package: packages · setup.py distributes the fins package.
- Client app → Omron PLC: reads/writes · Application-level operations ultimately target the PLC.
