Work with Elodin-DB, the time-series telemetry database. Use when running elodin-db, writing client integrations (C, C++, Rust, Python), configuring replication/follow mode, querying data via the Lua REPL, or connecting the Elodin Editor to a database.
Elodin-DB is a high-performance time-series database for telemetry data. It stores components, messages, and metadata using the Impeller2 protocol, and serves as the central data bus between simulations, flight software, and the Elodin Editor.
# Install (from source)
just install
# Run the database
elodin-db run [::]:2240 $HOME/.local/share/elodin/db --config libs/db/examples/db-config.lua --log-level warn
# Connect the Elodin Editor
elodin editor 127.0.0.1:2240
# Launch the Lua REPL
elodin-db lua
elodin-db run <bind_addr> <data_dir> [--config <lua_file>] [--log-level <level>]
| Parameter | Example | Purpose |
|---|---|---|
bind_addr |
[::]:2240 |
| Listen address (IPv4/IPv6 + port) |
data_dir | $HOME/.local/share/elodin/db | Storage directory |
--config | libs/db/examples/db-config.lua | Lua configuration script |
--log-level | warn | Log verbosity: error, warn, info, debug, trace |
Interactive database shell for debugging and exploration:
elodin-db lua
db> client = connect("127.0.0.1:2240")
db> client:dump_metadata()
db> :help
cc examples/client.c -lm -o /tmp/client && /tmp/client
See libs/db/examples/client.c for streaming fake sensor data.
c++ -std=c++23 examples/client.cpp -o /tmp/client-cpp && /tmp/client-cpp
The C++ library is C++20 compatible. See libs/db/examples/client.cpp for subscription example.
See libs/db/examples/rust_client/ for a complete Rust client using Impeller2.
Generate the single-header C++20 library with message definitions:
cargo run --bin elodin-db gen-cpp > libs/db/examples/db.hpp
Simulations automatically create an embedded database, or connect to an external one:
# Embedded (temporary)
w.run(system)
# Explicit path
w.run(system, db_path="./my_data")
# Connect to external DB
w.run(system, db_addr="127.0.0.1:2240")
Replicate data from one database to another over TCP:
# Source database
elodin-db run [::]:2240 $HOME/.local/share/elodin/source-db
# Follower database (replicates from source)
elodin-db run [::]:2241 $HOME/.local/share/elodin/follower-db --follows 127.0.0.1:2240
The follower:
Default batches outgoing data into ~1500-byte TCP writes (standard Ethernet MTU):
elodin-db run [::]:2241 ./follower-db --follows 127.0.0.1:2240 --follow-packet-size 9000
Run a simulation on source, follow on target, and add local streams:
# Source machine
elodin editor examples/video-stream/main.py
# Target — follow source
elodin-db run [::]:2241 ./follower-db --follows SOURCE_IP:2240
# Target — connect editor
elodin editor 127.0.0.1:2241
# Target — add local video stream
examples/video-stream/stream-video.sh
Combine two databases (e.g. SITL and real telemetry) with optional time alignment and component prefixes.
# Basic merge with prefixes
elodin-db merge -o merged --prefix1 sitl --prefix2 real ./sitl-db ./real-db
# Align using timestamps from the Elodin Editor's playback timeline
elodin-db merge -o merged --prefix1 sitl --prefix2 real \
--align1 15000000 --align2 14000000 --from-playback-start ./sitl-db ./real-db
Use --from-playback-start when alignment timestamps come from the Editor's playback timeline (relative to recording start). Without it, --align1/--align2 are absolute timestamps.
Remove data from the beginning or end of a recording. Values are in microseconds. Without --output, modifies in place.
# Remove the first 3 minutes from a recording
elodin-db trim --from-start 180000000 ./my-db
# Remove the last 2 minutes from a recording
elodin-db trim --from-end 120000000 --output ./trimmed ./my-db
# Trim 1 minute from the start and 2 minutes from the end
elodin-db trim --from-start 60000000 --from-end 120000000 --output ./window ./my-db
# Preview without modifying
elodin-db trim --from-start 180000000 --dry-run ./my-db
The Elodin Editor connects to any running database:
elodin editor 127.0.0.1:2240
From a simulation, the editor connects automatically when launched via elodin editor sim.py.
Elodin-DB uses the Impeller2 protocol internally:
Storage is append-only with configurable retention. The database supports concurrent readers and writers with lock-free data structures.