Asynchronous Python client for Netlink desk and display control.
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.
- 🔌 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
pip install pynetlinkimport 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())📚 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
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}")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# 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 WebSocketdiscover_devices.py- Device discovery with mDNSdesk_state_listener.py- Real-time desk state monitoring
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! 😍
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
Install all packages, including all development requirements:
poetry installPoetry creates by default an virtual environment where it installs all necessary pip packages.
This repository uses the prek framework, all changes are linted and tested with each commit. To setup the prek check, run:
poetry run prek installAnd to run all checks and tests manually, use the following command:
poetry run prek run --all-filesIt uses pytest as the test framework. To run the tests:
poetry run pytestTo update the syrupy snapshot tests:
poetry run pytest --snapshot-updateThis 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.