### Install luxtronik Library

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Install the library using pip. This command fetches the latest stable release from PyPI.

```shell
pip install luxtronik
```

--------------------------------

### Instantiate and Use Luxtronik Data Container Classes

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Shows how to create and use LuxtronikData and LuxtronikSmartHomeData container classes for organizing fields. These can be instantiated independently or with custom vectors. Demonstrates getting firmware version and using with interfaces for reading and writing data.

```python
from luxtronik.cfi.interface import LuxtronikData, LuxtronikSocketInterface
from luxtronik.cfi import Parameters, Calculations, Visibilities
from luxtronik.shi.interface import LuxtronikSmartHomeData
from luxtronik.shi import Holdings, Inputs

# Create CFI data container
cfi_data = LuxtronikData()
# Or with custom vectors
params = Parameters(safe=True)
calcs = Calculations()
visis = Visibilities()
cfi_data = LuxtronikData(params, calcs, visis, safe=True)

# Get firmware version from calculations
version = cfi_data.get_firmware_version()
print(f"Firmware: {version}")

# Create SHI data container with version
shi_data = LuxtronikSmartHomeData(version=(3, 92, 0))

# Create empty SHI data (no fields added)
empty_shi = LuxtronikSmartHomeData.empty(version=(3, 92, 0), safe=True)

# Access internal data vectors
print(shi_data.holdings)
print(shi_data.inputs)

# Use with interfaces
cfi = LuxtronikSocketInterface('192.168.1.23', 8889)
cfi.read(cfi_data)
cfi.write(cfi_data.parameters)

# Read specific data types
cfi.read_parameters(cfi_data.parameters)
cfi.read_calculations(cfi_data.calculations)
```

--------------------------------

### Install Latest luxtronik from Git

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Install the most recent version directly from the GitHub repository. This is useful for testing development versions.

```shell
pip install git+https://github.com/Bouni/python-luxtronik.git@main
```

--------------------------------

### Access Luxtronik Data Vectors with Python

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Demonstrates dictionary-style access, getting values with defaults, setting parameters, checking field existence, and iterating over fields and definitions in Luxtronik data vectors. Requires initializing the Luxtronik client with the device IP and port.

```python
from luxtronik import Luxtronik

l = Luxtronik('192.168.1.23', 8889)

# Dictionary-style access
temp = l.calculations["ID_WEB_Temperatur_TVL"]

# Get with default value
temp = l.calculations.get("nonexistent_field", default=None)

# Set values
l.parameters["ID_Einst_WK_akt"] = 1.0

# Check field existence
if "ID_WEB_Temperatur_TA" in l.calculations:
    print("Outside temperature available")

# Iterate over all fields
for field in l.calculations.values():
    print(f"{field.name}: {field.value} {field.unit}")

# Iterate with definitions
for definition, field in l.parameters.items():
    if field.writeable:
        print(f"{definition.name} is writable, current value: {field.value}")

# Get number of fields
print(f"Total parameters: {len(l.parameters)}")

# Field properties
field = l.calculations["ID_WEB_Temperatur_TVL"]
print(f"Name: {field.name}")
print(f"Value: {field.value}")
print(f"Raw value: {field.raw}")
print(f"Unit: {field.unit}")
print(f"Writeable: {field.writeable}")
print(f"Write pending: {field.write_pending}")
```

--------------------------------

### Get Available Options for a Parameter

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Retrieve a list of possible values for a given parameter using the `options()` method. This is helpful when unsure about valid inputs.

```python
print(parameters.get("ID_Ba_Hz_akt").options()) # returns a list of possible values to write, ['Automatic', 'Second heatsource', 'Party', 'Holidays', 'Off'] for example
```

--------------------------------

### Create Modbus-TCP Interface Instance

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Instantiate the smart home interface for Modbus-TCP communication. Replace 'your.lux.ip.addr' with the actual IP address of your Luxtronik controller. This method automatically detects the firmware version.

```python
from luxtronik.shi import create_modbus_tcp

# Use the default values for all arguments except the IP address
shi = create_modbus_tcp('your.lux.ip.addr')
```

--------------------------------

