acommand-edge
OfficialREADME.md
# Acommand Edge Gateway
**Read device telemetry. Give AI agents useful, bounded context.**
[中文说明](README.zh-CN.md) · [Acommand AI](https://acommandai.com) ·
[Research and sources](docs/research.md) · [Third-party notices](THIRD_PARTY_NOTICES.md)
Acommand Edge Gateway is an MIT-licensed Python integration starter connecting
MQTT messages and Modbus TCP readings to a local telemetry store and a read-only
Model Context Protocol (MCP) interface. It includes synthetic factory, port, and
warehouse examples for learning and prototyping.
Version **0.1.0** is a development starter, not a production industrial control
system. It does not operate equipment, include a language model, or call a paid
AI API. The demo needs no hardware, credentials, or runtime dependencies beyond
Python **3.11+**.
## What is included
- Validated numeric telemetry with explicit site, device, metric, unit, and time.
- SQLite storage; exact event replays are ignored, while changed data using an
existing event ID for the same site/device is rejected.
- Unit-aware threshold rules and stored alerts.
- Optional MQTT subscriber and single-register, read-only Modbus TCP adapter.
- Four read-only MCP tools over local stdio, using an existing database.
- Synthetic examples and tests for the core, connectors, and MCP interface.
```mermaid
flowchart TD
MQTT["MQTT messages"] --> Validate["Validate telemetry"]
Modbus["Modbus register"] --> Validate
Demo["Synthetic examples"] --> Validate
Validate --> Store["SQLite telemetry"]
Validate --> Rules["Threshold rules"]
Rules --> Store
Store --> CLI["CLI queries"]
Store --> MCP["Read-only MCP tools"]
MCP --> Host["AI client"]
```
## Quick start
```bash
git clone https://github.com/AcommandAIGroup/acommand-edge-gateway.git
cd acommand-edge-gateway
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
acommand-edge --db ./data/demo.db demo --scenario factory
acommand-edge --db ./data/demo.db devices
acommand-edge --db ./data/demo.db latest factory-demo motor-01
acommand-edge --db ./data/demo.db history factory-demo motor-01 bearing_temperature --limit 50
acommand-edge --db ./data/demo.db alerts --site factory-demo --device motor-01 --limit 50
```
On Windows, activate the environment with `.venv\Scripts\Activate.ps1` in
PowerShell. The `--db` option goes **before** the subcommand. The demo creates
the database and adds new synthetic events each time it runs; it is not a live
device feed.
| Scenario | Command suffix | Site | Device | Example metric |
| --- | --- | --- | --- | --- |
| Factory | `demo --scenario factory` | `factory-demo` | `motor-01` | `bearing_temperature` in `C` |
| Port | `demo --scenario port` | `port-demo` | `crane-01` | `vibration_rms` in `mm/s` |
| Warehouse | `demo --scenario warehouse` | `warehouse-demo` | `cold-room-01` | `temperature` in `C` |
Thresholds and measurements are illustrative, not manufacturer limits or
evidence of predictive maintenance performance.
## Telemetry format and JSONL ingestion
Each event requires **exactly** these seven fields:
```json
{
"event_id": "sample-001",
"site_id": "factory-demo",
"device_id": "motor-01",
"metric": "bearing_temperature",
"value": 78.0,
"unit": "C",
"timestamp": "2026-11-13T08:00:00Z"
}
```
Save one complete JSON object per line in a `.jsonl` file; the multi-line JSON
above is formatted only for readability. IDs and metric names are 1–64 ASCII
characters, start with a letter or digit, and may include `.`, `_`, or `-`.
Values must be finite numbers, not strings or booleans. Timestamps must contain
a timezone and are normalized to UTC. Units are short measurement labels; no
automatic unit conversion is performed.
```bash
acommand-edge --db ./data/demo.db ingest examples/telemetry.jsonl --rules examples/rules.json
```
Import stops at the first invalid line; earlier accepted lines remain stored.
It is not an all-or-nothing file transaction. Each nonblank line is limited to
64 KiB.
Rules are a JSON array. For example:
```json
[
{
"rule_id": "bearing-high",
"site_id": "factory-demo",
"device_id": "motor-01",
"metric": "bearing_temperature",
"unit": "C",
"operator": "gt",
"threshold": 75,
"severity": "warning"
}
]
```
Supported operators: `gt`, `gte`, `lt`, `lte`. Severity: `info`, `warning`, or
`critical`. `site_id` and `device_id` filters are optional; the metric and unit
must match exactly. Rules evaluate new events at ingestion, not historical rows
after a rule file changes. Alerts are observations, not equipment commands.
## Connect MQTT or Modbus
Install all optional adapters and the MCP SDK:
```bash
python -m pip install -e '.[all]'
```
Individual extras are `.[mqtt]`, `.[modbus]`, and `.[mcp]`. Optional direct
dependencies are pinned to Paho MQTT **2.1.0**, PyModbus **3.11.3**, and MCP
Python SDK **1.30.0**. These pins are not a complete transitive dependency lock.
### MQTT
Start your local broker, then run the subscriber:
```bash
acommand-edge --db ./data/demo.db mqtt --host localhost --port 1883 \
--topic 'acommand/+/+/telemetry' --rules examples/rules.json
```
Publish the telemetry schema to `acommand/{site_id}/{device_id}/telemetry` from
your device or simulator. For the JSON example above, the topic is
`acommand/factory-demo/motor-01/telemetry`. Topic and payload identities must
match. The adapter accepts at most 64 KiB per payload and only subscribes; it
does not publish control commands.
Remote hosts and any connection carrying credentials require verified TLS:
```bash
acommand-edge --db ./data/demo.db mqtt --host mqtt.example.com --port 8883 \
--tls --ca-cert /absolute/path/to/ca.pem \
--topic 'acommand/factory-demo/+/telemetry' --rules examples/rules.json
```
Set `ACOMMAND_MQTT_USERNAME` and `ACOMMAND_MQTT_PASSWORD` in your environment or
secret manager when required by the broker. Do not put secrets in tracked files.
Omit `--ca-cert` to use the default certificate trust store. Select the correct
TLS port explicitly; `--tls` does not change the port.
The subscription requests QoS 1. This starter does **not** guarantee durable
replay, exactly-once delivery, or lossless recovery after storage failure or a
process restart. Use broker access rules to constrain which sites each client
may publish or read.
### Modbus TCP
Edit `examples/modbus.json` to match a device you are authorized to query:
```json
{
"host": "127.0.0.1",
"port": 5020,
"site_id": "factory-demo",
"asset_id": "motor-01",
"device_id": 1,
"address": 0,
"count": 1,
"register_type": "holding",
"metric": "bearing_temperature",
"unit": "C",
"scale": 0.1,
"offset": 0,
"timeout": 3
}
```
```bash
acommand-edge --db ./data/demo.db modbus examples/modbus.json --rules examples/rules.json
```
Each invocation reads **one unsigned 16-bit register once** and closes the
connection. `address` is zero-based; `device_id` is the Modbus unit identifier;
`asset_id` becomes the telemetry device ID. The value is `register * scale +
offset`. `register_type` accepts `holding` or `input`. Signed, multi-register,
floating-point, serial RTU, and continuous polling are not implemented.
This adapter uses plain Modbus TCP. Keep it on an approved, isolated device
network; check the manufacturer's register map before connecting. A local
read timestamp is not the device's measurement timestamp.
## Give an AI client read-only access
Seed the database first using the demo or a collector. Then configure an MCP
client that supports launching stdio servers. Use absolute paths for both the
virtual-environment executable and database:
```json
{
"mcpServers": {
"acommand-edge": {
"command": "/absolute/path/to/acommand-edge-gateway/.venv/bin/acommand-edge",
"args": ["--db", "/absolute/path/to/data/demo.db", "mcp"]
}
}
}
```
This is a common configuration shape; use your client's configuration location
and syntax. On Windows, the executable is under `.venv/Scripts/acommand-edge.exe`.
Running `acommand-edge --db /absolute/path/to/data/demo.db mcp` directly waits
for MCP protocol messages; it is not an interactive chat prompt.
| Tool | Purpose |
| --- | --- |
| `list_devices` | List up to 200 site/device pairs and last observed times |
| `get_latest_telemetry` | Read the latest recorded value for up to 200 metrics on one device |
| `get_telemetry_history` | Read one device/metric history, with a 1–200 result limit |
| `get_recent_alerts` | Read threshold alerts, with optional filters and a 1–200 result limit |
The MCP server opens SQLite read-only and exposes no network listener or device
write tools. Results include a retrieval time and freshness note: a recent
query does not mean the measurement is recent. The AI client decides whether
to send returned telemetry to its model provider; configure that client for
your data requirements. The gateway itself makes no external model call.
Try asking your client: “Show the latest measurements for factory-demo/motor-01
and explain which configured thresholds were exceeded. Separate observations
from hypotheses and include measurement times.”
## Development and limitations
```bash
python -m pip install -e '.[all,dev]'
python -m unittest discover -s tests -v
ruff check .
python -m build
```
Tests are included; their presence is not a hardware certification. Real MQTT
brokers, Modbus devices, and AI clients need environment-specific validation.
This release has no multi-user authorization, high-availability deployment,
retention scheduler, equipment actuation, or production service guarantees.
SQLite files contain operational data and require appropriate filesystem
permissions and lifecycle management.
See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
[research notes](docs/research.md).
## About Acommand AI
Acommand AI is a global AI agent platform and solutions provider, connecting
devices, business systems, and people across factories, ports, warehouses, and
other operational environments.
[acommandai.com](https://acommandai.com) · Business enquiries:
[Service@Acommandai.com](mailto:Service@Acommandai.com)
Original integration code: [MIT](LICENSE). Dependencies retain their own
licenses; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data