# `interfaces` — System Interfaces

## API Documentation

### Pymodbus Interfaces

A collection of base classes that are used throughout the pymodbus library.

class `pymodbus.interfaces.``Singleton`

  Singleton base class http://mail.python.org/pipermail/python-list/2007-July/450681.html

  static `__new__`(*args, **kwargs)

    Create a new instance

class `pymodbus.interfaces.``IModbusDecoder`

  Modbus Decoder Base Class

  This interface must be implemented by a modbus message decoder factory. These factories are responsible for abstracting away converting a raw packet into a request / response message object.

  `decode`(message)

    Wrapper to decode a given packet

    Parameters: | message – The raw modbus request packet
    Returns: | The decoded modbus message or None if error

  `lookupPduClass`(function_code)

    Use function_code to determine the class of the PDU.

    Parameters: | function_code – The function code specified in a frame.
    Returns: | The class of the PDU that has a matching function_code.

class `pymodbus.interfaces.``IModbusFramer`

  A framer strategy interface. The idea is that we abstract away all the detail about how to detect if a current message frame exists, decoding it, sending it, etc so that we can plug in a new Framer object (tcp, rtu, ascii).

  `checkFrame`()

    Check and decode the next frame

    Returns: | True if we successful, False otherwise

  `advanceFrame`()

    Skip over the current framed message This allows us to skip over the current message after we have processed it or determined that it contains an error. It also has to reset the current frame header handle

  `addToFrame`(message)

    Add the next message to the frame buffer

    This should be used before the decoding while loop to add the received data to the buffer handle.

    Parameters: | message – The most recent packet

  `isFrameReady`()

    Check if we should continue decode logic

    This is meant to be used in a while loop in the decoding phase to let the decoder know that there is still data in the buffer.

    Returns: | True if ready, False otherwise

  `getFrame`()

    Get the next frame from the buffer

    Returns: | The frame data or ‘’

  `populateResult`(result)

    Populates the modbus result with current frame header

    We basically copy the data back over from the current header to the result header. This may not be needed for serial messages.

    Parameters: | result – The response packet

  `processIncomingPacket`(data, callback)

    The new packet processing pattern

    This takes in a new request packet, adds it to the current packet stream, and performs framing on it. That is, checks for complete messages, and once found, will process all that exist. This handles the case when we read N + 1 or 1 / N messages at a time instead of 1.

    The processed and decoded messages are pushed to the callback function to process and send.

    Parameters:

    - data – The new packet data
    - callback – The function to send results to

  `buildPacket`(message)

    Creates a ready to send modbus packet

    The raw packet is built off of a fully populated modbus request / response message.

    Parameters: | message – The request/response to send
    Returns: | The built packet

class `pymodbus.interfaces.``IModbusSlaveContext`

  Interface for a modbus slave data context

  Derived classes must implemented the following methods:
    reset(self) validate(self, fx, address, count=1) getValues(self, fx, address, count=1) setValues(self, fx, address, values)
  `decode`(fx)

    Converts the function code to the datastore to

    Parameters: | fx – The function we are working with
    Returns: | one of [d(iscretes),i(inputs),h(oliding),c(oils)

  `reset`()

    Resets all the datastores to their default values

  `validate`(fx, address, count=1)

    Validates the request to make sure it is in range

    Parameters:

    - fx – The function we are working with
    - address – The starting address
    - count – The number of values to test

    Returns: | True if the request in within range, False otherwise

  `getValues`(fx, address, count=1)

    Validates the request to make sure it is in range

    Parameters:

    - fx – The function we are working with
    - address – The starting address
    - count – The number of values to retrieve

    Returns: | The requested values from a:a+c

  `setValues`(fx, address, values)

    Sets the datastore with the supplied values

    Parameters:

    - fx – The function we are working with
    - address – The starting address
    - values – The new values to be set

class `pymodbus.interfaces.``IPayloadBuilder`

  This is an interface to a class that can build a payload for a modbus register write command. It should abstract the codec for encoding data to the required format (bcd, binary, char, etc).

  `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