### Read Heat Pump Data with Luxtronik Class

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Initializes a connection to the heat pump and retrieves parameters and calculations. The constructor performs an initial read, while subsequent updates require calling the read method.

```python
from luxtronik import Luxtronik

l = Luxtronik('192.168.1.23', 8889, True, 502)
# There is an initial reading during creation
heating_limit = l.parameters.get("ID_Einst_Heizgrenze_Temp")

# Do something else here...

# Read the values again
l.read()
t_forerun = l.calculations.get("ID_WEB_Temperatur_TVL")
t_outside = l.calculations.get("ID_WEB_Temperatur_TA")

# alternatively get also works with numerical ID values
t_forerun = l.calculations.get(10)

print(t_forerun) # this returns the temperature value of the forerun, 22.7 for example
print(t_forerun.unit) # gives you the unit of the value if known, °C for example

# or via Modbus TCP
t_flowline = l.inputs["flow_line_temp"]

print(t_flowline) # returns 22.7 for example again
```

--------------------------------

### Write Parameters with Parameters Object

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Create a Parameters object, set specific values, and then write them to the heat pump. This method allows for batch updates.

```python
parameters = Parameters()
parameters["ID_Ba_Hz_akt"] = "Party"
l.write(parameters)
```

--------------------------------

### Initialize Luxtronik Client with Safeguard Disabled

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Initializes the Luxtronik class with safe=False to allow writing to undocumented API parameters.

```python
from luxtronik import Luxtronik

l = Luxtronik('192.168.1.23', 8889, safe=False)
```

--------------------------------

### Watch Smart Home Interface Changes

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Monitors changes in the smart home interface of a Luxtronik device. Requires the IP address and port of the device.

```bash
luxtronik watch-shi 192.168.178.123 502
```

--------------------------------

### Discover Heat Pumps via CLI

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Sends broadcast packets to discover Luxtronik controllers on the network.

```sh
luxtronik discover
```

```sh
1 heatpump(s) reported back
Heat pump #0 -> IP address: 192.168.178.123 port: 8889
```

--------------------------------

### Dump system parameters via CLI

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Executes a dump of all system parameters from a controller at the specified IP address and port.

```bash
python -m luxtronik dump-shi 192.168.178.123 502
```

--------------------------------

### Initialize and Interact with Luxtronik Class

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Use the Luxtronik class for stateful interactions where the library maintains data internally. It performs an initial read upon instantiation and provides methods to refresh specific data categories.

```python
from luxtronik import Luxtronik

# Initialize connection - performs initial read automatically
# Parameters: host, config_port (8889), safe_mode (True), modbus_port (502)
l = Luxtronik('192.168.1.23', 8889, True, 502)

# Access parameters (writable configuration values)
heating_limit = l.parameters.get("ID_Einst_Heizgrenze_Temp")
print(f"Heating limit: {heating_limit.value} {heating_limit.unit}")
# Output: Heating limit: 20.0 °C

# Access calculations (read-only sensor values)
t_forerun = l.calculations.get("ID_WEB_Temperatur_TVL")
t_outside = l.calculations.get("ID_WEB_Temperatur_TA")
print(f"Flow temperature: {t_forerun}")  # Output: 32.7
print(f"Unit: {t_forerun.unit}")         # Output: °C

# Access by numeric index
t_forerun_by_idx = l.calculations.get(10)  # Same as "ID_WEB_Temperatur_TVL"

# Access smart home interface data (Modbus TCP)
t_flowline = l.inputs["flow_line_temp"]
print(f"Flow line temp via Modbus: {t_flowline}")

# Re-read all data from heat pump
l.read()

# Read specific data types only
l.read_parameters()
l.read_calculations()
l.read_visibilities()
l.read_holdings()
l.read_inputs()
```

--------------------------------

### Add Custom Field Definitions to Luxtronik SHI

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Enables adding custom or undocumented fields to the SHI interface for experimentation. Shows how to add a custom input definition and then access it.

```python
from luxtronik.shi import create_modbus_tcp

shi = create_modbus_tcp('192.168.1.23')

# Add custom input definition
shi.inputs.add({
    "index": 105,      # Register index
    "count": 2,        # Number of registers
    "names": "custom_sensor"  # Field name
})

# Now the custom field can be accessed
custom = shi.read_input('custom_sensor')
print(f"Custom sensor: {custom}")
```

