Add a device to a room with automatic parent group handling.

This function automatically handles the ESP RainMaker hierarchy requirement:

1. First adds the device to the parent group (e.g., "My Home")

2. Then adds the device to the target room group (e.g., "Kitchen")

Parameters:

• device_node_id: The node ID of the device to add

• room_group_id: The group ID of the room to add the device to

This is a convenience function that makes the hierarchical behavior explicit.

Checks if a valid login session exists based on stored credentials.

Create a new group (home, room, or custom group) using Python library API.

Parameters:

• name: Name of the group (required)

• group_type: Type of group ('home', 'room', or custom type)

• description: Description of the group (optional)

• mutually_exclusive: Set mutually exclusive flag (recommended for homes and rooms)

• parent_group_id: Parent group ID (required for rooms under a home)

• nodes: Comma-separated list of node IDs to add to the group (optional)

• custom_data: Custom data as JSON string (optional)

Examples:

• Create home: create_group("My Home", "home", mutually_exclusive=True)

• Create room: create_group("Living Room", "room", mutually_exclusive=True, parent_group_id="home_id")

Get comprehensive group information using Python library API.

Parameters:

• group_id: ID of specific group to show (optional - if None, lists all groups)

• include_nodes: Include detailed node information for groups

• fields: List of group/sub-group keys to include (if None, includes all fields)

• node_fields: List of node keys to include (if None, includes all node fields)

When group_id is None: Lists all groups with hierarchy When group_id is provided: Shows detailed information for that specific group When include_nodes is True: Includes comprehensive node details within groups

IMPORTANT USAGE GUIDELINES:

1. For home/room structure overview (recommended for most queries):

   {
       "include_nodes": true,
       "fields": ["group_id", "group_name", "type", "total", "sub_groups", "node_details"],
       "node_fields": ["node_id", "name", "type"]
   }

2. For home/room structure with basic device info:

   {
       "include_nodes": true,
       "fields": ["group_id", "group_name", "type", "total", "sub_groups", "node_details"],
       "node_fields": ["node_id", "name", "type", "model", "fw_version"]
   }

3. For detailed technical information:

   {
       "include_nodes": true,
       "fields": ["group_id", "group_name", "type", "total", "sub_groups", "node_details",
                 "is_matter", "fabric_id", "primary", "mutually_exclusive"],
       "node_fields": ["node_id", "name", "type", "model", "fw_version", "status", "params"]
   }

Common Use Cases:

Note: When fields/node_fields are not provided, defaults to summary mode (basic fields) to avoid overwhelming responses.

PREFERRED TOOL for getting comprehensive node information efficiently. Gets config, status, and params in a single API call instead of multiple separate calls.

USAGE:

• To get all nodes: set node_id=None (default).

• To get a single node: set node_id to a single node ID string.

  • Only a single node ID is supported. Do NOT use a comma-separated list or array.

  • If the node is not found or not accessible, the result will be an empty dict or contain empty/unknown fields.

FILTERING & FIELD SELECTION:

• fields: comma-separated list of fields to include in the output (e.g. "node_id,name,type,config,params,status.connectivity,fw_version,mapping_timestamp").

• name: substring match (matches user-visible name, extracted from params.{DeviceType}.Name).

• type_: substring match (matches device type, from config.devices[].type).

• node_id: single node ID string (for a single node), or None (for all nodes).

MULTIPLE NODE FILTERING:

• To filter for multiple node IDs, set node_id=None and use filtering (e.g. by name or type) in post-processing.

• Passing a comma-separated list of node IDs is NOT supported and will result in an error.

RETURN VALUE:

• If a single node is requested, returns a dict (or empty dict if not found).

• If all nodes are requested, returns a list of dicts (one per node).

EXAMPLES:

• Get all nodes, only node_id and name: get_node_details(ctx, fields="node_id,name")

• Get a single node by ID: get_node_details(ctx, node_id="30EDA0E0AF48", fields="node_id,name,config")

• Get all nodes of type 'lightbulb': get_node_details(ctx, type_="lightbulb", fields="node_id,name,type")

Get ONLY the list of node IDs (names) without detailed information.

Use this tool only when:

• User specifically asks for "node IDs", "device names", or "list of devices"

• You need just the names/IDs for reference

For comprehensive device information, use get_node_details instead.

Get ONLY the online/offline status for a specific node.

Use this tool only when:

• User specifically asks about "status", "online", "offline" of a particular device

• You already have other info and need just the status

For comprehensive device information, use get_node_details instead.

Get ONLY the current parameters (state) for a specific node.

Use this tool only when:

• User specifically asks for "parameters", "state", or "current values" of a particular device

• You already have other info and need just the current state

For comprehensive device information, use get_node_details instead.

