node-red-contrib-datacake-helpers 1.5.1

Node-RED nodes to interact with the Datacake GraphQL API for KPIs and device stats. Includes MQTT sensor nodes, AI integration, PDF reports, email, and automation helpers.

npm install node-red-contrib-datacake-helpers

Node-RED Datacake GraphQL Nodes

A collection of Node-RED nodes for interacting with the Datacake GraphQL API.

Installation

You can install these nodes directly from the Node-RED palette manager, or via npm:

npm install node-red-contrib-datacake-helpers

Available Nodes

Datacake GraphQL Config

Configuration node that stores your Datacake API credentials:

• Workspace UUID
• Workspace Token

Datacake GraphQL Device

This node fetches data from a Datacake device using the GraphQL API.

Features:

• Dynamic device selection from your Datacake workspace
• Retrieves all device measurements
• Outputs a flattened structure for easy use in flows
• Includes metadata for each measurement (type, unit, etc.)

Datacake GraphQL Field

This node fetches specific field values from one or multiple Datacake devices. Perfect for when you need just specific measurements rather than all device data.

Features:

• Select specific fields from one or multiple devices
• Smart output format:
  • Single field: outputs just the value (e.g., 25.4)
  • Multiple fields: outputs array of objects with deviceName, fieldName, and value
• Interactive field picker with device and field dropdowns
• Efficient API usage by grouping requests per device
• Ideal for monitoring specific sensors or building custom dashboards

Use Cases:

• Monitor a specific temperature sensor
• Track multiple humidity sensors across different locations
• Build custom monitoring flows with only the data you need
• Reduce data overhead when you don't need full device information

Datacake GraphQL Product Stats

This node calculates statistics across multiple devices in a product.

Features:

• Fetches data from all devices in a Datacake product
• Filter devices by tags
• Calculate min, max, average, sum, and count for selected fields
• Provides fleet health statistics (total, online, offline devices)

Datacake Device Post

This node sends data to a Datacake device using the HTTP API.

Features:

• Post data to a device using its HTTP API endpoint
• Supports both object and primitive payloads
• Automatically formats the payload according to Datacake requirements

Datacake GraphQL Semantic

This node fetches semantic data from all devices in a workspace. Supports querying multiple semantics in parallel.

Features:

• Query multiple semantic types at once (TEMPERATURE, HUMIDITY, CO2, BATTERY, etc.)
• Automatic semantic type detection (numeric vs boolean)
• Parallel fetching for optimal performance
• Optional tag-based filtering with clean editable list (loaded from workspace)
• Returns aggregated values across all devices (per semantic)
• Returns flat array of devices with semantic values (per semantic)
• Works with both numeric semantics (avg, max, min) and boolean semantics (true/false counts)
• Output is an array with one entry per configured semantic
• Includes device info for maximum and minimum values

Supported Semantics:

• Numeric: AIR_POLLUTION, AMBIENT_LIGHT, BATTERY, CO2, ENERGY_CONSUMPTION, FILL_LEVEL, HUMIDITY, LOUDNESS, PEOPLE_COUNT, POWER, SIGNAL, SOIL_MOISTURE, TEMPERATURE, VOC, WATER_CONSUMPTION, WATER_DEPTH, SNR
• Boolean: MOTION_DETECTED, WINDOW_OPENED

Datacake GraphQL Fleet Health

This node provides comprehensive workspace fleet health statistics and overview metrics.

Features:

• Total, online, and offline device counts
• Online percentage calculation
• Optional battery health statistics (average, min, max, low battery count)
• Optional signal & SNR statistics (average, min, max, weak signal count)
• Optional detailed device lists (online, offline, low battery, weak signal devices)
• Tag-based filtering for fleet segmentation
• Fast performance with compact mode
• Timestamp for tracking when data was fetched

Use Cases:

• Dashboard KPI widgets
• Alerting on fleet health issues (offline, low battery, weak signal)
• Monitoring workspace connectivity and signal quality over time
• Automated status reports
• Tag-based fleet analysis

Datacake GraphQL Consumption

This node calculates consumption statistics for meter and counter devices (energy, water, gas, people counters, etc.) using the GraphQL change() operation.

Features:

• Preset Timeframes: Today, Yesterday, This Week, Last Week, This Month, Last Month, Last 7/30 Days, This/Last Year
• Automatic Comparisons: Built-in percentage change calculations between periods
• Monthly Breakdown: Last 12 months consumption with month-over-month changes and trends
• Timezone Support: Configurable timezone for accurate day/week/month boundaries
• Current Reading: Optionally include the total cumulative meter value
• Field Auto-detection: Automatically highlights numeric fields suitable for meters
• Dynamic Overrides: Override device, field, or timeframes via msg properties
• Smart Output: Structured data with device info, consumption stats, and comparisons

Supported Device Types:

• ⚡ Energy Meters - Track kWh consumption
• 💧 Water Meters - Monitor water usage in m³
• 🔥 Gas Meters - Measure gas consumption
• 🌡️ Heating Meters - Track thermal energy
• 👥 People Counters - Count visitors/entries
• 🚗 Vehicle Counters - Track traffic
• 📦 Production Counters - Monitor manufacturing output

Use Cases:

