Skip to content

polarours/ArcticOwl

BranchesTags

Repository files navigation

ArcticOwl

Language: English | δΈ­ζ–‡

ArcticOwl 0.4.0 β€”β€” Integrated edge forwarding, RTMP/HLS distribution, and Flutter monitoring multi-component video pipeline.

Table of Contents

Project Overview

ArcticOwl consists of three native C++ binaries and a Flutter frontend:

  • Edge Device (apps/edge_device): Captures local camera, encodes to JPEG, and forwards to the server via lightweight TCP protocol.
  • Central Server (apps/server): Receives forwarded frames, runs OpenCV detection, broadcasts frames and events to clients, and pushes RTMP to MediaMTX.
  • Flutter Frontend (frontend/flutter_app): REST client, state management, RTMP playback, and device panels.

Current version: v0.4.0.

Project Highlights

  • πŸ—„οΈ Enhanced PostgreSQL Schema: Improved database structure with separate tables for camera devices, sensor devices, and video streams.
  • πŸ” Forwarding Channel: New forward://<device> source type; server receives edge TCP streams on port 7500 and reuses detection/distribution pipeline.
  • πŸ“‘ MediaMTX Integration: Server pushes rtmp://HOST/live/<stream_key>; MediaMTX outputs http://HOST:8080/live/<stream_key>.m3u8 for frontend playback.
  • 🌐 REST Metadata: /api/v1/capture/session/<id> returns stream output config, RTMP addresses, and device info.
  • πŸ“± Flutter Capture Page: Uses Riverpod + media_kit for RTMP/RTSP/HLS playback with metadata display.
  • 🧾 Documentation and Versioning: Semantic version bumped to 0.4.0; README/CHANGELOG/user manual updated.
  • πŸ”₯ Enhanced Detection Algorithms: Added fire detection, gas leak detection, and equipment failure detection on the server side.
  • πŸ–₯️ Unified Command Line Interface: Single entry point for all components with arcticowl --server, arcticowl --edge, and arcticowl --client options.
  • πŸ—‚οΈ Advanced Database Management: New CLI commands for database statistics, table listing, and table descriptions.

Update Highlights

v0.4.0 Highlights

  • πŸ—„οΈ Enhanced PostgreSQL Schema: Improved database structure with separate tables for camera devices, sensor devices, and video streams.
  • πŸ—‚οΈ Advanced Database Management: New CLI commands for database statistics, table listing, and table descriptions.
  • πŸ–₯️ Extended Command Line Interface: Additional device and stream management commands.

v0.3.5 Highlights

  • πŸ–₯️ Unified Command Line Interface: Single entry point for all components with arcticowl --server, arcticowl --edge, and arcticowl --client options.

v0.3.2 Highlights

  • πŸ—„οΈ PostgreSQL Migration: Complete migration from SQLite to PostgreSQL for improved scalability and performance.
  • πŸ” Forwarding Channel: New forward://<device> source type; server receives edge TCP streams on port 7500 and reuses detection/distribution pipeline.
  • πŸ“‘ SRS Integration: Server pushes rtmp://HOST/live/<stream_key>; SRS outputs http://HOST:8080/live/<stream_key>.m3u8 for frontend playback.
  • 🌐 REST Metadata: /api/v1/capture/session/<id> returns stream output config, HLS/RTMP addresses, and device info.
  • πŸ“± Flutter Capture Page: Uses Riverpod + media_kit for RTMP/RTSP/HLS playback with metadata display.
  • 🧾 Documentation and Versioning: Semantic version bumped to 0.3.2; README/CHANGELOG/user manual updated.
  • πŸ”₯ Enhanced Detection Algorithms: Added fire detection, gas leak detection, and equipment failure detection on the server side.

Architecture

ArcticOwl consists of three major components:

  1. Edge Device Agent (arcticowl-edge):

    • Runs on embedded hardware (Raspberry Pi, ESP32, etc.)
    • Captures video feeds from cameras or other sources
    • Encodes and streams video to the server via TCP
    • On boot, the device attempts to register itself into the device registry (PostgreSQL) and then streams frames.

  2. Central Processing Server (arcticowl-server):

    • Receives and decodes video streams from edge devices
    • Performs video analysis using computer vision techniques
    • Detects motion, intrusions, fires, gas leaks, and equipment failures
    • Stores events and metadata in PostgreSQL databases
    • Provides an HTTP API for clients to access processed data

  3. Client Application (arcticowl-client):

    • Cross-platform desktop application (Windows, macOS, Linux)
    • Displays live video feeds and historical events
    • Provides configuration interfaces for devices and alerts
    • Shows analytics dashboards and reports

Data Flow

Camera β†’ Edge Device β†’ TCP Forwarding (7500)
        β†’ Server β†’ StreamDispatcher β†’ RTMP (MediaMTX) β†’ RTMP Stream β†’ Flutter Player

Prerequisites

Database Setup

ArcticOwl uses PostgreSQL for device registry and metadata storage. Before running ArcticOwl, you need to set up a local PostgreSQL database.

Default configuration:

  • Database name: arcticowl_dev
  • Database user: arcticowl_dev
  • Database password: ArcticOwl_Dev!

To set up the database:

  1. Install PostgreSQL:

    # Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS
brew install postgresql

# CentOS/RHEL
sudo yum install postgresql-server postgresql-contrib

  2. Start PostgreSQL service:

    # Ubuntu/Debian/CentOS
sudo systemctl start postgresql
sudo systemctl enable postgresql

