# Modbus TCP (Python 版本)

#### Func01 读取线圈量

* 方法说明

  Modbus 读取线圈量，功能码 01。

```python
def read_coil_status(ip: str, port: int, slave_id: int, offset: int) -> bool | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
* 输出参数
  * None: 读取失败
  * bool: 读取成功的返回值
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func02 读取线圈量

* 方法说明

  Modbus 读取线圈量，功能码 02。

```python
def read_input_status(ip: str, port: int, slave_id: int, offset: int) -> bool | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
* 输出参数
  * None: 读取失败
  * bool: 读取成功的返回值
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func03 读取保持寄存器

* 方法说明

  Modbus 读取保持寄存器，功能码 03。

```python
def read_holding_register(ip: str, port: int, slave_id: int, offset: int, data_type: int) -> int | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
  * data_type: int 类型，2：无符号整形，3：有符号整形
* 输出参数
  * None: 读取失败
  * int: 读取成功的返回值
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func04 读取输入寄存器

* 方法说明

  Modbus 读取只读输入寄存器，功能码 04。

```python
def read_input_register(ip: str, port: int, slave_id: int, offset: int, data_type: int) -> int | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
  * data_type: int 类型，2：无符号整形，3：有符号整形
* 输出参数
  * None: 读取失败
  * int: 读取成功的返回值
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func01 批量读取线圈量

* 方法说明

  Modbus 读取线圈量多个连续地址值，并以数组的形式返回其中的值，功能码 01。

```python
def batch_read_coil_status(ip: str, port: int, slave_id: int, offset: int, len: int) -> list[bool] | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 首地址
  * len: int 类型，Modbus 地址数量
* 输出参数
  * None: 读取失败
  * list[bool]: 读取成功后，返回结果数组
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func02 批量读取离散输入

* 方法说明

  Modbus 读取离散输入多个连续地址值，并以数组的形式返回其中的值，功能码 02。

```python
def batch_read_input_status(ip: str, port: int, slave_id: int, offset: int, len: int) -> list[bool] | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 首地址
  * len: int 类型，Modbus 地址数量
* 输出参数
  * None: 读取失败
  * list[bool]: 读取成功后，返回结果数组
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func03 批量读取保持寄存器

* 方法说明

  Modbus 读取保持寄存器多个连续地址值，并以数组的形式返回其中的值，功能码 03。

```python
def batch_read_holding_registers(ip: str, port: int, slave_id: int, offset: int, len: int) -> list[int] | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 首地址
  * len: int 类型，Modbus 地址数量
* 输出参数
  * None: 读取失败
  * list[int]: 读取成功后，返回结果数组
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func04 批量读取输入寄存器

* 方法说明

  Modbus 读取输入寄存器多个连续地址值，并以数组的形式返回其中的值，功能码 04。

```python
def batch_read_input_registers(ip: str, port: int, slave_id: int, offset: int, len: int) -> list[int] | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 首地址
  * len: int 类型，Modbus 地址数量
* 输出参数
  * None: 读取失败
  * list[int]: 读取成功后，返回结果数组
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func05 写入线圈量

* 方法说明

  Modbus 写入线圈量，功能码 05。

```python
def write_coil_status(ip: str, port: int, slave_id: int, offset: int, value: bool) -> bool
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
  * value: bool 类型，写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func06 写入保持寄存器

* 方法说明

  Modbus 写入保持寄存器，功能码 06。

```python
def write_holding_register(ip: str, port: int, slave_id: int, offset: int, data_type: int, value: int) -> bool
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
  * data_type: int 类型，2：无符号整形，3：有符号整形
  * value: int 类型，写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func0f 批量写入线圈量

* 方法说明

  Modbus 写入线圈量多个连续地址，功能码 0f。

```python
def batch_write_coil_status(ip: str, port: int, slave_id: int, offset: int, value: list[bool]) -> bool
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
  * value: list[bool] 类型，多个需写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### Func10 批量写入保持寄存器

* 方法说明

  Modbus 写入保持寄存器多个连续地址，功能码 10。

```python
def batch_write_holding_register(ip: str, port: int, slave_id: int, offset: int, value: list[int]) -> bool
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * offset: int 类型，Modbus 地址
  * value: list[int] 类型，多个需写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### 通用写入单个地址

* 方法说明

  Modbus 写入单个地址，通过参数 type 指定读取的地址类型。

