Documentation

Everything you need to integrate ALEC compression into your IoT infrastructure. From quick start to advanced configuration.

🚀

Getting Started

Quick start guide to integrate ALEC in your project.

📦

ALEC Codec

Core compression engine for IoT sensor data.

📊

ALEC Gateway

Multi-sensor orchestration with metrics.

🔍

ALEC Complexity

Anomaly detection and baseline learning.

🔧

Integration

Connect with your infrastructure.

Installation

Cargo (Rust)

# Add to your Cargo.toml
[dependencies]
alec = "1.0"

From source

# Clone the repository
git clone https://github.com/zeekmartin/alec-codec.git
cd alec-codec

# Build
cargo build --release

# Run tests
cargo test

Basic Usage

ALEC works by maintaining a shared context between encoder and decoder. Here's a minimal example: 

use alec::{Encoder, Decoder, Context, Priority};

fn main() {
    // Create shared context
    let mut ctx = Context::new();
    
    // Encoder side (sensor/device)
    let encoder = Encoder::new(&mut ctx);
    
    // Simulate sensor readings
    let readings = vec![23.5, 23.6, 23.5, 23.7, 28.1];
    
    for value in readings {
        // Encode with automatic priority detection
        let msg = encoder.encode(value, Priority::Auto);
        
        println!("Value: {:.1} -> {} bytes, Priority: {:?}",
            value, msg.len(), msg.priority());
    }
}

Output

Value: 23.5 -> 4 bytes, Priority: P4
Value: 23.6 -> 1 byte, Priority: P5 (delta)
Value: 23.5 -> 1 byte, Priority: P5 (delta)
Value: 23.7 -> 1 byte, Priority: P5 (delta)
Value: 28.1 -> 4 bytes, Priority: P2 (anomaly!)

Encoding Modes

ALEC automatically selects the optimal encoding mode based on your data:

R

Raw

Full value transmission when no prediction is possible or context is uninitialized.

4-8 bytes depending on precision
D

Delta

Only the difference from previous/predicted value. Automatically chooses 8, 16, or 32-bit delta.

1-4 bytes, most common mode
=

Repeated

When value matches previous exactly. Just a marker, no data transmitted.

1 byte (header only)
M

Multi

Batch multiple values in a single message for high-frequency sensors.

Variable, efficient for bursts

Priority System

ALEC classifies every message with a priority level from P1 (critical) to P5 (routine). This enables intelligent data routing and ensures critical events are never delayed.

Priority Name Trigger Action
P1 Critical Safety threshold breach Immediate transmission
P2 Anomaly Unexpected value deviation Priority transmission
P3 Important Significant change Normal transmission
P4 Normal New baseline value Batch if needed
P5 Routine Predictable/repeated Maximum compression 
// Configure priority thresholds
let config = Config::builder()
    .critical_threshold(50.0)      // P1 if value > 50
    .anomaly_sigma(3.0)            // P2 if > 3 std deviations
    .significant_delta(5.0)        // P3 if change > 5
    .build();

let encoder = Encoder::with_config(&mut ctx, config);

Shared Context

The shared context is what makes ALEC different from generic compression. Both encoder and decoder maintain synchronized state that evolves with your data.

Context contains

  • Previous values - for delta encoding
  • Statistical model - mean, variance, trends
  • Pattern dictionary - learned sequences
  • Sequence counter - for synchronization

Synchronization

Context updates are deterministic. Given the same sequence of values, encoder and decoder contexts will always match.

If sync is lost (e.g., packet loss), ALEC includes resync markers to recover without full context reset.

📊

ALEC Gateway

Gateway manages multiple ALEC encoder instances for IoT gateways that aggregate data from many sensors into efficient transmission frames.

Channel Management

Handle up to 64+ sensor channels with individual configuration. Each channel maintains its own ALEC context for optimal compression.

gateway.add_channel("temperature",
  ChannelConfig::with_priority(1))?;
gateway.add_channel("humidity",
  ChannelConfig::with_priority(2))?;

Frame Aggregation

Optimize frame packing for LoRaWAN data rate limits (51-242 bytes). Priority-based aggregation ensures critical data is included first.

let config = GatewayConfig {
    max_frame_size: 242, // DR4-DR5
    ..Default::default()
};

Metrics Module

Enable the metrics feature for entropy-based observability. Monitor system health in real-time.

Metric Description
Total Correlation (TC) Redundancy across channels
Resilience Index (R) System health indicator (0-1)
Criticality (dR_k) Importance of each sensor
Learn more about Gateway →
🔍

ALEC Complexity

Complexity monitoring and anomaly detection for IoT systems. Learns what "normal" looks like and alerts you when things change.

Baseline Learning

Automatically builds a statistical model of your system's normal behavior during an initial learning period (default: 5 minutes).

Z-Score Detection

Computes deviation from baseline using z-scores. Configurable thresholds: 2.0 sigma (warning), 3.0 sigma (critical).

Event System

Emits structured events with persistence and cooldown to prevent alert fatigue. 7 event types for different anomaly patterns.

Event Types

Event Trigger
PayloadEntropySpike H_bytes z-score exceeds threshold
StructureBreak S-lite edges change abruptly
RedundancyDrop R z-score drops below threshold
ComplexitySurge TC/H_joint z-score persists high
Learn more about Complexity →

Integration Guides

📡

MQTT

Integrate with MQTT brokers for pub/sub IoT architectures.
📻

LoRaWAN

Maximize payload efficiency on low-power wide-area networks.
🖥️

Edge Computing

Run ALEC on edge devices for local processing.
🔧

C/C++ Bindings

Integrate ALEC into embedded firmware and native applications.

Resources

API Reference

Complete Rust API documentation on docs.rs

GitHub

Source code, issues, and contributions

Crates.io

Rust package registry

Need help?

Can't find what you're looking for? Our team is here to help with integration questions and custom solutions.

Ask on GitHub Contact Support