Labgrid WebRelayCon

A focused labgrid driver package for WebRelayCon relay controllers.

Overview

This package provides labgrid integration for WebRelayCon relay controllers, implementing the DigitalOutputProtocol for hardware-agnostic relay control. It works seamlessly with labgrid's built-in power and reset drivers.

Installation

pip install labgrid-webrelaycon

For development:

git clone <repository>
cd labgrid-webrelaycon
pip install -e .[dev]  # Installs package + dev dependencies (pytest, build, twine, etc.)

What This Package Provides

WebRelayConDriver

HTTP-based driver for WebRelayCon relay controllers that implements DigitalOutputProtocol.

Features:

• HTTP command interface to WebRelayCon controllers
• Logic inversion support (normally open/closed)
• Cached state tracking
• Configurable timeouts
• Session management

Protocol Compliance: Implements DigitalOutputProtocol so it works with:

• DigitalOutputPowerDriver (built-in labgrid)
• DigitalOutputResetDriver (built-in labgrid)
• Any other driver requiring digital output control

Resources

WebRelayConChannel

Represents a single relay channel on a WebRelayCon controller.

Parameters:

• channel: Relay channel number (1-based)
• invert: Logic inversion (default: False)
• controller_host: IP/hostname of relay controller
• controller_port: HTTP port (default: 80)

WebRelayConController

Represents the complete WebRelayCon controller hardware.

Parameters:

• channels: Total number of relay channels (8 or 16)

Usage Examples

Basic Configuration

Environment file (webrelaycon.yaml):

imports:
  - labgrid_webrelaycon

targets:
  main:
    resources:
      relay1:
        cls: WebRelayConChannel
        host: relay.lab.example.com
        channel: 1
        invert: false

    drivers:
      relay_output:
        cls: WebRelayConDriver
        bindings:
          channel: relay1

Python usage:

from labgrid import Environment

# Load environment
env = Environment("webrelaycon.yaml")
target = env.get_target("main")

# Get driver by name (resolved from environment)
relay = target.get_driver("relay_output")

# Use DigitalOutputProtocol methods
relay.set(True)   # Turn relay on
relay.set(False)  # Turn relay off
state = relay.get()  # Read current state (True/False)

Integration with Built-in Drivers

WebRelayConDriver implements DigitalOutputProtocol, allowing it to work with labgrid's built-in drivers:

imports:
  - labgrid_webrelaycon

targets:
  main:
    resources:
      power_relay:
        cls: WebRelayConChannel
        host: relay.lab.example.com
        channel: 1

    drivers:
      relay_output:
        cls: WebRelayConDriver
        bindings:
          channel: power_relay

      # Use built-in power driver
      power:
        cls: DigitalOutputPowerDriver
        bindings:
          output: relay_output

Python usage:

from labgrid import Environment

env = Environment("config.yaml")
target = env.get_target("main")

# Get driver by name (resolved from environment)
power = target.get_driver("power")

# Use PowerProtocol methods
power.on()
power.off()
power.cycle()

Hardware Compatibility

Supported Controllers

• WebRelayCon 8-channel relay controllers
• WebRelayCon 16-channel relay controllers
• Any HTTP-controlled relay with compatible /30000/{command} API

Command Protocol

WebRelayCon uses sequential command numbers:

• Channel N: off = (N-1) × 2, on = (N-1) × 2 + 1
• Example: Channel 3: off = 4, on = 5
• HTTP GET to http://host:port/30000/{command_number}

Configuration Options

WebRelayConDriver Parameters

• timeout: HTTP request timeout in seconds (default: 5.0)

WebRelayConChannel Parameters

• channel: Relay channel number (1-based, required)
• invert: Invert relay logic (default: False)
• controller_host: Override host from base NetworkResource
• controller_port: HTTP port (default: 80)

Integration Benefits

Protocol Compliance

By implementing DigitalOutputProtocol, WebRelayConDriver works with:

• Any labgrid driver expecting digital output control
• Built-in power and reset drivers
• Custom drivers requiring relay control

Composition Pattern

# Each component has a single responsibility:
WebRelayConDriver         # HTTP relay protocol
DigitalOutputPowerDriver  # Power control logic
JetsonRecoveryDriver     # Jetson-specific recovery sequence

Troubleshooting

Connection Issues

• Verify relay controller IP and port
• Test HTTP endpoint: curl http://relay.lab.example.com/30000/00
• Check network connectivity

Relay Operation

• Verify correct channel numbers (1-based)
• Check if invert parameter is needed for your wiring
• Test individual channels manually

Integration Issues

• Ensure WebRelayCon driver is bound to correct resource
• Verify protocol chain: Resource → WebRelayCon → Power/Reset → High-level operations

Related Packages

• labgrid-jetson: For NVIDIA Jetson recovery mode operations
• Built-in labgrid: For power, reset, and other standard protocols

Development and Publishing

Installing Development Dependencies

Install the package in editable mode with development tools (pytest, build, twine, etc.):

pip install -e .[dev]

Building and Publishing

The project includes a Makefile for building and uploading packages:

make help          # Show available targets
make clean         # Remove build artifacts
make build         # Build wheel and source distribution
make upload-gitea  # Build and upload to Gitea registry
make upload-pypi   # Build and upload to PyPI

Publishing Configuration

Create ~/.pypirc with your registry credentials:

[distutils]
index-servers =
    pypi
    gitea

[pypi]
username = __token__
password = <your-pypi-token>

[gitea]
repository = https://gitea.konsulko.com/api/packages/mporter/pypi
username = mporter
password = <your-gitea-token>

Security: Ensure ~/.pypirc has restricted permissions:

chmod 600 ~/.pypirc

Then publish with:

make upload-gitea  # Upload to Gitea
# or
make upload-pypi   # Upload to PyPI

Note: The version in setup.py must be incremented before uploading a new release, as registries don't allow overwriting existing versions.

License

This project follows the same license as labgrid.

Contributing

Contributions are welcome! Please ensure:

• Code follows existing style
• All drivers use standard labgrid protocols
• Documentation is updated
• Tests pass

Version

Current version: 1.0.0