Jeltz

Gateway core, CLI, serial + MQTT adapters, fleet-level tools, SQLite time-series storage, daemon mode, built-in profiles, and jeltz chat for local LLM interaction — all working. 367 tests passing. See the Getting Started guide to try it.

Your sensors will be processed.

Jeltz is an open source framework that connects AI assistants to physical devices — sensors, actuators, cameras, and edge ML boards — via the Model Context Protocol (MCP).

Write a TOML profile describing your hardware. Jeltz generates an MCP server. Plug in your device. Now any MCP client can reason across your entire sensor fleet.

$ jeltz start -p profiles
✓ Discovered 3 device(s), exposing 15 tools
  ✓ serial_sensor
  ✓ mqtt_sensor
  ✓ pressure_line
✓ MCP server ready on stdio

A dashboard shows you numbers. Jeltz lets an LLM reason about what they mean:

You: Anything weird going on?

LLM: Mostly nominal, but two things worth attention:

1. Tanks 2 and 5 are both climbing at 0.3°C/hr, but tank 5
   started rising 40 minutes after tank 2. They share glycol
   loop B — this looks like a chiller issue, not individual
   tank problems. I'd check the loop B circulation pump.

2. The humidity sensor in Bay 6 has been flatlined at exactly
   45.0% for 9 hours. That's almost certainly a stuck sensor,
   not perfect stability. Recommend recalibration.

Everything else is within baseline.

That's cross-device correlation, anomaly interpretation, and root cause inference — the stuff a Grafana panel can't do.

Why Jeltz exists

Dashboards show you numbers. They require you to know which panel to look at, already suspect something is wrong, and manually correlate across devices. Jeltz gives your sensor fleet a voice.

The MCP ecosystem has hundreds of integrations for SaaS tools — Slack, GitHub, databases, APIs. But nothing for the physical world. Meanwhile, the people with the most data (factories, labs, breweries, farms) are the ones with the least tooling to make sense of it.

Jeltz fixes this by making physical devices first-class participants in the MCP ecosystem. The value isn't "read a sensor value in English" — it's what an LLM can do when it has access to all your devices at once:

• Cross-device reasoning. Correlate readings across sensors to identify shared root causes (failing chiller, not individual tank problems).
• Anomaly interpretation. Not just "this number is red" — but why it's anomalous and what it probably means (stuck sensor vs real reading, bearing wear vs imbalance).
• Multi-step investigation. "Check all sensors on Line 4, find any drifting from their 30-day baseline, and tell me if the drift correlates with the ambient temp sensor." One sentence, 45 minutes of manual work eliminated.
• Proactive insight. An operator who says "anything weird?" gets answers about devices they weren't thinking to check.

How it works

Jeltz runs on a gateway device (Raspberry Pi, laptop, Qualcomm IQ9, any Linux box). It connects to your physical devices over their native protocols (serial, MQTT, USB, HTTP) and exposes them as MCP tools through a single unified endpoint.

The AI stays in the cloud (or on a local LLM). Jeltz is just the plumbing that connects it to your devices. An MCP server is not an AI model — it's a lightweight protocol endpoint. It uses negligible resources on the gateway.

Two types of AI

When Jeltz runs alongside edge ML (e.g., Edge Impulse models on a microcontroller), two complementary AI systems work together:

	Deterministic Model (on-device)	Reasoning Model (LLM via MCP)
What it does	Fast classification / detection	Planning, judgment, orchestration
Speed	Microseconds	Seconds
Role	Reflex — "this is anomalous"	Brain — "here's what to do about it"
Runs on	MCU / DSP	Gateway CPU / NPU / cloud
Deterministic?	Yes	No
Needs context?	No — stateless inference	Yes — history, correlations, goals

Deterministic first, agentic second. A 50KB model on a Cortex-M4 handles routine classification in microseconds. The LLM only engages when something requires judgment — anomalies, cross-device correlations, decisions that need context. Don't waste reasoning cycles on things a tiny model already handles.

Adding devices

There are two ways to connect a device to Jeltz:

Approach	Best for	How it works
TOML profile	Any device with a text command protocol. No firmware changes needed.	You write a .toml file describing the device's commands. Jeltz generates MCP tools from it.
Self-describing (jeltz-arduino)	Arduino/ESP32/Pico W projects where you control the firmware.	The device tells the gateway what it can do. No config files needed on the gateway side.

Both approaches produce the same result — MCP tools that any LLM can call. Pick whichever fits your workflow. You can mix both in the same fleet.

TOML profiles

A device profile is a tool description for the physical world. Think of it like onboarding an AI to a new device — the better the description, the better the agent performs. Write what the device does, how to connect, and what commands it understands. Jeltz generates MCP tools from it.

