ax-devil-mqtt


Nameax-devil-mqtt JSON
Version 0.1.1 PyPI version JSON
download
home_pageNone
SummaryPython package for setting up and retrieving data from Axis devices using MQTT
upload_time2025-03-18 21:32:59
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseMIT
keywords axis mqtt camera analytics iot
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # ax-devil-mqtt

<div align="center">

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Type Hints](https://img.shields.io/badge/Type%20Hints-Strict-brightgreen.svg)](https://www.python.org/dev/peps/pep-0484/)

Python package for working with Axis devices MQTT functionality.

See also: [ax-devil-device-api](https://github.com/rasmusrynell/ax-devil-device-api) for device API integration.

</div>

---

## 📋 Contents

- [Feature Overview](#-feature-overview)
- [Quick Start](#-quick-start)
- [Usage Examples](#-usage-examples)
- [Disclaimer](#-disclaimer)
- [License](#-license)

---

## 🔍 Feature Overview

<table>
  <thead>
    <tr>
      <th>Feature</th>
      <th>Description</th>
      <th align="center">Python API</th>
      <th align="center">CLI Tool</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><b>🔌 MQTT Connection</b></td>
      <td>Connect to MQTT brokers and Axis devices</td>
      <td align="center"><code>RawMQTTManager</code></td>
      <td align="center"><a href="#mqtt-connection">ax-devil-mqtt device monitor</a></td>
    </tr>
    <tr>
      <td><b>📊 Analytics Streaming</b></td>
      <td>Stream analytics data from Axis devices via MQTT</td>
      <td align="center"><code>AnalyticsManager</code></td>
      <td align="center"><a href="#analytics-streaming">ax-devil-mqtt device monitor</a></td>
    </tr>
    <tr>
      <td><b>💾 Data Recording</b></td>
      <td>Record any MQTT data for later replay and analysis</td>
      <td align="center"><code>manager.start(recording_file)</code></td>
      <td align="center"><a href="#data-recording">ax-devil-mqtt device monitor --record</a></td>
    </tr>
    <tr>
      <td><b>⏯️ Replay</b></td>
      <td>Replay recorded MQTT data for testing and development</td>
      <td align="center"><code>ReplayManager</code></td>
      <td align="center"><a href="#data-replay">ax-devil-mqtt replay</a></td>
    </tr>
  </tbody>
</table>

---

## 🚀 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=<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
```

---

## 💻 Usage Examples

### Python API Usage

🔌 MQTT Connection and Analytics Streaming

```python
import time
from ax_devil_mqtt import AnalyticsManager
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):
    print(message)

# 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

def message_callback(message):
    print(message)

# Create a replay manager
manager = ReplayManager(
    recording_file="recordings/device_recording.jsonl",
    message_callback=message_callback
)

# Start the manager
manager.start()
time.sleep(10)
manager.stop()
```

### CLI Usage Examples

<details open>
<summary><b>🔍 (Optional): Use ax-devil-device-api CLI to find available analytics streams.</b></summary>
<p>

```bash
ax-devil-device-api-analytics-mqtt sources
```
</p>
</details>

<details open>
<summary><a name="mqtt-connection"></a><a name="analytics-streaming"></a><b>📊 Streaming Analytics Data Source</b></summary>
<p>

```bash
ax-devil-mqtt device monitor \
    --device-ip <device-ip> \
    --username <username> \
    --password <password> \
    --broker <broker-ip> \
    --port 1883 \
    --stream "com.axis.analytics_scene_description.v0.beta#1" \
    --duration 3600
```
</p>
</details>

<details>
<summary><a name="data-recording"></a><b>💾 Recording MQTT Data</b></summary>
<p>

```bash
ax-devil-mqtt device monitor \
    --device-ip <device-ip> \
    --username <username> \
    --password <password> \
    --broker <broker-ip> \
    --port 1883 \
    --stream "com.axis.analytics_scene_description.v0.beta#1" \
    --record \
    --duration 3600
```
</p>
</details>

<details>
<summary><a name="data-replay"></a><b>⏯️ Replaying Recorded Data</b></summary>
<p>

```bash
ax-devil-mqtt replay recordings/device_recording.jsonl
```
</p>
</details>

### Example Scripts

<details>
<summary><b>Analytics Monitor Example</b></summary>
<p>

```bash
python src/ax_devil_mqtt/examples/analytics_monitor.py --host <broker-ip>
```
</p>
</details>

<details>
<summary><b>Replay Example</b></summary>
<p>

```bash
python src/ax_devil_mqtt/examples/replay.py recordings/device_recording.jsonl
```
</p>
</details>

> **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.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "ax-devil-mqtt",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "axis, mqtt, camera, analytics, iot",
    "author": null,
    "author_email": "Rasmus Rynell <Rynell.Rasmus@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/bd/12/456441a4c2665e5f78dde3723c5a11876d4dfd6cca952d6eb7037a49184e/ax_devil_mqtt-0.1.1.tar.gz",
    "platform": null,
    "description": "# ax-devil-mqtt\n\n<div align=\"center\">\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Type Hints](https://img.shields.io/badge/Type%20Hints-Strict-brightgreen.svg)](https://www.python.org/dev/peps/pep-0484/)\n\nPython package for working with Axis devices MQTT functionality.\n\nSee also: [ax-devil-device-api](https://github.com/rasmusrynell/ax-devil-device-api) for device API integration.\n\n</div>\n\n---\n\n## \ud83d\udccb Contents\n\n- [Feature Overview](#-feature-overview)\n- [Quick Start](#-quick-start)\n- [Usage Examples](#-usage-examples)\n- [Disclaimer](#-disclaimer)\n- [License](#-license)\n\n---\n\n## \ud83d\udd0d Feature Overview\n\n<table>\n  <thead>\n    <tr>\n      <th>Feature</th>\n      <th>Description</th>\n      <th align=\"center\">Python API</th>\n      <th align=\"center\">CLI Tool</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td><b>\ud83d\udd0c MQTT Connection</b></td>\n      <td>Connect to MQTT brokers and Axis devices</td>\n      <td align=\"center\"><code>RawMQTTManager</code></td>\n      <td align=\"center\"><a href=\"#mqtt-connection\">ax-devil-mqtt device monitor</a></td>\n    </tr>\n    <tr>\n      <td><b>\ud83d\udcca Analytics Streaming</b></td>\n      <td>Stream analytics data from Axis devices via MQTT</td>\n      <td align=\"center\"><code>AnalyticsManager</code></td>\n      <td align=\"center\"><a href=\"#analytics-streaming\">ax-devil-mqtt device monitor</a></td>\n    </tr>\n    <tr>\n      <td><b>\ud83d\udcbe Data Recording</b></td>\n      <td>Record any MQTT data for later replay and analysis</td>\n      <td align=\"center\"><code>manager.start(recording_file)</code></td>\n      <td align=\"center\"><a href=\"#data-recording\">ax-devil-mqtt device monitor --record</a></td>\n    </tr>\n    <tr>\n      <td><b>\u23ef\ufe0f Replay</b></td>\n      <td>Replay recorded MQTT data for testing and development</td>\n      <td align=\"center\"><code>ReplayManager</code></td>\n      <td align=\"center\"><a href=\"#data-replay\">ax-devil-mqtt replay</a></td>\n    </tr>\n  </tbody>\n</table>\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install ax-devil-mqtt\n```\n\n### Environment Variables\nFor an easier experience, you can set the following environment variables:\n```bash\nexport AX_DEVIL_TARGET_ADDR=<device-ip>\nexport AX_DEVIL_TARGET_USER=<username>\nexport AX_DEVIL_TARGET_PASS=<password>\nexport AX_DEVIL_USAGE_CLI=\"safe\" # Set to \"unsafe\" to skip SSL certificate verification for CLI calls\n```\n\n---\n\n## \ud83d\udcbb Usage Examples\n\n### Python API Usage\n\n\ud83d\udd0c MQTT Connection and Analytics Streaming\n\n```python\nimport time\nfrom ax_devil_mqtt import AnalyticsManager\nfrom ax_devil_device_api import DeviceConfig\n\n# Configure device\ndevice_config = DeviceConfig.http(\n    host=\"192.168.1.200\",\n    username=\"root\",\n    password=\"pass\"\n)\n\ndef message_callback(message):\n    print(message)\n\n# Create analytics manager\nmanager = AnalyticsManager(\n    broker_host=\"192.168.1.100\",\n    broker_port=1883,\n    device_config=device_config,\n    analytics_data_source_key=\"com.axis.analytics_scene_description.v0.beta#1\",\n    message_callback=message_callback\n)\n\nmanager.start()\n# or manager.start(recording_file=\"recordings/some_file_name.jsonl\")\ntime.sleep(10)\nmanager.stop()\n```\n\n\u23ef\ufe0f Replay\n\n```python\nimport time\nfrom ax_devil_mqtt import ReplayManager\n\ndef message_callback(message):\n    print(message)\n\n# Create a replay manager\nmanager = ReplayManager(\n    recording_file=\"recordings/device_recording.jsonl\",\n    message_callback=message_callback\n)\n\n# Start the manager\nmanager.start()\ntime.sleep(10)\nmanager.stop()\n```\n\n### CLI Usage Examples\n\n<details open>\n<summary><b>\ud83d\udd0d (Optional): Use ax-devil-device-api CLI to find available analytics streams.</b></summary>\n<p>\n\n```bash\nax-devil-device-api-analytics-mqtt sources\n```\n</p>\n</details>\n\n<details open>\n<summary><a name=\"mqtt-connection\"></a><a name=\"analytics-streaming\"></a><b>\ud83d\udcca Streaming Analytics Data Source</b></summary>\n<p>\n\n```bash\nax-devil-mqtt device monitor \\\n    --device-ip <device-ip> \\\n    --username <username> \\\n    --password <password> \\\n    --broker <broker-ip> \\\n    --port 1883 \\\n    --stream \"com.axis.analytics_scene_description.v0.beta#1\" \\\n    --duration 3600\n```\n</p>\n</details>\n\n<details>\n<summary><a name=\"data-recording\"></a><b>\ud83d\udcbe Recording MQTT Data</b></summary>\n<p>\n\n```bash\nax-devil-mqtt device monitor \\\n    --device-ip <device-ip> \\\n    --username <username> \\\n    --password <password> \\\n    --broker <broker-ip> \\\n    --port 1883 \\\n    --stream \"com.axis.analytics_scene_description.v0.beta#1\" \\\n    --record \\\n    --duration 3600\n```\n</p>\n</details>\n\n<details>\n<summary><a name=\"data-replay\"></a><b>\u23ef\ufe0f Replaying Recorded Data</b></summary>\n<p>\n\n```bash\nax-devil-mqtt replay recordings/device_recording.jsonl\n```\n</p>\n</details>\n\n### Example Scripts\n\n<details>\n<summary><b>Analytics Monitor Example</b></summary>\n<p>\n\n```bash\npython src/ax_devil_mqtt/examples/analytics_monitor.py --host <broker-ip>\n```\n</p>\n</details>\n\n<details>\n<summary><b>Replay Example</b></summary>\n<p>\n\n```bash\npython src/ax_devil_mqtt/examples/replay.py recordings/device_recording.jsonl\n```\n</p>\n</details>\n\n> **Note:** For more examples, check the [examples directory](src/ax_devil_mqtt/examples) in the source code.\n\n---\n\n## \u26a0\ufe0f Disclaimer\n\nThis 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).\n\n## \ud83d\udcc4 License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Python package for setting up and retrieving data from Axis devices using MQTT",
    "version": "0.1.1",
    "project_urls": {
        "Bug Tracker": "https://github.com/rasmusrynell/ax-devil-mqtt/issues",
        "Documentation": "https://github.com/rasmusrynell/ax-devil-mqtt#readme",
        "Homepage": "https://github.com/rasmusrynell/ax-devil-mqtt",
        "Repository": "https://github.com/rasmusrynell/ax-devil-mqtt.git"
    },
    "split_keywords": [
        "axis",
        " mqtt",
        " camera",
        " analytics",
        " iot"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "88f946335d770062f43c71028f694318807f0d8921b1f2d87de9b8a7f850aa09",
                "md5": "94d3e30c873566407b91aa7aed9d2d25",
                "sha256": "944a6efb9e0521d5708212b611a338649a2ed7df7c621141c63ea968c4c89d85"
            },
            "downloads": -1,
            "filename": "ax_devil_mqtt-0.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "94d3e30c873566407b91aa7aed9d2d25",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 16143,
            "upload_time": "2025-03-18T21:32:58",
            "upload_time_iso_8601": "2025-03-18T21:32:58.373501Z",
            "url": "https://files.pythonhosted.org/packages/88/f9/46335d770062f43c71028f694318807f0d8921b1f2d87de9b8a7f850aa09/ax_devil_mqtt-0.1.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "bd12456441a4c2665e5f78dde3723c5a11876d4dfd6cca952d6eb7037a49184e",
                "md5": "42143acf273192832b8adec88712b6e8",
                "sha256": "5b44cb16deb1c7770bba7aef2d29ffae42d24dba4a3a3d6f5791dbd6f34261f4"
            },
            "downloads": -1,
            "filename": "ax_devil_mqtt-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "42143acf273192832b8adec88712b6e8",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 15195,
            "upload_time": "2025-03-18T21:32:59",
            "upload_time_iso_8601": "2025-03-18T21:32:59.243118Z",
            "url": "https://files.pythonhosted.org/packages/bd/12/456441a4c2665e5f78dde3723c5a11876d4dfd6cca952d6eb7037a49184e/ax_devil_mqtt-0.1.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-03-18 21:32:59",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "rasmusrynell",
    "github_project": "ax-devil-mqtt",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "ax-devil-mqtt"
}
        
Elapsed time: 0.47270s