{"id":31044813,"url":"https://github.com/dzikus/shelly-speedwire-gateway","last_synced_at":"2026-04-21T03:31:28.087Z","repository":{"id":310514061,"uuid":"1040162271","full_name":"dzikus/shelly-speedwire-gateway","owner":"dzikus","description":"Shelly 3EM gataway to mimic SMA speedwire","archived":false,"fork":false,"pushed_at":"2025-09-14T08:45:01.000Z","size":152,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-15T00:32:20.723Z","etag":null,"topics":["iot","mqtt","pv","shelly","shelly-3em","sma","solar","speedwire"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dzikus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-18T14:48:11.000Z","updated_at":"2025-09-14T08:44:27.000Z","dependencies_parsed_at":"2025-08-18T16:40:51.795Z","dependency_job_id":null,"html_url":"https://github.com/dzikus/shelly-speedwire-gateway","commit_stats":null,"previous_names":["dzikus/shelly-speedwire-gateway"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dzikus/shelly-speedwire-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dzikus%2Fshelly-speedwire-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dzikus%2Fshelly-speedwire-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dzikus%2Fshelly-speedwire-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dzikus%2Fshelly-speedwire-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dzikus","download_url":"https://codeload.github.com/dzikus/shelly-speedwire-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dzikus%2Fshelly-speedwire-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32075218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iot","mqtt","pv","shelly","shelly-3em","sma","solar","speedwire"],"created_at":"2025-09-14T16:51:48.979Z","updated_at":"2026-04-21T03:31:28.069Z","avatar_url":"https://github.com/dzikus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shelly 3EM to SMA Speedwire Gateway\n\n[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue)](https://github.com/dzikus/shelly-speedwire-gateway)\n[![Docker Pulls](https://img.shields.io/docker/pulls/dzikus99/shelly-speedwire-gateway)](https://hub.docker.com/r/dzikus99/shelly-speedwire-gateway)\n[![Docker Image Size](https://img.shields.io/docker/image-size/dzikus99/shelly-speedwire-gateway/latest)](https://hub.docker.com/r/dzikus99/shelly-speedwire-gateway)\n\nA Python gateway that enables Shelly 3EM three-phase energy meters to communicate with SMA inverters by translating MQTT data to the SMA Speedwire protocol.\n\n## Features\n\n- Energy monitoring - forwards power, voltage, current, and energy data from Shelly 3EM to SMA devices\n- Three-phase support - three-phase measurements with individual phase data\n- SMA Speedwire protocol implementation - EMETER protocol v1.0 with reactive and apparent power calculations\n- CT clamp orientation support - handles backwards-mounted current transformers with the invert_values option\n- Deployment options - run as standalone Python script, systemd service, or Docker container\n- Networking - supports multicast, broadcast, and direct unicast communication\n- Discovery - responds to SMA device discovery requests\n- Configurable transmission intervals with immediate updates on data changes\n- **High-performance optimizations** - Cython compilation, memory pooling, LRU caching for minimal resource usage, Batch MQTT processing\n\n## Requirements\n\n### Hardware\n- **Shelly 3EM** energy meter connected to your electrical installation\n- **SMA inverter** or device that supports the Speedwire protocol\n- Network connectivity between Shelly 3EM, MQTT broker, and SMA devices\n\n### Software\n- Python 3.13+ (for standalone installation)\n- Docker (for containerized deployment)\n- MQTT broker (Mosquitto)\n- UV package manager\n\n## Getting Started\n\n### Docker\n\n```yaml\nversion: '3.8'\n\nservices:\n  shelly-speedwire-gateway:\n    image: dzikus99/shelly-speedwire-gateway:latest\n    container_name: shelly-speedwire\n    restart: unless-stopped\n    network_mode: host  # Required for multicast/broadcast\n    environment:\n      - MQTT_BROKER_HOST=192.168.1.123\n      - MQTT_BASE_TOPIC=shellies/shelly3em-XXXXXXXXXXXXX\n      - SPEEDWIRE_SERIAL=1234567890\n      - MQTT_INVERT_VALUES=false  # Set to true if CT clamps are backwards\n```\n\n```bash\ndocker-compose up -d\n```\n\n### Docker Run\n\n```bash\ndocker run -d \\\n  --name shelly-speedwire \\\n  --network host \\\n  --restart unless-stopped \\\n  -e MQTT_BROKER_HOST=192.168.1.123 \\\n  -e MQTT_BASE_TOPIC=shellies/shelly3em-XXXXXXXXXXXXX \\\n  -e SPEEDWIRE_SERIAL=1234567890 \\\n  -e LOG_LEVEL=INFO \\\n  -e MQTT_MAX_RECONNECT_ATTEMPTS=5 \\\n  -e SPEEDWIRE_MIN_SEND_INTERVAL=0.5 \\\n  -e GATEWAY_BATCH_SIZE=100 \\\n  dzikus99/shelly-speedwire-gateway:latest\n```\n\n## Installation Options\n\n### Option 1: Docker Container\n\nPull the image:\n```bash\ndocker pull dzikus99/shelly-speedwire-gateway:latest\n```\n\nOr build locally:\n```bash\ndocker build -t shelly-speedwire-gateway .\n```\n\n### Option 2: Systemd Service (Linux)\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/dzikus/shelly-speedwire-gateway\ncd shelly-speedwire-gateway\n```\n\n2. Install dependencies:\n```bash\n# Using UV (recommended)\npip install uv\nuv sync\n\n# Or using pip\npip install aiomqtt pydantic pydantic-settings structlog pyyaml uvloop psutil\n```\n\n3. Install the package:\n```bash\nsudo mkdir -p /opt/shelly-speedwire-gateway\nsudo cp -r shelly_speedwire_gateway/ /opt/shelly-speedwire-gateway/\nsudo cp scripts/run_gateway.py /opt/shelly-speedwire-gateway/\nsudo cp shelly_speedwire_gateway_config.yaml /opt/shelly-speedwire-gateway/\n```\n\n4. Install systemd service:\n```bash\nsudo cp shelly-speedwire-gateway.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable shelly-speedwire-gateway\nsudo systemctl start shelly-speedwire-gateway\n```\n\n5. Check status:\n```bash\nsudo systemctl status shelly-speedwire-gateway\nsudo journalctl -u shelly-speedwire-gateway -f\n```\n\n### Option 3: Standalone Python\n\n1. Install dependencies:\n```bash\n# Using UV (recommended)\npip install uv\nuv sync\n\n# Or using pip\npip install aiomqtt pydantic pydantic-settings structlog pyyaml uvloop psutil\n```\n\n2. Configure the gateway (see Configuration section)\n\n3. Run the gateway:\n```bash\npython3 scripts/run_gateway.py\n```\n\n## Configuration\n\nThe gateway supports two configuration methods: YAML files or environment variables (Docker).\n\n### Configuration File\n\nCreate or edit `shelly_speedwire_gateway_config.yaml`:\n\n```yaml\nmqtt:\n  broker_host: 192.168.1.123\n  broker_port: 1883\n  base_topic: shellies/shelly3em-XXXXXXXXXXXXX\n  keepalive: 60\n  invert_values: false  # Set to true if CT clamps are mounted backwards\n  # username: mqtt_user\n  # password: mqtt_pass\n\nspeedwire:\n  interval: 1.0                       # Send interval in seconds\n  use_broadcast: false                # Use broadcast instead of multicast\n  dualcast: false                     # Send both multicast and broadcast\n  include_voltage_current: true       # Include V, I, PF, Hz data\n  serial: 1234567890                  # Unique serial number\n  susy_id: 349                        # SUSy ID\n\n  # Optional: Direct unicast to specific devices\n  # unicast_targets:\n  #   - 192.168.1.50\n  #   - 192.168.1.51\n\nlog_level: INFO\nlog_format: structured\nenable_monitoring: false\nmetrics_port: 8080\n```\n\n### Environment Variables (Docker)\n\n#### MQTT Configuration\n\n| Variable | Default | Description | Required |\n|----------|---------|-------------|----------|\n| `MQTT_BROKER_HOST` | `localhost` | MQTT broker IP address or hostname | No |\n| `MQTT_BROKER_PORT` | `1883` | MQTT broker port | No |\n| `MQTT_BASE_TOPIC` | `shellies/shelly3em-XXXXXXXXXXXXX` | Your Shelly 3EM MQTT topic | Yes |\n| `MQTT_KEEPALIVE` | `60` | MQTT connection keepalive interval in seconds | No |\n| `MQTT_INVERT_VALUES` | `false` | Set to `true` if CT clamps are mounted backwards | No |\n| `MQTT_USERNAME` | - | MQTT broker username for authentication | No |\n| `MQTT_PASSWORD` | - | MQTT broker password for authentication | No |\n| `MQTT_QOS` | `1` | MQTT Quality of Service level (0, 1, or 2) | No |\n| `MQTT_MAX_RECONNECT_ATTEMPTS` | `3` | Maximum number of MQTT reconnection attempts | No |\n| `MQTT_CONNECTION_TIMEOUT` | `10.0` | MQTT connection timeout in seconds | No |\n| `MQTT_MESSAGE_TIMEOUT` | `300.0` | Maximum time to wait for MQTT messages in seconds | No |\n\n#### Speedwire Configuration\n\n| Variable | Default | Description | Required |\n|----------|---------|-------------|----------|\n| `SPEEDWIRE_INTERVAL` | `1.0` | Data packet transmission interval in seconds | No |\n| `SPEEDWIRE_USE_BROADCAST` | `false` | Use UDP broadcast instead of multicast | No |\n| `SPEEDWIRE_DUALCAST` | `false` | Send both multicast and broadcast packets | No |\n| `SPEEDWIRE_SERIAL` | `1234567890` | Unique serial number for the emulated energy meter | Yes |\n| `SPEEDWIRE_SUSY_ID` | `349` | SUSy ID for device identification | No |\n| `SPEEDWIRE_MIN_SEND_INTERVAL` | `0.1` | Minimum time between packet transmissions in seconds | No |\n| `SPEEDWIRE_HEARTBEAT_INTERVAL` | `30.0` | Heartbeat interval for keep-alive packets in seconds | No |\n| `SPEEDWIRE_DISCOVERY_LOOP_SLEEP` | `0.01` | Sleep interval in discovery loop in seconds | No |\n| `SPEEDWIRE_DATA_RECEIVE_TIMEOUT` | `0.05` | Timeout for data reception in seconds | No |\n| `SPEEDWIRE_HEALTH_CHECK_TIMEOUT` | `300` | Health check timeout in seconds | No |\n| `SPEEDWIRE_HEALTH_CHECK_INTERVAL` | `60.0` | Health check interval in seconds | No |\n| `SPEEDWIRE_RECEIVE_BUFFER_SIZE` | `2048` | UDP receive buffer size in bytes | No |\n| `SPEEDWIRE_MAX_PACKET_SIZE` | `1500` | Maximum packet size in bytes | No |\n| `SPEEDWIRE_MIN_PACKET_SIZE` | `64` | Minimum packet size in bytes | No |\n| `SPEEDWIRE_MAX_RETRIES` | `5` | Maximum number of retry attempts | No |\n| `SPEEDWIRE_BACKOFF_FACTOR` | `0.3` | Exponential backoff factor for retries | No |\n| `SPEEDWIRE_CONNECTION_POOL_SIZE` | `10` | Connection pool size for network connections | No |\n\n#### Gateway Performance Settings\n\n| Variable | Default | Description | Required |\n|----------|---------|-------------|----------|\n| `GATEWAY_LRU_CACHE_SIZE` | `128` | LRU cache size for performance optimization | No |\n| `GATEWAY_BATCH_SIZE` | `50` | Batch processing size for MQTT messages | No |\n| `GATEWAY_BATCH_FLUSH_INTERVAL` | `0.05` | Batch flush interval in seconds | No |\n| `GATEWAY_MAX_QUEUE_SIZE` | `10000` | Maximum queue size for message processing | No |\n\n#### Gateway Physical Limits\n\n| Variable | Default | Description | Required |\n|----------|---------|-------------|----------|\n| `GATEWAY_MAX_VOLTAGE` | `500.0` | Maximum voltage limit in volts | No |\n| `GATEWAY_MAX_CURRENT` | `100.0` | Maximum current limit in amperes | No |\n| `GATEWAY_MAX_POWER` | `50000.0` | Maximum power limit in watts | No |\n| `GATEWAY_MIN_FREQUENCY` | `45.0` | Minimum grid frequency in Hz | No |\n| `GATEWAY_MAX_FREQUENCY` | `65.0` | Maximum grid frequency in Hz | No |\n| `GATEWAY_DEFAULT_FREQUENCY` | `50.0` | Default grid frequency in Hz | No |\n| `GATEWAY_MIN_POWER_FACTOR_THRESHOLD` | `0.01` | Minimum power factor threshold | No |\n\n#### Gateway Device Configuration\n\n| Variable | Default | Description | Required |\n|----------|---------|-------------|----------|\n| `GATEWAY_DEFAULT_SW_VERSION` | `2.3.4.R` | Default software version to emulate | No |\n| `GATEWAY_MQTT_LOG_LEVEL` | `INFO` | MQTT-specific logging level | No |\n\n## Network Configuration\n\n### Requirements\n\n- **UDP Port 9522** - required for Speedwire communication\n- **Multicast** - address 239.12.255.254 (default mode)\n- **Broadcast** - address 255.255.255.255 (alternative mode)\n- **Network mode** - Docker containers use `network_mode: host`\n\n### Network Modes\n\n1. **Multicast (Default)** - requires multicast routing\n2. **Broadcast** - works in all configurations, higher network load\n3. **Dualcast** - sends both multicast and broadcast for better compatibility\n4. **Unicast** - direct communication to specific devices\n\n## CT Clamp Orientation\n\n### Important: Current Transformer Direction\n\nThe Shelly 3EM uses CT clamps to measure current flow. If these are installed backwards, the power readings will be inverted (consumption shows as generation and vice versa).\n\n### Using the invert_values Parameter\n\nIf your CT clamps are mounted backwards, set `invert_values: true`:\n\n```yaml\nmqtt:\n  invert_values: true\n```\n\nOr with Docker:\n```bash\n-e MQTT_INVERT_VALUES=true\n```\n\nThe invert_values option:\n- Reverses the sign of all power values\n- Swaps total and total_returned energy counters\n- Corrects power factor signs\n- Does not affect voltage, current, or frequency values\n\n## Data Mapping\n\nThe gateway translates Shelly 3EM MQTT data to SMA Speedwire protocol using OBIS codes:\n\n| Shelly 3EM Data | SMA Speedwire Field | OBIS Code | Description |\n|-----------------|---------------------|-----------|-------------|\n| Total Power | Total Active Power | 1.4.0 / 2.4.0 | Positive = Import, Negative = Export |\n| Phase A/B/C Power | L1/L2/L3 Active Power | 21/41/61.4.0 | Per-phase instantaneous power |\n| Calculated Total | Total Reactive Power | 3.4.0 / 4.4.0 | Calculated from V, I, PF |\n| Phase A/B/C Voltage | L1/L2/L3 Voltage | 32/52/72.4.0 | Phase voltages |\n| Phase A/B/C Current | L1/L2/L3 Current | 31/51/71.4.0 | Phase currents |\n| Phase A/B/C PF | L1/L2/L3 Power Factor | 33/53/73.4.0 | Per-phase power factors |\n| Grid Frequency | Frequency | 14.4.0 | Grid frequency |\n| Energy Consumed/Exported | Import/Export Energy | Various | Cumulative energy counters |\n\n### Power Flow Direction\n\n- **Positive power** = Energy consumption from grid\n- **Negative power** = Energy export to grid (solar feed-in)\n\n## Finding Your Shelly 3EM Topic\n\n### Method 1: MQTT Explorer\n1. Connect to your MQTT broker using MQTT Explorer\n2. Look for topics starting with `shellies/shelly3em-`\n3. The device ID is the part after `shelly3em-`\n\n### Method 2: Command Line\n```bash\nmosquitto_sub -h YOUR_BROKER_IP -t \"shellies/#\" -v\n```\n\n### Method 3: Shelly Web Interface\n1. Access your Shelly 3EM web interface\n2. Go to Settings → Device Info\n3. The device ID is shown there\n\n## Troubleshooting\n\n### Gateway Not Starting\n\nCheck MQTT connectivity:\n```bash\nping YOUR_BROKER_IP\nmosquitto_sub -h YOUR_BROKER_IP -t \"shellies/shelly3em-XXXXXXXXXXXXX/#\" -v\n```\n\nEnable debug logging:\n```bash\n# Docker\ndocker run -e LOG_LEVEL=DEBUG dzikus99/shelly-speedwire-gateway:latest\n\n# Systemd\n# Edit config file, set log_level to DEBUG, then restart\nsudo systemctl restart shelly-speedwire-gateway\n```\n\nCheck logs:\n```bash\n# Docker\ndocker logs shelly-speedwire\n\n# Systemd\njournalctl -u shelly-speedwire-gateway -f\n```\n\n### SMA Device Not Receiving Data\n\nTry different network modes:\n1. Enable broadcast: `SPEEDWIRE_USE_BROADCAST=true`\n2. Enable dualcast: `SPEEDWIRE_DUALCAST=true`\n3. Add device IP to unicast targets\n\n### Wrong Power Flow Direction\n\n1. Check CT clamp orientation - verify installation direction\n2. Enable `invert_values` if CT clamps are backwards\n3. Set `invert_values: true` in configuration\n\n### Debug Commands\n\n```bash\n# Monitor Shelly MQTT messages\nmosquitto_sub -h BROKER_IP -t \"shellies/#\" -v\n\n# Check network packets\ntcpdump -i any -n udp port 9522\n\n# Check Docker network mode\ndocker inspect shelly-speedwire | grep NetworkMode\n\n# Monitor specific power values\nmosquitto_sub -h BROKER_IP -t \"shellies/shelly3em-XXXXXXXXXXXXX/emeter/+/power\" -v\n```\n\n## Protocol Implementation\n\n### SMA Speedwire Protocol\n\nSMA Speedwire EMETER protocol v1.0:\n\n- **Protocol ID**: 0x6069 (EMETER)\n- **Discovery ID**: 0x6081\n- **Port**: UDP 9522\n- **Multicast**: 239.12.255.254\n- **Update Rate**: Configurable (default 1s)\n- **Reactive/apparent power support**\n- **Per-phase power factor with negative value support**\n\n## Development\n\n### Building from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/dzikus/shelly-speedwire-gateway\ncd shelly-speedwire-gateway\n\n# Install UV\npip install uv\n\n# Install dependencies and build Cython extensions\nuv sync\nuv run python setup.py build_ext --inplace\n\n# Run gateway\npython3 scripts/run_gateway.py\n```\n\n### Docker Build\n\n```bash\n# Single architecture\ndocker build -t shelly-speedwire-gateway .\n\n# Multi-architecture\ndocker buildx create --use\ndocker buildx build --platform linux/amd64,linux/arm64,linux/riscv64,linux/s390x,linux/386,linux/arm/v7 \\\n  --tag your-registry/shelly-speedwire-gateway:latest --push .\n```\n\n## Contributing\n\nContributing:\n\n1. Test changes with real hardware when available\n2. Update documentation for new features\n3. Use Python PEP 8 style guidelines\n4. Add debug logging for troubleshooting\n\n## Changelog\n\n### v2.0.0 (2025)\n- Added `invert_values` parameter for backwards CT clamp installations\n- Reactive power (VAr) calculation and transmission\n- Apparent power (VA) calculation and transmission\n- Per-phase power factor support with negative values\n- Complete SMA EMETER protocol implementation (all OBIS channels)\n- Software version emulation updated to 2.3.4.R\n- Removed `flip_import_export` parameter (replaced by `invert_values`)\n- **Performance optimizations**: Cython compilation, memory pooling, LRU caching, Batch processing\n### v1.0.0 (2025)\n- Initial release\n- Full Shelly 3EM support\n- SMA Speedwire EMETER protocol implementation\n- Docker, systemd, and standalone deployment options\n- Multicast, broadcast, and unicast transmission modes\n- Automatic discovery response\n- Configurable via environment variables or YAML\n\n## Acknowledgments\n\nProtocol implementation inspired by:\n- [venus.dbus-sma-smartmeter](https://github.com/Waldmensch1/venus.dbus-sma-smartmeter/)\n- [homeassistant-sma-sw](https://github.com/Wired-Square/homeassistant-sma-sw/)\n- [SMA-EM speedwire decoder](https://github.com/datenschuft/SMA-EM/)\n\nProtocol documentation from SMA and Shelly communities.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/dzikus/shelly-speedwire-gateway/issues)\n- **Docker Hub**: [dzikus99/shelly-speedwire-gateway](https://hub.docker.com/r/dzikus99/shelly-speedwire-gateway)\n\n---\n\nThis gateway is not affiliated with Shelly or SMA. Use at your own discretion.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdzikus%2Fshelly-speedwire-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdzikus%2Fshelly-speedwire-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdzikus%2Fshelly-speedwire-gateway/lists"}