--------------------------------

### Heat Pump Discovery

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Discover Luxtronik controllers on the local network.

```APIDOC
## GET /discovery

### Description
Broadcasts a discovery packet to identify Luxtronik heat pumps on the local network.

### Response
- **results** (list) - List of tuples containing (IP, port) for discovered devices
```

--------------------------------

### Write Data via LuxtronikInterface

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Uses the interface to create a data vector and write specific heating circuit values to the heat pump.

```python
from luxtronik import LuxtronikInterface

l = LuxtronikInterface('192.168.1.23', 8889, 502)
# To write the SHI values, it is important to use the data vector constructor function of the interface, as the firmware version used must be known here
data = l.create_all_data()

# Set the value of the heating circuit target temperature offset field to 2.
data.holdings["heating_offset"] = 2.0
# Write down the values to the heat pump.
l.write(data)
```

--------------------------------

### Set Domestic Hot Water Temperature

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Instantiate the Luxtronik client and set a specific parameter, such as domestic hot water temperature, before writing changes.

```python
from luxtronik import Luxtronik, Parameters

l = Luxtronik('192.168.1.23', 8889)

# Set the value of a field
# In this example, the domestic hot water temperature
# is set (for the time being only in this field) to 45 degrees
l.parameters.set("ID_Soll_BWS_akt", 45.0)

# Then write the data of all changed fields to the to the heat pump
l.write()
```

--------------------------------

### Raw Register Access for Debugging Luxtronik SHI

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Provides methods for raw register access on the SHI interface for debugging and exploring undocumented registers. Includes reading and writing raw holding and input registers. Use `create_modbus_tcp` with `version=None` for trial-and-error mode.

```python
from luxtronik.shi import create_modbus_tcp

shi = create_modbus_tcp('192.168.1.23', version=None)  # Trial-and-error mode

# Read raw holding registers
raw_data = shi.read_holding_raw(index=0, count=10)
print(f"Raw holdings 0-9: {raw_data}")

# Read raw input registers
raw_inputs = shi.read_input_raw(index=0, count=5)
print(f"Raw inputs 0-4: {raw_inputs}")

# Write raw holding registers (DANGEROUS!)
success = shi.write_holding_raw(index=5, data_arr=[100, 200])
print(f"Raw write successful: {success}")

# Trial-and-error mode reads all available definitions
from luxtronik.shi.interface import LuxtronikSmartHomeData

data = LuxtronikSmartHomeData(version=None)  # All available fields
shi.read(data)

# Explore unknown registers
for field in data.inputs.values():
    if "Unknown" in field.name:
        print(f"{field.name}: {field.raw}")
```

--------------------------------

### Luxtronik Data Fields Overview

Source: https://github.com/bouni/python-luxtronik/blob/main/docs/index.html

This section provides a general overview of the Luxtronik data fields. The data is presented in a tabular format with columns for Category, Index, Name, LSB, Width, Class, Unit, Writeable, Since, Until, and Description. Note that specific endpoints for retrieving this data are not detailed here, but the structure of the data is outlined.

```APIDOC
## Luxtronik Data Fields

### Description
Provides a structured list of all available data fields for Luxtronik systems. This information is automatically generated and can be used to understand the available parameters for data retrieval or manipulation.

### Parameters
This section outlines the general structure of the data fields. Specific API endpoints for querying these fields are not detailed in the provided text.

#### Available Fields:
- **Category**: The category to which the data field belongs.
- **Index**: The unique index of the data field within its category.
- **Name**: The human-readable name of the data field.
- **LSB**: Least Significant Bit information.
- **Width**: The data width of the field.
- **Class**: The class or type of the data field.
- **Unit**: The unit of measurement for the data field.
- **Writeable**: Indicates if the field can be written to.
- **Since**: The version or date from which this field is available.
- **Until**: The version or date until which this field is valid.
- **Description**: A detailed description of the data field.

### Request Example
No specific request examples are available as this section describes the data structure rather than a specific API endpoint.

### Response
#### Success Response (200)
- **data_fields** (array) - An array of objects, where each object represents a Luxtronik data field with the properties listed above.

#### Response Example
```json
{
  "data_fields": [
    {
      "Category": "Heater",
      "Index": 1,
      "Name": "Temperature",
      "LSB": 0.1,
      "Width": 16,
      "Class": "float",
      "Unit": "°C",
      "Writeable": "false",
      "Since": "1.0",
      "Until": "",
      "Description": "Current heating circuit temperature."
    }
    // ... more data fields
  ]
}
```
```

