Quick Start

This guide will help you get started with ModbusLink quickly.

Basic Concepts

ModbusLink follows a layered architecture:

  • Transport Layer: Handles the low-level communication (RTU, TCP)

  • Client Layer: Provides high-level Modbus operations

  • Utility Layer: Contains helper functions and data converters

Synchronous Operations

TCP Connection

from modbuslink import ModbusClient, TcpTransport

# Create TCP transport
transport = TcpTransport(
    host='192.168.1.100',
    port=502,
    timeout=10.0
)

# Create client
client = ModbusClient(transport)

try:
    # Connect to the device
    client.connect()

    # Read 10 holding registers starting from address 0
    registers = client.read_holding_registers(
        slave_id=1,
        start_address=0,
        quantity=10
    )
    print(f"Holding registers: {registers}")

    # Write a single register
    client.write_single_register(
        slave_id=1,
        address=0,
        value=1234
    )

    # Write multiple registers
    client.write_multiple_registers(
        slave_id=1,
        start_address=10,
        values=[100, 200, 300, 400]
    )

except Exception as e:
    print(f"Error: {e}")
finally:
    client.disconnect()

RTU Connection

from modbuslink import ModbusClient, RtuTransport

# Create RTU transport
transport = RtuTransport(
    port='COM1',  # or '/dev/ttyUSB0' on Linux
    baudrate=9600,
    bytesize=8,
    parity='N',
    stopbits=1,
    timeout=1.0
)

# Create client
client = ModbusClient(transport)

try:
    # Connect to the device
    client.connect()

    # Read coils
    coils = client.read_coils(
        slave_id=1,
        start_address=0,
        quantity=8
    )
    print(f"Coils: {coils}")

    # Write a single coil
    client.write_single_coil(
        slave_id=1,
        address=0,
        value=True
    )

except Exception as e:
    print(f"Error: {e}")
finally:
    client.disconnect()

ASCII Connection

For Modbus ASCII communication over serial:

from modbuslink import ModbusClient, AsciiTransport

# Create ASCII transport
transport = AsciiTransport(
    port='COM1',
    baudrate=9600,
    bytesize=7,
    parity='E',
    stopbits=1,
    timeout=1.0
)

# Create client
client = ModbusClient(transport)

try:
    # Connect to the device
    client.connect()

    # Read holding registers
    registers = client.read_holding_registers(
        slave_id=1,
        start_address=0,
        quantity=4
    )
    print(f"Registers: {registers}")

    # Write a single register
    client.write_single_register(
        slave_id=1,
        address=0,
        value=1234
    )

except Exception as e:
    print(f"Error: {e}")
finally:
    client.disconnect()

Asynchronous Operations

ModbusLink supports async/await for high-performance applications:

from modbuslink import AsyncModbusClient, AsyncTcpTransport
import asyncio

async def main():
    # Create async TCP transport
    transport = AsyncTcpTransport(
        host='192.168.1.100',
        port=502,
        timeout=10.0
    )

    # Create async client
    client = AsyncModbusClient(transport)

    async with client:
        # Read holding registers
        registers = await client.read_holding_registers(
            slave_id=1,
            start_address=0,
            quantity=10
        )
        print(f"Registers: {registers}")

        # Write multiple registers concurrently
        tasks = [
            client.write_single_register(slave_id=1, address=i, value=i*10)
            for i in range(5)
        ]
        await asyncio.gather(*tasks)

# Run the async function
asyncio.run(main())

Advanced Data Types

ModbusLink provides built-in support for advanced data types:

from modbuslink import ModbusClient, TcpTransport

transport = TcpTransport(host='192.168.1.100', port=502)
client = ModbusClient(transport)

try:
    client.connect()

    # Read/write 32-bit float
    client.write_float32(slave_id=1, start_address=100, value=3.14159)
    temperature = client.read_float32(slave_id=1, start_address=100)
    print(f"Temperature: {temperature}°C")

    # Read/write 32-bit integer
    client.write_int32(slave_id=1, start_address=102, value=-123456)
    counter = client.read_int32(slave_id=1, start_address=102)
    print(f"Counter: {counter}")

finally:
    client.disconnect()

Error Handling

ModbusLink provides comprehensive error handling mechanisms:

from modbuslink import ModbusClient, TcpTransport
from modbuslink.common.exceptions import (
    ConnectionError, TimeoutError, CRCError,
    InvalidResponseError, ModbusException
)

transport = TcpTransport(host='192.168.1.100', port=502)
client = ModbusClient(transport)

try:
    client.connect()
    registers = client.read_holding_registers(
        slave_id=1, start_address=0, quantity=10
    )
    print(f"Registers: {registers}")

except ConnectionError as e:
    print(f"Connection failed: {e}")
except TimeoutError as e:
    print(f"Request timed out: {e}")
except CRCError as e:
    print(f"CRC validation failed: {e}")
except ModbusException as e:
    print(f"Modbus protocol error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
finally:
    client.disconnect()

Next Steps

Now that you understand the basics of ModbusLink, you can: