Skip to content

Development Guide

This guide covers the development environment, tooling, and coding standards for contributing to the Meraki Dashboard Home Assistant integration.

Development Setup

Prerequisites

  • Python 3.14.2+
  • uv - the package manager every recipe uses; there is no Poetry path
  • Just command runner
  • Git

Dev Setup

  1. Clone the Repository

    git clone https://github.com/YOUR_USERNAME/meraki-dashboard-ha.git
cd meraki-dashboard-ha

  2. Install Dependencies

    just setup

  3. Install Pre-commit Hooks just setup installs both the pre-commit and commit-message hooks.

Development Workflow

  1. Make Changes
  2. Edit code in custom_components/meraki_dashboard/

  3. Add tests in tests/

  4. Run Tests

    just test
just coverage  # With coverage report

  5. Lint and Format

    just lint      # Run Ruff and Bandit
just fmt       # Format code with Ruff

  6. Type Check

    just typecheck

  7. Security Check

    just audit

Testing Your Integration

With Home Assistant

  1. Copy your integration to your HA config directory:

    cp -r custom_components/meraki_dashboard /path/to/homeassistant/config/custom_components/

  2. Restart Home Assistant

  3. Add the integration via the UI:

  4. Go to Settings → Devices & Services → Add Integration
  5. Search for "Meraki Dashboard"

Unit Tests

# Run all tests
just test

# Run specific test file
just test filter=tests/test_sensor.py

# Run with coverage
just coverage

Integration Tests

# Test with real API (requires valid API key)
python test_integration.py

Code Style and Standards

This project follows Home Assistant's development standards and our comprehensive naming conventions:

Python Style

  • Formatting: Ruff with 88-character line length (replaces Black)
  • Linting: Ruff for code quality (replaces flake8, isort, and other tools)
  • Type Hints: Required for all functions
  • Docstrings: Google-style docstrings
  • Async/Await: Use for all I/O operations
  • Naming: Follow our naming conventions guide for consistency

Home Assistant Conventions

  • Use Home Assistant's built-in helpers and utilities
  • Follow entity naming conventions
  • Implement proper error handling with ConfigEntryAuthFailed and ConfigEntryNotReady
  • Use update coordinators for efficient data fetching
  • Create devices for physical hardware, entities for individual metrics

Git Workflow

  1. Create Feature Branch

    git checkout -b feature/your-feature-name

  2. Make Changes and Test

    # Make your changes
just test
just lint

  3. Commit with Conventional Commits

    git commit -m "feat: add new sensor type for air quality"
git commit -m "fix: resolve authentication timeout issue"
git commit -m "docs: update configuration examples"

  4. Push and Create PR

    git push origin feature/your-feature-name

Project Structure

meraki-dashboard-ha/
├── .vscode/                # VS Code configuration
│   ├── settings.json       # Editor settings
│   ├── launch.json         # Debug configurations
│   ├── tasks.json          # Task definitions
│   └── extensions.json     # Recommended extensions
├── custom_components/      # Integration source code
│   └── meraki_dashboard/
├── tests/                  # Test files
├── docs/                   # Documentation
├── pyproject.toml          # Python project config
├── justfile               # Development commands
└── README.md              # Project overview

Adding New Features

Adding a New Sensor Type

  1. Add Constants (const.py)

    SENSOR_NEW_TYPE = "new_type"

  2. Add Sensor Description (sensor.py or binary_sensor.py)

    MerakiSensorEntityDescription(
    key=SENSOR_NEW_TYPE,
    name="New Type",
    # ... other properties
)

  3. Update Icons (icons.json)

    {
    "entity": {
        "sensor": {
            "new_type": "mdi:new-icon"
        }
    }
}

  4. Add Tests

    # tests/test_sensor.py
async def test_new_type_sensor():
    # Test implementation

Adding New Device Support

  1. Update device discovery logic in coordinator.py
  2. Add device-specific entity descriptions
  3. Update documentation
  4. Add comprehensive tests

Troubleshooting

