# pyhoff.modbus.SimpleModbusClient — pyhoff documentation

Skip to main content
`Ctrl`+`K`

# pyhoff.modbus.SimpleModbusClient

class pyhoff.modbus.SimpleModbusClient(host, port=502, unit_id=1, timeout=5, debug=False)

  Bases: `object`

  A simple Modbus TCP client

  host

    hostname or IP address

    Type:

      str

  port

    server port

    Type:

      int

  unit_id

    ModBus id

    Type:

      int

  timeout

    socket timeout in seconds

    Type:

      float

  last_error

    contains last error message or empty string if no error occurred

    Type:

      str

  debug

    if True prints out transmitted and received bytes in hex

    Type:

      bool

  Instantiate a Modbus TCP client

  Parameters:

    - host (`str`) – hostname or IP address

    - port (`int`) – server port

    - unit_id (`int`) – ModBus id

    - timeout (`float`) – socket timeout in seconds

    - debug (`bool`) – if True prints out transmitted and received bytes in hex

  Example

      >>> client = SimpleModbusClient('localhost', port = 502, unit_id = 1)
      >>> print(client.read_coils(0, 10))
      >>> print(client.read_discrete_inputs(0, 10))
      >>> print(client.read_holding_registers(0, 10))
      >>> print(client.read_input_registers(0, 10))
      >>> print(client.write_single_coil(0, True))
      >>> print(client.write_single_register(0, 1234))
      >>> print(client.write_multiple_coils(0, [True, False, True]))
      >>> print(client.write_multiple_registers(0, [1234, 5678]))
      >>> client.close()

  close()

    Close connection

    Return type:

      `bytes`

    Returns:

      empty bytes object

  connect()

    Connect manual to the configured modbus server. Usually there is no need to call this function since it is handled automatically.

    Return type:

      `bool`

  read_coil(address)

    Read a coil from the given register address.

    Parameters:

      address (`int`) – The register address to read from.

    Return type:

      `bool` | `None`

    Returns:

      The value of the coil or None if error

  read_coils(bit_address, bit_lengths=1)

    ModBus function for reading coils (0x01)

    Parameters:

      - bit_address (`int`) – Bit address (0 to 0xffff)

      - bit_lengths (`int`) – Number of bits to read (1 to 2000)

    Returns:

      Bits list or None if error

    Return type:

      list of bool or None

  read_discrete_input(address)

    Read a discrete input from the given register address.

    Parameters:

      address (`int`) – The register address to read from.

    Return type:

      `bool` | `None`

    Returns:

      The value of the discrete input.

  read_discrete_inputs(bit_address, bit_lengths=1)

    ModBus function for reading discrete inputs (0x02)

    Parameters:

      - bit_address (`int`) – Bit address (0 to 0xffff)

      - bit_lengths (`int`) – Number of bits to read (1 to 2000)

    Returns:

      Bits list or None if error

    Return type:

      list of bool or None

  read_holding_registers(register_address, word_lengths=1)

    ModBus function for reading holding registers (0x03)

    Parameters:

      - register_address (`int`) – Register address (0 to 0xffff)

      - word_lengths (`int`) – Number of registers to read (1 to 125)

    Returns:

      Registers list or None if error

    Return type:

      list of int or None

  read_input_registers(register_address, word_lengths=1)

    ModBus function for reading input registers (0x04)

    Parameters:

      - register_address (`int`) – Register address (0 to 0xffff)

      - word_lengths (`int`) – Number of registers to read (1 to 125)

    Returns:

      Registers list or None if error

    Return type:

      list of int or None

  receive_modbus_data()

    Receive a ModBus frame

    Return type:

      `bytes`

    Returns:

      bytes received or empty bytes object if an error occurred

  send_modbus_data(function_code, body)

    Send raw ModBus TCP frame

    Parameters:

      - unction_code – ModBus function code

      - body (`bytes`) – data

    Return type:

      `int`

    Returns:

      number of transmitted bytes or 0 if transmission failed

  write_multiple_coils(bit_address, values)

    ModBus function for writing multiple coils (0x0F)

    Parameters:

      - bit_address (`int`) – Bit address (0 to 0xffff)

      - values (`list`[`bool`]) – List of bit values to write

    Return type:

      `bool`

    Returns:

      True if write succeeded or False if failed

  write_multiple_registers(register_address, values)

    ModBus function for writing multiple registers (0x10)

    Parameters:

      - register_address (`int`) – Register address (0 to 0xffff)

      - values (`list`[`int`]) – List of 16 bit register values to write

    Return type:

      `bool`

    Returns:

      True if write succeeded or False if failed

  write_single_coil(bit_address, value)

    ModBus function for writing a single coil (0x05)

    Parameters:

      - bit_address (`int`) – Bit address (0 to 0xffff)

      - value (`bool`) – Value to write (single bit)

    Return type:

      `bool`

    Returns:

      True if write succeeded or False if failed

  write_single_register(register_address, value)

    ModBus function for writing a single register (0x06)

    Parameters:

      - register_address (`int`) – Register address (0 to 0xffff)

      - value (`int`) – Value to write (0 to 0xffff)

    Return type:

      `bool`

    Returns:

      True if write succeeded or False if failed