Get schedule information for a specific node. Returns the schedules configured for the node if any exist, along with support status.

Response includes:

• schedules_supported: Whether the node supports scheduling

• schedules: Array of schedule objects with trigger and action details

• schedule_count: Number of configured schedules

Each schedule object contains:

• id: Unique schedule identifier

• name: Human-readable schedule name

• enabled: Whether the schedule is active

• triggers: Array of trigger conditions (format explained below)

• action: What the schedule will do when triggered

TRIGGER FORMAT GUIDE (for understanding schedule responses):

• "m": Minutes since midnight (0-1439). Example: 480 = 8:00 AM, 1110 = 6:30 PM

• "d": Day bitmap for which days to trigger:

  • 31 = Weekdays (Mon-Fri)

  • 96 = Weekends (Sat-Sun)

  • 127 = Every day

  • 0 = One-time only

  • Individual days: 1=Mon, 2=Tue, 4=Wed, 8=Thu, 16=Fri, 32=Sat, 64=Sun

• "dd": Day of month (1-31)

• "mm": Month bitmap (4095 = all months)

• "rsec": Relative seconds from creation time

• "ts": Exact Unix timestamp when schedule was created or will trigger

Example: {"m": 1110, "d": 31} means "6:30 PM on weekdays"

NOTE: Schedule actions use device type names (like "Light") not display names. See get_node_details for the mapping between device types and their display names.

Provides instructions (formatted with Markdown) on how to log in using the standard ESP RainMaker CLI. This server relies on credentials saved locally by that process. Rendering as Markdown depends on the MCP client capabilities.

Set parameters for one or more nodes using a JSON object (dictionary).

Parameters:

• node_id: Single node ID or comma-separated list of node IDs (e.g., "node1" or "node1,node2,node3")

• params_dict: Dictionary containing the parameters to set

Example params_dict value: {'Thermostat': {'Power': False}}

When multiple node IDs are provided, the same parameters will be applied to all specified nodes. This is useful for bulk operations like turning off multiple devices or setting common configurations.

Manage schedules for one or more nodes.

Parameters:

• node_id: Single node ID or comma-separated list of node IDs (e.g., "node1" or "node1,node2,node3")

• operation: Operation to perform (add, edit, remove, enable, disable)

• schedule_id: Schedule ID (required for edit, remove, enable, disable operations)

• name: Schedule name (required for add operation, optional for edit)

• trigger: Dictionary defining when to trigger (required for add, optional for edit)

• action: Dictionary defining what to do (required for add, optional for edit)

• info: Additional information for the schedule (optional)

• flags: General purpose flags for the schedule (optional)

When multiple node IDs are provided:

• For 'add' operations: Creates the same schedule on all specified nodes with a common schedule ID

• For 'edit/remove/enable/disable' operations: Applies the operation to the specified schedule on all nodes

• This is useful for bulk schedule management across multiple devices

TRIGGER FORMAT GUIDE: Time-based triggers use these fields:

• "m": Minutes since midnight (0-1439). Example: 480 = 8:00 AM, 1110 = 6:30 PM

• "d": Day bitmap for which days to trigger:

  • 31 = Weekdays (Mon-Fri)

  • 96 = Weekends (Sat-Sun)

  • 127 = Every day

  • 0 = One-time only

  • Individual days: 1=Mon, 2=Tue, 4=Wed, 8=Thu, 16=Fri, 32=Sat, 64=Sun

• "dd": Day of month (1-31)

• "mm": Month bitmap (4095 = all months)

• "rsec": Relative seconds from now

• "ts": Exact Unix timestamp

COMMON TRIGGER EXAMPLES:

• Daily 8:00 AM: {"m": 480, "d": 127}

• Weekdays 6:30 PM: {"m": 1110, "d": 31}

• Weekends 10:00 AM: {"m": 600, "d": 96}

• One-time 7:00 PM: {"m": 1140, "d": 0}

• 15th of every month at noon: {"m": 720, "dd": 15, "mm": 4095}

• In 1 hour: {"rsec": 3600}

ACTION EXAMPLES:

• Turn on light: {"Light": {"Power": true}}

• Set brightness: {"Light": {"Power": true, "Brightness": 80}}

• Control thermostat: {"Thermostat": {"Power": true, "Temperature": 22}}

NOTE: Action keys use device type names (like "Light") not display names. Use get_node_details to see device types in config.devices[].name.

Edit an existing group's properties and manage nodes using Python library API.

Parameters:

• group_id: ID of the group to edit (required)

• name: New name for the group (optional)

• description: New description for the group (optional)

• custom_data: New custom data as JSON string (optional)

• add_nodes: Comma-separated list of node IDs to add to the group (optional)

• remove_nodes: Comma-separated list of node IDs to remove from the group (optional)

At least one parameter must be provided.