How aphyt/omron_fins works
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: __init__.py fins package · README.md Examples · fins_common.py Common core · tcp.py TCP transport
Components 15
Public package
Import and session boundary exposed to client code.
- fins package · Package boundary for imports and connection classes.
fins/__init__.py - Packaging · Python packaging and distribution entry point.
setup.py
Protocol core
Shared FINS framing, parsing, and PLC addressing logic.
- Common 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 · FINS over TCP connection implementation.
fins/tcp.py - UDP transport · FINS over UDP connection implementation.
fins/udp.py - USB transport · USB-based FINS communication path.
fins/usb.py
Usage artifacts
Repository documentation and runnable examples.
- Examples · Repository examples showing transport-specific send/get flows.
examples/README.md - TCP get · Example for retrieving PLC data over TCP.
examples/example_tcp_get_program.py - TCP send · Example for sending PLC data over TCP.
examples/example_tcp_send_program.py - UDP get · Example for retrieving PLC data over UDP.
examples/example_udp_get_program.py - UDP send · Example for sending PLC data over UDP.
examples/example_udp_send_program.py - README · Top-level overview of supported transports and usage.
README.md - Docs · Standalone documentation for the library.
docs/README.md
External endpoint
The PLC and network path the library communicates with.
- Client app · User code that creates a connection and issues FINS operations.
- Omron PLC · External PLC endpoint speaking FINS over TCP, UDP, or USB.
Connections 20
- 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.