--------------------------------

### Read Heat Pump Data with LuxtronikInterface

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Uses the interface class to read all data from the heat pump into a data object.

```python
from luxtronik import LuxtronikInterface

l = LuxtronikInterface('192.168.1.23', 8889, 502)
# Read all data from the heatpump
data = l.read()

t_forerun = data.calculations["ID_WEB_Temperatur_TVL"]
if t_forerun.value > 30:
#...
```

--------------------------------

### Heat Pump Discovery

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Locate Luxtronik controllers on the local network using broadcast packets.

```python
from luxtronik import discover

# Discover all heat pumps on the network
results = discover()

print(f"Found {len(results)} heat pump(s)")
for i, (ip, port) in enumerate(results):
    print(f"Heat pump #{i}: IP={ip}, Port={port}")

# Example output:
# Found 1 heat pump(s)
# Heat pump #0: IP=192.168.1.23, Port=8889
```

--------------------------------

### Visualize register, field, and data block mapping

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

A diagram illustrating how registers are grouped into fields and data blocks for bulk operations.

```json
Index
      +------------+      +------------+      +------------+
0x00  | Register 0 |      | Field 0    |      | Data block |
      +------------+      +------------+      +            +
0x01  | Register 1 |      | Field 1    |      |            |
      +------------+      +            +      +            +
0x02  | Register 2 |      |            |      |            |
      +------------+      +------------+      +------------+
0x03  Register 3 do not exist

0x04  Register 4 do not exist
      +------------+      +------------+      +------------+
0x05  | Register 5 |      | Field 5    |      | Data block |
      +------------+      +            +      +            +
0x06  | Register 6 |      |            |      |            |
      +------------+      +------------+      +------------+
0x07  Register 7 do not exist

0x08  Register 8 do not exist
      +------------+      +------------+      +------------+
0x09  | Register 9 |      | Field 9    |      | Data block |
      +------------+      +------------+      +------------+
...
```

--------------------------------

### Read all fields together (all data vectors)

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Use this method to read data from all supported data vectors. Create the data vector collection once and then read into all its fields.

```python
# First create the data vector collection (once) that contains
# all supported data vectors which contains all data fields
data = shi.create_data()
# ... and afterwards read the data into those fields
shi.read(data)
print(data.inputs)
```

--------------------------------

### Dump Heat Pump Data via CLI and Scripts

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Retrieves all available data from the heat pump using CLI commands or the provided Python scripts.

```sh
luxtronik dump-cfi 192.168.178.123 8889

# or analog for Modbus TCP register
luxtronik dump-shi 192.168.178.123 502
```

```python
PYTHONPATH=. ./luxtronik/scripts/dump_cfi.py 192.168.178.123 8889
```

--------------------------------

### Trial-and-Error Mode

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Set version to None to enable trial-and-error mode, which performs individual operations without bundling, useful when the controller version is unknown.

```python
from luxtronik.shi import create_modbus_tcp
from luxtronik.shi.interface import LuxtronikSmartHomeData

shi = create_modbus_tcp('your.lux.ip.addr', version=None)

data = LuxtronikSmartHomeData(version=None)
shi.read(data)

holdings = shi.create_holdings()
holdings[1].value = 22.0
holdings[2].value =  5.0
success = shi.write_holdings(holdings)
```

--------------------------------

### Perform Stateless Operations with LuxtronikInterface

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Use LuxtronikInterface for applications requiring manual control over the data lifecycle. This class does not maintain internal state, requiring explicit read and write calls.