• Energy management and cost tracking
• Water leak detection via consumption patterns
• Foot traffic analysis for retail/office spaces
• Billing period consumption calculations
• Efficiency analysis and trend monitoring
• Automated consumption reports and alerts

Datacake GraphQL Downlink

This node sends pre-configured LoRaWAN downlink commands to Datacake devices for remote configuration and control.

Features:

• Smart Device Picker: Search and pagination support for large workspaces
• Dynamic Downlink Loading: Automatically loads available downlinks from device's product
• Status Reporting: Clear success/failure feedback with detailed output
• Simple Trigger: Just send any input to trigger the configured downlink

Device Selection:

• Search by device name or serial number
• Paginated results (10 devices per page) with "Load More" button
• Works efficiently with workspaces containing hundreds of devices

Use Cases:

• Remote device configuration (change reporting intervals, measurement settings)
• Trigger device actions (LED control, relay switching, sensor calibration)
• Emergency commands (reset, reboot, alarm triggers)
• Scheduled configuration changes (off-peak hours, seasonal adjustments)
• Conditional downlinks based on sensor readings or external events

Datacake GraphQL History

This node fetches historical time series data from a Datacake device with flexible time range configuration and automatic resolution optimization.

Features:

• Three time range modes:
  • Preset: Quick selections (Last 1h, 6h, 24h, 7d, 30d, 90d)
  • Dynamic: Calculate ranges relative to current time or incoming timestamp
  • Fixed: Specify exact start and end dates
• Dynamic time calculations: Use incoming msg.timestamp to calculate ranges on-the-fly
• Flexible offsets: Positive (future) or negative (past) time offsets with multiple units (minutes, hours, days, weeks)
• Automatic resolution: Smart bucketing based on time range to optimize performance
• Manual resolution: Choose specific resolution (1m, 5m, 15m, 1h, 6h, 1d) or custom
• Field selection: Multi-select specific fields to query
• Performance warnings: UI recommendations to prevent heavy queries
• Resolution recommendations: Dynamic suggestions based on selected time range

Time Range Examples:

• Last 24 hours: Preset mode → "Last 24 Hours"
• Yesterday: Dynamic → Start: "Now -2 days", End: "Now -1 days"
• From incoming timestamp: Enable "Use Incoming Timestamp" → Start: "msg.timestamp -1 hours", End: "msg.timestamp"
• Specific dates: Fixed mode → Start: "2025-02-01 00:00", End: "2025-02-02 00:00"

Performance Guidelines:

• ⚠️ Short ranges (<1h): Use 1m or 5m resolution
• ⚠️ Medium ranges (1h-24h): Use 15m or 1h resolution
• ⚠️ Long ranges (>7 days): Use 6h or 1d resolution (never raw data)
• ⚠️ Very long ranges (>30 days): Always use 1d resolution

Datacake GraphQL PDF Report

This node generates professional PDF reports from Datacake device data with statistics and data tables.

Features:

• 📊 Standalone Mode: Automatically fetches data and generates PDF
• 🔗 Connected Mode: Works with History node for advanced time ranges
• 📈 Statistics: Min, max, and average values for each field
• 📋 Data Tables: Recent measurements in formatted tables
• ⚙️ Flexible Configuration: Select specific fields and time ranges
• 📄 Professional Output: Clean, ready-to-share PDF documents

Configuration:

• Device: Select the device to generate report for
• Report Name: Title that appears at the top of the PDF
• Time Range: Choose how far back to fetch data (Last 1h, 6h, 24h, 7d, 30d)
• Fields: Select which measurement fields to include

Two Usage Modes:

1. ⭐ Standalone Mode (Easiest):

[Inject] → [PDF Report] → [File]

• Configure device, fields, and time range in the PDF Report node
• No History node needed - data is fetched automatically!
• Perfect for simple scheduled reports

2. Connected Mode (Advanced):

[Inject] → [History] → [PDF Report] → [File]

• Use History node for custom time ranges and filtering
• More control over data resolution and time calculations
• Perfect for complex reporting requirements

Input Properties:

• msg.payload (optional) - Historical data from History node
• msg.deviceId (optional) - Override configured device
• msg.fields (optional) - Override configured fields
• msg.timeRange (optional) - Override time range (e.g., "last24h", "last7d")

Output Properties:

• msg.payload (Buffer) - The generated PDF file
• msg.filename (string) - Suggested filename (auto-generated with timestamp)
• msg.headers (object) - HTTP headers for serving PDF

Report Contents:

• Device Information: Name, serial number, device ID, generation timestamp
• Data Overview: Total data points and time range covered
• Field Statistics: Min, max, average, and count for each selected field
• Recent Data Table: Last 10 measurements with timestamps

Use Cases:

• Scheduled Reports: Daily/weekly automated device reports
• Compliance Documentation: Generate reports for audits
• HTTP API: Serve reports via REST endpoints
• Email Attachments: Automated report delivery
• Dashboard Integration: On-demand report generation

Example - Scheduled Weekly Report:

[Inject: Every Monday at 9 AM]
  ↓
[PDF Report: Device XYZ, Last 7 Days]
  ↓
[Email Node: Send as attachment]

Example - HTTP API for On-Demand Reports:

