# Sigenergy x Shelly Integration -- Public Files

All credentials and device-specific values have been removed.
Configure using environment variables or by editing the placeholder constants
at the top of each file.

---

## Files

### Shelly Scripts

| File | Approach | Description |
|---|---|---|
| `sigen-monitor.js` | Cloudflare Worker relay | Polls any HTTP relay (Cloudflare Worker, Val.town, GitHub Actions…) every 5 minutes and updates VCs 200-204. Set `WORKER_URL` to your deployed relay endpoint. Laptop-independent. |
| `sigen-monitor-rs485.js` | Modbus RS485 addon | Reads Sigenergy registers directly over RS485 every 30 seconds. Fully local — no internet, no cloud, no laptop. Requires Shelly RS485 addon wired to gateway RS485 port. |

**Which script to use:**
- Have a Cloudflare (or similar) account → `sigen-monitor.js` + `worker.js`
- Prefer fully local, no internet → `sigen-monitor-rs485.js` (requires physical RS485 wiring)
- Laptop on the same network → use `sigen-poller.py` or `sigen-modbus-bridge.py` directly (no Shelly script needed — Python pushes values to the device)

### Python Scripts (laptop / server)

| File | Description |
|---|---|
| `sigen-poller.py` | Polls Sigenergy OpenAPI every 60s and writes to Shelly VCs via HTTP. Requires: `SIGEN_AUTH_KEY`, `SIGEN_SYSTEM_ID`, `SHELLY_IP`. No extra dependencies (stdlib only). |
| `sigen-modbus-bridge.py` | Reads Sigenergy gateway via Modbus TCP every 30s and writes to Shelly VCs. Requires: `GATEWAY_IP`, `SHELLY_IP`. Install: `pip install pymodbus requests`. Local network only, no internet needed. |

### Cloudflare Worker (laptop-independent relay)

| File | Description |
|---|---|
| `worker.js` | Cloudflare Worker: 5-minute cron fetches Sigenergy data, caches in KV. HTTP GET serves cached JSON for Shelly to poll. Set `SYSTEM_ID` in the file. Add secret `SIGEN_AUTH_KEY` via wrangler CLI. |
| `wrangler.toml` | Worker configuration: cron schedule, KV binding, worker name. |

### Sigenergy API Agent

| File | Description |
|---|---|
| `sigen_agent.py` | Claude-powered conversational assistant with complete Sigenergy OpenAPI knowledge. Answers questions, makes live API calls. Requires `pip install anthropic requests`. |
| `sigen_agent_README.md` | Agent setup guide and example prompts. |

---

## Quick start: Cloudflare Worker relay (laptop-independent)

1. Create free Cloudflare account at [dash.cloudflare.com](https://dash.cloudflare.com)
2. Create KV namespace named `SIGEN_DATA` in Workers & Pages -> KV
3. Copy the KV namespace ID into `wrangler.toml`
4. Set your worker name in `wrangler.toml`
5. Set `SYSTEM_ID` in `worker.js`
6. Deploy:
   ```
   npm install -g wrangler
   npx wrangler deploy
   npx wrangler secret put SIGEN_AUTH_KEY
   ```
7. Copy the deployed worker URL into `sigen-monitor.js` (`WORKER_URL`)
8. Deploy `sigen-monitor.js` as a script on your Shelly device and start it

---

## Virtual Component layout (configure on your Shelly device)

| VC ID | Signal | Type | Notes |
|---|---|---|---|
| 200 | PV Power (W) | number | Always >= 0 |
| 201 | Battery SOC (%) | number | 0-100 |
| 202 | Battery Power (W) | number | Positive = charging |
| 203 | Grid Power (W) | number | Positive = exporting |
| 204 | Load Power (W) | number | Always >= 0 |

---

## Modbus register map (Sigenergy gateway, TCP or RS485)

| Signal | Register | Count | Type | Scale | Notes |
|---|---|---|---|---|---|
| gridPower | 30005 | 2 | int32 | 1 W | Positive = import from grid |
| batterySoc | 30014 | 1 | uint16 | 0.1 | Divide by 10 for % |
| pvPower | 30035 | 2 | int32 | 1 W | |
| batteryPower | 30037 | 2 | int32 | 1 W | Positive = charging |
| loadPower | 30284 | 2 | int32 | 1 W | |

Connection: Unit ID 247 (plant level), port 502.
pymodbus 3.x: PDU address = full register number (no offset subtraction).