pynetlink 1.4.0

Async Python client for NetLink desk and display control

Asynchronous Python client for NetLink desk and display control.

About

NetLink is the operating software for smart standing desks, developed by NetOS. The system powers smart desks in commercial office environments, most notably at Mr.Green Offices locations throughout the Netherlands.

This Python package provides a modern, fully typed client for controlling NetLink-equipped desks. It offers both WebSocket (for real-time state updates and fast commands) and REST API support, making it ideal for integration with Home Assistant and other automation systems.

Target Audience: This package is primarily intended for organizations and developers working with NetLink-equipped office environments. While publicly available on PyPI, the NetLink system itself is designed for commercial office spaces.

Key Features

• 🔌 Real-time state updates via WebSocket (desk position, display settings)
• ⚡ Fast WebSocket commands with acknowledgements (~50% faster than REST)
• 🔄 Smart transport - automatic fallback from WebSocket to REST when needed
• 🔍 mDNS/Zeroconf discovery - automatically find NetLink devices on your network
• 📦 Type-safe with full type hints and mashumaro data models
• 🏠 Home Assistant ready with auto-reconnection and exponential backoff
• ⚡ Async-first using modern Python async/await patterns
• 🧪 Production-ready with 100% test coverage

Installation

pip install pynetlink

Quick Start

import asyncio
from pynetlink import NetlinkClient

async def main() -> None:
    """Quick start example."""
    async with NetlinkClient("192.168.1.100", "your-token") as client:
        # Connect via WebSocket for real-time updates
        await client.connect()

        # Get current desk state
        if client.desk_state:
            print(f"Desk height: {client.desk_state.height}cm")

        # Control desk (automatically uses WebSocket when connected)
        await client.set_desk_height(120.0)

        # Control displays
        await client.set_display_brightness(bus_id=0, brightness=80)

        # Optional: Force specific transport if needed
        await client.set_desk_height(110.0, transport="rest")

if __name__ == "__main__":
    asyncio.run(main())

Documentation

📚 Complete Examples & Documentation

The examples folder contains comprehensive guides for:

• Device discovery with mDNS
• Real-time WebSocket events
• Desk control (height, calibration, presets)
• Display control (power, brightness, volume, input source)
• Browser control
• Error handling
• Advanced usage patterns

Usage Examples

Discover Devices

from pynetlink import NetlinkClient

# Auto-discover devices on network
devices = await NetlinkClient.discover_devices(discovery_timeout=5.0)
for device in devices:
    print(f"Found: {device.device_name} at {device.host}")

Real-time Events

async with NetlinkClient(host, token) as client:
    await client.connect()

    @client.on("desk.state")
    async def on_desk_state(data: dict) -> None:
        print(f"Desk: {data['height']}cm")

    await asyncio.sleep(60)  # Listen for events

Control Desk & Displays

# Desk control
await client.set_desk_height(120.0)
await client.stop_desk()
await client.calibrate_desk()

# Display control
displays = await client.get_displays()
await client.set_display_power(bus_id=0, state="on")
await client.set_display_brightness(bus_id=0, brightness=80)
await client.set_display_source(bus_id=0, source="HDMI1")

More examples:

• basic_usage.py - Comprehensive usage with REST and WebSocket
• discover_devices.py - Device discovery with mDNS
• desk_state_listener.py - Real-time desk state monitoring

Read Current Daily Access Codes

async with NetlinkClient(host, token) as client:
    access_codes = await client.get_access_codes()
    if access_codes.web_login:
        print(access_codes.web_login.code)
    if access_codes.signing_maintenance:
        print(access_codes.signing_maintenance.valid_until)

This uses the privileged admin endpoint GET /api/v1/admin/access-codes and therefore requires the device REST_BEARER_TOKEN. web_login or signing_maintenance can be omitted when that login does not expose a current daily code.

Contributing

This is an active open-source project. We are always open to people who want to use the code or contribute to it.

We've set up a separate document for our contribution guidelines.

Thank you for being involved! :heart_eyes:

Setting up development environment

The simplest way to begin is by utilizing the Dev Container feature of Visual Studio Code or by opening a CodeSpace directly on GitHub. By clicking the button below you immediately start a Dev Container in Visual Studio Code.

This Python project relies on Poetry as its dependency manager, providing comprehensive management and control over project dependencies.

You need at least:

• Python 3.12+
• Poetry

Installation

Install all packages, including all development requirements:

poetry install

Poetry creates by default an virtual environment where it installs all necessary pip packages.

Prek

This repository uses the prek framework, all changes are linted and tested with each commit. To setup the prek check, run:

poetry run prek install

And to run all checks and tests manually, use the following command:

poetry run prek run --all-files

Testing

It uses pytest as the test framework. To run the tests:

poetry run pytest

To update the syrupy snapshot tests:

poetry run pytest --snapshot-update

License

This project is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). See the LICENSE file for details.