```python
from luxtronik import LuxtronikInterface

# Initialize interface without automatic data read
# Parameters: host, config_port, modbus_port
l = LuxtronikInterface('192.168.1.23', 8889, 502)

# Read all data from the heat pump (creates and returns data object)
data = l.read()

# Access values from returned data object
t_forerun = data.calculations["ID_WEB_Temperatur_TVL"]
if t_forerun.value > 30:
    print(f"Flow temperature is high: {t_forerun.value}°C")

# Access parameters and holdings
heating_mode = data.parameters["ID_Ba_Hz_akt"]
print(f"Heating mode: {heating_mode.value}")

flow_temp = data.inputs["flow_line_temp"]
print(f"Flow temp (SHI): {flow_temp.value}")

# Create custom data object for specific operations
custom_data = l.create_all_data()
l.read_all(custom_data)  # Populate with fresh data
```

--------------------------------

### Specifying Firmware Versions

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Define specific firmware versions for data objects to ensure compatibility, or use 'latest' to automatically select the most recent supported version.

```python
from luxtronik.shi import create_modbus_tcp
from luxtronik.shi.holdings import Holdings

shi = create_modbus_tcp('your.lux.ip.addr', version="3.92.0")
holdings = Holdings("3.92.0")
shi.read_holdings(holdings)

# inputs is created with version "3.92.0"
inputs = shi.read_inputs()
```

```python
from shi import create_modbus_tcp

shi = create_modbus_tcp('your.lux.ip.addr', version="latest")
```

--------------------------------

### Read all fields together (single data vector)

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Use this method when you need to read all data fields within a single data vector. Create the data vector once and then read into it.

```python
# First create the data vector (once) that contains all data fields
inputs = shi.create_inputs()
# ... and afterwards read the data into those fields
shi.read_inputs(inputs)
print(inputs)
```

--------------------------------

### Writing Holdings via Smart Home Interface

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Modify volatile heat pump settings that reset upon system restart. Supports both individual field updates and combined interface operations.

```python
from luxtronik.shi import create_modbus_tcp

shi = create_modbus_tcp('192.168.1.23')

# Create holdings data vector
holdings = shi.create_holdings()

# Set heating mode to offset control with +2K adjustment
holdings['heating_mode'] = 'Offset'
holdings['heating_offset'] = 2.0

# Write to heat pump
success = shi.write_holdings(holdings)
print(f"Write successful: {success}")

# Write and read back to verify
success = shi.write_and_read_holdings(holdings)
print(f"Verified heating offset: {holdings['heating_offset'].value}")

# Write a single field directly
shi.write_holding('lock_hot_water', True)

# Unsafe write (bypasses safety checks)
shi.write_holding('heating_mode', 'Setpoint', safe=False)

# Using LuxtronikInterface for combined operations
from luxtronik import LuxtronikInterface

l = LuxtronikInterface('192.168.1.23', 8889, 502)
data = l.create_all_data()

data.holdings["heating_offset"] = 2.0
l.write(data)
```

--------------------------------

### Display Changed Values Output

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

The output format for changed values, showing the old and new values or indicating a revert.

```txt
================================================================================                                                                                                                                 │
calc: Number: 15    Name: ID_WEB_Temperatur_TA                                         Value: 27.2 -> 27.0                                                                                                       │
calc: Number: 73    Name: ID_WEB_Time_VDStd_akt                                        Value: 47189 -> 47192                                                                                                     │
calc: Number: 75    Name: ID_WEB_Time_HRW_akt                                          Value: 353732 -> 353735                                                                                                   │
calc: Number: 134   Name: ID_WEB_AktuelleTimeStamp                                     Value: 2023-07-12 11:47:43 -> 2023-07-12 11:47:46                                                                         │
calc: Number: 20    Name: ID_WEB_Temperatur_TWA                                        Value: 24.8 -> reverted                                                                                                   │
calc: Number: 178   Name: ID_WEB_LIN_UH                                                Value: 3.1 -> reverted                                                                                                    │
calc: Number: 180   Name: ID_WEB_LIN_HD                                                Value: 15.46 -> reverted                                                                                                  │
calc: Number: 181   Name: ID_WEB_LIN_ND                                                Value: 15.67 -> reverted                                                                                                  │
calc: Number: 232   Name: Vapourisation_Temperature                                    Value: 25.2 -> reverted                                                                                                   │
calc: Number: 233   Name: Liquefaction_Temperature                                     Value: 24.8 -> reverted                                                                                                   │
calc: Number: 10    Name: ID_WEB_Temperatur_TVL                                        Value: 32.7 -> 32.8                                                                                                       │
calc: Number: 13    Name: ID_WEB_Temperatur_TRL_ext                                    Value: 26.2 -> 26.1
```

