License: MIT Python 3.11+ CI FastAPI

GridOS is a lightweight FastAPI service for DER device registration, telemetry ingestion, telemetry lookup, and basic control workflows.

The repository still contains broader experimental areas such as digital twin simulation, forecasting, and optimisation. Those modules remain available for contributors. The supported first-run experience is intentionally smaller so that a new user can clone the repository, start the API, send telemetry, and confirm a working result without being forced into a large deployment.

This smaller scope is intentional. It is better for GridOS to be simple, reliable, and truthful than broad and internally inconsistent. The current work focuses on a dependable end-to-end path that works from a fresh clone. Experimental modules are still available for contributors, but the public launch story now matches what the repository can support immediately.

flowchart LR
 A[Client or Script] --> B[FastAPI Service]
 B --> C[Device Routes]
 B --> D[Telemetry Routes]
 B --> E[Control Routes]
 D --> F[In-Memory Storage by Default]
 F --> G[History and Latest Queries]
 D -. optional .-> H[InfluxDB]
 D -. optional .-> I[TimescaleDB]
 J[Experimental Modules] -. not in default app .-> B

git clone https://github.com/iceccarelli/GridOS.git
cd GridOS
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
uvicorn gridos.main:app --host 0.0.0.0 --port 8000 --reload

Then open:

http://localhost:8000/docs

cp .env.example .env
docker compose up --build

Then open:

http://localhost:8000/docs

GridOS can talk to real DER hardware over Modbus TCP, and ships a built-in device simulator so the full loop is demonstrable without hardware:

pip install -e ".[adapters]"
# Terminal 1 — emulate a battery on Modbus TCP:
gridos simulate --port 5020
# Terminal 2 — run the API, then drive the device over REST:
gridos serve

Register a device with an adapter_config, then connect, poll live telemetry, and dispatch control:

BASE=http://127.0.0.1:8000/api/v1
curl -s -X POST $BASE/devices/register -H 'Content-Type: application/json' -d '{
 "device": {"device_id":"batt-1","name":"Battery","der_type":"battery","rated_power_kw":100},
 "adapter_config": {"protocol":"modbus_tcp","host":"127.0.0.1","port":5020}
}'
curl -s -X POST $BASE/devices/batt-1/connect # attach + connect the adapter
curl -s -X POST $BASE/devices/batt-1/poll # read LIVE telemetry, persist + broadcast it
curl -s -X POST $BASE/control/batt-1 -H 'Content-Type: application/json' \
 -d '{"device_id":"batt-1","mode":"power_setpoint","setpoint_kw":40}'

A complete scripted walkthrough (including a restart to prove device persistence) lives at scripts/demo_modbus.sh.

The Modbus adapter resolves a register map from adapter_config["register_map"], which may be a named preset or an inline custom map. Presets include gridos_default, sunspec_inverter, and sunspec_battery:

{"protocol": "modbus_tcp", "host": "127.0.0.1", "port": 5020, "register_map": "sunspec_inverter"}

The sunspec_* presets approximate the SunSpec information models for common inverter/battery measurement points using fixed scale factors; full SunSpec scale-factor decoding is a future enhancement, and inline maps cover exact hardware. The simulator can emulate any map: gridos simulate seeds registers from the chosen layout.

For EV chargers and IoT gateways that push telemetry, GridOS ships an MQTT adapter and a self-contained broker simulator:

# Terminal 1 — broker simulator that also publishes battery telemetry:
gridos simulate --protocol mqtt --port 1883
# Register an MQTT device and drive it the same way as Modbus:
curl -s -X POST $BASE/devices/register -H 'Content-Type: application/json' -d '{
 "device": {"device_id":"ev-1","name":"EV Charger","der_type":"ev_charger","rated_power_kw":11},
 "adapter_config": {"protocol":"mqtt","host":"127.0.0.1","port":1883,
 "telemetry_topic":"gridos/mqtt-sim/telemetry"}
}'
curl -s -X POST $BASE/devices/ev-1/connect
curl -s -X POST $BASE/devices/ev-1/poll

For production, point the adapter at any MQTT broker (e.g. Mosquitto).

Run gridos serve and open http://127.0.0.1:8000/demo — a no-terminal page that registers a device, connects its adapter, polls live telemetry (with an auto-poll mode), and dispatches a setpoint, all from the browser. Start gridos simulate alongside it and a prospect can watch the full loop without touching a command line.

By default GridOS runs open, which suits local development and demos. To require credentials on mutating endpoints, set two environment variables:

GRIDOS_REQUIRE_AUTH=true
GRIDOS_API_KEYS=gos_your_first_key,gos_your_second_key

When enabled, POST /api/v1/devices/register, DELETE /api/v1/devices/{id}, POST /api/v1/telemetry/, POST /api/v1/telemetry/batch, and POST /api/v1/control/{id} require a matching X-API-Key header. Read endpoints remain open. Check the current posture at GET /api/v1/auth/status.

The default .env.example enables in-memory storage. That means the first run does not require any external database.

Protect the supported scope first.

pytest tests/test_api.py tests/test_models.py tests/test_storage.py -v --tb=short

The most important docs for the current release are:

Contributions are welcome, especially when they improve startup reliability, telemetry handling, testing, packaging, and documentation consistency. The priority is to strengthen the lightweight path before expanding the public scope again.

GridOS is released under the MIT License.