Automation

Automation allows you to create triggers and actions for nodes. You can set up automations that respond to specific conditions or events.

Overview

Automation in RainMaker enables you to:

• Create automation triggers for nodes
• Retrieve and manage automations
• Set up conditional actions based on device states

Add Automation

Add a new automation trigger for a node using the addAutomation method.

try {
  const automationDetails = {
    name: "Turn on lights when motion detected",
    events: [
      {
        params: {
          Motion: {
            Motion: true,
          },
        },
        check: "==",
      },
    ],
    eventOperator: "and",
    actions: [
      {
        node_id: "target_node_id",
        params: {
          Light: {
            Power: true,
            Brightness: 80,
          },
        },
      },
    ],
    retrigger: false,
    metadata: {
      description: "Automation to turn on lights when motion is detected",
    },
  };

  const automation = await node.addAutomation(automationDetails);
  console.log("Automation created:", automation);
} catch (error) {
  console.error("Error creating automation:", error);
}

ESPAutomationDetails Interface

The addAutomation method requires an ESPAutomationDetails object with the following properties:

Property	Type	Required	Description
name*	string	Yes	The name of the automation.
events*	ESPAutomationEvent[]	Yes	Array of events that trigger the automation.
eventOperator*	ESPAutomationEventOperator	Yes	Operator to combine multiple events ("and" or "or").
actions*	ESPAutomationAction[]	Yes	Array of actions to execute when events are triggered.
retrigger*	boolean	Yes	Whether the automation can be retriggered while already active.
metadata	any	No	Optional metadata associated with the automation.

Example: Multiple Events with AND Operator

try {
  const automationDetails = {
    name: "Turn on lights when brightness is low AND motion detected",
    events: [
      {
        params: {
          Light: {
            Brightness: 30,
          },
        },
        check: "<=",
      },
      {
        params: {
          Motion: {
            Motion: true,
          },
        },
        check: "==",
      },
    ],
    eventOperator: "and",
    actions: [
      {
        node_id: "light_node_id",
        params: {
          Light: {
            Power: true,
            Brightness: 100,
          },
        },
      },
    ],
    retrigger: false,
  };

  const automation = await node.addAutomation(automationDetails);
  console.log("Automation created:", automation);
} catch (error) {
  console.error("Error creating automation:", error);
}

Example: Multiple Events with OR Operator

try {
  const automationDetails = {
    name: "Turn on lights when motion detected OR time is after sunset",
    events: [
      {
        params: {
          Motion: {
            Motion: true,
          },
        },
        check: "==",
      },
      {
        params: {
          Time: {
            Time: "18:00",
          },
        },
        check: ">=",
      },
    ],
    eventOperator: "or",
    actions: [
      {
        node_id: "light_node_id",
        params: {
          Light: {
            Power: true,
          },
        },
      },
    ],
    retrigger: true,
  };

  const automation = await node.addAutomation(automationDetails);
  console.log("Automation created:", automation);
} catch (error) {
  console.error("Error creating automation:", error);
}

Get Automations

Retrieve a list of all automations for a node with optional pagination using the getAutomations method.

try {
  const automations = await node.getAutomations();
  console.log("Node automations:", automations);
} catch (error) {
  console.error("Error fetching automations:", error);
}

ESPPaginatedAutomationsResponse Interface

The getAutomations method returns an ESPPaginatedAutomationsResponse object with the following properties:

Property	Type	Description
automations*	ESPAutomation[]	List of automations in the current page.
hasNext*	boolean	Indicates if there are more pages available.
fetchNext	() => Promise<ESPPaginatedAutomationsResponse>	Optional function to fetch the next page of automations.

Example: Handling Pagination

try {
  let response = await node.getAutomations();
  let allAutomations = [...response.automations];

  // Fetch all pages if available
  while (response.hasNext && response.fetchNext) {
    response = await response.fetchNext();
    allAutomations = [...allAutomations, ...response.automations];
  }

  console.log("All automations:", allAutomations);
  console.log("Total count:", allAutomations.length);
} catch (error) {
  console.error("Error fetching automations:", error);
}

Example: Processing Automations

try {
  const response = await node.getAutomations();

  response.automations.forEach((automation) => {
    console.log(`Automation: ${automation.name}`);
    console.log(`Events: ${automation.events.length}`);
    console.log(`Actions: ${automation.actions.length}`);
    console.log(`Retrigger: ${automation.retrigger}`);
  });

  if (response.hasNext) {
    console.log(
      "More automations available. Use fetchNext() to retrieve them."
    );
  }
} catch (error) {
  console.error("Error fetching automations:", error);
}

Prerequisites: Setting Geo Coordinates

Before using location-based automations (Daylight and Weather), you must set the user's geographical coordinates. This is required because both daylight and weather automations rely on the user's location to determine trigger conditions.

Set Geo Coordinates

Use the setGeoCoordinates method to store the user's latitude and longitude.