[device]
name = "fermentation_temps"
description = "Temperature monitoring for 6 fermentation tanks"

[connection]
protocol = "serial"
port = "/dev/ttyUSB0"
baud_rate = 115200
timeout_ms = 3000

[[tools]]
name = "get_reading"
description = "Get current temperature for a specific tank"
command = "READ_TEMP {tank_index}"

[tools.params.tank_index]
type = "int"
min = 0
max = 5

[tools.returns]
type = "float"
unit = "celsius"

[health]
check_command = "PING"
expected = "PONG"
interval_ms = 10000

$ jeltz add-device fermentation_temps.toml
✓ Added fermentation_temps (profiles/fermentation_temps.toml)

$ jeltz test profiles/fermentation_temps.toml
Device:   fermentation_temps
Protocol: serial
Tools:    1
✓ Connected
✓ Health check passed
✓ Disconnected

The device firmware just needs to accept text commands over serial (or MQTT) and respond with plain text. See the built-in profiles for complete firmware examples.

Self-describing devices (jeltz-arduino)

If you control the firmware, you can skip TOML entirely. The jeltz-arduino C++ library lets devices describe their own capabilities to the gateway:

#include <Jeltz.h>

Jeltz babel("dht22_sensor", "DHT22 temp + humidity");

void setup() {
    Serial.begin(115200);

    babel.tool("get_temperature", "Get current temperature")
         .command("READ_TEMP")
         .returns("float", "celsius");

    babel.health("PING", "PONG");
    babel.begin(Serial);
}

Plug in the device and the gateway discovers it automatically — no TOML profile to write or maintain. See the jeltz-arduino README for the full API and examples, or the protocol spec for wire-level details.

Note: Gateway-side auto-discovery (--probe flag) is coming soon. The Arduino library and protocol are ready now.

Built-in profiles

Jeltz ships with profiles for common setups. Each includes complete firmware examples you can flash:

Profile	Protocol	Description
serial_sensor	Serial	Any microcontroller with a text command protocol over USB serial
mqtt_sensor	MQTT	Any WiFi device publishing sensor data over MQTT
mock_sensor	Mock	Simulated sensor for testing and development without hardware

These profiles use temperature + humidity as an example, but the commands and return types are easily adapted to any sensor.

Installation

git clone https://github.com/heath0xFF/jeltz.git
cd jeltz
pip install -e .

Requires Python 3.11+.

Quickstart

For a full walkthrough (wiring, firmware, MCP client setup), see the Getting Started guide.

Quick version:

# Scaffold a new project (creates profiles/ with a mock sensor)
jeltz init myproject && cd myproject

# Test the mock device
jeltz test profiles/mock_sensor.toml

# Check what the gateway sees
jeltz status -p profiles

# Start the MCP server
jeltz start -p profiles

Or chat directly with a local LLM (requires Ollama or any OpenAI-compatible server):

jeltz chat -p profiles -m llama3.2

To use a cloud LLM instead, add Jeltz to your MCP client. For Claude Desktop or Claude Code:

Stdio mode (client manages the process):

{
  "mcpServers": {
    "jeltz": {
      "command": "jeltz",
      "args": ["start", "-p", "/path/to/your/profiles"]
    }
  }
}

Daemon mode (connect to a running jeltz daemon):

{
  "mcpServers": {
    "jeltz": {
      "url": "http://localhost:8374/mcp"
    }
  }
}

CLI

jeltz init [directory]        # Scaffold a new project with mock profile
jeltz start -p profiles      # Start the MCP gateway (stdio transport)
jeltz daemon -p profiles     # Long-running daemon: background recording + HTTP
jeltz chat -p profiles       # Interactive chat with a local LLM
jeltz status -p profiles     # Show connected devices and health
jeltz test <profile.toml>    # Test a single device connection
jeltz add-device <file.toml> # Validate and copy a profile into profiles/

All commands accept -v (INFO) or -vv (DEBUG) for verbose logging.

jeltz chat — local LLM interaction

jeltz chat connects a local LLM to your sensor fleet. It bridges any OpenAI-compatible API (Ollama, llama.cpp, LM Studio, vLLM) to Jeltz's MCP tools in-process. The LLM reasons about your devices; Jeltz executes the tool calls against real hardware.

jeltz chat -p profiles -m llama3.2

✓ Connected to 3 device(s), exposing 15 tools
✓ LLM: llama3.2 via http://localhost:11434/v1
✓ Ready (Ctrl+C to exit)

You: anything weird happening?
  ⚙ fleet.search_anomalies
  ⚙ fleet.get_history(device_id='pressure_line', sensor_id='get_psi', hours=24)

Two things worth looking at:

