Integration new device using modbus tcp

Hi, someone can help me to realize an integration of a modbus device to read the energy meter?
Using modbus via configuration.yaml it’s very easy, but i need to integrate this for my company and must be an integration.
This is yaml file and it works very well:

  • name: device
    type: tcp
    port: 502
  • name: Potenza Attiva Prelevata Istantanea
    device_class: power
    unit_of_measurement: W
    state_class: measurement
    data_type: uint16
    address: 2
    count: 1

But how can i convert it in an integration?
How can i create in my platform that do the same thing?
Can I use modbus function stored in HA?
Someone can help me with an example?
I’m ready with developer ambient


#!/usr/bin/env python
Pymodbus Synchronous Client Examples

The following is an example of how to use the synchronous modbus client
implementation from pymodbus.

It should be noted that the client can also be used with
the guard construct that is available in python 2.5 and up::

    with ModbusClient('') as client:
        result = client.read_coils(1,10)
        print result
# --------------------------------------------------------------------------- #
# import the various client implementations
# --------------------------------------------------------------------------- #
from pymodbus.client.sync import ModbusTcpClient as ModbusClient
# from pymodbus.client.sync import ModbusUdpClient as ModbusClient
# from pymodbus.client.sync import ModbusSerialClient as ModbusClient

# --------------------------------------------------------------------------- #
# configure the client logging
# --------------------------------------------------------------------------- #
import logging
FORMAT = ('%(asctime)-15s %(threadName)-15s '
          '%(levelname)-8s %(module)-15s:%(lineno)-8s %(message)s')
log = logging.getLogger()

UNIT = 0x1

def run_sync_client():
    # ------------------------------------------------------------------------#
    # choose the client you want
    # ------------------------------------------------------------------------#
    # make sure to start an implementation to hit against. For this
    # you can use an existing device, the reference implementation in the tools
    # directory, or start a pymodbus server.
    # If you use the UDP or TCP clients, you can override the framer being used
    # to use a custom implementation (say RTU over TCP). By default they use
    # the socket framer::
    #    client = ModbusClient('localhost', port=5020, framer=ModbusRtuFramer)
    # It should be noted that you can supply an ipv4 or an ipv6 host address
    # for both the UDP and TCP clients.
    # There are also other options that can be set on the client that controls
    # how transactions are performed. The current ones are:
    # * retries - Specify how many retries to allow per transaction (default=3)
    # * retry_on_empty - Is an empty response a retry (default = False)
    # * source_address - Specifies the TCP source address to bind to
    # * strict - Applicable only for Modbus RTU clients.
    #            Adheres to modbus protocol for timing restrictions
    #            (default = True).
    #            Setting this to False would disable the inter char timeout
    #            restriction (t1.5) for Modbus RTU
    # Here is an example of using these options::
    #    client = ModbusClient('localhost', retries=3, retry_on_empty=True)
    # ------------------------------------------------------------------------#
    client = ModbusClient('', port=502)
    # from pymodbus.transaction import ModbusRtuFramer
    # client = ModbusClient('localhost', port=5020, framer=ModbusRtuFramer)
    # client = ModbusClient(method='binary', port='/dev/ptyp0', timeout=1)
    # client = ModbusClient(method='ascii', port='/dev/ptyp0', timeout=1)
    # client = ModbusClient(method='rtu', port='/dev/ptyp0', timeout=1,
    #                       baudrate=9600)

    log.debug("Read input registers")
    rr = client.read_input_registers(2, 1, unit=UNIT)
    assert(not rr.isError())     # test that we are not an error

    # ----------------------------------------------------------------------- #
    # close the client
    # ----------------------------------------------------------------------- #

if __name__ == "__main__":

Hi @nikito7 ,
i have the same problem of @warrenriccio, i try to explain what is my problem… When i try to use an external library the client told me that can’t find the module. how i can fix this issue?

Thanks so much

Thank you my friend.
Like Marco, now and ever, I have this problem (with every python library)
Traceback (most recent call last):
File “/config/custom_components/example_sensor/”, line 1, in
from pymodbus.client.sync import ModbusTcpClient as ModbusClient
ModuleNotFoundError: No module named ‘pymodbus’ ’

Maybe the error can be in manifest?

Thanks in advance


  "requirements": ["pymodbus==2.5.3"],

If outside HA, pip install pymodbus

Hi, You think it works if i’m testing this solution via config custom ?
In developer ambient it’s not working, it seems like if it didn’t download anything. The module is never present.
I don’t know if you have some other suggest for me, but you are very kindle.



If you installed outside virtualenv, you need install again

I programmed in different ways but no way to work…
Maybe i’m not be able to do this. The main problem is that i can’t use any python library not present in HA. And i can’t understand why i can’t integrate a new device using a configuration file in device domain. It would be easy for all in this case.
I thought it was simpler, like programming in python.
I am discouraged, but thanks for your time: you were the only one who tried to help me…

HA is more hard that a simple .py

You need know how HA works

Maybe using a dumb modbus: yaml install it for you

Anyway check github modbus from HA

You want something with a Logo without any user configuration

Just click

Something like this, I think

Yes, but like you see, this modbusTCP it’s in a custom component , it’s not builted in HA.
And have functions to decode data (not need this)
My company has made a device that will be installed in many home to receive data from fiscal meter.
And it will be possible to get data from this device via modbus TCP. The configuration.yaml is like this:

  • name: DeviceTCP

    type: tcp


    port: 502


    - name: Potenza Attiva Prelevata Istantanea
      device_class: power
      unit_of_measurement: W
      state_class: measurement
      data_type: uint16
      address: 2
      count: 1

(and more sensors)

And i have created a new sensor (calculated from other DeviceTCP sensor, for power break advise):

  • platform: template



    friendly_name: "Avviso distacco"
    value_template: >
      {% if (states('sensor.data_evento') | int ) > 4294967294 %} Nessun avviso
      {% else %} {{ (states('sensor.data_evento') | int + (states('sensor.tempo_residuo_distacco') | int))  | timestamp_local }}
      {% endif %}

And it works like a charm. :smiley:
I wanted only avoid to our customers to modify the configuration file, finding automatically the deviceTCP on the network (via hostname or mac address) with the sensors in.
A builted integration in the end…

From the devices integration builted in HA i haven’t found anything, only example for custom component folder. So i thought it’s not possible to do this, but it’s possible to integrate a new device only via api.
Like you see, i have many doubts :laughing:

I use packages or !include

Need user edit yaml anyway

You can do “something” to:

  • check if modbus exist in yaml
  • discovery ip
  • append new yaml
  • restart

Custom components need user intervention anyway.
If a user knows how to use custom components, will know edit yaml.

To be easy for client. Your “solution” need to be added to HA. And that may be hard…

Hi my friend, i have a last question for you: if i made a python script file that make a yaml file, included the ip address of this device (put it on from customer via input config). You think it could be an integration in HA?

Let me know what you think…


There is no easy way.

Just share yaml with clients

Clients will need to know how to edit configuration.yaml


  • external program, needs some access ssh etc
  • custom_component needs user be smart and above
  • hacs same
  • all options need user intervention

Add to HA official you can try. If someone aprove your PR…

some sort of “Meter X Easy Setup”

( ahaha I almost said same thing in last post :joy: )

ahahah, no way!!

Frank has rejected every code (code that worked in develop ambient via splitting yaml file :wink: )
For now i will write a guide for my customers to edit yaml file.
Many thanks for your help!