Solarman Collector (Rust)

A high-performance Rust-based TCP server that receives telemetry data from Solarman micro-inverter data loggers using the Solarman V5 protocol.

Overview

This is a Rust rewrite of the TypeScript collector, designed to provide better performance, lower memory usage, and improved reliability.

Features

• Solarman V5 Protocol: Full packet decoding and validation with checksum verification
• Message Decoders: Support for all control codes:
  • Hello message (0x4110)
  • Primary telemetry (0x4210)
  • Secondary telemetry (0x4310)
  • Heartbeat (0x4710)
  • Hello End (0x4810)
• Deye 0x5408 Format: Specialized decoder for Deye micro-inverter data
• TCP Server: High-performance async TCP server with connection pooling
• Database Integration: TimescaleDB storage layer with connection pooling
• Logger Verification: Database-backed logger cache with verification
• Observability: OpenTelemetry OTLP instrumentation for traces and metrics
• Configuration: Environment variable-based configuration
• Docker Support: Multi-stage Dockerfile with optimized image size
• CI/CD: Automated testing and Docker image publishing via GitHub Actions
• Testing: Integration tests with solarman-emulator

Architecture

collector-rust/
├── src/
│   ├── main.rs              # Entry point
│   ├── lib.rs               # Library exports
│   ├── config.rs            # Configuration
│   ├── error.rs             # Error types
│   ├── observability.rs     # OpenTelemetry OTLP instrumentation
│   │
│   ├── protocol/            # Solarman V5 protocol
│   │   ├── mod.rs
│   │   ├── packet.rs        # Packet decode/encode
│   │   ├── control_codes.rs # Control code constants
│   │   ├── decoder.rs       # Message decoders
│   │   └── decoder_5408.rs  # Deye format decoder
│   │
│   ├── server/              # TCP server implementation
│   │   ├── mod.rs           # Server setup and listener
│   │   ├── connection.rs    # Connection handling
│   │   └── packet_handler.rs # Packet processing
│   │
│   ├── backend/             # Logger verification with caching
│   │   ├── mod.rs
│   │   └── logger_cache.rs  # Database-backed cache
│   │
│   └── storage/             # TimescaleDB integration
│       ├── mod.rs
│       └── timescale.rs     # Storage layer with connection pooling
│
├── Cargo.toml
├── .env.example
└── README.md

Building

Prerequisites

• Rust 1.75 or higher (tested with 1.86)
• Cargo

Build Commands

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Check code without building
cargo check

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run

Configuration

Create a .env file (see .env.example):

# TCP Server
PORT=10000

# Database (TimescaleDB)
DATABASE_URL=postgres://user:password@localhost:5432/deyehard

# Logging
RUST_LOG=info

# OpenTelemetry OTLP (optional, for observability)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=solarman-collector

For detailed observability setup, see docs/OTLP_INSTRUMENTATION.md.

Running

# Using cargo
cargo run --release

# Or run the binary directly
./target/release/solarman-collector

Testing

The project uses the solarman-emulator (in parent directory) for integration testing.

Quick test:

# Run emulator in single-shot mode
cd ../solarman-emulator
cargo run --release -- \
  --host localhost \
  --port 10000 \
  --logger-serial 4142050081 \
  --mode single-shot

For comprehensive testing guide including load tests, continuous mode, and CI/CD integration, see docs/TESTING.md.

Docker Deployment

The project includes production-ready Docker support:

# Build locally
docker build -t solarman-collector:latest .

# Run with Docker
docker run --rm \
  -e PORT=10000 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/deyehard \
  -e RUST_LOG=info \
  -p 10000:10000 \
  solarman-collector:latest

Docker Registry Deployment:

• Quick Start Guide (ARM64 → AMD64) - Build on Apple Silicon for AMD64 deployment
• Complete Docker Publishing Guide - Multi-arch builds, CI/CD, and registry setup

GitHub Actions CI/CD:

• Automated testing on push/PR: .github/workflows/test.yml
• Automated Docker builds on tags: .github/workflows/docker-build-push.yml

Development Status

Completed:

• ✅ Solarman V5 protocol implementation
• ✅ TCP server with async connection handling
• ✅ TimescaleDB storage layer
• ✅ Logger verification with caching
• ✅ OpenTelemetry OTLP instrumentation
• ✅ Docker support with multi-stage builds
• ✅ CI/CD pipeline with GitHub Actions
• ✅ Integration testing with emulator

Documentation:

• ✅ Main README
• ✅ OTLP Instrumentation guide
• ✅ Docker build and publish guide
• ✅ Quick start guide for ARM64/AMD64 builds
• ✅ Testing guide

Protocol Documentation

See:

• ../CLAUDE.md - Collector overview
• ../solarman-emulator/PLAN.md - Detailed protocol specification
• ../solarman-emulator/README.md - Emulator usage

License

AGPL-3.0

Authors

Björn Hauffe