try {
  const geoCoordinates = {
    latitude: "37.7749", // Example: San Francisco latitude
    longitude: "-122.4194", // Example: San Francisco longitude
  };

  const response = await user.setGeoCoordinates(geoCoordinates);
  console.log("Geo coordinates set successfully:", response);
} catch (error) {
  console.error("Error setting geo coordinates:", error);
}

Get Geo Coordinates

Retrieve the stored geographical coordinates using the getGeoCoordinates method.

try {
  const coordinates = await user.getGeoCoordinates();
  console.log("Latitude:", coordinates.latitude);
  console.log("Longitude:", coordinates.longitude);
} catch (error) {
  console.error("Error retrieving geo coordinates:", error);
}

Note: If you attempt to create a daylight or weather automation without setting geo coordinates first, the SDK will automatically retrieve the stored coordinates. If no coordinates are found, an error will be thrown.

Add Daylight-Based Automation

Create automations that trigger based on daylight events such as sunrise and sunset using the addDaylightBasedAutomation method.

try {
  const daylightAutomationDetails = {
    name: "Turn on lights at sunset",
    events: ["sunset"], // Can be "sunrise" or "sunset"
    eventOperator: "or",
    actions: [
      {
        nodeId: "light_node_id",
        deviceName: "Light",
        param: "Power",
        value: true,
      },
    ],
    retrigger: true,
    metadata: {
      description: "Automatically turn on lights when the sun sets",
    },
  };

  const automation = await user.addDaylightBasedAutomation(
    daylightAutomationDetails
  );
  console.log("Daylight automation created:", automation);
} catch (error) {
  console.error("Error creating daylight automation:", error);
}

ESPDaylightAutomationDetails Interface

The addDaylightBasedAutomation method requires an ESPDaylightAutomationDetails object with the following properties:

Property	Type	Required	Description
name*	string	Yes	The name of the automation.
events*	ESPDaylightEvent[]	Yes	Array of daylight events ("sunrise" or "sunset").
eventOperator*	ESPAutomationEventOperator	Yes	Operator to combine multiple events ("and" or "or").
actions*	ESPAutomationAction[]	Yes	Array of actions to execute when events are triggered.
retrigger*	boolean	Yes	Whether the automation can be retriggered while already active.
location	ESPGeoCoordinates	No	Optional location override. If not provided, uses stored geo coordinates.
metadata	any	No	Optional metadata associated with the automation.

Example: Turn on Lights at Sunrise

try {
  const daylightAutomationDetails = {
    name: "Morning lights",
    events: ["sunrise"],
    eventOperator: "or",
    actions: [
      {
        nodeId: "bedroom_light_node_id",
        deviceName: "Light",
        param: "Power",
        value: true,
      },
      {
        nodeId: "bedroom_light_node_id",
        deviceName: "Light",
        param: "Brightness",
        value: 50,
      },
    ],
    retrigger: true,
    metadata: {
      description: "Gradually turn on bedroom lights at sunrise",
    },
  };

  const automation = await user.addDaylightBasedAutomation(
    daylightAutomationDetails
  );
  console.log("Sunrise automation created:", automation.automationId);
} catch (error) {
  console.error("Error creating sunrise automation:", error);
}

Example: Multiple Actions at Sunset

try {
  const daylightAutomationDetails = {
    name: "Evening routine",
    events: ["sunset"],
    eventOperator: "or",
    actions: [
      {
        nodeId: "living_room_light_node_id",
        deviceName: "Light",
        param: "Power",
        value: true,
      },
      {
        nodeId: "outdoor_light_node_id",
        deviceName: "Light",
        param: "Power",
        value: true,
      },
      {
        nodeId: "thermostat_node_id",
        deviceName: "Thermostat",
        param: "Temperature",
        value: 22,
      },
    ],
    retrigger: true,
  };

  const automation = await user.addDaylightBasedAutomation(
    daylightAutomationDetails
  );
  console.log("Evening automation created successfully");
} catch (error) {
  console.error("Error creating evening automation:", error);
}

Example: Using Custom Location

try {
  // Use a custom location instead of the stored geo coordinates
  const customLocation = {
    latitude: "40.7128", // New York City
    longitude: "-74.0060",
  };

  const daylightAutomationDetails = {
    name: "NYC sunset lights",
    events: ["sunset"],
    eventOperator: "or",
    actions: [
      {
        nodeId: "light_node_id",
        deviceName: "Light",
        param: "Power",
        value: true,
      },
    ],
    retrigger: true,
    location: customLocation,
  };

  const automation = await user.addDaylightBasedAutomation(
    daylightAutomationDetails
  );
  console.log("Custom location automation created:", automation);
} catch (error) {
  console.error("Error creating automation:", error);
}

Add Weather-Based Automation

Create automations that trigger based on weather conditions using the addWeatherBasedAutomation method.

