Skip to content

README.md

Latest commit

 

History

History
272 lines (196 loc) · 8.5 KB

README.md

File metadata and controls

272 lines (196 loc) · 8.5 KB
AimDB Logo

Build Status Security Audit Documentation Crates.io License Rust Docs Website

⚠️ PRE-RELEASE v0.1.0
AimDB v0.1.0 is the initial release with core functionality complete. The architecture is stable, but APIs may evolve based on community feedback. Production use is possible but proceed with caution and thorough testing.

One codebase. Any hardware. Always in sync.

AimDB is an async, in-memory database for real-time data synchronization across MCU → edge → cloud — without internal brokers or vendor lock-in. Built in Rust with no_std support for embedded systems.

🚀 Why AimDB?

Modern IoT stacks are fragmented:

  • Multiple brokers/databases to sync MCU, edge, and cloud
  • Device-specific integrations that make hardware swaps risky
  • Batch-oriented pipelines that miss real-time insights

AimDB simplifies this:

  • Fast: Lock-free buffers + async transforms for <50ms reactivity
  • Portable: Works on MCUs (Embassy), edge (Tokio), and cloud
  • Flexible: Three buffer types (SPMC Ring, SingleLatest, Mailbox) for different patterns
  • Protocol-agnostic: MQTT bridges ready, Kafka/DDS planned

🧩 Architecture

  • Language: Rust 🦀 (async/await, no_std capable)
  • Runtimes: Embassy (embedded) or Tokio (std)
  • Data Core: Type-safe records with TypeId routing, three buffer types
  • Protocols: MQTT ✅, Kafka 🚧, DDS 🚧
  • Platforms: MCUs, Linux edge devices, cloud VMs/containers

🎉 What's New in v0.1.0

Initial Release - November 6, 2025

This is the first public release of AimDB! Highlights include:

  • ✅ Type-Safe Core: TypeId-based record routing eliminates runtime string lookups
  • ✅ Dual Runtime: Works on both Tokio (std) and Embassy (no_std/embedded)
  • ✅ Three Buffer Types: SPMC Ring, SingleLatest, and Mailbox patterns
  • ✅ MQTT Integration: Connector works in both std and embedded environments
  • ✅ Developer Tools: MCP server for LLM-powered debugging, CLI tools, and client library
  • ✅ Production Ready: Comprehensive tests, CI/CD, security audits, and documentation

See CHANGELOG.md for complete details.

📦 Installation

Add AimDB to your project:

# For standard library (Tokio runtime)
[dependencies]
aimdb-core = "0.1"
aimdb-tokio-adapter = "0.1"

# Optional: MQTT connector
aimdb-mqtt-connector = { version = "0.1", features = ["tokio-runtime"] }

# Optional: Synchronous API
aimdb-sync = "0.1"

For embedded systems using Embassy:

[dependencies]
aimdb-core = { version = "0.1", default-features = false }
aimdb-embassy-adapter = { version = "0.1", default-features = false, features = ["embassy-runtime"] }
aimdb-mqtt-connector = { version = "0.1", default-features = false, features = ["embassy-runtime"] }

🏃 Quick Start

Option 1: Use the Dev Container (Recommended)

The fastest way to get started with a complete development environment:

# Clone the repository
git clone https://github.com/aimdb-dev/aimdb.git
cd aimdb

# Open in VS Code and reopen in container
code .  # Then: Dev Containers: Reopen in Container

# Build and test
make check

# Run an example
cargo run --example tokio-mqtt-connector-demo --features tokio-runtime,tracing

Option 2: Local Development

Prerequisites: Rust 1.75+ (2021 edition)

# Clone and build
git clone https://github.com/aimdb-dev/aimdb.git
cd aimdb
cargo build --all-features

# Run tests
make test

# Generate documentation
make doc

Basic Usage

use aimdb_core::{AimDbBuilder, DbResult, Producer, RuntimeContext};
use aimdb_core::buffer::BufferCfg;
use aimdb_tokio_adapter::{TokioAdapter, TokioRecordRegistrarExt};
use std::sync::Arc;

#[derive(Debug, Clone)]
struct Temperature { celsius: f32 }

// Producer: generates temperature readings
async fn temperature_producer(
    ctx: RuntimeContext<TokioAdapter>,
    producer: Producer<Temperature, TokioAdapter>,
) {
    let temp = Temperature { celsius: 23.5 };
    producer.produce(temp).await.ok();
}

#[tokio::main]
async fn main() -> DbResult<()> {
    let runtime = Arc::new(TokioAdapter::new()?);
    
    let mut builder = AimDbBuilder::new().runtime(runtime);
    
    builder.configure::<Temperature>(|reg| {
        reg.buffer(BufferCfg::SpmcRing { capacity: 32 })
           .source(temperature_producer);
    });
    
    builder.run().await
}

For complete examples with consumers and MQTT integration, see the /examples directory.

📦 Buffer Types

Choose the right buffer for your data pattern:

1. SPMC Ring - High-frequency telemetry (100+ Hz sensors, logs)

reg.buffer_sized::<100>(BufferType::SpmcRing);

Multiple consumers read independently. Handles lag with explicit notifications.

2. SingleLatest - Configuration & state (UI sync, feature flags)

reg.buffer_sized::<10>(BufferType::SingleLatest);

Only newest value matters. Consumers skip intermediate updates automatically.

3. Mailbox - Commands & control (device control, RPC)

reg.buffer_sized::<1>(BufferType::Mailbox);

Single slot with overwrite. Latest command wins.

Runtime Agnostic: Same API works on Tokio (std) and Embassy (no_std).

🚧 Roadmap

✅ Completed:

  • Core database with type-safe records
  • Tokio & Embassy runtime adapters
  • Three buffer types with simplified API
  • MQTT connector (std and embedded)
  • MCP server for LLM-powered introspection
  • CLI tools (basic implementation)
  • Remote access protocol (AimX v1)
  • Synchronous API wrapper
  • Comprehensive CI/CD and security auditing

🔨 In Progress:

  • Performance benchmarks and optimization
  • Kafka connector (std environments)

📋 Planned:

  • DDS connector for real-time systems
  • HTTP/REST bridge
  • Advanced observability and metrics
  • Multi-instance clustering

🤝 Contributing

We welcome contributions! AimDB is open source and community-driven.

Ways to contribute:

  • 🐛 Report bugs and request features via GitHub Issues
  • 💡 Join discussions on design and architecture
  • 📝 Improve documentation and examples
  • 🔧 Submit pull requests with bug fixes or features
  • ⭐ Star the repo to show your support!

Getting Started:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-idea
  3. Make your changes and add tests
  4. Run make check to validate (fmt + clippy + tests)
  5. Submit a PR with a clear description

See CONTRIBUTING.md for detailed guidelines, coding standards, and development workflow.

🌟 Community & Support

📚 Documentation

  • Changelog: See CHANGELOG.md for release history
  • Examples: Check /examples for working demos:
    • tokio-mqtt-connector-demo - Full MQTT integration with Tokio
    • embassy-mqtt-connector-demo - Embedded MQTT on RP2040
    • sync-api-demo - Synchronous API wrapper usage
    • remote-access-demo - Cross-process introspection server
  • Design Docs: See /docs/design for architecture details
  • API Docs: Run make doc to generate rustdoc
  • Contributing: Read CONTRIBUTING.md for guidelines

� License

Licensed under Apache License 2.0. See LICENSE for details.

Let's build the future of edge intelligence — together!