Source code for pyModbusTCP.server.functions

""" pyModbusTCP server: the Modbus functions, as handlers of a registry.

A function handler takes a Request and returns the response PDU (bytes, the function code first). It raises a
ModbusException (like IllegalDataAddress) for an exception response. The server routes each request to the handler
of its function code (ModbusServer.functions), or to its fallback for the other codes::

    @server.function(0x41)
    def my_function(req: Request) -> bytes:
        (address,) = req.unpack('>H', 1, 3)
        with req.transaction() as tx:
            value = tx.read(Space.HOLDING_REGISTERS, address)[0]
        return req.reply('>H', value)

Every standard function runs in one transaction of the store: it's atomic (like the write then the read of 0x17).
"""

from __future__ import annotations

import struct
from collections.abc import Callable
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any

from ..constants import (
    ENCAPSULATED_INTERFACE_TRANSPORT,
    MAX_PDU_SIZE,
    MEI_TYPE_READ_DEVICE_ID,
    READ_COILS,
    READ_DISCRETE_INPUTS,
    READ_HOLDING_REGISTERS,
    READ_INPUT_REGISTERS,
    WRITE_MULTIPLE_COILS,
    WRITE_MULTIPLE_REGISTERS,
    WRITE_READ_MULTIPLE_REGISTERS,
    WRITE_SINGLE_COIL,
    WRITE_SINGLE_REGISTER,
)
from ..utils import _pack_bits, _unpack_bits
from .errors import (
    DataFormatError,
    IllegalDataAddress,
    IllegalDataValue,
    PDUDecodeError,
)
from .store import DataStore, RequestContext, Space, Transaction

if TYPE_CHECKING:
    from contextlib import AbstractContextManager

    from .device_id import DeviceIdentification