--------------------------------

### Add a custom input definition

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Manually register a new field by providing its index, register count, and name to the local configuration.

```python
shi.inputs.add({
    "index": 5,
    "count": 2,
    "names": "foo"
})
```

--------------------------------

### Read all fields (new data vector collection per operation)

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Creates a new data vector collection for each read operation. This is less efficient if multiple reads are performed.

```python
# Create the data vector collection and read the fields
data = shi.read()
# or ...
data = shi.read_data()
print(data.inputs)
```

--------------------------------

### Watch Changed Values (Script)

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Invoke watch scripts directly for monitoring changed values. Ensure the PYTHONPATH is set correctly.

```python
PYTHONPATH=. ./luxtronik/scripts/watch_cfi.py 192.168.178.123 8889

# or
PYTHONPATH=. ./luxtronik/scripts/watch_shi.py 192.168.178.123
```

--------------------------------

### Disable Safe Mode for Experimental Writes

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Perform direct configuration writes by disabling safety checks. Use with caution as this bypasses standard protection mechanisms.

```python
l_unsafe = Luxtronik('192.168.1.23', 8889, safe=False)
l_unsafe.parameters.set("ID_Einst_Heizgrenze_Temp", 18.0)
l_unsafe.write()
```

--------------------------------

### Watch Changed Values (CLI)

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Use `watch-cfi` or `watch-shi` sub-commands to monitor values that have recently changed. This is useful for interactive use and identifying unknown parameters.

```sh
luxtronik watch-cfi 192.168.178.123 8889

# or
luxtronik watch-shi 192.168.178.123
```

--------------------------------

### Read all fields (new data vector per operation)

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Creates a new data vector for each read operation. This is less efficient if multiple reads are performed.

```python
# Create the data vector and read the fields
inputs = shi.read_inputs()
print(inputs)
```

--------------------------------

### Command Line Interface Operations

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Perform diagnostic tasks and monitor values directly from the terminal.

```bash
# Discover heat pumps on network
luxtronik discover
# Output:
# 1 heatpump(s) reported back
# Heat pump #0 -> IP address: 192.168.178.123 port: 8889

# Dump all config interface values
luxtronik dump-cfi 192.168.178.123 8889
# Output shows all parameters, calculations, visibilities with names, types, values

# Dump all smart home interface values (Modbus TCP)
luxtronik dump-shi 192.168.178.123 502

# Watch for value changes in real-time (config interface)
luxtronik watch-cfi 192.168.178.123 8889
# Output shows only changing values:
```

--------------------------------

### Write all updated fields together (all data vectors)

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Writes all user-updated fields across all supported data vectors. Create the data vector collection once, set values, and then write.

```python
# First create the data vector collection (once) that contains
# all supported data vectors which contains all data fields
data = shi.create_data()
# ..., set the user data
holdings.set('heating_mode', 'Setpoint')
# ... and then write the data from these fields
success = shi.write(data)
# or ...
success = shi.write_data(data)
```

--------------------------------

### Write fields using an empty data vector

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Writes specified fields by creating an empty data vector, adding fields, setting their values, and then writing. This generates the same data transfer as writing a pre-populated vector.

```python
# Create (once) an empty data vector
holdings = shi.create_empty_holdings()
# ..., add the desired data fields (index 0 is 'heating_mode')
heating_mode = holdings.add(0)
# ..., set the user data
heating_mode.value = 'Setpoint'
# ... and then write the data from these fields
success = shi.write_holdings(holdings)
```

--------------------------------

### Collect and Send Pattern for Batch Operations

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Queue multiple read and write operations to be executed in a single transmission for atomic updates and reduced overhead.

