SETUP GUIDE · CLIENT DOCUMENTATION

FROM PILOT TO
LIVE INTELLIGENCE.

This guide takes you from a fresh Avrenix account to fully live engines in six steps. Your pilot starts with simulated data so you can explore the platform immediately. When you're ready to connect your real asset, follow the steps below.

Time estimate: Steps 1–4 take 2–4 hours for someone comfortable with a terminal and basic networking. Step 5 (historical data) can be done in parallel. You don't need all steps complete before the engines start producing value — HELIOS and STRIX go live as soon as Step 2 is done.

YOU NEED

Python 3.10+
pip / virtualenv
Terminal access
Network to your BMS

MINIMUM DATA

7 days price history
Real-time SOC feed
Real-time LMP feed
Asset specs (MW, MWh)

IDEAL DATA

90+ days price history
5-min dispatch history
Revenue records
Weather history

Step 1

RUN THE API GATEWAY

The gateway is a FastAPI server that sits between your frontend and the Python engine modules. It handles CORS, mock fallback, and routes all nine engine calls through a single port.

1.1

Clone or download the backend. Your account includes the full backend source. Place the backend folder somewhere permanent — e.g. C:\avrenix\backend\ on Windows or ~/avrenix/backend/ on Mac/Linux.

1.2

Install Python dependencies. Open a terminal in the backend root and run:
pip install -r requirements-gateway.txt
This installs FastAPI, uvicorn, and pydantic. The engine modules have their own requirements — install those as needed.

1.3

Set PYTHONPATH so the gateway can find the engine modules.

Windows (Command Prompt)

:: Set PYTHONPATH to include your backend root
set PYTHONPATH=C:\avrenix\backend

:: Run the gateway (leave this terminal open)
cd C:\avrenix\backend
uvicorn api_gateway:app --host 0.0.0.0 --port 8000 --reload

Mac / Linux

# Set PYTHONPATH and run the gateway
export PYTHONPATH=/home/you/avrenix/backend
cd /home/you/avrenix/backend
uvicorn api_gateway:app --host 0.0.0.0 --port 8000 --reload

Verify it's running: Open your browser and go to http://localhost:8000. You should see a JSON response with "service": "Avrenix API Gateway". If you see an error, check that PYTHONPATH is set correctly in the same terminal window you're running uvicorn from.

1.4

Tell the frontend to use your gateway. In your browser, open the Avrenix portal → Settings → Data Source. Enter http://localhost:8000 in the Gateway URL field and click Save. Then flip the Mock Data toggle OFF.

Step 2

CONNECT MARKET PRICE DATA

HELIOS needs real-time LMP (locational marginal price) data from your ISO/RTO. This is the most impactful single connection — once this is live, HELIOS, FENRIR, SYNDEX, and SPECTER all switch from mock to real market intelligence.

ERCOT users: No API key required. ERCOT publishes real-time LMP data publicly. Start with Step 2a below. Other ISOs require registration — see Steps 2b and 2c.

ERCOT — free, no registration. ERCOT's real-time LMP API is public. The gateway's HELIOS route already knows how to call it when you provide a node name.

Test the ERCOT price feed — run this in Python

import requests

# ERCOT public real-time LMP — no API key needed
url = "https://api.ercot.com/api/public-reports/NP6-905-CD/rtd_lmp_node_zone_hub"
params = {
    "deliveryDateFrom": "2026-03-01",
    "deliveryDateTo":   "2026-03-19",
    "settlementPoint":  "HB_WEST",  # change to your hub
    "size": 96
}
r = requests.get(url, params=params)
data = r.json()["data"]
prices = [row["settlementPointPrice"] for row in data]
print(f"Got {len(prices)} price intervals. Latest: ${prices[-1]:.2f}/MWh")

CAISO / PJM / MISO / SPP — EIA API key required. Register at eia.gov/opendata (free, takes 5 minutes). You'll get an API key by email. Enter it in Portal → Integrations → ISO/RTO Market Data.

Configure the integration in the portal. Go to Integrations → ISO/RTO Market Data → Configure. Select your ISO, enter your node/hub name (e.g. HB_WEST for ERCOT, SP15 for CAISO), and paste your API key if required. Click Save & Connect. The gateway will begin pulling real-time prices immediately.

Once connected: HELIOS will rebuild its forecast model within 1 hour using real price history. The HELIOS cockpit will show actual MAPE against real out-of-sample prices within 24 hours.

Step 3

CONNECT BATTERY TELEMETRY

