shelly-solution-workflow

Shelly Device Solution Development Workflow

This rule defines the standard workflow for designing and implementing solutions for Shelly devices.

Solution Design Phase

• Always start by creating a solution design document in the docs/ folder
• Name the file docs/<solution-name>.md
• The solution design must be complete before proceeding to implementation
• Design document should include:
  • Solution overview and purpose
  • Required hardware (Shelly devices and peripherals)
  • Logical components and their interactions
  • Required scripts and their functionality
  • Configuration parameters
  • MQTT topics (if applicable)

✅ Correct:

# Smart Heating Solution

## Overview
This solution provides zoned heating control using Shelly Plus 1PM devices to control radiator valves.

## Hardware Requirements
- Shelly Plus 1PM (one per zone)
- NTC Temperature Sensors (one per zone)
- Motorized radiator valves (one per zone)

## Components
1. Temperature monitoring script
2. Zone controller script
3. Central scheduler
...

Environment Variable Management

• All device-specific information must be defined as environment variables
• Define device information in .env file for actual values
• Document all required variables in .env.example with placeholder values
• Prefix variables with SHELLY_PUBLIC_ if you want to use them within the scripts
• Other env variables are used during build time defined in the solution.config.json
• Include all environment variables in the solution design document

✅ Correct:

# Device Network Configuration
SHELLY_PUBLIC_DEVICE_HOSTNAME=192.168.1.100
SHELLY_PUBLIC_UPDATE_INTERVAL=600

✅ Correct Environment Variable Usage in Scripts:

// Access environment variables in scripts
const deviceHostname = process.env.SHELLY_PUBLIC_DEVICE_HOSTNAME;
const updateInterval = parseInt(process.env.SHELLY_PUBLIC_UPDATE_INTERVAL || "600");

// Use variables in device calls
Shelly.call("HTTP.GET", {
  url: `http://${deviceHostname}/status`
}, processResponse);