Development Issues

  • Import errors: Ensure PYTHONPATH includes the project root
  • Test failures: Check that all dependencies are installed
  • Linting errors: Run just fmt to auto-fix formatting issues

Home Assistant Issues

  • Integration not loading: Check Home Assistant logs for errors
  • API errors: Verify your Meraki API key and permissions
  • Entity not updating: Check coordinator update intervals and API rate limits

Getting Help

  • Issues: Create an issue on GitHub with detailed information
  • Discussions: Use GitHub Discussions for questions and ideas
  • Documentation: Check the docs/ directory for more information

Logging Configuration

Default logging behavior

The integration follows Home Assistant logging best practices:

  • ERROR: Only critical errors that affect functionality
  • WARNING: Potential issues or misconfigurations
  • INFO: Limited to important operational information
  • DEBUG: Detailed operational information (only when enabled)

Third-party library logging

The integration automatically suppresses verbose third-party library logging:

  • Meraki Python SDK: Suppressed to ERROR level only
  • urllib3/requests: Suppressed to ERROR level only

Enable debug logging

Add to configuration.yaml for troubleshooting:

logger:
  default: warning
  logs:
    # Enable debug for the integration
    custom_components.meraki_dashboard: debug

    # Optionally enable for third-party libraries (very verbose)
    meraki: debug
    urllib3.connectionpool: debug

Log level examples

Minimal logging (production)

logger:
  default: warning
  logs:
    custom_components.meraki_dashboard: warning

Standard logging (most users)

logger:
  default: warning
  logs:
    custom_components.meraki_dashboard: info

API Reference

Device data structures

MT Environmental Sensor Data

{
    "serial": "Q2XX-XXXX-XXXX",
    "model": "MT20",
    "networkId": "N_123456789",
    "productType": "sensor",
    "readings": [
        {
            "metric": "temperature",
            "value": 22.5,
            "ts": "2024-01-15T10:30:00Z"
        },
        {
            "metric": "humidity",
            "value": 45.2,
            "ts": "2024-01-15T10:30:00Z"
        }
    ]
}

Sensor mappings

Environmental sensors

SENSOR_MAPPINGS = {
    "temperature": {
        "device_class": SensorDeviceClass.TEMPERATURE,
        "unit": UnitOfTemperature.CELSIUS,
        "state_class": SensorStateClass.MEASUREMENT
    },
    "humidity": {
        "device_class": SensorDeviceClass.HUMIDITY,
        "unit": PERCENTAGE,
        "state_class": SensorStateClass.MEASUREMENT
    },
    "co2": {
        "device_class": SensorDeviceClass.CO2,
        "unit": CONCENTRATION_PARTS_PER_MILLION,
        "state_class": SensorStateClass.MEASUREMENT
    }
}

Binary sensors

BINARY_SENSOR_MAPPINGS = {
    "water_present": {
        "device_class": BinarySensorDeviceClass.MOISTURE
    },
    "door_open": {
        "device_class": BinarySensorDeviceClass.DOOR
    }
}

Entity naming conventions

Sensor entities: sensor.{device_model}_{location}_{metric} - Example: sensor.mt20_office_temperature

Binary sensor entities: binary_sensor.{device_model}_{location}_{metric} - Example: binary_sensor.mt15_basement_water_present

Device entities: {network_name} - {device_type} - Example: Main Office - MT

Error handling

Authentication errors

raise ConfigEntryAuthFailed("Invalid API key")

Connection errors

raise ConfigEntryNotReady("Unable to connect to Meraki API")

Rate limiting

await asyncio.sleep(60)  # Back off for rate limits

Contributing Guidelines

  1. Follow the Code Style: Use the provided linting and formatting tools
  2. Write Tests: All new features should include tests
  3. Update Documentation: Document new features and changes
  4. Use Conventional Commits: Follow the commit message format
  5. Test Thoroughly: Test with real Home Assistant installation

Thank you for contributing to the Meraki Dashboard Home Assistant integration! 🎉