```python
def write_single_modbus_value(ip: str, port: int, slave_id: int, type_str: str, offset: int, value: int) -> bool
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * type_str: str 类型，表示地址类型，可选择'0x'，'1x'，'3x'，'4x'，和功能码的对应关系如下：
    * 0x：对应功能码0x01，表示读线圈
    * 1x：对应功能码0x02，表示读离散输入
    * 3x：对应功能码0x04，表示读输入寄存器
    * 4x：对应功能码0x03，表示读保持寄存器
  * offset: int 类型，表示Modbus 地址
  * value: int 类型，表示写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### 通用写入多个地址

* 方法说明

  Modbus 写入单个地址，通过参数 type 指定读取的地址类型。

```python
def write_batch_modbus_value(ip: str, port: int, slave_id: int, type_str: str, offset: int, values: list[int]) -> bool
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * type_str: str 类型，表示地址类型，可选择'0x'，'1x'，'3x'，'4x'，和功能码的对应关系如下：
    * 0x：对应功能码0x01，表示读线圈
    * 1x：对应功能码0x02，表示读离散输入
    * 3x：对应功能码0x04，表示读输入寄存器
    * 4x：对应功能码0x03，表示读保持寄存器
  * offset: int 类型，表示Modbus 地址
  * values: list[int] 类型，表示写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### 通过实例名称写入单个地址

* 方法说明

  Modbus 写入单个地址，通过参数 name 指定已经配置的实例名称。

```python
def write_single_modbus_value_by_instance_name(name: str, offset: int, value: int) -> bool
```

* 输入参数
  * name: str 类型，已经配置的实例名称
  * offset: int 类型，表示 Modbus 地址
  * value: int 类型，表示写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  如果没有配置 modbus 实例，则会抛出初始化异常。

#### 通过实例名称写入多个地址

* 方法说明

  Modbus 写入多个地址，通过参数 name 指定已经配置的实例名称。

```python
def write_batch_modbus_value_by_instance_name(name: str, offset: int, values: list[int]) -> bool
```

* 输入参数
  * name: str 类型，已经配置的实例名称
  * offset: int 类型，表示 Modbus 地址
  * values: list[int] 类型，表示写入的值
* 输出参数
  * True: 写入成功
  * False: 写入失败
* 异常
  如果没有配置 modbus 实例，则会抛出初始化异常。

#### 通用读取单个地址

* 方法说明

  Modbus 读取单个地址，通过参数 type 指定读取的地址类型。

```python
def read_single_modbus_value(ip: str, port: int, slave_id: int, type_str: str, offset: int) -> int | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * type_str: str 类型，表示地址类型，可选择'0x'，'1x'，'3x'，'4x'，和功能码的对应关系如下：
    * 0x：对应功能码0x01，表示读线圈
    * 1x：对应功能码0x02，表示读离散输入
    * 3x：对应功能码0x04，表示读输入寄存器
    * 4x：对应功能码0x03，表示读保持寄存器
  * offset: int 类型，Modbus 地址
* 输出参数
  * None: 读取失败
  * int: 读取成功的返回值
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### 通用读取多个地址

* 方法说明

  Modbus 读取多个地址，通过参数 name 指定已经配置的实例名称。

```python
def read_batch_modbus_value(ip: str, port: int, slave_id: int, type_str: str, offset: int, length: int) -> list[int] | None
```

* 输入参数
  * ip: str 类型，从机 IP
  * port: int 类型，从机端口
  * slave_id: int 类型，从机 slave ID
  * type_str: str 类型，表示地址类型，可选择'0x'，'1x'，'3x'，'4x'，和功能码的对应关系如下：
    * 0x：对应功能码0x01，表示读线圈
    * 1x：对应功能码0x02，表示读离散输入
    * 3x：对应功能码0x04，表示读输入寄存器
    * 4x：对应功能码0x03，表示读保持寄存器
  * offset: int 类型，Modbus 地址
  * length: int 类型，读取的数据长度
* 输出参数
  * None: 读取失败
  * list[int]: 读取成功的返回值数组
* 异常
  本方法不抛出异常，异常捕获后只作日志记录。

#### 通过实例名称读取单个地址

* 方法说明

  Modbus 读取单个地址，通过参数 name 指定已经配置的实例名称。

```python
def read_single_modbus_value_by_instance_name(name: str, offset: int) -> int | None
```

* 输入参数
  * name: str 类型，配置的唯一实例名称
  * offset: int 类型，Modbus 地址
* 输出参数
  * None: 读取失败
  * int: 读取成功的返回值
* 异常
  如果没有配置 modbus 实例，则会抛出初始化异常。

#### 通过实例名称读取多个地址

* 方法说明

  Modbus 读取多个地址，通过参数 name 指定已经配置的实例名称。

```python
def read_batch_modbus_value_by_instance_name(name: str, offset: int, length: int) -> list[int] | None
```

* 输入参数
  * name: str 类型，配置的唯一实例名称
  * offset: int 类型，Modbus 地址
  * length: int 类型，读取的数据长度
* 输出参数
  * None: 读取失败
  * list[int]: 读取成功的返回值
* 异常
  如果没有配置 modbus 实例，则会抛出初始化异常。