```python
from luxtronik.shi import create_modbus_tcp

shi = create_modbus_tcp('192.168.1.23')

# Collect write operation for hot water lock
shi.collect_holding_for_write('lock_hot_water', True)

# Collect holdings data vector for write then read
holdings_for_heating = shi.create_holdings()
holdings_for_heating['heating_mode'] = 'Offset'
holdings_for_heating['heating_offset'] = 1.5
shi.collect_holdings(holdings_for_heating)

# Collect inputs for reading
inputs_for_heating = shi.create_inputs()
shi.collect_inputs(inputs_for_heating)

# Send all collected operations in one transmission
success = shi.send()
print(f"Batch operation successful: {success}")

# Access results from populated data vectors
print(f"Flow temp: {inputs_for_heating['flow_line_temp']}")
print(f"Heating offset set: {holdings_for_heating['heating_offset']}")

# Collect entire data objects
data = shi.create_data()
data.holdings['heating_mode'] = 'Automatic'
shi.collect_data(data)  # Collects writes and reads
shi.send()
```

--------------------------------

### Writing Holdings via SHI

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Perform volatile writes to heat pump configuration registers.

```APIDOC
## POST /shi/holdings

### Description
Update volatile configuration values on the heat pump. These changes are temporary and reset upon system restart.

### Parameters
#### Request Body
- **holdings** (object) - Key-value pairs of configuration fields to update
- **safe** (boolean) - Optional - Whether to perform safety checks (default: True)
```

--------------------------------

### Smart Home Interface (SHI) - Modbus TCP Operations

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Provides methods to read volatile status inputs and configuration holdings via Modbus TCP.

```APIDOC
## Modbus TCP SHI Operations

### Description
Read real-time status inputs and configuration holdings from the heat pump using the Smart Home Interface.

### Parameters
#### Path Parameters
- **ip** (string) - Required - IP address of the heat pump
- **version** (string) - Optional - Specific SHI version or 'latest'

### Response
- **inputs** (object) - Collection of read-only status values
- **holdings** (object) - Collection of read/write configuration values
```

--------------------------------

### Modify and Write Parameters to Heat Pump

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Update configuration parameters via the Config Interface. Note that safe mode is enabled by default to prevent unauthorized or dangerous parameter changes.

```python
from luxtronik import Luxtronik, Parameters

# Connect with safe mode enabled (default)
l = Luxtronik('192.168.1.23', 8889)

# Set a parameter value and write to heat pump
# Set domestic hot water target temperature to 45°C
l.parameters.set("ID_Soll_BWS_akt", 45.0)
l.write()

# Alternative: Create separate parameters object
parameters = Parameters()
parameters["ID_Ba_Hz_akt"] = "Party"  # Set heating mode to Party
l.write(parameters)

# Get available options for a selection field
heating_param = parameters.get("ID_Ba_Hz_akt")
print(heating_param.options())
# Output: ['Automatic', 'Second heatsource', 'Party', 'Holidays', 'Off']

# Using LuxtronikInterface for writes
from luxtronik import LuxtronikInterface

l = LuxtronikInterface('192.168.1.23', 8889, 502)
data = l.create_all_data()

# Set values and write
data.parameters["ID_Einst_WK_akt"] = 1.5  # Set room temperature offset
l.write(data)
```

--------------------------------

### Batching Operations with Collect

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Use collect methods to stage read and write operations internally before triggering a single transmission with send().

```python
# Collect a write to activate the hot water lock
shi.collect_holding_for_write('lock_hot_water', True)
# Collect all data fields within "holdings_for_heating"
# to write first and then read back afterwards
shi.collect_holdings(holdings_for_heating)
# Collect all data fields within "inputs_for_heating" to read them
shi.collect_inputs(inputs_for_heating)
# Trigger communication
success = shi.send()
```

--------------------------------

### Write all updated fields together (single data vector)

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Writes all fields that have been updated by the user within a single data vector. Create the data vector once, set values, and then write.

```python
# First create the data vector (once) that contains all data fields
holdings = shi.create_holdings()
# ..., set the user data
holdings['heating_mode'] = 'Setpoint'
# ... and then write the data from these fields
success = shi.write_holdings(holdings)
```

