node-red-contrib-senec-cloud-v2 1.0.0

Node-RED nodes for SENEC Cloud API integration - supports new API, CCU RedMatic optimized

npm install node-red-contrib-senec-cloud-v2

node-red-contrib-senec-cloud-v2

Node-RED nodes for SENEC Cloud API integration - supports the new SENEC Cloud API (2025+), optimized for CCU RedMatic.

Features

• ✅ SENEC Cloud API Integration - Works with the new SENEC Cloud API (August 2025+)
• ✅ Backward Compatible - Drop-in replacement for existing flows
• ✅ CCU RedMatic Optimized - Low resource usage, tested on CCU hardware
• ✅ Automatic Error Recovery - Exponential backoff retry logic
• ✅ Image Generation - Create PNG images for TRMNL e-ink displays
• ✅ Secure - Credentials encrypted using Node-RED's credential system

Installation

Via Node-RED Palette Manager (Recommended)

1. Open Node-RED editor
2. Click menu (☰) → Manage palette
3. Go to "Install" tab
4. Search for senec-cloud-v2
5. Click "Install"

Via npm

cd ~/.node-red
npm install node-red-contrib-senec-cloud-v2
node-red-restart

On CCU RedMatic

1. Open CCU WebUI
2. Navigate to RedMatic add-on
3. Open Node-RED editor
4. Use Palette Manager as described above

Quick Start

1. Add Configuration Node

1. Drag a senec-data node into your flow
2. Double-click to edit
3. Click the pencil icon next to "SENEC Config"
4. Enter your SENEC Cloud credentials:
   • Username: Your SENEC Cloud username/email
   • Password: Your SENEC Cloud password
5. Click "Test Connection" to verify
6. Click "Add" to save

2. Configure Data Node

1. Set poll interval (default: 60 seconds, recommended 120s for CCU)
2. Enable/disable automatic polling
3. Deploy your flow

3. Use the Data

The node outputs energy data in msg.payload:

{
  steuereinheitState: "online",
  gridimport: { today: 2.5, now: 150 },      // kWh, W
  powergenerated: { today: 18.5, now: 3200 }, // kWh, W
  consumption: { today: 12.3, now: 1800 },    // kWh, W
  gridexport: { today: 8.2, now: 1400 },      // kWh, W
  acculevel: { now: 85 }                      // %
}

Nodes

senec-config

Configuration node for SENEC Cloud credentials. Shared across multiple data nodes.

Configuration:

• Username (required)
• Password (required)
• Test Connection button

senec-data

Retrieves energy data from SENEC Cloud.

Configuration:

• SENEC Config: Reference to config node
• Poll Interval: Seconds between automatic updates (default: 60)
• Enable Polling: Automatic periodic updates

Input: Any message triggers immediate data retrieval (independent of polling)

Output: msg.payload contains SENEC energy data

Status Indicators:

• 🟢 Connected - Successfully connected and retrieving data
• 🟡 Retrying - Temporary error, retrying automatically
• 🔴 Error - Persistent error, check credentials or connection

senec-image

Generates PNG images from SENEC data for displays.

Configuration:

• Template: trmnl, compact, or detailed
• Width/Height: Image dimensions
• Output Format: buffer, base64, or file
• Color Scheme: monochrome (e-ink) or color

Input: msg.payload with SENEC data

Output: PNG image as Buffer, base64 string, or file path

Examples

Basic Monitoring

[senec-data] → [debug]

TRMNL Display

[inject: every 5 min] → [senec-data] → [senec-image: TRMNL] → [http response]

CCU Homematic Integration

[senec-data] → [function: extract battery] → [ccu-value: battery variable]

Automation Example

// In a function node after senec-data
var battery = msg.payload.acculevel.now;
var solar = msg.payload.powergenerated.now;

if (battery > 80 && solar > 2000) {
    // Excess solar available - turn on devices
    return { payload: true };
}

Configuration Tips

For CCU RedMatic

• Use poll interval of 120 seconds (2 minutes) to reduce resource usage
• Monitor memory usage in CCU WebUI
• Disable polling if only triggered retrieval needed

For Raspberry Pi / Standard Node-RED

• Default 60 second interval works well
• Can use shorter intervals if needed (minimum 10 seconds)

For TRMNL Displays

• Use senec-image node with TRMNL template
• Set dimensions to 800x480 (or your display size)
• Use monochrome color scheme for e-ink
• Serve via HTTP endpoint for TRMNL to fetch

Troubleshooting

Authentication Failed

• Verify credentials in config node
• Check SENEC Cloud account is active
• Try logging in to SENEC web portal to confirm credentials

Connection Timeout

• Check internet connectivity
• Verify firewall allows HTTPS outbound
• SENEC Cloud may be temporarily unavailable (automatic retry)

Rate Limited

• Reduce poll frequency
• Default backoff will handle this automatically
• Check for multiple flows polling the same account

High Memory Usage on CCU

• Increase poll interval to 120-300 seconds
• Disable polling, use triggered retrieval only
• Check for other resource-intensive flows

API Changes

This package supports the new SENEC Cloud API (August 2025+). The old API is no longer supported by SENEC.

Migration from old package:

• Payload structure is identical - existing flows work without changes
• Simply replace old nodes with new ones
• Update credentials in config node

Development

Setup

git clone https://github.com/aunovis-fitting/node-red-contrib-senec-cloud-v2.git
cd node-red-contrib-senec-cloud-v2
npm install

Build

npm run build

Test

npm test
npm run test:coverage

Local Testing in Node-RED

npm run build
npm link
cd ~/.node-red
npm link node-red-contrib-senec-cloud-v2
node-red-restart

Architecture

See docs/00-ARCHITECTURE_SUMMARY.md for complete architecture documentation.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Node-RED Forum: Node-RED Community
• HomeMatic Forum: HomeMatic-Forum.de (German)

License

MIT License - see LICENSE file

Acknowledgments

• SENEC for their solar energy storage systems
• Node-RED community
• CCU RedMatic project
• Original senec-cloud package contributors

Disclaimer

This is an unofficial integration. Not affiliated with or endorsed by SENEC GmbH.

Status: 🚧 In Development

Current Version: 0.1.0 (Pre-release)

Target Release: v1.0.0