ax-devil-device-api 0.6.0

Python library for interacting with Axis device APIs

ax-devil-device-api

A Python library for interacting with Axis device APIs. Provides a type-safe interface with tools for device management, configuration, and integration.

See also: ax-devil-mqtt for using MQTT with an Axis device.

---

📋 Contents

• Feature Overview
• Quick Start
• Development Setup
• Usage Examples
• Disclaimer
• License

---

🔍 Feature Overview

Feature	Description	Python API	CLI Tool
📱 Device Information	Get device details, check health status, and restart device	client.device	ax-devil-device-api device
🔧 Device Debugging	Download server reports, crash reports, and run diagnostics	client.device_debug	ax-devil-device-api debug
📷 Media Operations	Capture snapshots from device cameras	client.media	ax-devil-device-api media
🔐 SSH Management	Add, list, modify, and remove SSH users	client.ssh	ax-devil-device-api ssh
📡 MQTT Client	Configure, activate, deactivate, and check MQTT client status	client.mqtt_client	ax-devil-device-api mqtt
📊 Analytics MQTT	Manage analytics data sources and publishers for MQTT	client.analytics_mqtt	ax-devil-device-api analytics
🔎 API Discovery	List and inspect available APIs on the device	client.discovery	ax-devil-device-api discovery
🌍 Geocoordinates	Get and set device location and orientation	client.geocoordinates	ax-devil-device-api geocoordinates
🚩 Feature Flags	List, get, and set device feature flags	client.feature_flags	ax-devil-device-api features
🌐 Network	Get network interface information	client.network	ax-devil-device-api network

---

🚀 Quick Start

Installation

pip install ax-devil-device-api

Environment Variables

For an easier experience, you can set the following environment variables:

export AX_DEVIL_TARGET_ADDR=<device-ip>
export AX_DEVIL_TARGET_USER=<username>
export AX_DEVIL_TARGET_PASS=<password>
export AX_DEVIL_USAGE_CLI="safe" # Set to "unsafe" to skip SSL certificate verification for CLI calls

---

🛠️ Development Setup

• Create and activate a virtual environment.
• Install the package with development extras (dev dependencies now live in pyproject.toml): pip install -e ".[dev]"
• Run the test suite with pytest (use pytest --cov for coverage).

---

💻 Usage Examples

Python API Usage

import json
from ax_devil_device_api import Client, DeviceConfig

# Initialize client (recommended way using context manager)
config = DeviceConfig.https("192.168.1.81", "root", "pass", verify_ssl=False)
with Client(config) as client:
    device_info = client.device.get_info()
    print(json.dumps(device_info, indent=4))

# Alternative: Manual resource management (not recommended)
client = Client(config)
try:
    device_info = client.mqtt_client.get_state()
    print(json.dumps(device_info, indent=4))
finally:
    client.close()  # Always close the client when done

CLI Usage Examples

🎯 New Unified CLI (Recommended)

The project now provides a unified CLI with organized subcommands:

# Main help - shows all available subcommands
ax-devil-device-api --help

# Check version
ax-devil-device-api --version

# Set common parameters as environment variables for convenience
export AX_DEVIL_TARGET_ADDR=192.168.1.10
export AX_DEVIL_TARGET_USER=admin
export AX_DEVIL_TARGET_PASS=secret

📱 Device Operations

# Get device information
ax-devil-device-api device info

# Check device health
ax-devil-device-api device health

# Restart device (with confirmation)
ax-devil-device-api device restart

# Force restart without confirmation
ax-devil-device-api device restart --force

🔧 Device Debugging

# Download server report
ax-devil-device-api debug download-server-report report.tar.gz

# Download crash report
ax-devil-device-api debug download-crash-report crash.tar.gz

# Run ping test
ax-devil-device-api debug ping-test google.com

📷 Media Operations

# Capture snapshot
ax-devil-device-api media snapshot --output image.jpg

# With custom resolution
ax-devil-device-api media snapshot --resolution 1920x1080 --output snapshot.jpg

🔐 SSH Management

# List SSH users
ax-devil-device-api ssh list

# Add SSH user
ax-devil-device-api ssh add new-user password123 --comment "John Doe"

# Remove SSH user
ax-devil-device-api-ssh --device-ip 192.168.1.10 --device-username admin --device-password secret remove user123

📡 MQTT Client

# Activate MQTT client
ax-devil-device-api-mqtt-client --device-ip 192.168.1.10 --device-username admin --device-password secret activate

# Deactivate MQTT client
ax-devil-device-api-mqtt-client --device-ip 192.168.1.10 --device-username admin --device-password secret deactivate

📊 Analytics MQTT

# List available analytics data sources
ax-devil-device-api-analytics-mqtt --device-ip 192.168.1.10 --device-username admin --device-password secret sources

# List configured publishers
ax-devil-device-api-analytics-mqtt --device-ip 192.168.1.10 --device-username admin --device-password secret list

🔎 API Discovery

# List available APIs
ax-devil-device-api-discovery --device-ip 192.168.1.10 --device-username admin --device-password secret list

# Get API info
ax-devil-device-api-discovery --device-ip 192.168.1.10 --device-username admin --device-password secret info vapix

🌍 Geocoordinates

# Get current location coordinates
ax-devil-device-api geocoordinates location get

# Set location coordinates (latitude, longitude)
ax-devil-device-api geocoordinates location set 59.3293 18.0686

# Apply pending location changes
ax-devil-device-api geocoordinates location apply

# Get device orientation
ax-devil-device-api geocoordinates orientation get

# Set device orientation (pan, tilt, roll)
ax-devil-device-api geocoordinates orientation set 45 30 0

🚩 Feature Flags

# List all feature flags
ax-devil-device-api features list

# Get specific feature flag values
ax-devil-device-api features get flag1 flag2

# Set feature flags
ax-devil-device-api features set flag1=true flag2=false

🌐 Network Operations

# Get network interface information
ax-devil-device-api network info

# Get info for specific interface
ax-devil-device-api network info --interface eth0

Note: All CLI commands support the --help flag to see available options and parameters.

Breaking Change in v1.0: The old individual commands (e.g., ax-devil-device-api-device-info) have been removed. Please use the new unified CLI structure shown above.

---

⚠️ Disclaimer

This project is an independent, community-driven implementation and is not affiliated with or endorsed by Axis Communications AB. For official APIs and development resources, please refer to Axis Developer Community.

📄 License

MIT License - See LICENSE file for details.