--------------------------------

### Batch Operations

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Collect multiple read and write operations to be executed in a single transmission.

```APIDOC
## POST /shi/batch

### Description
Collect multiple input reads and holding writes to reduce communication overhead and ensure atomic updates.

### Parameters
#### Request Body
- **operations** (list) - List of collected read/write tasks

### Response
- **success** (boolean) - Status of the batch transmission
```

--------------------------------

### Smart Home Interface Modbus TCP Operations

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Interact with volatile control registers using Modbus TCP for real-time monitoring and temporary overrides.

```python
from luxtronik.shi import create_modbus_tcp, Holdings, Inputs

# Create SHI interface with automatic version detection
shi = create_modbus_tcp('192.168.1.23')  # Port 502 by default

# Specify version explicitly or use latest
shi_versioned = create_modbus_tcp('192.168.1.23', version="3.92.0")
shi_latest = create_modbus_tcp('192.168.1.23', version="latest")

# Read all inputs (read-only status values)
inputs = shi.read_inputs()
print(inputs)

# Read a single input field
op_mode = shi.read_input('operation_mode')
print(f"Operation mode: {op_mode}")

# Read by register index
op_mode_by_idx = shi.read_input(2)

# Read all holdings (read/write configuration values)
holdings = shi.read_holdings()

# Create empty data vector and add specific fields
inputs = shi.create_empty_inputs()
op_mode = inputs.add('operation_mode')
flow_temp = inputs.add('flow_line_temp')
shi.read_inputs(inputs)
print(f"Mode: {op_mode}, Flow: {flow_temp}")

# Read using index access
print(inputs.get(2))  # By index
print(inputs['operation_mode'])  # By name
```

--------------------------------

### Write to a holding register with safety override

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Use the safe flag to control whether the interface restricts writes to verified fields or attempts to write to all provided user data.

```python
shi.write_holding('heating_mode', 'Setpoint', safe=False)
```

--------------------------------

### Explore Modbus TCP Holdings

Source: https://context7.com/bouni/python-luxtronik/llms.txt

Use this snippet for trial-and-error exploration of Modbus TCP registers. It allows direct value manipulation and writing to holdings.

```python
shi_explore = create_modbus_tcp('192.168.1.23', version=None)
holdings = shi_explore.create_holdings()
holdings[1].value = 22.0  # Access by index
holdings[2].value = 5.0
success = shi_explore.write_holdings(holdings)
```

--------------------------------

### Read a single field by name, index, or definition

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Reads a single data field. You can specify the field by its name, its index, or by using a pre-created field object or its definition.

```python
# Read field by name
op_mode = shi.read_input('operation_mode')
# ... or register index (index 2 is 'operation_mode')
op_mode = shi.read_input(2)
# ... or first create the field (once)
op_mode = shi.create_input('operation_mode')
shi.read_input(op_mode)
# ... or use the definition of the field
op_mode_def = shi.get_input('operation_mode')
op_mode = shi.read_input(op_mode_def)
print(op_mode)
```

--------------------------------

### Read a subset of data fields

Source: https://github.com/bouni/python-luxtronik/blob/main/luxtronik/shi/README.md

Reads a selected subset of data fields efficiently. Create an empty data vector, add desired fields, and then read them in a single operation.

```python
# Create (once) an empty data vector
inputs = shi.create_empty_inputs()
# ..., add the desired data fields
op_mode = inputs.add('operation_mode')
# ...
# Afterwards read the data into those fields
shi.read_inputs(inputs)
print(op_mode)
# (index 2 is 'operation_mode')
print(inputs.get(2))
print(inputs['operation_mode'])
```

--------------------------------

### Modify Heating Controller Temperature Offset

Source: https://github.com/bouni/python-luxtronik/blob/main/README.md

Updates the heating circuit target temperature offset and commits the change to the heat pump.

```python
heating_offset = l.holdings.get(2)    # Get an object for the offset
heating_offset.value = 2.0            # Set the desired value
l.holdings["heating_mode"] = "Offset" # Set the value to activate the offset mode
l.write()                             # Write down the values to the heatpump
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.