1. pressure_line PSI has been climbing for 6 hours — up 12% from baseline.
   Check for a downstream restriction or failing relief valve.

2. mqtt_sensor humidity is flatlined at 45.0% for 9 hours.
   Almost certainly a stuck sensor. Recommend recalibration.

Everything else is within normal range.

You:

No internet required. No data leaves the gateway. Works with any model that supports tool calling — just point --api-url at the right endpoint:

Runtime	Command
Ollama	jeltz chat -p profiles (default)
llama.cpp	jeltz chat -p profiles --api-url http://localhost:8080/v1
LM Studio	jeltz chat -p profiles --api-url http://localhost:1234/v1
vLLM	jeltz chat -p profiles --api-url http://localhost:8000/v1

If you have a running jeltz daemon, chat can connect to it remotely instead of starting its own gateway:

jeltz chat --daemon-url http://localhost:8374/mcp -m llama3.2

start vs daemon

jeltz start runs as a subprocess of your MCP client (Claude Desktop, Claude Code, etc.). The client manages the process lifecycle — when the client disconnects, the gateway stops. Good for development and single-client setups.

jeltz daemon runs as a long-lived process. It continuously polls sensors and records readings to the SQLite store, runs periodic retention cleanup, and serves MCP over Streamable HTTP so clients can connect and disconnect without affecting the recording loop. Use this when you want always-on monitoring with persistent history.

jeltz daemon -p profiles --host 0.0.0.0 --port 8374

✓ Discovered 3 device(s), exposing 15 tools
  ✓ serial_sensor
  ✓ mqtt_sensor
  ✓ pressure_line
✓ Background recording active
✓ MCP server ready on http://0.0.0.0:8374/mcp

Use cases

Edge AI development loop. Deploy a model to a dev board with Edge Impulse, then use an LLM of your choice to run inference batches across 50 test samples, generate a confusion matrix, pull raw sensor data for misclassifications, and identify what additional training data you need — all in one conversation instead of a half-day manual investigation.

Small-scale industrial monitoring. A brewery with 6 fermentation tanks and a glycol chiller. A machine shop with vibration sensors on 4 presses. A research lab with 20 environmental monitors. Too small for Azure IoT Hub, too important for a spreadsheet. The LLM correlates across devices, interprets drift patterns, and catches the stuck sensor you wouldn't notice on a dashboard for days.

Natural language commissioning. "I just installed 3 new pressure sensors on the coolant lines. Run a health check on all three, verify they're reading within spec, and set alert thresholds at 15% above their current baseline." One sentence drives a multi-tool workflow: discover, read, calculate, configure.

Air-gapped / local-first deployments. jeltz chat pairs with any local LLM (Ollama, llama.cpp on a Raspberry Pi 5 or Qualcomm IQ9) for fully offline, data-sovereign AI interaction with your equipment. No cloud, no internet, no data leaving the building.

Home automation with brains. Bridge your DIY sensors into any MCP-compatible AI assistant. Not just "turn on the lights" — "the humidity in the basement has been climbing for 3 days and the sump pump hasn't cycled. You might have a drainage issue."

Roadmap

Done: Core framework, serial + MQTT + mock adapters, SQLite time-series storage, fleet-level tools, CLI, built-in profiles, daemon mode, local LLM chat, self-describing device protocol

Next up:

• Gateway-side auto-discovery for self-describing devices (--probe flag)
• Modbus RTU/TCP adapter, OPC-UA adapter
• Actuator safety controls (escalation policy)
• Community profile repository

Later: BLE adapter, CAN bus adapter, USB adapter, Edge Impulse integration, event streaming, web dashboard, alert system

Documentation

• Getting Started — full tutorial: install, wire hardware, flash firmware, connect an MCP client
• Writing Profiles — TOML profile reference: tools, parameters, return types, health checks
• Writing Adapters — how to add support for a new protocol

Development

hatch run test        # Run tests (367 tests, mock adapter, no hardware needed)
hatch run lint        # Ruff linter
hatch run typecheck   # Mypy strict mode

Contributing

Jeltz is built in public. Follow along and contribute:

• Profiles: The easiest way to contribute. Write a TOML profile for hardware you own, test it, submit a PR. See the writing profiles guide.
• Adapters: New protocol support. Implement the BaseAdapter interface for your protocol. See the writing adapters guide.
• Core: Gateway, aggregator, CLI improvements.

Why "Jeltz"?

Named after Prostetnic Vogon Jeltz from The Hitchhiker's Guide to the Galaxy — the captain who processes everything, methodically, without exception. Every tool call, every sensor reading, every health check gets routed, validated, and delivered.

Your sensors will be processed.

License

Apache 2.0