try {
  const weatherAutomationDetails = {
    name: "Turn on heater when cold",
    events: [
      {
        param: "temperature",
        value: 15,
        check: "<=",
      },
    ],
    eventOperator: "or",
    actions: [
      {
        nodeId: "heater_node_id",
        deviceName: "Heater",
        param: "Power",
        value: true,
      },
      {
        nodeId: "heater_node_id",
        deviceName: "Heater",
        param: "Temperature",
        value: 22,
      },
    ],
    retrigger: true,
    metadata: {
      description: "Turn on heater when temperature drops below 15°C",
    },
  };

  const automation = await user.addWeatherBasedAutomation(
    weatherAutomationDetails
  );
  console.log("Weather automation created:", automation);
} catch (error) {
  console.error("Error creating weather automation:", error);
}

ESPWeatherAutomationDetails Interface

The addWeatherBasedAutomation method requires an ESPWeatherAutomationDetails object with the following properties:

Property	Type	Required	Description
name*	string	Yes	The name of the automation.
events*	(ESPWeatherEvent | ESPWeatherCondition)[]	Yes	Array of weather events or conditions.
eventOperator*	ESPAutomationEventOperator	Yes	Operator to combine multiple events ("and" or "or").
actions*	ESPAutomationAction[]	Yes	Array of actions to execute when events are triggered.
retrigger*	boolean	Yes	Whether the automation can be retriggered while already active.
location	ESPGeoCoordinates	No	Optional location override. If not provided, uses stored geo coordinates.
metadata	any	No	Optional metadata associated with the automation.

Weather Event Types

Weather events can be specified in two ways:

1. Weather Condition String: Use predefined weather condition strings like "rain", "snow", "clear", etc.
2. Weather Parameter Object: Specify a weather parameter with a value and comparison operator:
   • param: The weather parameter (e.g., "temperature", "humidity", "wind_speed")
   • value: The threshold value
   • check: Comparison operator ("==", "!=", "<", ">", "<=", ">=")

Example: Weather Condition Trigger

try {
  const weatherAutomationDetails = {
    name: "Close windows when raining",
    events: ["rain"], // Using weather condition string
    eventOperator: "or",
    actions: [
      {
        nodeId: "window_controller_node_id",
        deviceName: "Window",
        param: "Position",
        value: 0, // Fully closed
      },
    ],
    retrigger: false,
  };

  const automation = await user.addWeatherBasedAutomation(
    weatherAutomationDetails
  );
  console.log("Rain automation created:", automation.automationId);
} catch (error) {
  console.error("Error creating rain automation:", error);
}

Example: Multiple Weather Parameters

try {
  const weatherAutomationDetails = {
    name: "Climate control",
    events: [
      {
        param: "temperature",
        value: 30,
        check: ">=",
      },
      {
        param: "humidity",
        value: 70,
        check: ">=",
      },
    ],
    eventOperator: "and", // Both conditions must be true
    actions: [
      {
        nodeId: "ac_node_id",
        deviceName: "AC",
        param: "Power",
        value: true,
      },
      {
        nodeId: "ac_node_id",
        deviceName: "AC",
        param: "Temperature",
        value: 24,
      },
      {
        nodeId: "dehumidifier_node_id",
        deviceName: "Dehumidifier",
        param: "Power",
        value: true,
      },
    ],
    retrigger: true,
    metadata: {
      description: "Turn on AC and dehumidifier when hot and humid",
    },
  };

  const automation = await user.addWeatherBasedAutomation(
    weatherAutomationDetails
  );
  console.log("Climate automation created successfully");
} catch (error) {
  console.error("Error creating climate automation:", error);
}

Example: Wind Speed Monitor

try {
  const weatherAutomationDetails = {
    name: "High wind alert",
    events: [
      {
        param: "wind_speed",
        value: 50, // km/h
        check: ">=",
      },
    ],
    eventOperator: "or",
    actions: [
      {
        nodeId: "outdoor_blind_node_id",
        deviceName: "Blind",
        param: "Position",
        value: 0, // Retract blinds
      },
      {
        nodeId: "notification_node_id",
        deviceName: "Alert",
        param: "Status",
        value: true,
      },
    ],
    retrigger: false,
  };

  const automation = await user.addWeatherBasedAutomation(
    weatherAutomationDetails
  );
  console.log("Wind speed automation created:", automation);
} catch (error) {
  console.error("Error creating wind automation:", error);
}

Example: Combining Weather Condition and Parameters

try {
  const weatherAutomationDetails = {
    name: "Smart weather response",
    events: [
      "snow", // Weather condition string
      {
        param: "temperature",
        value: 0,
        check: "<=",
      },
    ],
    eventOperator: "or", // Trigger if snowing OR temperature below 0°C
    actions: [
      {
        nodeId: "heating_node_id",
        deviceName: "Heating",
        param: "Power",
        value: true,
      },
      {
        nodeId: "heating_node_id",
        deviceName: "Heating",
        param: "Mode",
        value: "max",
      },
    ],
    retrigger: true,
    metadata: {
      description: "Maximize heating during snow or freezing conditions",
    },
  };

  const automation = await user.addWeatherBasedAutomation(
    weatherAutomationDetails
  );
  console.log("Winter weather automation created:", automation);
} catch (error) {
  console.error("Error creating weather automation:", error);
}