DucoPy

DucoPy is a Python library and CLI tool that allows for full control of a DucoBox ventilation unit equipped with a DucoBox Connectivity Board. Using DucoPy, you can retrieve information, control settings, and monitor logs of your DucoBox system directly from your Python environment or command line.

Features

• Retrieve API information from the DucoBox system
• Get details about available modules, nodes, actions, and logs
• Interact with specific nodes and configure them
• Control actions available on the DucoBox unit
• Output information in a structured or JSON format

Installation

The easiest way to install DucoPy is through pip:

pip install ducopy

Alternatively, you can clone the repository and install manually:

git clone https://github.com/sikerdebaard/ducopy.git
cd ducopy
pip install .

Additional Requirements

This project uses Typer for the CLI, Loguru for logging, Rich for pretty-printing, and Pydantic for data validation. These will be installed automatically with the above command.

Using the DucoPy Facade in Python

The DucoPy Python class provides a simple interface for interacting with the DucoBox API. Below is an example of how to use it:

Example

from ducopy.ducopy import DucoPy
from pydantic import HttpUrl

# Initialize the DucoPy client with the base URL of your DucoBox
base_url = "https://your-ducobox-ip"  # Replace with the actual IP
ducopy = DucoPy(base_url=base_url)

# Retrieve API information
api_info = ducopy.get_api_info()
print(api_info)

# Get nodes
nodes = ducopy.get_nodes()
print(nodes.model_dump(mode='json'))

# Retrieve information for a specific node
node_id = 1
node_info = ducopy.get_node_info(node_id=node_id)
print(node_info.model_dump(mode='json'))

# Close the DucoPy client connection when done
ducopy.close()

Available Methods

Here is a list of the main methods available in the DucoPy facade:

• get_api_info() -> dict: Retrieve general API information.
• get_info(module: str | None = None, submodule: str | None = None, parameter: str | None = None) -> dict: Retrieve information about modules and parameters.
• get_nodes() -> NodesResponse: Retrieve a list of all nodes in the DucoBox system.
• get_node_info(node_id: int) -> NodeInfo: Get details about a specific node by its ID.
• get_config_node(node_id: int) -> ConfigNodeResponse: Get configuration settings for a specific node.
• get_action(action: str | None = None) -> dict: Retrieve information about a specific action.
• get_actions_node(node_id: int, action: str | None = None) -> ActionsResponse: Retrieve available actions for a specific node.
• get_logs() -> dict: Retrieve the system logs from the DucoBox.

All methods return a dictionary or a Pydantic model instance. Use .model_dump(mode='json') on Pydantic models to get JSON-serializable output if needed.

Using the CLI Client

DucoPy also provides a command-line interface (CLI) for interacting with your DucoBox system.

CLI Commands

After installing DucoPy, you can access the CLI using the ducopy command:

ducopy --help

This will display a list of available commands.

Example Commands

1. Retrieve API information

   ducopy get-api-info --base-url https://your-ducobox-ip
   

2. Get details about nodes

   ducopy get-nodes --base-url https://your-ducobox-ip
   

3. Get information for a specific node

   ducopy get-node-info --base-url https://your-ducobox-ip --node-id 1
   

4. Get actions available for a node

   ducopy get-actions-node --base-url https://your-ducobox-ip --node-id 1
   

5. Retrieve system logs

   ducopy get-logs --base-url https://your-ducobox-ip
   

Output Formatting

All commands support an optional --output-format argument to specify the output format (pretty or json):

ducopy get-nodes --base-url https://your-ducobox-ip --output-format json

• pretty (default): Formats the output in a structured, readable style.
• json: Outputs raw JSON data, which can be useful for further processing or debugging.

Logging Level

To set the logging level, use the --logging-level option, which accepts values like DEBUG, INFO, WARNING, ERROR, or CRITICAL.

ducopy --logging-level DEBUG get-nodes --base-url https://your-ducobox-ip

Contributing

We welcome contributions! Please open issues or submit pull requests on GitHub to improve DucoPy.

License

DucoPy is licensed under the MIT License. See LICENSE for more information.

With DucoPy, you have a powerful tool at your fingertips to manage and control your DucoBox ventilation unit. Whether you're using the Python API or the CLI, DucoPy provides flexible, straightforward access to your system.