🔧

C/C++ Bindings

Integrate ALEC into C/C++ firmware and native applications. Perfect for embedded systems, microcontrollers, and legacy codebases.

C99 Compatible C++11+ No Runtime Dependencies Cross-Platform

Features

Sensor Value Encoding

Single and multi-value compression with automatic priority detection.

Preload Support

Load pre-trained contexts for instant optimal compression on first value.

Checksum Verification

Optional CRC32 checksums for data integrity protection.

Minimal Footprint

~2-4 KB per encoder, no per-encoding allocations.

Building from Source

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

# Build FFI library
cargo build --release -p alec-ffi

# Output files:
# target/release/libalec_ffi.a      (static)
# target/release/libalec_ffi.so     (shared, Linux)
# target/release/libalec_ffi.dylib  (shared, macOS)

Precompiled Binaries

Download precompiled libraries from GitHub Releases. Available for Linux (x86_64, ARM64), macOS (x86_64, ARM64), and Windows.

Basic Example

#include "alec.h"
#include <stdio.h>

int main(void) {
    // Create encoder
    AlecEncoder* enc = alec_encoder_new();

    // Encode a temperature value
    double temperature = 22.5;
    uint8_t buffer[64];
    size_t len;

    AlecResult res = alec_encode_value(
        enc,
        temperature,
        0,              // timestamp (optional)
        NULL,           // source_id (optional)
        buffer,
        sizeof(buffer),
        &len
    );

    if (res == ALEC_OK) {
        printf("Encoded to %zu bytes\n", len);
        // Send buffer[0..len] over LoRaWAN, MQTT, etc.
    } else {
        printf("Error: %s\n", alec_result_to_string(res));
    }

    // Cleanup
    alec_encoder_free(enc);
    return 0;
}

Linking

Linux (GCC)

gcc -o myapp myapp.c -I./include -L./lib -lalec_ffi -lpthread -ldl -lm

macOS (Clang)

clang -o myapp myapp.c -I./include -L./lib -lalec_ffi

API Reference

Encoder Functions

Function	Returns	Description
alec_encoder_new()	AlecEncoder*	Create encoder with default config
alec_encoder_new_with_checksum()	AlecEncoder*	Create encoder with checksum verification
alec_encoder_free(enc)	void	Free encoder (NULL-safe)
alec_encode_value(...)	AlecResult	Encode single sensor value
alec_encode_multi(...)	AlecResult	Encode multiple values at once
alec_encoder_load_context(enc, path)	AlecResult	Load preload file into encoder
alec_encoder_save_context(enc, path, type)	AlecResult	Save encoder context to file

Decoder Functions

Function	Returns	Description
alec_decoder_new()	AlecDecoder*	Create decoder
alec_decoder_new_with_checksum()	AlecDecoder*	Create decoder with checksum verification
alec_decoder_free(dec)	void	Free decoder (NULL-safe)
alec_decode_value(...)	AlecResult	Decode to single value
alec_decode_multi(...)	AlecResult	Decode to multiple values
alec_decoder_load_context(dec, path)	AlecResult	Load preload file into decoder

Result Codes

Code	Value	Description
ALEC_OK	0	Success
ALEC_ERROR_INVALID_INPUT	1	Invalid input data
ALEC_ERROR_BUFFER_TOO_SMALL	2	Output buffer too small
ALEC_ERROR_ENCODING_FAILED	3	Encoding error
ALEC_ERROR_DECODING_FAILED	4	Decoding error
ALEC_ERROR_NULL_POINTER	5	NULL pointer passed
ALEC_ERROR_FILE_IO	7	File I/O error

Using Preloads

Preload files contain pre-trained compression contexts. Load them at startup to achieve optimal compression immediately, without a warm-up period.

AlecEncoder* enc = alec_encoder_new();

// Load pre-trained context for immediate optimal compression
AlecResult res = alec_encoder_load_context(enc, "temperature.alec-context");
if (res != ALEC_OK) {
    fprintf(stderr, "Load failed: %s\n", alec_result_to_string(res));
    return 1;
}

// Encoder now starts with trained model
// First value already benefits from compression!

Thread Safety

! Encoder/decoder instances are not thread-safe
Use one instance per thread, or protect with mutex
No global state in the library

Memory Usage

Encoder	~2-4 KB
Decoder	~1-2 KB
Per encoding	No allocation

Next Steps

Explore more integration options or get commercial support for embedded platforms.

Rust API Reference Full FFI Documentation Commercial Licensing