The engines need to know the current state of your battery in real time — primarily state of charge (SOC), charge/discharge rate, and battery health indicators. This comes from your BMS (battery management system) or SCADA system.

3.1

Identify your BMS protocol. Most utility-scale BESS use Modbus TCP, DNP3, or IEC 61850. Some newer systems have REST APIs. Ask your BMS vendor which protocol they support — they will also give you the register map (which registers correspond to SOC, MW, voltage, etc.).

3.2

Configure the BMS connection in the portal. Go to Integrations → BMS / SCADA → Configure. Select your protocol, enter the IP address of your BMS (must be reachable from the machine running the gateway), port (typically 502 for Modbus), and poll interval (5 seconds recommended).

3.3

For Modbus TCP specifically — install the optional Modbus library: pip install pymodbus. The gateway will use this automatically when Modbus is configured.

Quick Modbus test — verify your BMS is reachable

from pymodbus.client import ModbusTcpClient

client = ModbusTcpClient("192.168.1.100", port=502)  # your BMS IP
client.connect()

# Read holding registers — adjust addresses to your BMS register map
soc_result = client.read_holding_registers(100, count=1)  # SOC register
mw_result  = client.read_holding_registers(102, count=1)  # Power MW register

soc = soc_result.registers[0] / 10  # scale factor from your vendor docs
mw  = mw_result.registers[0] / 100

print(f"SOC: {soc}%  |  Power: {mw} MW")
client.close()

Network requirement: The machine running api_gateway.py must have network access to your BMS IP and port. If your BMS is on an isolated SCADA network, you may need to configure a firewall rule or run the gateway on a machine inside that network.

3.4

REST API alternative. If your BMS has a REST API (some modern systems like Tesla Megapack, FLUENCE Nispera, or Powin Stack have this), contact your vendor for the endpoint documentation. The gateway can poll any REST endpoint — configure it in Integrations with the URL, authentication headers, and the JSON path to the SOC and MW values.

Step 4

CONFIGURE YOUR SITE IN THE PORTAL

With data flowing, tell Avrenix about your asset's physical characteristics. The engines use these to calibrate their models.

4.1

Open the Add Site wizard. Click + Add Site in the portal topbar (or you were guided here on first login). You'll be asked for: site name, market, power rating (MW), energy capacity (MWh), battery chemistry, and commercial operation date.

4.2

Select your revenue streams. Choose which markets you participate in: spot arbitrage, regulation, FCAS/spinning reserve, capacity. CONSUL will only bid into services you enable here.

4.3

Set dispatch model. Select Hybrid RL + Solver (recommended). The RL agent starts in "warm-up" mode for the first 7 days, relying more heavily on the solver while it learns your site. You'll see a banner in the FENRIR cockpit indicating warm-up status.

After completing the wizard: SPECTER begins building your grid personality profile. HELIOS starts fitting models to your price node. FENRIR begins generating adversarial scenarios with your actual battery parameters. Expect the first meaningful dispatch recommendations within 30–60 minutes.

Step 5

UPLOAD HISTORICAL DATA (OPTIONAL BUT RECOMMENDED)

Historical data dramatically accelerates how quickly the engines reach peak performance. KAIROS needs dispatch + revenue history to build its causal graph. SPECTER needs 30+ days to build a mature personality profile. STRIX needs price history to calibrate its Monte Carlo paths.

5.1

Prepare your historical price data. Export LMP data from your ISO's settlement portal for the past 90–180 days. ERCOT: download from the ERCOT market portal. CAISO: use OASIS. PJM: use PJM Data Miner 2. Format it as CSV with columns: timestamp, price_mwh at 5-minute or 15-minute intervals.

5.2

Prepare your dispatch and revenue history. If you have records of past dispatch decisions and settlement statements, export them as CSV: timestamp, dispatch_mw, direction, revenue_usd, soc_pct. Even partial records help KAIROS build its causal graph.

5.3

Upload in the portal. Go to Integrations → File Upload, or use the Add Site wizard Step 2. Drag and drop your CSV files. The system accepts CSV, XLSX, JSON, and Parquet. Multiple files can be uploaded together.

Expected CSV format — price history

timestamp,price_mwh
2026-01-01T00:00:00Z,42.10
2026-01-01T00:05:00Z,38.75
2026-01-01T00:10:00Z,41.20

Expected CSV format — dispatch history

timestamp,dispatch_mw,direction,revenue_usd,soc_pct
2026-01-01T14:00:00Z,84.0,discharge,7100.80,72.4
2026-01-01T14:05:00Z,80.0,discharge,6820.00,71.8

Step 6