[HTTP In: GET /report/:deviceId]
  ↓
[Function: Extract device ID]
  ↓
[PDF Report: Standalone mode]
  ↓
[HTTP Response: Return PDF]

Tips:

• Use standalone mode for simplicity - just configure and go!
• Connect to History node when you need custom time ranges
• Set File node to use msg.filename for automatic naming
• Monitor node status: Blue (working), Green (success), Red (error)
• See PDF_REPORT_NODE_UPDATE.md for detailed documentation

Datacake Raw GraphQL

This node allows you to execute any raw GraphQL query against the Datacake API.

Features:

• Direct API token input (no config node needed)
• Full GraphQL query editor
• Support for query variables (static JSON or from msg.variables)
• Pre-loaded example queries (workspace info, devices, semantics, history, etc.)
• Cross-workspace queries with different tokens
• Detailed error logging with query and variables
• Returns both data payload and full GraphQL response
• Built-in rate limiting (1 request per second) for protection

Use Cases:

• Custom queries not covered by pre-built nodes
• Cross-workspace data aggregation
• Prototyping and testing new queries
• Advanced filtering and complex nested queries
• Batch operations
• Power user workflows

⚠️ Rate Limiting: This node enforces a 1-second minimum interval between requests to protect against accidental API abuse and excessive costs. Requests that come in faster will be ignored with a warning.

---

Datacake AI Nodes

Datacake AI Config

Configuration node for storing OpenAI API credentials securely.

Configuration:

• Name: Optional name for the configuration
• OpenAI API Key: Your OpenAI API key (starts with sk-...)

Get your API key from the OpenAI Platform.

Datacake AI

AI-powered data analysis and report generation using OpenAI's Responses API (2025).

Key Features:

• 🤖 Multiple model support (GPT-5, GPT-5-mini, GPT-5-nano)
• 💰 Automatic Cost Calculation - Real-time cost tracking for every API call
• 💻 Code Interpreter - Execute Python code for data analysis and visualizations
• 🌐 Web Search - Real-time information retrieval
• 📊 CSV/JSON data analysis
• 📝 Automated report generation (Markdown, HTML, PDF-ready)
• 🔄 Conversational context with response ID chaining
• 📈 Time series analysis and anomaly detection
• 💡 Actionable insights and recommendations

Configuration:

• API Config: Select your Datacake AI config node with OpenAI API key
• Model: Choose the AI model:
  • gpt-5 - Most capable ($1.25/1M in, $10/1M out)
  • gpt-5-mini - Balanced performance and cost ($0.25/1M in, $2/1M out) - Recommended
  • gpt-5-nano - Fastest and cheapest ($0.05/1M in, $0.40/1M out)
• Prompt Source: Static prompt from config or dynamic from msg.prompt
• Include msg.payload: Automatically include incoming data in the prompt
• Enable Code Interpreter: Allow Python code execution for analysis
• Enable Web Search: Enable real-time web information retrieval
• Max Output Tokens: Control response length (default: 16,000)
  • 💡 UI shows real-time cost estimates based on this setting

Input Properties:

• msg.prompt (string, optional) - The AI prompt/instruction (when using dynamic prompts)
• msg.payload (any, optional) - Data to analyze (CSV, JSON, text, etc.)
• msg.previousResponseId (string, optional) - Previous response ID for context
• msg.model (string, optional) - Override the configured model

Output Properties:

• msg.payload (string) - Clean AI response text (user-friendly, ready to use)
• msg.responseId (string) - Response ID for follow-up questions with context
• msg.openai (object) - Metadata including:
  • model - Model used
  • toolsUsed - Array of tools enabled
  • responseId - Response ID (same as msg.responseId)
  • usage - Token usage (input, cached, output)
  • cost - Calculated cost breakdown in USD:
    • inputTokens, cachedTokens, outputTokens, totalTokens
    • inputCost, cachedCost, outputCost, totalCost
  • fullResponse - Complete raw API response (for advanced users/debugging)

Use Cases:

1. 📊 IoT Sensor Data Analysis

   // Read CSV sensor data
   msg.payload = flow.get('sensorDataCSV');
   msg.prompt = `Analyze this IoT sensor data and identify:
   1. Temperature trends
   2. Anomalies in CO2 levels
   3. Correlations between humidity and temperature
   4. Recommendations for optimization`;
   return msg;
   

2. 📝 Automated Markdown Report Generation

   // Configure node with Code Interpreter enabled
   msg.payload = csvData;
   msg.prompt = `Create a professional markdown report with:
   - Executive Summary
   - Statistical Analysis (with real calculated values)
   - Visualizations
   - Recommendations
   Output ONLY the markdown (no preamble)`;
   return msg;
   

3. 🔄 Conversational Analysis with Context

   // First message
   msg.prompt = "Analyze this sales data and identify trends";
   msg.payload = salesCSV;
   
   // Store response ID from output: msg.responseId
   
   // Follow-up message (in next node)
   msg.prompt = "What are your top 3 recommendations?";
   msg.previousResponseId = flow.get('lastResponseId');
   return msg;
   

4. 📈 Predictive Maintenance

   msg.payload = deviceHistoryData;
   msg.prompt = `Analyze device performance data:
   1. Detect degradation patterns
   2. Predict potential failures
   3. Recommend maintenance schedule`;
   return msg;
   