# macOS
brew services start postgresql

  3. Create the database and user:

    sudo -u postgres psql

    In the PostgreSQL shell, run:

    CREATE USER arcticowl_dev WITH PASSWORD 'ArcticOwl_Dev!';
CREATE DATABASE arcticowl_dev OWNER arcticowl_dev;
GRANT ALL PRIVILEGES ON DATABASE arcticowl_dev TO arcticowl_dev;
\c arcticowl_dev
GRANT ALL PRIVILEGES ON SCHEMA public TO arcticowl_dev;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO arcticowl_dev;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO arcticowl_dev;
\q

The application will automatically create the required tables on first run.

Quick Start

# 1. Start MediaMTX (keep terminal running).
mediamtx

# 2. Build binaries from repository root.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# 3. Start server (new terminal).
./build/arcticowl --server \
  --enable-rest --http-port 8081 \
  --enable-rtmp --rtmp-url rtmp://127.0.0.1:1935/live/stream \
  --config-db "postgresql://arcticowl_dev:ArcticOwl_Dev!@localhost/arcticowl_dev"

# 4. Start edge device (another terminal).
./build/arcticowl --edge \
  --config-file config/edge_device_profile.json

# 5. (Optional) Run Flutter desktop.
cd frontend/flutter_app
flutter run -d linux

To use a different stream key, modify both the RTMP address accordingly.

Building and Running Components

Server (arcticowl-server)

  • --ingest-port: Edge forwarding listen port (default 7500).
  • --enable-rtmp --rtmp-url: Push stream to MediaMTX or self-hosted media server.
  • --enable-rest --http-port: Start REST service (default 8081).
  • --config-db: PostgreSQL connection string for device registry (default: postgresql://localhost/arcticowl_dev).

Edge Device (arcticowl-edge)

  • Uses config/edge_device_profile.json to configure capture/registration/forwarding parameters.
  • Sends one frame every 100ms by default; adjust frame_interval_ms in config file.
  • To use PostgreSQL, update the uplink.registry_path field in the configuration file to: "registry_path": "postgresql://arcticowl_dev:ArcticOwl_Dev!@localhost/arcticowl_dev"

Flutter Frontend

  • Requires Flutter 3.24+ with desktop support enabled.
  • Pass REST base URL and device ID (e.g. Manjaro) via --dart-define.

Command Line Interface

ArcticOwl provides a unified command-line interface through the arcticowl executable. Run arcticowl --help for detailed usage information.

Database Management

  • --db-stats: Show database statistics
  • --db-list-tables: List all database tables
  • --db-describe-table --table-name <name>: Describe a table structure

Device Management

  • --device-list: List all registered devices
  • --device-register: Register a new device
  • --device-update: Update device configuration (not yet implemented)
  • --device-delete: Delete a device (not yet implemented)

Stream Management

  • --stream-list: List all video streams (not yet implemented)
  • --stream-add: Add a new video stream (not yet implemented)
  • --stream-update: Update a video stream (not yet implemented)
  • --stream-delete: Delete a video stream (not yet implemented)

REST and Streaming APIs

  • REST: GET /api/v1/capture/session/<id> returns device name, stream outputs, RTMP addresses, etc.
  • TCP Forwarding: Edge sends 1-byte type + 4-byte little-endian length + JPEG data.
  • RTMP Push: Server pushes to MediaMTX per parameters.
  • TCP Broadcast: Historical frame/event broadcast still available on port 7000.

Project Structure

apps/
  server/
    main.cpp
    core/
    modules/
  edge_device/
    main_edge.cpp
    core/
    modules/
frontend/
  flutter_app/

Continuous Integration

This project uses GitHub Actions for continuous integration. The workflow includes:

  • Building on Ubuntu, macOS, and Windows
  • Running unit tests
  • Verifying the build process

You can find the workflow configuration in .github/workflows/build.yml.

Troubleshooting

  • Database Connection Issues: Ensure PostgreSQL is running and the database/user have been created as described in the Database Setup section.

  • Build Failures: Make sure all dependencies are installed correctly. Check the platform-specific installation instructions.

  • Runtime Issues: Check logs in the terminal. For Qt-related issues, make sure Qt libraries are properly installed and accessible.

  • PostgreSQL connection failed: could not connect to server.

    • Ensure the PostgreSQL server is running and accessible.
    • Check the connection string in the configuration.

  • PostgreSQL insert failed: duplicate key value violates unique constraint "idx_devices_primary".

    • Only one device can be set as primary. Unset the current primary device first.

  • Can I use a local camera instead of an edge device?

    • Yes. Use --source-type camera --camera-id <n> or register a device in the PostgreSQL registry with kind=camera.

  • Is RTSP output available?

    • Not yet implemented. Current version only supports RTMP (via MediaMTX) and legacy TCP broadcast.

Roadmap

  1. Flutter Real Device List: Implement REST-based DeviceService to replace static fixtures.
  2. Native RTSP/WebRTC Output: Complete RTSP/WebRTC outputs in StreamDispatcher for lower latency.
  3. Recording and Playback: Add optional local recording capability on the server side.
  4. Authentication and Permissions: Add authentication to REST and streaming interfaces for production deployment.
  5. Complete Device and Stream Management: Implement remaining device and stream management CLI commands.

License

MIT License, see LICENSE.

About

An edge-to-cloud video pipeline with RTMP/HLS streaming, REST metadata, and Flutter monitoring.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages