CatLink SDK Development Assistant
An expert AI assistant for working with the catlink_sdk Python project - a Poetry-managed SDK that provides async Python interfaces for CatLink smart pet devices including litter boxes, feeders, scoopers, and water fountains.
What This Skill Does
This skill provides comprehensive guidance for developing, maintaining, and using the catlink_sdk Python package. It helps with Poetry dependency management, SDK architecture, device integration, and implementing new features following the project's async patterns.
Instructions
When working with the catlink_sdk project, follow these guidelines:
1. Project Context Recognition
Identify that this is a Poetry-managed Python 3.11+ projectRecognize the SDK architecture: `CatLinkClient` for authentication and device management, model classes in `models/` for device-specific functionalityUnderstand the reference implementation exists in `vendors/catlink/` from the Home Assistant integrationNote the project structure: main package in `catlink_sdk/`, config in `pyproject.toml`2. Dependency Management Commands
For all package operations, use Poetry:
```bash
Install all dependencies
poetry install
Add runtime dependency
poetry add <package-name>
Add development dependency
poetry add --group dev <package-name>
Update dependencies
poetry update
Show installed packages
poetry show
```
3. Development Workflow
When making changes:
Run Python scripts via `poetry run python <script.py>`Activate the virtual environment with `poetry shell`Run tests (when configured) using `poetry run pytest`Build the package with `poetry build`Main dependencies are: aiohttp (async HTTP), cryptography (password encryption)4. SDK Architecture Understanding
The SDK follows this structure:
**Core Components:**
`client.py` - `CatLinkClient` main class handling authentication and device retrieval`auth.py` - Authentication flow and session management`constants.py` - API endpoints, device types, action mappings**Device Models:**
`models/device.py` - Base `Device` class with common functionality`models/litterbox.py` - Litter box and scooper specific features`models/feeder.py` - Feeder device implementation`models/scooper.py` - Scooper device functionality`models/config.py` - `AdditionalDeviceConfig` for device-specific settings**Supported Device Types:**
`SCOOPER` - Smart litter box with scooping mechanism`LITTER_BOX_599` - Litter box model 599`FEEDER` - Smart pet feeder`WATER_FOUNTAIN` - Smart water fountain (future)5. Device Parameter Support (Latest Updates)
The SDK supports 36+ device parameters including:
**Lighting & Audio:**
`atmosphere_model`, `light_color_model`, `light_color`, `indicator_light``panel_tone`, `warning_tone`**Timing & Scheduling:**
`timing_settings` (array), `near_enable_timing`, `all_timing_toggle``timer_times`, `clear_times`**User Management:**
`master`, `sharers`**Device Information:**
`firmware_version`, `timezone_id`, `gmt`, `real_model``default_status`, `current_message_type`**Advanced Features:**
`auto_update_pet_weight`, `pro_model`, `support_weight_calibration``deodorization_status`, `box_installed`, `sand_type``quiet_enable`, `error_alert_flag`**Product Information:**
`show_buy_btn`, `good_url`, `mall_code`6. Implementing New Features
When adding functionality:
Use async/await patterns consistently (aiohttp-based)Handle device ID field compatibility (`id` vs `deviceId`)Support flexible parameter types (e.g., `weight` can be string like "充足" or numeric)Add device-specific methods to appropriate model classesUpdate `constants.py` for new action types or device typesFollow the existing error handling patterns7. Example Usage Pattern
When demonstrating SDK usage:
```python
import asyncio
from catlink_sdk import CatLinkClient, AdditionalDeviceConfig
async def main():
# Initialize with credentials
client = CatLinkClient(phone="1234567890", password="password")
# Optional device-specific config
device_configs = {
"device_id": AdditionalDeviceConfig(
empty_weight=5.0,
max_samples_litter=24
)
}
# Authenticate and get devices
await client.authenticate()
devices = await client.get_devices(device_configs)
# Device control
for device in devices:
if device.type in ["SCOOPER", "LITTER_BOX_599"]:
await device.set_mode("auto")
await device.execute_action("Cleaning")
print(f"Litter weight: {device.litter_weight} kg")
print(f"Temperature: {device.temperature}°C")
if device.type == "FEEDER":
await device.dispense_food(amount=10)
# Clean up
await client.close()
asyncio.run(main())
```
8. Code Quality Standards
Python 3.11+ requiredKeep dependencies minimalUse type hints where appropriateFollow async best practices (proper session cleanup, error handling)Document new public APIs with docstringsMaintain backward compatibility with existing device parameter handling9. Testing Approach
When tests are configured:
Run with `poetry run pytest`Test async code with pytest-asyncioMock external API callsTest device-specific functionality in isolation10. Build and Distribution
For package distribution:
Build with `poetry build` (creates wheel and sdist)Publish with `poetry publish` (requires PyPI credentials)Version is managed in `pyproject.toml`Key Constraints
Always use Poetry for dependency management (never use pip directly)Maintain Python 3.11+ compatibilityKeep async/await patterns consistent throughoutHandle both `id` and `deviceId` field names from API responsesSupport flexible parameter types (strings, numbers, arrays) as devices may return varied formatsPreserve reference implementation in `vendors/catlink/` for comparisonExamples
Adding a New Device Type
```python
In constants.py
DEVICE_TYPES = {
"WATER_FOUNTAIN": "water_fountain"
}
In models/water_fountain.py
from .device import Device
class WaterFountain(Device):
async def set_flow_rate(self, rate: int):
"""Set water flow rate (1-10)"""
await self.execute_action("SetFlowRate", {"rate": rate})
```
Adding a New Dependency
```bash
For async HTTP library
poetry add aiohttp
For development tools
poetry add --group dev pytest pytest-asyncio
```
Accessing New Device Parameters
```python
device = await client.get_device("device_id")
Lighting control
print(f"Light color: {device.light_color}")
print(f"Indicator status: {device.indicator_light}")
Timing settings
if device.timing_settings:
for timing in device.timing_settings:
print(f"Scheduled: {timing['timingHour']}:{timing['timingMin']}")
Device info
print(f"Firmware: {device.firmware_version}")
print(f"Pro model: {device.pro_model}")
print(f"Litter type: {device.sand_type}")
```