https://github.com/rasmusrynell/ax-devil-mqtt
Python package for working with Axis devices MQTT functionality.
https://github.com/rasmusrynell/ax-devil-mqtt
api ax-devil axis axis-communications axis-scene-description axis-scene-metadata camera cli library metadata mqtt python python3
Last synced: 12 months ago
JSON representation
Python package for working with Axis devices MQTT functionality.
- Host: GitHub
- URL: https://github.com/rasmusrynell/ax-devil-mqtt
- Owner: RasmusRynell
- License: mit
- Created: 2025-02-16T23:05:13.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-25T19:50:41.000Z (12 months ago)
- Last Synced: 2025-06-25T20:34:43.648Z (12 months ago)
- Topics: api, ax-devil, axis, axis-communications, axis-scene-description, axis-scene-metadata, camera, cli, library, metadata, mqtt, python, python3
- Language: Python
- Homepage:
- Size: 153 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ax-devil-mqtt
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/dev/peps/pep-0484/)
Python package for retrieving analytics data from Axis devices over MQTT.
See also: [ax-devil-device-api](https://github.com/rasmusrynell/ax-devil-device-api) for device API integration.
---
## 📋 Contents
- [Feature Overview](#-feature-overview)
- [Quick Start](#-quick-start)
- [Usage Examples](#-usage-examples)
- [Disclaimer](#-disclaimer)
- [License](#-license)
---
## 🔍 Feature Overview
Feature
Description
Python API
CLI Tool
🔌 Device Setup
Configure Axis devices for analytics MQTT publishing
RawMQTTManager
ax-devil-mqtt device monitor
📊 Analytics Streaming
Stream analytics data from Axis devices with automated setup
AnalyticsManager
ax-devil-mqtt device monitor
💾 Data Recording
Record analytics MQTT data for later replay and analysis
manager.start(recording_file)
ax-devil-mqtt device monitor --record
⏯️ Replay
Replay recorded MQTT data for testing and development
ReplayManager
ax-devil-mqtt replay
---
## 🚀 Quick Start
### Installation
```bash
pip install ax-devil-mqtt
```
### Environment Variables
For an easier experience, you can set the following environment variables:
```bash
export AX_DEVIL_TARGET_ADDR=
export AX_DEVIL_TARGET_USER=
export AX_DEVIL_TARGET_PASS=
export AX_DEVIL_USAGE_CLI="safe" # Set to "unsafe" to skip SSL certificate verification for CLI calls
```
---
## 💻 Usage Examples
### Python API Usage
🔌 MQTT Connection and Analytics Streaming
```python
import time
from ax_devil_mqtt import AnalyticsManager
from ax_devil_mqtt.core.types import Message
from ax_devil_device_api import DeviceConfig
# Configure device
device_config = DeviceConfig.http(
host="192.168.1.200",
username="root",
password="pass"
)
def message_callback(message: Message):
print(f"Topic: {message.topic}")
print(f"Payload: {message.payload}")
print(f"Timestamp: {message.timestamp}")
# Create analytics manager
manager = AnalyticsManager(
broker_host="192.168.1.100",
broker_port=1883,
device_config=device_config,
analytics_data_source_key="com.axis.analytics_scene_description.v0.beta#1",
message_callback=message_callback
)
manager.start()
# or manager.start(recording_file="recordings/some_file_name.jsonl")
time.sleep(10)
manager.stop()
```
⏯️ Replay
```python
import time
from ax_devil_mqtt import ReplayManager
from ax_devil_mqtt.core.types import Message, ReplayStats
def message_callback(message: Message):
print(f"Topic: {message.topic}")
print(f"Payload: {message.payload}")
print(f"Timestamp: {message.timestamp}")
def on_replay_complete(stats: ReplayStats):
print(f"Replay completed!")
print(f" Total messages: {stats.message_count}")
print(f" Average drift: {stats.avg_drift:.2f}ms")
print(f" Max drift: {stats.max_drift:.2f}ms")
# Create a replay manager
manager = ReplayManager(
recording_file="recordings/device_recording.jsonl",
message_callback=message_callback,
on_replay_complete=on_replay_complete
)
# Start the manager
manager.start()
time.sleep(10)
manager.stop()
```
### CLI Usage Examples
🔍 Discover Available Analytics Streams
Using ax-devil-device-api:
```bash
ax-devil-device-api-analytics-mqtt sources
```
Or discover and list with ax-devil-mqtt:
```bash
ax-devil-mqtt device list-sources --device-ip --username --password
```
📊 Streaming Analytics Data Source
```bash
ax-devil-mqtt device monitor \
--device-ip \
--username \
--password \
--broker \
--port 1883 \
--stream "com.axis.analytics_scene_description.v0.beta#1" \
--duration 3600
```
```bash
ax-devil-mqtt device monitor \
--device-ip \
--username \
--password \
--broker \
--port 1883 \
--stream "com.axis.analytics_scene_description.v0.beta#1" \
--record \
--duration 3600
```
```bash
ax-devil-mqtt replay recordings/device_recording.jsonl
```
### Example Scripts
Analytics Monitor Example
```bash
python src/ax_devil_mqtt/examples/analytics_monitor.py --host
```
Replay Example
```bash
python src/ax_devil_mqtt/examples/replay.py recordings/device_recording.jsonl
```
> **Note:** For more examples, check the [examples directory](src/ax_devil_mqtt/examples) in the source code.
---
## ⚠️ 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](https://www.axis.com/en-us/developer).
## 📄 License
MIT License - See [LICENSE](LICENSE) file for details.