5. 🌐 Market Research with Web Search

   // Enable Web Search in node config
   msg.prompt = `Research the latest IoT market trends for 2025 and
   compare them to our device performance data`;
   msg.payload = ourDeviceStats;
   return msg;
   

Output Structure:

{
  payload: "Your AI response text here...",
  responseId: "resp_abc123...",
  openai: {
    model: "gpt-5-mini",
    cost: {
      inputTokens: 1234,
      cachedTokens: 0,
      outputTokens: 567,
      totalTokens: 1801,
      inputCost: 0.000308,    // USD
      cachedCost: 0.000000,   // USD
      outputCost: 0.001134,   // USD
      totalCost: 0.001442,    // USD
      currency: "USD"
    },
    usage: { /* raw token usage from API */ },
    fullResponse: { /* complete raw API response */ }
  }
}

Cost Tracking:

The node automatically calculates and displays costs for every API call:

• 💡 Real-time cost estimates in the configuration UI
• 📊 Actual costs calculated after each request
• 🏷️ Cost displayed in node status (e.g., "Success ($0.00142)")
• 📈 Detailed breakdown in msg.openai.cost

Pricing (per 1M tokens):

Model	Input	Cached Input	Output
gpt-5	$1.25	$0.125	$10.00
gpt-5-mini	$0.25	$0.025	$2.00
gpt-5-nano	$0.05	$0.005	$0.40

Tips:

• Use Code Interpreter for any data analysis (calculations, statistics, correlations)
• Be specific in prompts for better results
• Use previousResponseId to maintain conversation context
• For large datasets, consider preprocessing or chunking
• Access the full raw response via msg.openai.fullResponse for debugging
• Monitor costs at the OpenAI Usage Dashboard
• Use gpt-5-nano for simple tasks, gpt-5-mini for most use cases, gpt-5 for complex analysis

Performance:

• Typical response time: 5-30 seconds
• With code execution: 10-60 seconds
• Timeout: 5 minutes

---

Datacake LNS Nodes

Helper nodes for interacting with LoRaWAN Network Servers (LNS) and retrieving gateway status information.

TTS Config

Configuration node for storing The Things Stack (TTS) API credentials securely.

Configuration:

