Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,8 +211,26 @@ Test fixtures (JSON responses) are in `tests/fixtures/`

## Common Tasks

### Fetching Parameters from a Real Device

Use `examples/fetch_param.py` to query raw parameter data from a real BSB-LAN device before adding new parameters:

```bash
# Set your device connection details
# Leave BSBLAN_HOST unset to use auto-discovery, or set it explicitly:
export BSBLAN_HOST="192.168.1.100"
export BSBLAN_PASSKEY=your_passkey # if needed

# Fetch one or more parameters
cd examples && python fetch_param.py 1645
cd examples && python fetch_param.py 1645 1641 1642 1644 1646
```

The output shows the raw JSON response including value, unit, description, and data type — use this to determine the correct model field type and naming.

### Adding a New Settable Parameter

0. Fetch the parameter from a real device using `examples/fetch_param.py` to inspect the raw response
1. Add parameter ID mapping in `constants.py`
2. Add field to appropriate model in `models.py`
3. Add parameter to method signature in `bsblan.py`
Expand Down
51 changes: 51 additions & 0 deletions .github/skills/bsblan-parameters/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,57 @@ This skill guides you through adding new parameters to the python-bsblan library
- Legionella-related parameters use `legionella_function_*` prefix
- DHW (Domestic Hot Water) parameters use `dhw_*` prefix

## Discovering Parameters from a Real System

Before adding a new parameter, use `examples/fetch_param.py` to retrieve the raw API response from a real BSB-LAN device. This shows the exact structure, data types, units, and descriptions returned by the device.

### Setup

```bash
# Set environment variables for your device
export BSBLAN_HOST=<ip-or-host> # Your BSB-LAN IP address; leave unset to use autodiscovery
export BSBLAN_PASSKEY=your_passkey # Optional: if your device requires a passkey
export BSBLAN_USER=username # Optional: if authentication is enabled
export BSBLAN_PASS=password # Optional: if authentication is enabled
export BSBLAN_PORT=80 # Optional: defaults to 80
```

### Fetching Parameters

```bash
# Fetch a single parameter
cd examples && python fetch_param.py 1645

# Fetch multiple parameters at once
cd examples && python fetch_param.py 1645 1641 1642 1644 1646
```

### Example Output

The raw API response shows the exact structure you need to model:

```json
{
"1645": {
"name": "Legionella function setpoint",
"value": "70.0",
"unit": "°C",
"desc": "",
"dataType": 0
}
}
```

Use this output to determine:
- **Field type**: `float`, `int`, or `str` based on the `value` format
- **Unit**: The `unit` field (e.g., `°C`, `%`, `-`)
- **Description**: The `name` field for docstrings
- **Data type**: The `dataType` field for `EntityInfo` typing

### Device Discovery

`fetch_param.py` uses mDNS/Zeroconf discovery (via `examples/discovery.py`) to find your BSB-LAN device automatically when `BSBLAN_HOST` is not set. If mDNS is unavailable, set the `BSBLAN_HOST` environment variable directly.

## Steps to Add a New Parameter

### 1. Add to `constants.py`
Expand Down
Loading
Loading