# `payload` — Modbus Payload Utilities

## API Documentation

### Modbus Payload Builders

A collection of utilities for building and decoding modbus messages payloads.

class `pymodbus.payload.``BinaryPayloadBuilder`(payload=None, endian='<')

  A utility that helps build payload messages to be written with the various modbus messages. It really is just a simple wrapper around the struct module, however it saves time looking up the format strings. What follows is a simple example:

      builder = BinaryPayloadBuilder(endian=Endian.Little)
      builder.add_8bit_uint(1)
      builder.add_16bit_uint(2)
      payload = builder.build()

  `__init__`(payload=None, endian='<')

    Initialize a new instance of the payload builder

    Parameters:

    - payload – Raw binary payload data to initialize with
    - endian – The endianess of the payload

  `to_string`()

    Return the payload buffer as a string

    Returns: | The payload buffer as a string

  `__str__`()

    Return the payload buffer as a string

    Returns: | The payload buffer as a string

  `reset`()

    Reset the payload buffer

  `to_registers`()

    Convert the payload buffer into a register layout that can be used as a context block.

    Returns: | The register layout to use as a block

  `build`()

    Return the payload buffer as a list

    This list is two bytes per element and can thus be treated as a list of registers.

    Returns: | The payload buffer as a list

  `add_bits`(values)

    Adds a collection of bits to be encoded

    If these are less than a multiple of eight, they will be left padded with 0 bits to make it so.

    Parameters: | value – The value to add to the buffer

  `add_8bit_uint`(value)

    Adds a 8 bit unsigned int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_16bit_uint`(value)

    Adds a 16 bit unsigned int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_32bit_uint`(value)

    Adds a 32 bit unsigned int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_64bit_uint`(value)

    Adds a 64 bit unsigned int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_8bit_int`(value)

    Adds a 8 bit signed int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_16bit_int`(value)

    Adds a 16 bit signed int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_32bit_int`(value)

    Adds a 32 bit signed int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_64bit_int`(value)

    Adds a 64 bit signed int to the buffer

    Parameters: | value – The value to add to the buffer

  `add_32bit_float`(value)

    Adds a 32 bit float to the buffer

    Parameters: | value – The value to add to the buffer

  `add_64bit_float`(value)

    Adds a 64 bit float(double) to the buffer

    Parameters: | value – The value to add to the buffer

  `add_string`(value)

    Adds a string to the buffer

    Parameters: | value – The value to add to the buffer

class `pymodbus.payload.``BinaryPayloadDecoder`(payload, endian='<')

  A utility that helps decode payload messages from a modbus reponse message. It really is just a simple wrapper around the struct module, however it saves time looking up the format strings. What follows is a simple example:

      decoder = BinaryPayloadDecoder(payload)
      first   = decoder.decode_8bit_uint()
      second  = decoder.decode_16bit_uint()

  `__init__`(payload, endian='<')

    Initialize a new payload decoder

    Parameters:

    - payload – The payload to decode with
    - endian – The endianess of the payload

  classmethod `fromRegisters`(registers, endian='<')

    Initialize a payload decoder with the result of reading a collection of registers from a modbus device.

    The registers are treated as a list of 2 byte values. We have to do this because of how the data has already been decoded by the rest of the library.

    Parameters:

    - registers – The register results to initialize with
    - endian – The endianess of the payload

    Returns: | An initialized PayloadDecoder

  classmethod `fromCoils`(coils, endian='<')

    Initialize a payload decoder with the result of reading a collection of coils from a modbus device.

    The coils are treated as a list of bit(boolean) values.

    Parameters:

    - coils – The coil results to initialize with
    - endian – The endianess of the payload

    Returns: | An initialized PayloadDecoder

  `reset`()

    Reset the decoder pointer back to the start

  `decode_8bit_uint`()

    Decodes a 8 bit unsigned int from the buffer

  `decode_bits`()

    Decodes a byte worth of bits from the buffer

  `decode_16bit_uint`()

    Decodes a 16 bit unsigned int from the buffer

  `decode_32bit_uint`()

    Decodes a 32 bit unsigned int from the buffer

  `decode_64bit_uint`()

    Decodes a 64 bit unsigned int from the buffer

  `decode_8bit_int`()

    Decodes a 8 bit signed int from the buffer

  `decode_16bit_int`()

    Decodes a 16 bit signed int from the buffer

  `decode_32bit_int`()

    Decodes a 32 bit signed int from the buffer

  `decode_64bit_int`()

    Decodes a 64 bit signed int from the buffer

  `decode_32bit_float`()

    Decodes a 32 bit float from the buffer

  `decode_64bit_float`()

    Decodes a 64 bit float(double) from the buffer

  `decode_string`(size=1)

    Decodes a string from the buffer

    Parameters: | size – The size of the string to decode

  `skip_bytes`(nbytes)

    Skip n bytes in the buffer

    Parameters: | nbytes – The number of bytes to skip