shelly-development-standards

Shelly Development Standards

This rule defines standards and best practices for developing solutions for Shelly devices.

Overview

Shelly scripts run on a modified version of mJS (a subset of JavaScript) and operate in a non-blocking environment that shares CPU time with device firmware. Development must follow specific patterns to ensure reliability and prevent device crashes.

TypeScript Requirements

• Always use TypeScript for all Shelly solution development
• Use types from the shelly-forge library when available: node_modules/shelly-forge/types/**/*
• Define custom types for all data structures and API responses

✅ Correct:

export type ThermostatState = "On" | "Off";
export interface Schedule {
  weekDays: boolean[];
  startTime: number;
  endTime: number;
  temperature: number;
}

❌ Incorrect:

// Using plain JavaScript without types
let state = "Off";
let schedule = {
  weekDays: [false, true, true, true, true, true, false],
  startTime: 6,
  endTime: 9,
  temperature: 39
};

Callback Functions

Due to limitations in the JavaScript engine, avoid deep nesting of anonymous functions as this can crash the device:

✅ Correct:

function processResponse(result: any, error_code: number, error_message: string) {
  if (error_code !== 0) {
    print("Error: " + error_message);
    return;
  }
  // Process result
}

Shelly.call("HTTP.GET", { url: "http://example.com/" }, processResponse);

❌ Incorrect:

Shelly.call(
  "HTTP.GET",
  { url: "http://example.com/" },
  function(result, error_code, error_message) {
    if (error_code !== 0) {
      print("Error: " + error_message);
      Shelly.call(
        "Switch.Set",
        { id: 0, on: false },
        function(res, err_code, err_msg) {
          // More nested callbacks - DANGEROUS!
        }
      );
    }
  }
);

State Management

• Use the Storage/KVS API for persistent state storage
• Create a typed interface around the Storage API for type safety
• Implement the store as a singleton to ensure consistent access