Add support for OpenWebNet Camera/Multimedia system (WHO 7)

[Copilot]

Overview

This PR adds complete support for the OpenWebNet Camera/Multimedia system (WHO = 7) to control video door entry systems and cameras through the OpenWebNet protocol.

Implementation Details

New Camera Module

Added a new camera module under pyown/items/ with:

• Camera class: Main class for controlling camera devices, inheriting from BaseItem
• WhatCamera enum: Defines all 32 camera commands from the OpenWebNet specification
• CameraEvents enum: Event types for callback registration

Supported Commands

The implementation includes all commands from the WHO 7 specification:

Video Control:

• receive_video() - Activate camera to receive video (WHAT=0)
• free_resources() - Free audio/video resources (WHAT=9)

Zoom & Positioning:

• zoom_in(), zoom_out() - Zoom controls
• increase_x_coordinate(), decrease_x_coordinate() - Horizontal positioning
• increase_y_coordinate(), decrease_y_coordinate() - Vertical positioning

Image Adjustments:

• increase_luminosity(), decrease_luminosity() - Brightness control
• increase_contrast(), decrease_contrast() - Contrast control
• increase_color(), decrease_color() - Color saturation control
• increase_quality(), decrease_quality() - Image quality control

Display Control:

• display_dial(x, y) - Display specific dial positions (16 positions: 1-1 through 4-4)

Message Format Handling

The implementation correctly handles two different OpenWebNet message formats:

1. Commands with WHERE (e.g., receive_video):

   *7*0*4000##  # WHO=7, WHAT=0, WHERE=4000

   Uses NormalMessage class.

2. Commands without WHERE (e.g., zoom, adjustments):

   *7*120##  # WHO=7, WHAT=120

   Uses GenericMessage class via _send_command_without_where() helper method.

Camera Addressing

Cameras use WHERE addresses 4000-4099:

• 4000 = Camera 00
• 4001 = Camera 01
• ...
• 4099 = Camera 99

Video Streaming

Note: The OpenWebNet protocol only handles camera control commands. The actual video streaming is done via HTTP/HTTPS at the gateway's endpoint (e.g., http://gateway-ip/telecamera.php). This implementation intentionally does not include an HTTP client, focusing solely on the OpenWebNet protocol commands as requested.

Usage Example

import asyncio
from pyown import Client
from pyown.items import Camera

async def main():
    async with Client("192.168.1.35", 20000) as client:
        # Create camera instance for camera 00 (WHERE = 4000)
        camera = Camera(client, "4000")
        
        # Activate camera
        await camera.receive_video()
        # Video stream available at: http://gateway-ip/telecamera.php
        
        # Adjust camera settings
        await camera.zoom_in()
        await camera.increase_luminosity()
        await camera.increase_contrast()
        
        # Display a specific dial
        await camera.display_dial(1, 1)
        
        # Free resources when done
        await camera.free_resources()

asyncio.run(main())

Files Changed

• Core Module: pyown/items/camera/ (camera.py, init.py)
• Integration: Updated pyown/items/__init__.py to export camera module
• Documentation: docs/api/items/camera.md with complete API reference
• Example: examples/camera_01/ with working demonstration
• Tests: tests/items/test_camera.py with comprehensive unit tests
• Summary: CAMERA_IMPLEMENTATION.md with detailed implementation notes

Code Quality

• ✅ Follows existing repository patterns (similar to Automation and Lighting modules)
• ✅ Async/await throughout
• ✅ Comprehensive docstrings and type hints
• ✅ Event callback system implemented
• ✅ Unit tests included
• ✅ Complete documentation with examples
• ✅ All 32 commands from WHO 7 specification implemented

Testing

All functionality has been validated:

• Message formats match OpenWebNet specification exactly
• Camera class properly inherits from BaseItem
• WHO value correctly set to VIDEO_DOOR_ENTRY (7)
• All methods functional with proper error handling
• Unit tests pass successfully

References

• OpenWebNet WHO 7 specification: docs/original/who7.md
• Compatible devices: BTicino F453AV, Legrand video door entry systems

Original prompt

Add support to controll the cam system in openwebnet. Limit to add only code for openwebnet, do not add any http client. Make sure to follow the code style. Read the whole documentation and code before acting.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull Request Overview

This PR adds comprehensive support for the OpenWebNet Camera/Multimedia system (WHO = 7), enabling control of video door entry systems and cameras. The implementation includes all 32 commands from the OpenWebNet specification for video control, zoom, positioning, and image adjustments.

Key Changes:

• New Camera class with support for all WHO=7 commands including video control, zoom, positioning, and image adjustments
• Proper handling of two message formats: commands with WHERE parameter (using NormalMessage) and without WHERE (using GenericMessage)
• Complete documentation, working examples, and comprehensive unit tests

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pyown/items/camera/camera.py	Core camera implementation with Camera class, WhatCamera enum (32 commands), and CameraEvents enum
pyown/items/camera/init.py	Module exports for camera components
pyown/items/init.py	Integration of camera module into items package
tests/items/test_camera.py	Unit tests validating message formats, command values, and class structure
examples/camera_01/main.py	Working example demonstrating camera control usage
examples/camera_01/README.md	Example documentation
docs/api/items/camera.md	Complete API documentation with usage examples
CAMERA_IMPLEMENTATION.md	Detailed implementation summary and design decisions

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The dial_map dictionary is recreated on every call to display_dial(). Consider moving this to a class-level constant to avoid unnecessary allocations on repeated calls.

[github-actions]

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines	Covered	Coverage	Threshold	Status
2113	1301	62%	0%	🟢

New Files

File	Coverage	Status
pyown/items/camera/_init_.py	100%	🟢
pyown/items/camera/camera.py	70%	🟢
tests/items/test_camera.py	100%	🟢
TOTAL	90%	🟢

Modified Files

File	Coverage	Status
pyown/items/_init_.py	100%	🟢
TOTAL	100%	🟢

updated for commit: 675e991 by action🐍

[Copilot]

Pull Request Overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}