[docs] @dataclass class Request: """A request given to a function handler.""" # the request PDU (function code first) pdu: bytes # where the request comes from (client, unit id, function code) ctx: RequestContext # the data store of the unit id of the request store: DataStore # the device identification of the server (function 0x2B/0x0E), if any device_id: DeviceIdentification | None = None @property def function_code(self) -> int: """The function code of the request (the first byte of the PDU).""" return self.pdu[0]
[docs] def unpack(self, fmt: str, from_byte: int | None = None, to_byte: int | None = None) -> tuple[Any, ...]: """Decode a part of the PDU with struct. :param fmt: struct format; its byte order prefix is used as is ('<' for little endian data...), a format without prefix is big endian (the byte order of Modbus), not the native order of struct :raises PDUDecodeError: if this part is too short (the client gets an "illegal data value" exception) """ fmt = _with_byte_order(fmt) raw_section = self.pdu[from_byte:to_byte] try: return struct.unpack(fmt, raw_section) except struct.error: raise PDUDecodeError(f"unable to decode PDU (fmt: '{fmt}', values: {raw_section!r})") from None
[docs] def reply(self, fmt: str = '', *args: Any) -> bytes: """Build a response PDU: the function code of the request, then args packed with struct. :param fmt: struct format of the fields after the function code; its byte order prefix is used as is ('<' for little endian data...), a format without prefix is big endian (the byte order of Modbus), not the native order of struct :raises DataFormatError: if a value doesn't fit its field (the client gets a "slave device failure") """ fmt = _with_byte_order(fmt) try: return bytes([self.function_code]) + struct.pack(fmt, *args) except struct.error as e: raise DataFormatError(f'unable to build the response PDU (fmt: {fmt}, values: {args}): {e}') from None
[docs] def transaction(self) -> AbstractContextManager[Transaction]: """A transaction of the store, with the context of this request.""" return self.store.transaction(self.ctx)
def _with_byte_order(fmt: str) -> str: """A struct format with a byte order: its own prefix if any ('<', '>', '!', '=', '@'), else big endian ('>', the byte order of Modbus) instead of the native order of struct.""" return fmt if fmt[:1] in ('<', '>', '!', '=', '@') else '>' + fmt # a function handler: returns the response PDU, raises a ModbusException for an exception response FunctionHandler = Callable[[Request], bytes] def _check_size(req: Request, size: int) -> None: """A request of a standard function has exactly the size of its fields (function code included). A missing byte, or a byte after the fields, is an "illegal data value" (03), never executed: a request with bytes after its data is not the request of the client (a bug, a frame cut or merged by a gateway, the remains of another request), and a gateway that relays it to a serial line would write them in the same RTU frame (a hidden request for a slave that ends a frame by its size, see mbtcp-tcp2rtu). :raises IllegalDataValue: if the PDU is not exactly size bytes """ if len(req.pdu) != size: raise IllegalDataValue() def read_bits(req: Request) -> bytes: """Functions Read Coils (0x01) and Read Discrete Inputs (0x02).""" _check_size(req, 5) (address, quantity) = req.unpack('>HH', 1, 5) if not 0x0001 <= quantity <= 0x07D0: raise IllegalDataValue() space = Space.COILS if req.function_code == READ_COILS else Space.DISCRETE_INPUTS with req.transaction() as tx: bits = tx.read(space, address, quantity) data = _pack_bits(bits) return req.reply(f'>B{len(data)}s', len(data), data) def read_words(req: Request) -> bytes: """Functions Read Holding Registers (0x03) and Read Input Registers (0x04).""" _check_size(req, 5) (address, quantity) = req.unpack('>HH', 1, 5) if not 0x0001 <= quantity <= 0x007D: raise IllegalDataValue() space = Space.HOLDING_REGISTERS if req.function_code == READ_HOLDING_REGISTERS else Space.INPUT_REGISTERS with req.transaction() as tx: words = tx.read(space, address, quantity) return req.reply(f'>B{quantity}H', quantity * 2, *words) def write_single_coil(req: Request) -> bytes: """Function Write Single Coil (0x05).""" _check_size(req, 5) (address, value) = req.unpack('>HH', 1, 5) if value not in (0x0000, 0xFF00): raise IllegalDataValue() with req.transaction() as tx: tx.write(Space.COILS, address, [value == 0xFF00]) return req.reply('>HH', address, value) def write_single_register(req: Request) -> bytes: """Function Write Single Register (0x06).""" _check_size(req, 5) (address, value) = req.unpack('>HH', 1, 5) with req.transaction() as tx: tx.write(Space.HOLDING_REGISTERS, address, [value]) return req.reply('>HH', address, value) def write_multiple_coils(req: Request) -> bytes: """Function Write Multiple Coils (0x0F).""" (address, quantity, byte_count) = req.unpack('>HHB', 1, 6) # byte count must match the quantity, the data must be complete, no byte after them (see _check_size()) if not (0x0001 <= quantity <= 0x07B0 and byte_count == (quantity + 7) // 8 and len(req.pdu) == 6 + byte_count): raise IllegalDataValue() bits = _unpack_bits(req.pdu[6:6 + byte_count], quantity) with req.transaction() as tx: tx.write(Space.COILS, address, bits) return req.reply('>HH', address, quantity) def write_multiple_registers(req: Request) -> bytes: """Function Write Multiple Registers (0x10).""" (address, quantity, byte_count) = req.unpack('>HHB', 1, 6) if not (0x0001 <= quantity <= 0x007B and byte_count == quantity * 2 and len(req.pdu) == 6 + byte_count): raise IllegalDataValue() words = list(req.unpack(f'>{quantity}H', 6, 6 + byte_count)) with req.transaction() as tx: tx.write(Space.HOLDING_REGISTERS, address, words) return req.reply('>HH', address, quantity) def write_read_multiple_registers(req: Request) -> bytes: """Function Write Read Multiple Registers (0x17). The write is done before the read, in one transaction: no other access can occur between them, and if the read fails (like an invalid address), the write is cancelled. """ (read_address, read_quantity, write_address, write_quantity, byte_count) = req.unpack('>HHHHB', 1, 10) if not (0x0001 <= write_quantity <= 0x0079 and byte_count == write_quantity * 2 and len(req.pdu) == 10 + byte_count and 0x0001 <= read_quantity <= 0x007D): raise IllegalDataValue() words = list(req.unpack(f'>{write_quantity}H', 10, 10 + byte_count)) with req.transaction() as tx: tx.write(Space.HOLDING_REGISTERS, write_address, words) read_words_l = tx.read(Space.HOLDING_REGISTERS, read_address, read_quantity) return req.reply(f'>B{read_quantity}H', read_quantity * 2, *read_words_l) # read device identification, stream access: ReadDevId code -> (first, last) object id of its category _DEVICE_ID_STREAM_RANGES = {1: (0x00, 0x02), 2: (0x03, 0x7f), 3: (0x80, 0xff)} def encapsulated_interface_transport(req: Request) -> bytes: """Modbus Encapsulated Interface transport (0x2B): only the read device identification (MEI type 0x0E).""" (mei_type,) = req.unpack('B', 1, 2) if mei_type != MEI_TYPE_READ_DEVICE_ID: raise IllegalDataAddress() _check_size(req, 4) (device_id_code, object_id) = req.unpack('BB', 2, 4) if device_id_code not in (1, 2, 3, 4): raise IllegalDataValue() device_id = req.device_id if device_id is None: raise IllegalDataAddress() if device_id_code == 4: # individual access: an unknown object is an illegal data address if object_id not in device_id: raise IllegalDataAddress() objects = device_id.items(start=object_id, end=object_id) else: # stream access: basic (code 1), regular (code 2) or extended (code 3) objects first_id, last_id = _DEVICE_ID_STREAM_RANGES[device_id_code] # an object id that is not a known object of the category: restart at its first object (as the spec # requires for object 0) if not (first_id <= object_id <= last_id and object_id in device_id): object_id = first_id objects = device_id.items(start=object_id, end=last_id) conformity_level = device_id.conformity_level more_follows = 0 next_object_id = 0 head_size = 7 data = b'' number_of_objs = 0 for obj_id, obj_value in objects: block = struct.pack(f'BB{len(obj_value)}s', obj_id, len(obj_value), obj_value) # stop before an object that would exceed the max PDU size: the client asks the next one if head_size + len(data) + len(block) > MAX_PDU_SIZE: more_follows = 0xff next_object_id = obj_id break data += block number_of_objs += 1 return req.reply('>BBBBBB', mei_type, device_id_code, conformity_level, more_follows, next_object_id, number_of_objs) + data # the standard functions of the server (a copy is the default of ModbusServer.functions) STANDARD_FUNCTIONS: dict[int, FunctionHandler] = { READ_COILS: read_bits, READ_DISCRETE_INPUTS: read_bits, READ_HOLDING_REGISTERS: read_words, READ_INPUT_REGISTERS: read_words, WRITE_SINGLE_COIL: write_single_coil, WRITE_SINGLE_REGISTER: write_single_register, WRITE_MULTIPLE_COILS: write_multiple_coils, WRITE_MULTIPLE_REGISTERS: write_multiple_registers, WRITE_READ_MULTIPLE_REGISTERS: write_read_multiple_registers, ENCAPSULATED_INTERFACE_TRANSPORT: encapsulated_interface_transport, }