• Name: Optional name for the configuration
• Server URL: The URL of your TTS server (e.g., https://eu1.cloud.thethings.network)
• API Key: Your TTS API key with gateway read permissions

Required API Key Permissions:

• RIGHT_GATEWAY_INFO - Read gateway information
• RIGHT_GATEWAY_STATUS_READ - Read gateway status and statistics

Get your API key from your The Things Stack Console.

TTS Gateway

Monitor LoRaWAN gateway status and connection statistics from The Things Stack.

Key Features:

• 🌐 Poll gateway status on demand or at intervals
• 📊 Normalized output format for easy integration
• 🔄 Support for configured or dynamic gateway IDs
• 📈 Real-time connection statistics
• ⚡ Uplink/downlink counters
• 🕒 Round-trip time metrics
• 📍 Location information

Configuration:

• TTS Config: Select your TTS config node with API credentials
• Gateway ID Source: Choose between:
  • Configured: Use a fixed gateway ID from the node configuration
  • From Message: Extract gateway ID dynamically from incoming messages
• Gateway ID: The gateway ID to query (when using configured mode)

Input Properties:

• Any input message will trigger a gateway status query
• When using "From Message" mode:
  • msg.payload.gatewayId (string) - Gateway ID to query
  • msg.gatewayId (string) - Alternative location for gateway ID
  • msg.payload (string) - Gateway ID as direct payload

Output Properties:

• msg.payload (object) - Normalized gateway status data
• msg.gatewayId (string) - The gateway ID that was queried

Output Structure:

{
  "gateway_id": "my-gateway",
  "gateway_eui": "0000000000000000",
  "name": "My Gateway",
  "description": "Gateway description",
  "connected": true,
  "connected_at": "2025-10-08T10:30:00.000Z",
  "disconnected_at": null,
  "protocol": "udp",
  "uplink_count": 1234,
  "downlink_count": 56,
  "last_uplink_received_at": "2025-10-08T10:35:00.000Z",
  "last_downlink_received_at": "2025-10-08T10:34:00.000Z",
  "latitude": 52.5200,
  "longitude": 13.4050,
  "altitude": 100,
  "frequency_plan_id": "EU_863_870",
  "round_trip_times": {
    "min": "10ms",
    "max": "50ms",
    "median": "25ms",
    "count": 100
  },
  "_raw": {
    "info": { /* Raw gateway info */ },
    "stats": { /* Raw connection stats */ }
  }
}

Use Cases:

1. 🔄 Periodic Gateway Monitoring

   [Inject: Every 5 minutes]
     ↓
   [TTS Gateway Node]
     ↓
   [Function: Check if offline]
     ↓
   [Alert/Notification]
   

2. 📊 Gateway Performance Dashboard

   [Inject: Every minute]
     ↓
   [TTS Gateway Node]
     ↓
   [Function: Extract metrics]
     ↓
   [Dashboard Gauges: Uplinks, Downlinks, Latency]
   

3. 🚨 Offline Alert System

   [TTS Gateway Node: Poll every 5 min]
     ↓
   [Switch: Check if connected === false]
     ↓
   [Email/SMS/Slack Notification]
   

4. 📈 Multi-Gateway Monitoring

   [Inject: List of gateway IDs]
     ↓
   [Split: One message per gateway]
     ↓
   [TTS Gateway Node: From Message mode]
     ↓
   [Join: Combine results]
     ↓
   [Database/Dashboard]
   

5. 🔍 Gateway Health Check

   [Schedule: Daily at 8 AM]
     ↓
   [TTS Gateway Node]
     ↓
   [Function: Calculate uptime %]
     ↓
   [Email: Daily report]
   

Status Display:

The node provides real-time status feedback:

• 🟢 Green dot: Gateway connected (shows uplink/downlink counts)
• 🟡 Yellow ring: Gateway disconnected
• 🔴 Red ring: Error occurred
• 🔵 Blue dot: Fetching data

Tips:

• Poll gateways every 1-5 minutes for real-time monitoring
• Use the _raw field to access complete TTS API responses
• Monitor round_trip_times.median for network quality
• Track uplink_count increases to verify gateway activity
• Set up alerts when connected becomes false
• Store historical data in a database for uptime tracking

Performance:

• Typical response time: 1-3 seconds
• Two API calls per request (gateway info + connection stats)
• Rate limit: Follows TTS API rate limits

Datacake MQTT Config

Configuration node for Datacake MQTT sensor nodes that references Node-RED's built-in MQTT infrastructure.

Key Features:

• 🔌 Uses Node-RED's standard MQTT broker node (no additional dependencies!)
• 🔐 Stores Datacake credentials for API access
• ⚡ Compatible with older Node-RED installations
• 🔄 Leverages Node-RED's proven MQTT handling

Configuration:

• MQTT Broker: Reference to a standard Node-RED mqtt-broker config node
• Workspace UUID: Your Datacake workspace UUID
• Workspace Token: Your Datacake API token (for GraphQL queries)

Setup Instructions:

1. Create MQTT Broker Node (one-time setup):

   Server: mqtt.datacake.co
   Port: 8883
   Protocol: MQTT V3.1.1 or V5
   ☑ Enable secure (SSL/TLS) connection
   Username: <Your Workspace Token>
   Password: <Your Workspace Token> (same value)
   

2. Configure Datacake MQTT Config:

   • Select the mqtt-broker created above
   • Enter your workspace UUID
   • Enter your workspace token

Benefits:

• No mqtt npm package dependency
• Works with Node-RED 1.0.0+
• Better connection visibility in Node-RED UI
• Shared MQTT connection across all sensor nodes

See MQTT_MIGRATION_GUIDE.md for detailed setup and migration instructions.

Datacake MQTT Sensor

Subscribe to real-time device measurements via MQTT with semantic typing for automation.

Key Features:

• 📡 Real-time sensor data (< 2 second latency vs 1-5 minute polling)
• 🎯 Automatic semantic type detection (temperature, humidity, occupancy, etc.)
• 🔌 Uses Node-RED's built-in MQTT (no additional dependencies)
• 🚀 Zero API usage after subscription
• 📊 Works perfectly with Room Controller and other automation nodes
• 🎛️ Easy device/field selection via dropdown UI

Configuration:

• MQTT Config: Reference to Datacake MQTT Config node
• Device: Select your Datacake device from dropdown
• Field: Select the measurement field to monitor
• Semantic Type: Auto-detected (temperature, humidity, etc.) but customizable

Output Properties:

{
  "payload": 22.45,
  "semantic": "temperature",
  "topic": "dtck/product/device/field",
  "deviceId": "...",
  "deviceName": "Living Room Sensor",
  "fieldName": "TEMPERATURE",
  "verboseFieldName": "Temperature",
  "qos": 0,
  "retain": false
}

Supported Semantic Types:

• temperature - Temperature sensors
• humidity - Humidity/moisture sensors
• occupancy - Motion/PIR sensors
• window - Door/window contacts
• co2 - CO2 sensors
• pressure - Air pressure sensors
• light - Light level sensors
• sound - Sound level sensors
• battery - Battery/voltage sensors
• custom - Custom sensor types

Use Cases:

1. 🏠 Real-time Climate Control

   [MQTT Sensor: Temperature] ──┐
   [MQTT Sensor: Humidity] ─────┤
   [MQTT Sensor: Occupancy] ────┼─→ [Room Controller] ──→ [Downlink]
   [MQTT Sensor: Window] ───────┘
   

2. 📊 Live Dashboard

   [MQTT Sensor: Temperature] ──→ [Dashboard Gauge]
   [MQTT Sensor: Battery] ──────→ [Dashboard Chart]
   

3. 🚨 Instant Alerts

   [MQTT Sensor: Temperature]
     ↓
   [Switch: > 30°C]
     ↓
   [Email/Notification]
   

4. 💾 Time-Series Logging

   [MQTT Sensor] → [Function: Format] → [InfluxDB]
   

Why MQTT vs Polling?

Feature	MQTT Sensor	Polling (Device Node)
Latency	< 2 seconds	1-5 minutes
API Usage	None (after sub)	Constant polling
Real-time	✅ Yes	❌ No
Scalability	Excellent	Limited by rate limits
Battery Impact	None	Additional queries

Status Indicators:

• 🔵 Blue dot: Subscribed, waiting for data
• 🟢 Green dot: Receiving data (shows last value)
• 🟡 Yellow ring: Subscribing...
• 🔴 Red ring: Configuration or connection error

Tips:

• Use with Room Controller for automatic climate control
• Connect multiple sensors to create complete automation systems
• Semantic types enable auto-configuration in controller nodes
• All sensors using the same config share one MQTT connection

See MQTT_NODES_README.md for comprehensive documentation.

---

Usage

Basic Device Data Fetching

1. Add a Datacake GraphQL Config node and configure your Datacake API credentials
2. Add a Datacake GraphQL Device node and select your configuration
3. Choose a device from the dropdown (populated from your Datacake workspace)
4. Connect any input to trigger fetching the latest device data
5. Use the flattened output data in your flow

Consumption Statistics

Quick Start:

1. Add a Datacake GraphQL Consumption node
2. Select your config and device (devices with meter/counter fields)
3. Choose the meter field (e.g., ACTIVE_ENERGY_IMPORT_T1_KWH, WATER_CONSUMPTION_M3)
4. Select timeframes to calculate (Today, Yesterday, This Week, etc.)
5. Optionally set timezone for accurate local time boundaries
6. Connect an inject node to trigger consumption calculation

Dynamic Usage:

[Inject Node]
  ↓
[Function Node]
  msg.deviceId = "device-uuid-123";  // Optional override
  msg.fieldName = "ENERGY_KWH";      // Optional override
  msg.timeframePresets = ['today', 'yesterday', 'thisMonth'];
  return msg;
  ↓
[Consumption Node]
  ↓
[Dashboard/Alert/Database]

Monthly Breakdown Feature: Enable "Monthly Breakdown" to get the last 12 months of consumption data with:

• Individual month consumption calculations
• Month-over-month changes (absolute and percentage)
• Trend indicators (increasing/decreasing/stable)
• Monthly statistics (average, highest, lowest)
• Perfect for year-over-year comparisons and trend analysis

Common Use Cases:

• Energy Billing: Calculate monthly kWh consumption for invoicing
• Leak Detection: Compare daily water usage to detect abnormal patterns
• Traffic Analysis: Track visitor counts by day/week/month
• Cost Monitoring: Calculate consumption costs with percentage changes
• Efficiency Reports: Generate automated consumption comparison reports
• Trend Analysis: Use monthly breakdown to identify seasonal patterns and anomalies

Sending Downlinks to Devices

Quick Start:

1. Add a Datacake GraphQL Downlink node
2. Select your config node
3. Use the search field to find your device (supports pagination)
4. Select the device from the dropdown
5. Select the downlink command from the automatically loaded list
6. Connect an inject node to trigger the downlink
7. Monitor the output for success/failure status

Dynamic Usage with Conditions:

[Device Data Node]
  ↓
[Function: Check if action needed]
  if (msg.payload.TEMPERATURE > 30) {
    // Temperature too high, trigger cooling
    return msg;
  }
  return null;
  ↓
[Downlink Node: "Activate Cooling"]
  ↓
[Debug/Notification]

Scheduled Configuration Changes:

[Inject: Daily at 8 AM]
  ↓
[Downlink Node: "Set reporting to 5 minutes"]
  ↓
[Inject: Daily at 6 PM]
  ↓
[Downlink Node: "Set reporting to 30 minutes"]

Notes:

• Downlinks must be pre-configured in the device's product on Datacake
• LoRaWAN downlinks are queued and sent on the next device uplink
• The node will report success if the downlink was queued successfully
• If a device has no downlinks configured, the dropdown will show "No downlinks available"

Historical Data Fetching

Quick Start (Preset Mode):

1. Add a Datacake GraphQL History node
2. Select your config and device
3. Choose fields you want to query (multi-select)
4. Select a preset like "Last 24 Hours"
5. Keep resolution on "Auto" for optimal performance
6. Connect an inject node to trigger the query

Dynamic Time Ranges:

1. Set Time Mode to "Dynamic"
2. Configure start: "Now -24 hours" (or any offset)
3. Configure end: "Now +0 hours"
4. Enable "Use Incoming Timestamp" to calculate from msg.timestamp
5. Inject nodes can pass custom timestamps to calculate relative ranges

Advanced Usage - Scheduled Daily Reports:

[Inject: Daily at midnight]
  ↓
[Function: Set yesterday's date range]
  msg.timestamp = new Date();
  msg.timestamp.setDate(msg.timestamp.getDate() - 1);
  return msg;
  ↓
[History Node: Dynamic mode, "msgTimestamp -24h" to "msgTimestamp +0h"]
  ↓
[Process/Store daily data]

Advanced Usage - Custom Time Windows:

[Inject: Triggered by external event]
  ↓
[Function: Calculate custom window]
  msg.timestamp = new Date('2025-02-15T12:00:00Z');
  return msg;
  ↓
[History Node: msgTimestamp -2h to msgTimestamp +2h]
  ↓
[Analyze 4-hour window around event]

Example Outputs

Device Node Output

{
  "id": "device-uuid",
  "serialNumber": "70B3D5CDD000185E",
  "verboseName": "My Device Name",
  "location": "Device Location",
  "online": true,
  "lastHeard": "2023-05-04T04:31:15.929264+00:00",
  "lastHeardThreshold": 2880,
  "BATTERY": 3.3,
  "BATTERY_metadata": {
    "id": "field-uuid",
    "type": "FLOAT",
    "unit": ""
  },
  "TEMPERATURE": 14.64,
  "TEMPERATURE_metadata": {
    "id": "field-uuid",
    "type": "FLOAT",
    "unit": "°C"
  }
}

Semantic Node Output (Multiple Semantics)

[
  {
    "semantic": "TEMPERATURE",
    "semanticType": "NUMERIC",
    "tags": ["Floor-1"],
    "aggregated": {
      "total": 25,
      "average": 22.5,
      "maximum": 28.3,
      "maximumDevice": {
        "id": "device-uuid-2",
        "name": "Sensor 2",
        "serialNumber": "DEF456"
      },
      "minimum": 18.7,
      "minimumDevice": {
        "id": "device-uuid-3",
        "name": "Sensor 3",
        "serialNumber": "GHI789"
      }
    },
    "devices": [
      {
        "id": "device-uuid-1",
        "name": "Sensor 1",
        "serialNumber": "ABC123",
        "value": 22.5
      },
      {
        "id": "device-uuid-2",
        "name": "Sensor 2",
        "serialNumber": "DEF456",
        "value": 28.3
      }
    ]
  },
  {
    "semantic": "HUMIDITY",
    "semanticType": "NUMERIC",
    "tags": ["Floor-1"],
    "aggregated": {
      "total": 25,
      "average": 55.2,
      "maximum": 78.5,
      "maximumDevice": {
        "id": "device-uuid-1",
        "name": "Sensor 1",
        "serialNumber": "ABC123"
      },
      "minimum": 42.1,
      "minimumDevice": {
        "id": "device-uuid-4",
        "name": "Sensor 4",
        "serialNumber": "JKL012"
      }
    },
    "devices": [
      {
        "id": "device-uuid-1",
        "name": "Sensor 1",
        "serialNumber": "ABC123",
        "value": 78.5
      }
    ]
  }
]

History Node Output

{
  "device": {
    "id": "device-uuid",
    "verboseName": "My CO2 Sensor",
    "serialNumber": "ABC123"
  },
  "timeRange": {
    "start": "2025-02-22T00:00:00.000Z",
    "end": "2025-02-23T00:00:00.000Z"
  },
  "resolution": "15m",
  "fields": ["TEMPERATURE", "HUMIDITY", "CO2"],
  "data": {
    "TEMPERATURE": [
      {"timestamp": "2025-02-22T00:00:00Z", "value": 22.5},
      {"timestamp": "2025-02-22T00:15:00Z", "value": 22.7},
      {"timestamp": "2025-02-22T00:30:00Z", "value": 22.3}
    ],
    "HUMIDITY": [
      {"timestamp": "2025-02-22T00:00:00Z", "value": 55.2},
      {"timestamp": "2025-02-22T00:15:00Z", "value": 55.8},
      {"timestamp": "2025-02-22T00:30:00Z", "value": 54.9}
    ],
    "CO2": [
      {"timestamp": "2025-02-22T00:00:00Z", "value": 450},
      {"timestamp": "2025-02-22T00:15:00Z", "value": 455},
      {"timestamp": "2025-02-22T00:30:00Z", "value": 448}
    ]
  }
}

Consumption Node Output

{
  "device": {
    "id": "db8286e3-306d-4e25-96a2-f8b68f05ce35",
    "verboseName": "Main Building Energy Meter",
    "serialNumber": "EM-001",
    "online": true,
    "lastHeard": "2025-10-08T10:30:00.000Z"
  },
  "fieldName": "ACTIVE_ENERGY_IMPORT_T1_KWH",
  "timezone": "Europe/Berlin",
  "currentReading": 31823.075,
  "consumption": {
    "today": 6.399,
    "yesterday": 92.264,
    "thisWeek": 166.746,
    "lastWeek": 234.123,
    "thisMonth": 364.409,
    "lastMonth": 914.303,
    "last7Days": 150.5,
    "last30Days": 2750.8
  },
  "comparisons": {
    "todayVsYesterday": {
      "today": 6.399,
      "yesterday": 92.264,
      "change": "-93.06%",
      "changeValue": -85.865
    },
    "thisWeekVsLastWeek": {
      "thisWeek": 166.746,
      "lastWeek": 234.123,
      "change": "-28.78%",
      "changeValue": -67.377
    },
    "thisMonthVsLastMonth": {
      "thisMonth": 364.409,
      "lastMonth": 914.303,
      "change": "-60.15%",
      "changeValue": -549.894
    }
  },
  "monthlyBreakdown": [
    {
      "month": "November 2024",
      "monthShort": "Nov 2024",
      "timestamp": "2024-11-01T00:00:00Z",
      "meterReading": 29850.5,
      "consumption": 850.5,
      "change": -50.2,
      "changePercent": "-5.57%",
      "trend": "decreasing"
    },
    {
      "month": "December 2024",
      "monthShort": "Dec 2024",
      "timestamp": "2024-12-01T00:00:00Z",
      "meterReading": 30765.8,
      "consumption": 915.3,
      "change": 64.8,
      "changePercent": "7.62%",
      "trend": "increasing"
    }
  ],
  "monthlyStats": {
    "totalMonths": 12,
    "averageConsumption": "875.45",
    "highestMonth": {
      "month": "January 2025",
      "consumption": 1050.2
    },
    "lowestMonth": {
      "month": "July 2024",
      "consumption": 720.5
    },
    "trend": "stable"
  },
  "timestamp": "2025-10-08T10:30:00.000Z"
}

Downlink Node Output

{
  "ok": true,
  "device": {
    "id": "4be3ea6f-e078-4568-843f-f3aa4f3d7303",
    "name": "Culvert Sensor NR End"
  },
  "downlink": {
    "id": "0c4a7da5-0074-4c12-b639-6e0e827b845f",
    "name": "Set timebase to 30 minutes"
  },
  "timestamp": "2025-10-08T12:34:56.789Z"
}

Fleet Health Node Output

{
  "workspace": {
    "name": "My Workspace",
    "allTags": ["Floor-1", "Floor-2", "Building-A"]
  },
  "filters": {
    "tags": []
  },
  "fleet": {
    "total": 150,
    "online": 142,
    "offline": 8,
    "onlinePercentage": 94.67
  },
  "battery": {
    "devicesWithBattery": 130,
    "average": 87.5,
    "minimum": 12.3,
    "maximum": 100,
    "lowBatteryCount": 5,
    "lowBatteryPercentage": 3.85
  },
  "signal": {
    "devicesWithSignal": 145,
    "average": -85.3,
    "minimum": -112.5,
    "maximum": -45.0,
    "weakSignalCount": 8,
    "weakSignalPercentage": 5.52
  },
  "snr": {
    "devicesWithSNR": 145,
    "average": 8.7,
    "minimum": -2.5,
    "maximum": 12.3
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Raw GraphQL Node Output

{
  "payload": {
    "workspace": {
      "name": "My Workspace",
      "deviceCount": 150,
      "allTags": ["Floor-1", "Floor-2"]
    }
  },
  "graphql": {
    "query": "query { workspace(id: \"...\") { name deviceCount allTags } }",
    "variables": {},
    "fullResponse": {
      "data": {
        "workspace": {
          "name": "My Workspace",
          "deviceCount": 150,
          "allTags": ["Floor-1", "Floor-2"]
        }
      }
    }
  }
}

Raw GraphQL with Variables Example

Query:

query GetDevice($deviceId: String!) {
  device(deviceId: $deviceId) {
    id
    verboseName
    online
  }
}

Variables (from function node):

msg.variables = {
  deviceId: "abc-123-def-456"
};
return msg;

Output:

{
  "payload": {
    "device": {
      "id": "abc-123-def-456",
      "verboseName": "My Device",
      "online": true
    }
  }
}

TTS Gateway Node Output

{
  "gateway_id": "eui-b827ebfffe8b1234",
  "gateway_eui": "B827EBFFFE8B1234",
  "name": "Office Building Gateway",
  "description": "Main gateway for office building IoT sensors",
  "location": {
    "latitude": 52.52,
    "longitude": 13.405,
    "altitude": 45,
    "source": "SOURCE_REGISTRY"
  },
  "latitude": 52.52,
  "longitude": 13.405,
  "altitude": 45,
  "frequency_plan_id": "EU_863_870_TTN",
  "frequency_plan_ids": ["EU_863_870_TTN"],
  "status_public": true,
  "location_public": true,
  "attributes": {
    "placement": "indoor",
    "antenna_type": "omni"
  },
  "version_ids": {
    "brand_id": "dragino",
    "model_id": "dlos8",
    "hardware_version": "1.0",
    "firmware_version": "4.4.3"
  },
  "connected": true,
  "connected_at": "2025-10-08T08:15:30.123Z",
  "disconnected_at": null,
  "protocol": "udp",
  "uplink_count": 15234,
  "downlink_count": 127,
  "last_uplink_received_at": "2025-10-08T10:35:22.456Z",
  "last_downlink_received_at": "2025-10-08T10:30:15.789Z",
  "round_trip_times": {
    "min": "12ms",
    "max": "89ms",
    "median": "34ms",
    "count": 1250
  },
  "sub_bands": [
    {
      "min_frequency": "863000000",
      "max_frequency": "870000000",
      "downlink_utilization": 0.02
    }
  ],
  "_raw": {
    "info": {
      "ids": {
        "gateway_id": "eui-b827ebfffe8b1234",
        "eui": "B827EBFFFE8B1234"
      },
      "created_at": "2023-05-15T12:00:00.000Z",
      "updated_at": "2025-10-08T10:35:22.456Z",
      "name": "Office Building Gateway"
    },
    "stats": {
      "connected_at": "2025-10-08T08:15:30.123Z",
      "protocol": "udp",
      "uplink_count": "15234",
      "downlink_count": "127"
    }
  }
}

License

MIT