VERIFY ALL ENGINES ARE LIVE

Run through this checklist to confirm everything is connected correctly.

Gateway health check passes: http://localhost:8000/api/health shows all engines as "ok" (not "mock")

Portal Settings → Data Source shows Mock Data toggle OFF and gateway URL set

HELIOS cockpit shows real price values that match your ISO's current LMP

Overview → Site Overview shows the real SOC value from your BMS (not the placeholder mock value)

FENRIR cockpit shows scenarios generated with your actual battery MW/MWh

Chai responds with site-specific data when asked "What's the current SOC?"

STRIX simulation uses your actual asset parameters (visible in the STRIX cockpit)

All seven checked? You're live. The engines are now operating on real data. SPECTER will have a mature personality profile within 30 days. KAIROS will have a calibrated causal graph within 14 days of dispatch history. HELIOS's MAPE should improve noticeably within the first week as it adapts to your specific price node.

HELIOS — data requirements

WHAT HELIOS NEEDS TO PERFORM

HELIOS runs four models. Each has different minimum data requirements. The ensemble degrades gracefully — if you only have 7 days of history, the Naive and Moving Average models carry more weight while LSTM and Transformer train on limited data.

MINIMUM (7 days)

Naive + Moving Average models active. Conformal intervals wider than normal while data is thin. Your out-of-sample MAPE will start higher and tighten as history accumulates. Sufficient for STRIX and FENRIR to operate.

FULL (90+ days)

All four models active. LSTM and N-BEATS carry highest weight. HELIOS reports your own out-of-sample MAPE against your realised prices, benchmarked with a 12-month walk-forward. Seasonal patterns captured.

PHALANX — BTM setup

PHALANX FACILITY DATA

PHALANX requires facility-specific load data that general market feeds don't provide. This section only applies to BTM/Enterprise plans.

Export your interval meter data. Request 15-minute interval load data from your utility. Most utilities provide a green button download from their portal. This gives PHALANX your facility's load fingerprint.

Confirm your demand charge rate. Find the demand charge in $/kW/month on your utility bill. Enter this in the PHALANX cockpit settings. TARSIS will also use this value.

Set the asymmetric cost weight. Default is 45× (a false negative — missing a peak — is penalised 45× more than a false positive). For data centres and critical facilities, set this to 60–80×.

TARSIS — tariff setup

TARSIS TARIFF CONFIGURATION

Find your tariff code. Look at your utility bill for the rate schedule name — e.g. "PG&E-BDB", "SCE-TOU-D-PRIME", "ConEd SC-9". TARSIS has 200+ pre-loaded structures. Enter the code in the TARSIS cockpit.

If your tariff isn't in the library, export the rate schedule from your utility's website as a PDF and contact support. We'll add it within 48 hours.

Configure NEM / export compensation if applicable. Select your export program (NEM 2.0, NEM 3.0, FiT) and CAISO zone in the TARSIS settings. TARSIS will automatically value export at hourly rates.

Troubleshooting

COMMON ISSUES

Gateway shows engines as "mock" even after setting PYTHONPATH

PYTHONPATH must be set in the same terminal session where you run uvicorn. Setting it in a different window has no effect. On Windows, use set PYTHONPATH=... immediately before uvicorn api_gateway:app ... in the same Command Prompt window.

Browser shows CORS error when calling the gateway

The gateway allows all origins by default. If you see a CORS error, your browser is blocking the request for a different reason — usually because the gateway isn't actually running. Check that http://localhost:8000 loads in a browser tab before testing from the portal.

HELIOS shows stale or zero prices

The ISO/RTO feed may not be configured yet. Check Portal → Integrations → ISO/RTO Market Data shows status CONNECTED. If the price still looks wrong, verify your node/hub name is correct — HB_WEST not HB_WESTY.

BMS connection timeout

Verify: (1) The BMS IP address is reachable from the gateway machine — ping 192.168.1.100. (2) The port is open — telnet 192.168.1.100 502. (3) Your BMS is configured to accept connections from external hosts (some BMS systems whitelist client IPs).

Portal shows data but it looks like yesterday's numbers

The portal fetches fresh data from the gateway every 30 seconds via AVRAPI.startHybridTicker(). Between API calls, it displays the last cached value. If data looks persistently stale, check that the gateway is still running (the terminal window may have closed) and reload the portal.

Need help? Email [email protected] with your gateway health check output (http://localhost:8000/api/health) and we'll diagnose within 4 hours.

FROM PILOT TOLIVE INTELLIGENCE.

FROM PILOT TO
LIVE INTELLIGENCE.