# Welcome Welcome to our official Datacake Documentation ## Get Started with Datacake The following guide will help you to get started with Datacake: {% content-ref url="/pages/RhRXMTMf0NgZSAJ4SjGr" %} [Get Started](/get-started) {% endcontent-ref %} {% hint style="info" %} Needing some help? You can check out our [support options](https://datacake.co/support) or join our [Discord community](https://discord.com/invite/E8pu8j24KA) for personalised assistance. {% endhint %} ## LoRaWAN ### Datacake LNS - LoRaWAN Network Server The Datacake IoT platform features **an integrated LoRaWAN network server**. That means you can **add your gateways and your LoRaWAN devices directly to the platform** without the need for an external network server. {% content-ref url="/pages/Ci1zns1nju2MmONmLv71" %} [Datacake LNS](/datacake-lns/getting-started) {% endcontent-ref %} And the best part of it is that **it's absolutely free**. So even for your first five free devices, you can add any gateway and any devices to the platform directly. ### Third Party LNS Datacake also integrates with any third-party LoRaWAN Network Server. We have integrations for Actility, The Things Stack, Loriot, KPN and many more. Check out: {% content-ref url="/pages/-MEvCX0yD7MNAkixwfzA" %} [Configuring LNS](/lorawan/lns) {% endcontent-ref %} # Get Started The following document will help you with the first steps on Datacake -> Onboard your first devices, select between our list of templates and start making the most out of your data. ## **Sign Up** First of all, create a free account with an email address, name, and password. You can go ahead and do so in [the following link.](https://app.datacake.de/signup) Once you create your account you can login. Your first workspaces will be created. At first you won't have devices, but we will soon come to that step...
## **First Steps** You can now start adding devices to the platform. To begin with, Datacake offers you up to 5 devices for free. Use them to test your PoC or small application and enjoy of the benefits Datacake has to offer on the free tier. While adding devices, you can choose between different options. In this document we will cover the most common ones: * [LoRaWAN](#adding-lorawan-devices) -> Devices that communicate via de LoRaWAN protocol * [API](#adding-api-devices) → Devices that communicate via HTTP or MQTT protocols You also have the possibility to do [Pincode Claiming](/device/claiming), which means your devices can be copied into another workspace. For that, you need to first add the devices as LoRaWAN or API devices. We also have [Dragino NB-IoT](/integrations/dragino-nb-iot) and [1NCE](/integrations/1nce-os) integrations for NB-IoT connected devices. Please refer to the documentation for those specifically. Now lets learn how to add your first devices.
## **Adding LoRaWAN Devices** Click on Add Device and select LoRaWAN. 1. **Select between different Datacake Products** If you want to go ahead and add a LoRaWAN device to Datacake, you will have to choose between three available options: Select "New Product from Template", to create a new product based on one of our more than 350 different templates that Datacake has to offer. You can also create a new device based on a previously created product ("Existing Product") or create a whole "New Product".
To learn more about what a product is, visit: {% content-ref url="/pages/-MUgdk-KYbvOYZCYpTdb" %} [Product](/device/product) {% endcontent-ref %} {% hint style="success" %} The first time you will want select "New Product from Template". That will create the Product within your workspaces that all of the next devices will belong to. The template will already contain payload decoder, fields, downlinks and dashboard to work on. If your device is not in the template catalog, you can either select "New Product", which will create an empty product, or contact our support team. They might be able to guide you. {% endhint %} If you have already created a product, you can select "Existing Product". That will create more devices inside of the same product, which will ensure consistency and better management of your devices. 2. **Select the LoRaWAN Network Server** The LoRaWAN Network Server (LNS) is the central component of a LoRaWAN architecture that manages the communication between LoRaWAN gateways and end devices. The LNS ensures secure and efficient data transmission across the LoRaWAN network. Datacake supports 15 different LoraWAN Network Servers. Select the one you are working with.
### If you want to make it easy for you, select the Datacake LNS. That way, you don't need to manage gateways and devices in two platforms anymore. {% hint style="success" %} Are you interested in adding LoRaWAN devices to Datacake? Did you know that Datacake has its own LoRaWAN Network Server (LNS)? You can add gateways and devices directly to Datacake without the need of an external LNS. And the best part of it is that it is totally free. {% endhint %} {% content-ref url="/pages/Ci1zns1nju2MmONmLv71" %} [Datacake LNS](/datacake-lns/getting-started) {% endcontent-ref %} 3. **Add Device Information** Enter DevEUI, name, location, and tags. Bulk upload via CSV is available. If you selected the Datacake LNS, you will need to provide DevEUI, Name, AppEUI, App Key, Frequency and Class. Those are provided by your device manufacturer/the store you bought them from.
4. **Select a Plan** As said before, the first 5 devices are for free, included in your Starter package. If you have obtained a [Datacake Package](https://datacake.co/pricing#pricingpackages), your device quota will be available for you at the moment of adding a device. Simply select your organization's plan and click on "Add device". That is it! Now you can go ahead and start configuring dashboards, reports and rules for your LoRaWAN devices. ## **Adding API Devices** An API device is basically a virtual device on Datacake that connects with a real device, which communicates with the internet, either wired or wirelessly. This virtual devices contain an HTTP endpoint that allows them to pull in information from a server. They also allow to connect via an external MQTT broker. To connect a device of this nature to Datacake you need to follow the next steps: 1. **Select Device Template** Choose from the 28 available API templates when creating a "New Product from Template", create a device on an "Existing Product" or create a "New Product".
1. **Add Device Information** Datacake can auto-generate a serial number for this kind of devices, or enter your device's serial number. You will need to give the device a name, and configure a device location and tags if needed. 2. **Select Plan**: Similar to LoRaWAN devices. Once that is done, click on Create. For API devices an HTTP Endpoint URL is created, which you can use to create a webhook or API call to fill in information to the platform. Please note that [API payload decoders](/generic-api-devices/access-measurements-in-api-decoders) have a different structure than [LoRaWAN decoders](/lorawan/payload-decoders). **Following Steps** After adding your first devices, you can proceed to configure automatic reports, email/SMS alarms, downlinks, and public dashboard links. # Changelog The purpose of this document is to provide an overview of the changes and updates (new features, bug fixes) made to the Datacake IoT platform over time. ## August 2026 #### 🚀 New Features * **Move devices to another workspace:** Devices can now be handed over to another workspace without recreating them by hand. Select them in the fleet view, choose **Advanced** → **Move to workspace**, and pick the target — either one of your own workspaces or any workspace whose ID you paste in. Nothing moves until an administrator there accepts the request and picks a plan for the devices, so billing never lands on a workspace that did not agree to it. Pending requests show up as a banner above the device list and on the new **Device move requests** page under Administration. 📖 Documentation: * **Enterprise Single Sign-On for White Label:** White label sites can now let their users sign in through their own identity provider — Okta, Microsoft Entra ID, Google Workspace, OneLogin and others. Verify your users' email domains with a DNS record, connect your identity provider from the new **Single Sign-On** tab, and optionally switch off password login so Single Sign-On becomes the only way in. 📖 Documentation: * **See and revoke device claims:** You can now see which workspaces have claimed your devices, and take those claims back. The device configuration shows a **Claimed by** list under **Device Claiming**, naming each claiming workspace and the organization it belongs to. 📖 Documentation: #### ✨ Improvements * **Delete dashboards straight from the sidebar:** Removing a global dashboard no longer means opening it and switching into edit mode. The sidebar configuration — now called **Manage Dashboards & Folders** — lets you delete a dashboard right where you already rename and delete folders. You are asked to type the dashboard name to confirm, and told upfront how many public share links will stop working and how many members will lose access. 📖 Documentation: #### 🛠 Fixes * Editing a device's name, location or tags no longer switches off claiming. A device that was waiting to be claimed could quietly become unclaimable after an unrelated change. ## July 2026 #### 🚀 New Features * New Cooling Health Widget: The new Cooling Health Widget turns fridge, freezer and cold room temperature data into a **health score** with status, KPIs and actionable insights — including door-opening detection, recovery time, temperature drift and condensation risk. Appliance-type presets get you started with sensible target ranges and thresholds. 📖 Documentation: #### 📊 Widget enhancements * **Enhanced color picker inside of widgets:** The color picker now includes a gradient selector and a slider for adjusting transparency. #### ✨ Improvements * **Searchable export configuration:** Fields and semantics can now be searched when configuring exports, making large configurations easier to manage. #### 🛠 Fixes * Fixed a crash in the device picker used in IAQ dashboards. * Resolved spacing issues in the modal for adding a new workspace. * Fixed a navigation issue in the device configuration tab. ## June 2026 #### 📊 Widget enhancements * Vertical Layout for Heatmaps: Heatmap widgets now support a vertical layout, giving users more flexibility when designing dashboards and displaying time-based data. #### ✨ Improvements * Organization Overview: The Organization Overview now automatically loads all workspaces, making it easier to get a complete overview without manually loading additional workspaces. * Zones Map: The Zones Map can now display more than 100 zones, improving support for larger installations and more complex deployments. #### 🚀 New Features * Push Notification rule action: The New Rule Engine can now send a **mobile push notification** to selected workspace members through the Datacake app when a rule fires, alongside the existing Email, SMS, and Webhook actions. 📖 Documentation: * New ASHRAE Chart Widget: We added a new ASHRAE Chart Widget to help visualise environmental conditions against ASHRAE-Handbook for museums, galleries, archives, and libraries recommended and allowable operating zones. 📖 Documentation: * New Scatter Plot Widget: The new Scatter Plot Widget allows users to compare two data fields against each other, making it easier to identify correlations and patterns between measurements. 📖 Documentation: ## May 2026 #### 🚀 New Features * New Organization Overview: Added a new overview page for organizations to improve navigation and management. 📖 Documentation: * New Menu Widget: Added a new **Menu widget** that allows displaying custom links directly inside dashboards. 📖 Documentation: #### **💠 White Label enhancements** * New cleaner White Label configurator: Navigate through the options to configure your white label site in an easier and cleaner way. * Restrict Available LNS Options: Inside of "Device Types" you can now select between "**Allow all LoRaWAN network servers**" or "**Allow only the selected LoRaWAN network servers**". If your users can add LoRaWAN devices, they will only see the Network Server selection you enable for them to choose from. * Auto-Assign Signups to Organizations: Introduced the new **“Auto-assign signups to this organization”** feature for whitelabel portals, allowing newly registered users to automatically join a predefined organization. You will find the option inside of "Sign-up & login". 📖 Documentation:\ #### 📊 Widget enhancements * **Heatmap Widget:** Mark Stale Data. When selected, it visually distinguishes cells where a device stopped reporting from cells with fresh measurements, making offline gaps obvious at a glance. 📖 Documentation:\ * Chart Widget: AI Summary Button that generates summaries of chart data. * Set Value Widget Improvements: Added additional configuration options to the Set Value widget for more flexible user interactions. ## April 2026 #### 🚀 New Features * Introduced our [**AI Assistant** ](/ai-assistant/overview)to enhance user support and workflow automation * Deployed the [**Dashboard History**](/dashboards/dashboard-history) feature, enabling tracking of dashboard modifications over time and restoring previous versions #### ✨ Improvements * Default timezone selection across the app now automatically follows the **browser’s system settings consistently everywhere** (Rules, Reports, Exports and Dashboards). * Improved **automatic scaling in the Chart Widget**, especially for setups with multiple data sources sharing the same Y-axis #### 🛠 Fixes * Fixed an issue that could cause a **crash when viewing the list of exports** #### ⚠️ Deprecations * **Simple CSV Reports** have been deprecated. Check out our new [Exports](/portal/exports) feature, which is an easier tool to create automatic backups of your data. ## March 2026 #### 📩 SMS Credits automatic top-up Introduced automatic top-up functionality for SMS usage to ensure uninterrupted alert delivery. The auto top-up is available when "Share credits between all workspaces" is enabled.
#### **📀 Exports Functionality** Added a new [Exports](/portal/exports) feature, allowing users to easily extract and download their data. 📖 Learn more: {% content-ref url="/pages/ynUlTi7Fear8PDAuPzxD" %} [Exports](/portal/exports) {% endcontent-ref %} #### 📊 Widget enhancements * **SOS Widget Enhancements**\ Improved visual appearance for better clarity and user experience. * **Fill Level Widget Enhancements**\ Updated visuals to provide a more intuitive and polished display. * **Image Map Widget Update**\ Sensor value display now uses the same bubble style as the Map Widget for a more consistent UI across widgets. * **Vertical Slider Widget Optimization**\ The value display now dynamically adjusts its position based on the current value for improved readability. ## February 2026 #### **💠 White Label enhancements** * **Assign Device Quota:** You can now manually assign device quotas to workspaces. This gives organizations more flexibility and control over how device limits are distributed across workspaces. 📖 Learn more:\ * **Default Whitelabel Preselection on Invitations:** When inviting members to a whitelabel site, the default whitelabel branding is now automatically preselected from the "Workspace" section. This ensures a smoother onboarding experience and consistent branding. #### 📩 SMS Credits * **SMS credits fully depleted notification:** In addition to the existing notification when only **10 SMS credits remain**, we’ve added a second automatic email notification that triggers once **SMS credits are fully depleted**. #### 🔢 Unified Numeric Data Type Float and integer field types have been unified into a single **“Numeric”** data type. This simplifies field configuration and improves consistency when handling numerical values across the platform. #### 📈 Dashboard Enhancements * **Preconfigured Indoor Air Quality Dashboard:** We’ve added a ready-to-use **Indoor Air Quality dashboard** to help you quickly visualise common IAQ metrics without building everything from scratch. * Fahrenheit Support for Climate Dashboards: Climate dashboards can now be displayed in **Fahrenheit (°F)**. This makes it easier to support US-based customers and projects requiring imperial units. #### ⚙️ Device Management Improvements * Expanded Bulk Editing Options: We’ve added more quick-edit and bulk action options directly in the **Device List**, making device management faster and more efficient. 📖 Learn more about multi-select & bulk actions:\ ## January 2026 #### 📊 Widget enhancements **Heatmap Widget Improvements** * **Export as CSV** – Easily download heatmap data for external analysis. * **Bulk configuration** – Add multiple devices and fields at once, similar to the Table and Map widgets. **Text Widget Enhancements** * Added **bold** and *italic* formatting options for improved content styling. * For security reasons, **not all HTML tags are supported.** **Value Widget Enhancements** * **Hide value option** – Display the widget without showing the numeric value. * **Background color based on value** – Apply color mapping rules to dynamically style the widget background. #### **💠 White Label enhancements** * **White Label URLs now visible in Share Dashboard modals**\ Users with White Label access will see their White Label URL(s) even when logged in via `app.datacake.de.` * **Device and Product change tracking added**\ All changes to devices and products are now logged in the White Label Audit Log for better transparency and traceability. #### **📋 Reports** * Added a **warning banner in reports** when the selected time range exceeds the scheduled report interval, clarifying resolution limitations documented in our guides and helping improve overall platform performance. ## November 2025 #### ⚙️ Rule Engine The Rule Engine offers logs for better control. This feature is limited to our packages up to Standard, Plus and Enterprise. ➡️ *Want access? Request a demo to explore this feature.* #### **💠 White Label enhancements** Enterprise customers with white label sites now have access to **User and Audit Logs**, offering up to **100 entries** for tracking automation activity. Option to **download the logs** to make compliance data easier to download and archive.\ ➡️ *Want access? Request a demo to explore this feature.* #### 🚀 **Workspace Overview** Added a **Workspace Configurator** that provides a central overview of: * Workspace configuration * SMS credits and usage logs * Product management options, including deletion for products without any devices attached #### 🌈 Widgets * **Value Widget Presets:** Added **three new presets** to the **Value Widget**, helping users set up dashboards faster and more consistently. * **Table Widget Filtering**: it now includes **filtering capabilities**, allowing users to refine and explore data with ease. #### 🐞 Fixes * **Debug Log Table Overflow:** Fixed an issue where the **Debug Log table** overflowed horizontally, improving readability on all screens. ## October 2025 #### 🌈 Widgets * **Map Widget:** You can now **set custom colours for boolean measurements** directly in Map widget. * **Table Widget:** Added support for **multiple conditional formatting rules per column**. #### ⚙️ Rule Engine * Introduced a **limit for the “Execute action when conditions are fulfilled consecutively”** option in Actions. This prevents excessive execution loops and provides safer rule handling. #### 👥 Member Management * The Member management UI received a **major UX upgrade**: * Add and remove multiple members simultaneously. * Select and modify multiple device permissions at once. * Enhanced **search capabilities** for individual device permissions, now includes **search by tags**. * Added **“Select All” checkboxes** for faster bulk operations. * Refreshed visual design to match Datacake’s **new look and feel**. #### 📊 Dashboards * You can now **share Global Dashboards,** just like Device Dashboards! * Create **multiple public links**, each with its own **password and purpose** (e.g., internal use, customer access, demo sharing). * **Links can be deleted individually**, giving you full control. * As before, **Global Dashboard public links are read-only** for external viewers. #### 🧩 API * Added support for the **`DeviceType.created` timestamp** in the API. This allows developers to track when a Device Type was originally created. ## September 2025 #### ✨ New Features * **Semantic field selection for histogram widgets:** Select fields more intuitively for better insights. * **Easier device dashboard sharing:** You will now find the Share button outside of the "Edit mode", so you can more quickly access and create public links. * **Default branding for workspaces for White Label Sites:** You can now set up which default branding will be set within your workspace. That will save you time and avoid mistakes when inviting members, creating reports and rules within your white label site. * **SMS quota assignation inside white-label sites:** Organizations can now assign SMS quota per workspace. #### 🛠 Improvements * **Chart widget enhancements** * Additional date formatting options. * Minor visual improvements to y-axis tick marks. * **Input & usability** * Improved width of Tax ID input field for better usability. ## August 2025 #### 🚀 New Features * Set Configuration Values using **Set Value Widget** * Cloning Products across Workspaces: You can now **clone your products between workspaces**, reducing setup time and ensuring consistency across projects and customers. #### 📡 New Semantics * SNR (Signal-to-Noise Ratio): We’ve added a **dedicated semantic for SNR**, making it easier to visualise and interpret signal quality across devices. * Booleans now have their own semantic type, including a **dedicated table view in the “Overview”**. This makes it simple to track and manage on/off or true/false states. ## July 2025 #### 🚀 New Features * **Table Widget**: Added the ability to **download data to Excel**, with timestamps now aligned to the user's timezone. * **Value Widget**: Introduced **Value Range Names**, **Legend display**, and a **Range Name Indicator** for clearer insights. * **Map Widget**: Added **Value Range Name support** and **heatmap rendering**, enriching geospatial data visualisation. * **LoRaWAN Tab for Devices**: Released a new **Radio Analytics View** for deeper insights into LoRaWAN device behaviour. * **Folders for Device Organization**: Added support for organising devices into **folders using Tags**. * **Serial Number Placeholders**: Introduced the **serial number** placeholder variable for rule engine email configurator. #### **💠 White Label enhancements** * Added **toggles** to control visibility of the **Device Overview** and **LoRaWAN Debugging** on white label sites. #### 🎨 Widget Improvements * **Histogram Widget f**ully **redesigned.** * Introduced **Pie Chart** support and **Value Widget - Gauge** enhancements. * **Headline Widget**: Now supports **gradient backgrounds** and **subtitle options**. * **Delta Bar Chart**: * Updated visuals by **removing stroke color**. * Now **colour-coded based on values** for better data clarity. * **Set Value Widget**: Numeric actions now always **send values as numeric**, avoiding type errors. * **Measurement List**: Enhanced with **lookup tables** and various usability refinements. #### **📋 Reports**: * Improved **crontab input** UX. ## June 2025 #### 📊 **Reports** * **Device Info in CSVs**: Individual device reports can now include both **device name** and **serial number**. * **Energy Reports Enhancement**: You can now **include device location** in your Energy Reports for improved context and tracking. #### 🔧 **Improvements** * **Heatmap Widget**: Now uses **static time buckets** (e.g., starts always at the beginning of day/hour). Plus, you can **configure the timezone** directly in the widget. * **Sorted Device List**: Behaves better, sorting is now limited to **sortable columns only**. * **Device View**: Now shows **online status** next to device names, so you always know what’s connected. * **Add Widget Modal**: Redesigned for a **smoother, more intuitive experience**, now with full **keyboard navigation** support. * **Device Configuration Page**: Got a stylish **UI refresh** for a more modern and organised layout. * **Sidebar**: Now **collapsible**, giving you more space and flexibility in your workspace. * **Device Overview Page**: A **brand-new view** that gives you the full picture at a glance. * **Device Overview Cache**: Refreshed to ensure you’re always seeing the most up-to-date info. * **CO₂ Modal**: New addition to help you track **carbon-related insights**. * **Login Screen**: Now features a **snazzy animated background** to greet you with style. * **Luxembourgish**: Added as a **dashboard language option** 🇱🇺. #### 🛠️ **Fixes** * **Permissions Bug**: Users with **"Manage Workspaces" permission at the organisation level** can now correctly see and update product-related data. * **Device List Rendering**: Fixed an issue causing **infinite re-renders**. * **Zones Beta Info**: Removed for a **simplified interface**. #### 🌐 **Integrations** * **Netmore Native Support**: We’ve added **native LNS support for Netmore**, simplifying your LoRaWAN device onboarding process. ## May 2025 **💠 White Label enhancements** * SMS notifications are now displayed in the "Notifications" overview on white label sites. * Reorganised white label capabilities into categories for better clarity. **🛠 Improvements** * Device metadata can be shown in the **Table Widget.** * **Chart Widget** supports hiding/highlighting individual data sources via the legend. * New option to colorise bar charts based on values in **Chart Widget**. * **Chart Widget** supports background colorisation to highlight areas like work schedules. * **Heatmap Widget** now allows display of weekdays. * Tooltip on widget titles (in global dashboards) now shows device and field name on hover. * Added option to hide the marker background in the **Map Widget**. **🐞 Bug Fixes** * Fixed pagination issues in the Measurement List Widget. * Gauge values in the Value Widget are now sorted automatically from low to high. * Notification list sorting now works as expected. * On global dashboards, it’s possible again to: * Copy and paste dashboards. * Copy desktop dashboards to mobile versions. * **Rule Engine Fix:** Calendar-like selector on "Time Restrictions" now always shows all available time slots. * **Chart Widget Fix:** Events are now displayed as overlays rather than altering the X-axis. ## April 2025 #### **✨ New Features** * **Set Value Rule Action**: You can now create new measurements by setting values directly through a rule. * **Table Widget**: Add **metadata fields** from your device's configuration section alongside your regular device data. You will find the option on the Table Widget's "Meta" fields. * **Chart Widget**: **Click on chart legends** to show or hide specific values — a smoother way to focus on what matters. See the[ Chart widgets documentation](/dashboards/widgets/chart-widget). * **Global Dashboard**: Hover over widget titles to **quickly see the device and field names** behind the data. * **White Label Capabilities**: We’ve reorganized White Label "Capabilities" section into groups for a **cleaner, easier-to-navigate setup**. #### 🔧 **Improvements** * **Heatmap Widget**: Want to see weekdays in your heatmap? Now you can! * **Manage Suggested Fields**: You can now **delete suggested measurement fields individually** — keep things tidy! * **Notifications View**: **SMS is now supported** inside your "Notifications" view for even more control. #### 📱 SMS Upgrades * **Character Replacement**: Automatically replace non-standard SMS characters with compatible ones. * **Better Quote Handling on SMS**: Standard quotes (`"`) are now correctly escaped, so your messages deliver just the way you wrote them. ## March 2025 **📝 Updates** * **New "Manage Workspaces" Permission**\ Organisation administrators can now view and manage all workspaces and related resources. This permission was automatically granted to all organisation owners. * **Public Dashboard URL Variable in Rule Engine Notifications**\ A new variable is available for email and webhook actions. It will be replaced with a dashboard URL if a link exists; otherwise, it will remain empty. * **White Label Site Notification Overview**\ Added an overview where users can see and disable rule notifications or edit receivers. * **Optional Columns in Rule Engine Page**\ Users can now optionally display: * Rule description * Affected product * Resulting actions #### 🔧 Improvements * **Heatmap Widget Enhancements** * Can now display **average, minimum, or maximum** values for the selected timeframe. * Color gradient can be disabled globally or per field. * **Device List Performance** * Improved loading times in the device list, grid view, and map view—especially for large workspaces. #### 🐞 Bug Fixes * **CSV Export Formatting**\ Fixed formatting issues in CSV exports when using local time. * **Localised Timestamps**\ Timestamps in the **Measurement List widget** are now correctly localised. * **Device Dashboard Creation**\ Creating a new dashboard tab no longer results in empty or deleted dashboards. * **Map Widget Zoom Crash**\ Maximum zoom level is now limited to prevent potential crashes. ## February 2025 #### ✨ Widgets * Value and Table widgets now support a new time range operation: **Count**. **👮 Rule Engine Upgrades** * You can now select any specific device in the rule conditions * Conditions are supported in system scheduler rules now * Rule Engine Actions: “Fire when conditions stay hot” is unselected by default now **📝 Updates** * We have changed the way **Energy Reports** buckets work. You can read all about it [in our documentation](/portal/reports/energy-report-1). **💠 White Label enhancements** * New capability "Restrict Login"! The capability enforces users that have signed up on a white label site to only log in on the same white label site, not [app.datacake.de](http://app.datacake.de/) or other WL sites. #### 🌏 Datacake LNS * Asian LoRaWAN frequencies are now supported (Asia 920-923 MHz) . ## January 2025 Happy New Year to all of you! Here's how the year has started for Datacake. ✨ **Widgets** * The [Heatmap Widget](/dashboards/widgets/heatmap-widget) is now live and available for all on Datacake **☃️ Members and Organization** * It is no longer possible to delete the organization admin from the workspace member list. **🌈 Zones** * feature: when adding or editing a zone there’s a new button to change the map style which helps with visibility in certain areas **🐥 History** * In the device history, boolean values are displayed correctly now **👮 Rule Engine Upgrades** * You can set a product, device or tags filter in rules now * If no filter is selected, rules can be applied to the entire workspace (= all devices in the workspace) * Product + tags filter can be combined * If a rule has a device filter and all devices are removed from the workspace, the rule will be deactivated, so it is not executed for all devices in the workspace * If a rule has a product filter and the product is deleted, the rule will be deleted * The new measurement trigger will trigger by any new measurement by default for all new rules created * Before it would only trigger on new measurements that are referenced in conditions * You can specify selected fields on which the rule should trigger to keep the previous behaviour * Conditions are only available if you select a product filter or devices where all selected devices belong to the same product * Rule templates will pre-select the relevant trigger * New scheduled device-independent “system rules” can be used to schedule e-mail reports or downlinks ## December 2024 #### ✨ Widgets * **Measurement List Widget:** Introduced a new widget to display historical measurement data. * **Chart Widget Enhancements:** * Added an option to set the tick interval manually. * **Table Widget Enhancements:** * Added an option to set the default sorting direction. #### 🌏 Datacake LNS * **Expanded AU915-928 Support:** * Added support for the AU915-928 frequency for the Australian region. * Introduced support for AU915-928 "for LatAm," with a server geographically located in the Americas. This applies to both gateways and devices. #### 🐞 Bug Fixes * **Chart Widget:** * Selecting a custom timeframe no longer randomly closes the sidebar. * Empty data sources in the chart widget no longer prevent other data sources on the same axis from displaying. ## **November 2024** November brought a variety of new features, enhancements, and bug fixes to improve the platform's functionality and user experience. Below is a summary of the changes: **🚀 New Features** * **Event Display in Chart Widget**: Customers can now add events to the chart widget for improved visualization of boolean-based data. [**Read more in the documentation**](/dashboards/widgets/chart-widget)**, or see this** [**awesome newly amazing video**](https://www.loom.com/share/1de4c4c7b9f745ca827e93250d7a8849) **hohoho 🎄** * **Conditional Table Formatting**: Conditional formatting can now be applied to individual columns instead of the entire row. * **Timezone Selector in Table Widget**: A timezone selector has been added to the table widget, with time parsing aligned across all widgets. * **Decimal Place Limit in Table Widget**: Additional options have been added to limit decimal places in table widget data. * **Automatic Widget Title Updates**: Selecting a data field for Boolean, SOS, Slider, and Value widgets automatically updates the widget title. **🛠️ Bug Fixes** * **Dropdown Visibility**: Fixed an issue where dropdown lists appeared behind modals. * **Missing Chart Widget Config Fields**: Addressed missing configuration fields for reference lines in the chart widget. * **Audit Log and User Table**: Resolved an issue where the audit log and users table didn’t display data in the whitelabel overview. * **Datacake LNS Importer**: Fixed a bug where importing CSV files with empty lines caused failures. * **Image Orientation on Upload**: Fixed an issue with images not respecting their EXIF orientation data upon upload. (Customers must re-upload affected images.) * **Chart Widget Y-Axis Labels**: Y-axis label widths in the chart widget now dynamically adjust to fit long values. * **Geo Fields in Device Configuration**: Only geo fields can now receive the role for device location, as intended. * **Reference Line in Chart Widget**: Fixed an issue where setting the reference line via a config field applied the change to all devices of the same product instead of the intended device. * **Slideover Dashboard Online Status**: The slideover dashboard now correctly displays device online status. * **Modal Layering**: Modals, such as those for exporting CSV files, now always appear in front of the slideover dashboard. **🛡️ Enhancements** * **Custom Date Format for CSV Reports**: You can now define a custom format for date columns in CSV reports. * **Reduced Network Requests**: Optimized widget editing by reducing the number of network requests. **📝 Updates** * **Add-ons Sidebar Update**: Add-ons are no longer displayed in the sidebar and are only visible to customers with an active individual Rule Engine subscription. The link remains functional for those users. * **Rule Engine Banner Update**: The Rule Engine banner on the Legacy Rules view now links to the billing view/package plans. * **Workspace Loading in Billing**: Users with more than 100 workspaces in one organization can now use a “Load More” button to view additional workspaces. ## **October 2024** #### **Widgets** * Added appereance setting to Image Map Widget that allows users to set value-based color for all markers at once. #### Improvements * [HTTP downlinks ](/generic-api-devices/http-downlinks)now available! #### **Organizations & Billing** * Organization "Administrators" now available! #### Reports * Energy reports allow to select multiple fields of one same device #### Rule Engine * New "Time Restrictions" feature for actions on the Rule Engine. You can now setup time windows in which your actions should be triggered (e.g. send an email only Mon-Fri from 8:00-17:00). ## **September 2024** #### **New Features** * NEW - 2FA now available! #### LoRaWAN * We now support the ChirpStack v4 gRPC to REST API proxy for LoRaWAN downlinks (next to the already existing gRPC one) #### Improvements * [CSV support for importing Datacake LNS devices](/best-practices/best-practices-getting-started#batch-addition-of-devices) * Copy/paste function on Rule Engine #### Zones * CSV file import of zones * Multi-select actions in the zones list (adding tags to multiple zones, deleting zones) * Edit zone coordinates * Duplicate zone * Edit a zone from the zone list * Address search box to zones and set value modal on location fields #### Widgets * Updated map widgets to use the latest Mapbox styles ## **August 2024** **Widgets** * NEW Set Value Widget! * Send multiple downlinks on Global Dashboard's **Downlink Widget.** **Improvements** * Now you can access a device's public dashboard (if public link is created) via a global dashboard's map or image map widgets. Just click on a device - the device's side-dashboard will open. Click on the hyperlink and you will get redirected to the detailed public dashboard of the device. There are three possible states: 1. User is authenticated: Link to device in workspace (as before) 2. User is not authenticated, public link exists: Link to public link 3. User is not authenticated, no public link exists: No link at all **White label** * You can now disable individual device configuration fields on white label sites. ## **July 2024** **Organizations & Billing** * SMS logs available with basic permissions (No billing permissions required anymore) **Widgets** * NEW [SOS Widget](/dashboards/widgets/sos-widget)! * Added color range for Map widget icons **LoRaWAN** * Confirmed downlinks for Actility **Fixes** * Improvements to timeframe selector in Chart widget * Table widget support for 100+ devices * Performance of side dashboards on Image Map widget ## **June 2024** **Reports** * Added a table to show selected fields with identifier in reports to prevent missing fields (when multiple fields share the same name but different identifier) **Zones** * Zones are now available as Beta on the platform * Support for zone actions in rule engine (device has entered zone, has left zone, stayed in zone for longer than X minutes) to trigger SMS, E-Mail, Webhook **Infrastructure & Performance** * Found & fixed a huge performance issue that impacted customers with huge dashboards but also indirectly impacted the overall performance of the platform. **LoRaWAN** * Downlink support for the KPN LoRaWAN network * Support for new Tektelic uplink format * Fixed Senet Base64 vs. Hex payload decoding issues ## **May 2024** #### **Integrations** The 1NCE OS Integration now supports downlinks. ## **April 2024** #### **New Features** * **New Widget:** Online Status Widget **->** Specially useful for device dashboards shared via a public link. You can now monitor the online status of your devices directly on the dashboard. * **New Workspace navigation experience.** You can now navigate through your workspaces on a separate view. Click on your workspace's name to open up a new modal. You have a Search line and can now use your keyboard arrows ↑↓ to select a workspace and select it with an Enter ⏎. * You will now find Account Settings and Logout on the left-side menu on your workspace. #### **Widget Enhancements** * Use `{ device_name }` on the title field of your **value widgets**. This will automatically get replaced by the device's name. #### Fixes * Overall performance improvements on big global dashboards. ## **March 2024** #### **New Features** * **Confirmed downlinks** for devices added to the **Datacake LNS**. * New **Purge Data** function. You can now delete data from Datacake's database. Scroll down on your device's configuration to see the Purge Data section on the "Danger Zone". Take this with care! Once you delete data, it cannot be recovered. #### Widgets Enhancements * **Word Breaking in Text Widget:** Improved word breaking in the text widget ensures text alignment and correct word wrapping, addressing customer feedback for enhanced readability. * **Chart Widget:** Fixed an issue where chart axis labels did not match the chart data, ensuring accurate data representation. * **Value Widget:** Implemented code modifications in the value widget to enhance performance and stability, with no changes to the UX. #### **White Label** * **Map View Option:** Introduced an option to hide the map view, catering to specific customer requests for privacy or political reasons. * **Branding Selection for User Invites:** Enhanced the process of inviting users to workspaces by allowing the selection of white-label branding directly on the app.datacake.de platform. This feature, previously available only for rules and reports, has now been extended to include user invitations, streamlining the process and offering more flexibility. #### Fixes * **Un-resizable Widget in Copied Dashboard:** Addressed a bug where widgets in copied dashboards were un-resizable, particularly affecting dashboards with a single widget. * **Removed Unverified Email White Label sites:** Enhanced security and branding consistency by removing white label sites with unverified emails from the branding selection options. * **Rule engine fix:** When you build a condition with a numeric measurement field (float or int) and choose “Measurement field from another device”, fields of both numeric types (float and int) are displayed now. Before, we only displayed the fields of the exact same type. #### **UX Improvements** * **Device List Error Handling:** Added an error message display in the device list when the API returns an error, improving user awareness and troubleshooting. #### MQTT Connection * Enhanced MQTT Connection Checking ## **February 2024** #### **New Features** * [**Datacake LNS** ](/datacake-lns/getting-started)is live now {% content-ref url="/pages/Ci1zns1nju2MmONmLv71" %} [Datacake LNS](/datacake-lns/getting-started) {% endcontent-ref %} * New **Device fields widget** * Added [**Home Dashboards**](/dashboards/global-dashboard/setting-homepage): Now you can setup a global dashboard to be the first thing your users see when accessing a workspace. #### Widget Enhancements * **Vertical gauge** available on [**value widget**](/dashboards/widgets/value-widget) * Use configuration fields from any device in a workspace dashboard for a reference line in [**chart** ](/dashboards/widgets/chart-widget)**and vertical gauge widgets** * Switch between round or square icons in [**image map widget**](/dashboards/widgets/image-map) * Add device's fields support in [**text widget**](/dashboards/widgets/text-widget) * Boolean support in **table widget** #### **Fixes** * Fixed error message in empty chart widget * Chart widget scales automatically to highest and lowest values on the same axis * Improved Grid view: Secondary values are always right-aligned, device titles fit always inside card #### White Label * Added option to enable/disable 1NCE devices * Added option to enable/disable Map view on Devices *** ## January 2024 #### Widgets Enhancements * Improved loading state for widgets: 1. New loading animation 2. Loading state to widgets when switching between dashboard tabs #### **Bug Fixes** * Fixed bug in device fields widget where tint color wouldn’t cover the whole widget when it was too small * Removed “No Data” text while widget is still loading #### **UX Improvements** * Added status link to sidebar and status widget when site is under maintenance. * Improvements to device list, grid, and map views: * Faster reaction when switching between views. * Deleting a device doesn’t require a page reload. * When adding a device on one page (e.g., grid view), it also shows in other views without requiring a page reload. *** ## December 2023 #### Widgets Enhancements * Added option to choose configuration fields as a value for reference lines in [**chart widget**](/dashboards/widgets/chart-widget) *** ## November 2023 #### **New Features** * New widget Device Fields Overview #### **Integrations** * [**1NCE integration**](/integrations/1nce-os) now available #### **UX Improvements** * Live dashboards are rendered instantly in a new “connecting” state * Device list and grid views are sorted by online status by default * Sort device fields in device configuration * Added a button to reset the view in the global dashboard's map widget and map view #### **Rule Engine** * Sort rule engine list by name or status *** ## October 2023 #### **Widget Enhancements** * Set maximum font size for strings in [**value widget**](/dashboards/widgets/value-widget) * Auto-resize long strings in **value widget** over multiple lines * New option to set thickness of reference line in [**chart widget**](/dashboards/widgets/chart-widget) #### **White Label** * Search on [**white label** ](/organization/white-label)users list. * Filter for actions in **white label** audit log. #### **UX Improvements** * Hide last update in all widgets. *** ## September 2023 #### **UX Improvements** * New login/signup/password reset screens. * Dashboard connection status indicator for three states: * Connected (blue, pulsing). * Reconnecting (orange, pulsing). * Disconnected (gray, just a dot, not pulsing). * You can now set a "Claim Serial Number" in the device settings, which will override the Serial Number during claiming. #### **GraphQL API** * There's a new field `currentConfigurationValues` on the `DeviceType` which allows you to get all configuration fields and their current values for a device. *** ## August 2023 #### 23th August * **Multi-Language** * The frontend of the portal is now fully translatable into the following languages: **French**, **Spanish**, **English**. * The following languages will follow later: German, Dutch * You can select languages from within the account profile settings. * **Bugs** * We fixed a bug in the display of sidebar dashboards or mobile dashboards that caused maps not to be displayed correctly. #### 8th August * **Permission changes for workspaces and devices** * Permission changes for workspaces and devices are now logged in the audit log. You can check them in the white-label audit log (for users with enterprise white-label package). * The “Save” button for workspace permissions was removed in the front end. Instead, permission changes are sent directly but debounced to the API. * **Dashboard Widgets can be now translated into 33 languages** * Users can use the language selector in the dashboard builder to preview the translations in different languages. * Translatable fields in new widgets will be automatically initialized with all languages that were used on the dashboard so far. Translatable fields on existing widgets can be automatically synced with the “Sync Translations With Other Widgets” button. *** ## **July 2023** #### 5th July * **Added new template language options to Rule Engine E-Mail and Webhook Editor** * `{{ ["location"] }}` returns the device location * `{{ ["tags"] }}` returns the device tags * For SMS and email notifications, the new `join` filter will be automatically appended when using the variable autocomplete feature. `join(", ")` will automatically separate all tags with a comma, but the separator argument can also be adjusted. * For webhook notifications, the new `json` filter will be automatically appended when using the variable autocomplete feature, so the tag list can be send as valid JSON to another web service. * `{{ ["online"] }}` returns the online status for the device, which is either `True` or `False` * For SMS and email notifications, the new `ifelse` filter will be appended when using the variable autocomplete feature. `{{ ["online"] | ifelse("online", "offline") }}` will convert the boolean value to the `online` or `offline` text, respectively. * For webhook notifications, the new `json` filter will be automatically appended when using the variable autocomplete feature, so the online status can be send as valid JSON `true` or `false` value to another web service. * `{{ ["last_heard"] }}` returns the online status for the device. Similarly to the measurement timestamps, the new `datetime` filter is automatically appended when using the variable autocomplete feature in the SMS or email editor. * The new `ifelse` filter can also be used in combination with boolean measurement values. For example, `The device is currently {{ triggering_device["measurements"]["IS_MOVING"] | ifelse("moving", "not moving") }}` will convert boolean measurements into human-friendly messages such as “The device is currently moving” or “The device is currently not moving”. #### 4th July * Starting from July 4th, 2023, measurement timestamps are now supported in the Rule Engine notifications on the Datacake IoT platform. * This means that you can use the `{{ triggering_device["timestamps"]["TEMPERATURE"] }}` code to display the timestamp of the measurement in UTC ISO format (e.g. `2023-07-04 09:41:00+00:00`). * This is useful when the timestamp is sent through a webhook (by rule engine) and needs to be processed by a machine (which is receiving the webhook). * In addition, you can use the `datetime` "filter" to render the timestamp in the rule's timezone, making it more human-friendly. * By default, `{{ triggering_device["timestamps"]["TEMPERATURE"] | datetime }}` will return the timestamp in the format `2023-07-04 17:41:00`. * For more advanced formatting options, you can adjust the format using `{{ triggering_device["timestamps"]["TEMPERATURE"] | datetime("%A, %B %d, %Y %I:%M %p") }}` (which returns `Tuesday, July 04, 2023 05:41 PM`). * All available variable options can be found at [strftime.org](http://strftime.org/). * Please note that when using the variable auto-suggestions feature, the webhook editor will insert the variable without the `datetime` filter, while the editors for emails and SMS will insert the variable with the datetime filter (but without a format argument). #### 3rd July * Add a white-label audit log for the selected user. * Center the white label logo on the signup form. * Reposition the timeframe selector (chart widget) on mobile devices or small widget sizes. * Disable mouse zoom in the image map widget. * Show the current icon size for the marker in the image map settings. *** ## **June 2023** * Optionally hide LoRaWAN settings in the device config. * Added export to CSV for device history and chart widget. * Added "Edit Tags" modal to the devices list. * Added white-label audit log. *** ## May 2023 [**Custom Timerange Buttons on Chart Widget**](https://www.notion.so/Custom-Timerange-Buttons-on-Chart-Widget-cb02f3f8e3fb4c87a8d93305b2991404?pvs=21) # Best practices This is a comprehensive guide to navigate through Datacake, designed to provide a meaningful journey through its features for optimal IoT management. The purpose of the following document is to ensure that the performance of the functionalities within the platform is optimal. General best practices for getting started within the platform will be described step by step, following by best practices for creating dashboards, best practices for creating reports, best practices for creating rules and best practices for managing users. ## Getting Started {% content-ref url="/pages/ZWLYVxHp7UgSKpiiemUo" %} [Best practices: Getting started](/best-practices/best-practices-getting-started) {% endcontent-ref %} ## Dashboards {% content-ref url="/pages/Yy8s37Ia993wq7mJKvxz" %} [Best practices: Dashboards](/best-practices/best-practices-dashboards) {% endcontent-ref %} ## Managing Fleets # Best practices: Getting started ## 1. **Device Addition** ### **Product definition** Initiating your journey with the 'Product' definition is fundamental. This approach is the cornerstone of easy fleet management. By using Products, you ensure that all devices on one kind inherit essential characteristics, creating a uniform yet flexible operating environment. {% hint style="info" %} All Devices belonging to one same Product have the same Payload Decoder, Fields and Dashboard. If you modify one device, all of them will reflect those changes. This enables you to manage fleets of hundreds of devices, maintaining the integrity ensuring that your whole IoT fleet stays up to date. {% endhint %} In the following video you will learn how to add a device to an existing product. {% embed url="" %} [Learn more about Products.](/device/product) ### **Configuration Fields** Configuration fields introduce a layer of customisation for the individuality of each device and offer flexibility when using the Product definition. This is important when devices require unique operational parameters, ensuring they perform their roles effectively. If, for example, your gas tank filling measuring devices are all of the same type, however, they are installed in tanks of different heights. In this case the configuration fields allow you to define a different height value for each tank. These can be used in the payload decoder to make calculations, or they can be called within the new rule engine to trigger notifications. [Learn more about Configuration Fields.](/device/database/configuration-fields) ### **Batch addition of devices** Utilising the CSV drag-and-drop feature for adding devices is more than an operational shortcut; it's a growth strategy. By integrating multiple devices simultaneously, you maintain a rhythm and coherence to your expanding network. This strategic addition ensures your system scales with purpose, keeping complexity at bay. {% hint style="info" %} There is not known limit to the amount of devices you can add at once to Datacake. Make sure all DevEUIs are unique, otherwise you will get an error **No valid DevEUIs were found in the CSV file**. {% endhint %} Make sure that the order of the columns on the CSV file is correct and that there are no empty rows or columns. The order must be **DevEUI, Name, Location description, Tags**. Location description and Tags are optional columns. The tags must be separated by commas in the same column of the document. Here an example of a CSV file containing all columns mentioned: | 49 54 95 75 56 55 65 66 | Device 1 | First Floor | Office01, Temperature | | ----------------------- | -------- | ------------ | --------------------- | | 49 23 47 30 94 74 38 24 | Device 2 | Second Floor | Office02, CO2 | For batch adding devices to the **Datacake LNS** you need to prepare the CSV file with the following information: DevEUI, Name, AppEUI (or JoinEUI), AppKey, Frequency, Class, Location description, Tags.
49 54 95 75 56 55 65 66Device 1cd1a75ae5818dcbec39ebd8578c3d7ac6dfef73afb60dfbaEU_863_870_TTNAFirst FloorOffice01, Temperature
49 23 47 30 94 74 38 24Device 2cd1a75ae5818dcbef171b14be6e3494ce6da3dd8e67cbb8cEU_863_870_TTNASecond FloorOffice02, CO2
Remember that DevEUI and AppEUI are strings 8 bytes long. AppKey is a 12 byte string. All of them should be provided by your device manufacturer. We currently support the frequencies: * `EU_863_870_TTN` * `US_902_928_FSB_2` And the devices classes: * `A` * `C` {% hint style="warning" %} Please make sure the frequency and class are written correctly, exactly as shown above. {% endhint %} Again, Location description and Tags are optional columns. {% hint style="info" %} Make sure that your CSV file doesn't have a header with the titles (it should simply start with the first device). Otherwise the platform will return an Error message. {% endhint %} ## 2. Data Ingestion Rate Guidelines for Datacake To ensure optimal performance and reliability, all IoT devices connected to Datacake must adhere to the following data ingestion guidelines: * **Minimum Ingestion Interval**: Devices should **not** send payloads at intervals of less than **1 minute**. The Datacake platform is not designed to handle high-frequency data transmission, and payloads sent at rates faster than this may result in data loss or system instability. * **Intended Use**: Datacake is optimised for IoT devices that typically transmit data **a few times per day**. Our infrastructure and functions are built around this usage pattern, and adhering to these guidelines will help maintain system efficiency and reliability. Please configure your devices accordingly to prevent any potential issues with the platform features. ## **3. Workspace management** Implementing separate workspaces for different tenants is a practice of meaningful delegation. You can manage who gets access to what in an easy way. If you have multiple customers/locations/departments, the easiest way to grant access to specific devices is to have different workspaces for each one of them. When having control over the devices is important, Datacake recommends you to create a **master workspace**, to which you will add all of your devices, while having sub-workspaces for each one of your customers. You can use the [Pincode claiming](/device/claiming) functionality to claim specific devices to those sub-workspaces. This structure safeguards your devices, ensuring it remains a hub for all devices, while subsidiary workspaces function as dedicated environments tailored to specific tasks or teams. This clear delineation promotes responsible access and efficient management. An additional advantage of employing this structure is that it ensures the receipt of a unified invoice including all devices in the master workspace, due to the fact that the billing procedure is conducted on a per-workspace basis. ## **4. Application of Tags** By applying tags, you facilitate targeted reporting, efficient rule-setting, and effective device visualisation. You can set/create tags when adding the devices to the platform. You can also add them once the devices are on the platform using the Actions/Add Tags button or by navigating to each device's configuration section. You can manage devices and sort them by type/location/owner, among others. Tags can be used to generate reports in device batches, create custom notifications in the new rules system or add them to the map widget. The following video shows you how to use the multi-selector in the List view to add tags to your devices: {% embed url="" %} ## **5. Overview, List, Grid and Map Views** Choosing between your Overview, List, Grid and Map views is a decision rooted in your information needs. This choice influences how you interact with your fleet data, prioritising the most critical metrics front and center. By customising these views, you are making a conscious decision about what metrics drive your decisions daily. At the top of the page, next to "Add Device" you will see the Settings configuration. That will allow you to configure the Temperature unit (°C or °F) and select the Sensor Metrics style (Cards or Table). ### Devices View – Overview The **Overview** tab provides a high-level summary of all devices within your workspace. It is designed to give you an immediate understanding of device status and key sensor metrics across your entire fleet. This view displays aggregated KPIs in the form of visual cards, allowing you to quickly identify issues, trends, and overall performance. At the top of the Overview page, you will find the **Device Status** summary. These cards provide a quick snapshot of your fleet’s operational state: * **Total Devices** – The total number of devices in the workspace. * **Online Devices** – Devices currently connected and actively sending data. * **Offline Devices** – Devices that are currently not connected. * **Active in Last 24h** – Devices that have transmitted data within the last 24 hours. This section helps you quickly assess system health and connectivity across all devices. Below the Device Status section, you will find the **Sensor Metrics** area. This section contains metric cards automatically generated based on the **device** [**semantics**](/field-semantics) configured in your devices. Semantics define the meaning of device fields (e.g., Temperature, Humidity, CO₂, Battery, Signal Strength, etc.), allowing Datacake to aggregate and display them consistently across devices. Each KPI card in the Overview is interactive. When you click on a card you are redirected to a detailed view. The system filters devices that contain the selected semantic. * You can see: * Average value * Minimum value * Maximum value * The list of relevant devices * Individual device values This allows you to move from a fleet-wide summary to a more detailed device-level analysis in just one click. The Overview view is ideal when you want to quickly check overall fleet health, identify abnormal environmental conditions, detect connectivity issues, compare aggregated values across devices and/or monitor key KPIs at a glance. It serves as a dashboard-style summary before switching to List, Grid, or Map view for more specific device management tasks. ### Devices View – List The **List** view provides a structured, table-based overview of all devices in your workspace. It is designed for detailed device management, quick comparisons, and bulk operations. This view is especially useful when you need to configure multiple devices at once or customise the displayed device information. Each row in the List view represents a single device. By default, the table displays Online status, device name, primary, secondary, device signal and device battery. You can select which columns to display. The options available are: * Online Status * Device Name * Primary Value * Secondary Value * Device Signal * Device Battery * Serial Number * Location (Location description) * Tags * Last Seen * Product * Product Type (LoRaWAN, API, etc) * Device Location (geolocation coordinates) The visible columns depend on your configuration (see below). You can drag each of them up or down the list, depending on the position you want to put them in. {% hint style="warning" %} Keep in mind that the selected columns are stored in the caché memory of your browser, so your customers or users within the platform will have the possibility to select the columns that are important to them. This facilitates customisation, therefore if you want your customers to see certain parameters then you will have to create custom views using global dashboards. If you clear your browser cache or switch browsers/devices, your column configuration may reset. {% endhint %} At the top of the List view, you can also use the **Search bar** to quickly find devices. #### Multi-Select and Bulk Actions The List view supports multi-device selection for bulk management. At the right side of the table you will see the option to select devices. Click on the first checkbox to select all of the devices (in the current page), or feel free to multi-select the devices you'd like to configure. A selection bar will appear at the top showing the number of selected devices. Once devices are selected, you can perform bulk operations: 1. Click **Edit** to open a configuration modal that applies changes to all selected devices. Within the Edit modal, you can: * Change the **Device Name** * Use a name template (e.g., `{name}`, `{serial}`, `{location}`) * Use index counters for batch renaming * Set or update the **Location description** * **Add tags** to all selected devices * **Remove tags** from all selected devices Changes are applied to all selected devices simultaneously. If a field is left empty in the modal, the current value will remain unchanged. 2. Click **Delete** to remove all selected devices at once. {% hint style="danger" %} Deleting devices is permanent and cannot be undone. {% endhint %} ### Devices View – Grid The **Grid** view displays your devices as visual cards, providing a compact and intuitive overview of each device and its key metrics. This view is ideal when you want a quick, device-by-device snapshot while still maintaining a visually structured layout. Each card typically displays: * **Device Name** * **Meta information** (e.g., Serial Number, Location, or Last Updated) * **Primary value** * **Secondary value** * **Battery level** * **Signal strength** * **Online status indicator** * Quick action icons (View and More options) The layout makes it easy to visually scan multiple devices at once. You can customize how device cards are displayed using the **Settings** button in the top-right corner. The options allow you to choose which metadata appears under the device name: * **Serial Number** * **Last Updated** * **Location (Location Description)** Only one meta information field can be displayed at a time. You can also adjust the size of the device cards: * **Small** – Compact layout, ideal for viewing many devices at once. * **Medium** – Balanced view with more readable spacing. * **Large** – Expanded layout with greater emphasis on device values. This allows you to optimize visibility depending on screen size and monitoring needs. At the top of the Grid view, you can use the **Search bar** to search and filter devices. ### Devices View – Map The **Map** view allows you to visualize your devices geographically on an interactive world map. This view is ideal for location-based monitoring, regional analysis, and large-scale deployments where physical device distribution matters. To appear in the Map view, devices must have: * A defined **Device Location** field * Valid **geolocation coordinates** (with latitude and longitude) If a device does not have proper coordinates configured as Device Location ([Roles](/device/database/fields/field-roles)), it will not be displayed on the map. Each device is represented by a marker on the map. Depending on the configuration established in **Settings**, markers can display: * Primary value * Secondary value * Device battery * Device signal * No value (Marker only. The marker taken will be the Device's Icon set in your device's "Configuration" section) When clicking on a marker, a detail popup appears showing: * Device name * Meta information * Primary and/or secondary values * Battery status * Signal strength * Status indicators (if applicable) * Quick access icons (View / More options) This allows you to analyze device performance directly within its geographic context. When multiple devices are located close to each other, the Map view can group them into **clusters**. * A cluster displays the number of devices inside it. * Zooming in separates clustered devices into individual markers. You can enable or disable clustering via the **Settings** menu. You can also adjust the visual style of the map: * Light * Dark * Outdoors * Satellite * Streets This helps optimize visibility depending on lighting conditions, presentation needs, or specific geographic use cases. ### Navigation Controls The Map view includes: * Zoom controls (+ / −) * Pan functionality * Search functionality (via the top search bar) # Best practices: Resolution (Timeframe) This article will guide you on how to configure resolution (timeframe) on different parts of the platform, such as chart, value and map widgets, as well as reports. Datacake has a time-series database framework, which organises data into time buckets. These buckets help in managing and querying data efficiently over various periods of time. Selecting the right resolution is very important for dashboard performance. You should choose a timeframe that not only presents the most relevant information but also maintains the dashboard's responsiveness and efficiency. A higher resolution (i.e., more granular data points) can provide detailed insights but may slow down performance due to the larger volume of data being processed. That is why we advise you to opt for the smallest practical resolution that still captures the essential details of your data. This approach ensures that viewers access the most critical information without compromising the dashboard’s overall performance. Datacake will allow you to select a specific resolution on Value, Chart and (device dashboard) Map Widgets, as well as on your automated reports. ## Setting Resolution on Value, Chart and Map Widgets The Chart, Value and Map Widgets come with options to set up a custom time range. You will find them when entering the edit modus of your dashboard and on your widget's configuration under Timeframe. You will find specific documentation for each of the widgets here: {% content-ref url="/pages/l6anCSSay8KSrOUgr3Ub" %} [Value Widget](/dashboards/widgets/value-widget) {% endcontent-ref %} {% content-ref url="/pages/4eu4UWG389lmNabSxx5G" %} [Chart Widget](/dashboards/widgets/chart-widget) {% endcontent-ref %} {% content-ref url="/pages/-M-LSJpHE3OMX0HKg7XF" %} [Map Widget](/dashboards/widgets/map-widget) {% endcontent-ref %} {% hint style="info" %} Take into consideration that the **Map Widget** on [Device Dashboards](/dashboards/public-dashboard) is the only that has historical data. Historical data is not available on [Global Dashboards](/dashboards/global-dashboard). For that we have developed side-dashboards, that will allow to click on a specific device and show the device's dashboard on the right side of the screen. {% endhint %} ### Relative Time Range Options You can select between a range of relative time range options. This allow you to select a fix-sized window of time that will move in the future. We suggest you to use them. Some of the available options are: `startOfHour, startOfDay, startOfYesterday, startOfWeek, startOfLastWeek, startOfMonth, startOfLastMonth, startOfYear, startOfLastYear, 30 minutes ago, an hour ago, a day ago, 7 days ago, a week ago, a month ago, last year, now` Some examples may be: * Rolling the last 24 hours: From: `24 hours ago` or `1 day ago` -> Until: `now` * Rolling this week: From: `7 days ago` or `a week ago` -> Until: `now` * Rolling from the start of the week until now: From: `startOfWeek` -> Until: `now` The next step after entering the timeframe is selecting the resolution. You can enter manually a specific amount of Minutes or Hours. Remember that the platform makes an effort to fetch the data from the time-series database, so be mindful when selecting a large timeframe and a very low resolution, since this will affect negatively the performance of your dashboard. If you still don't know how to select the timeframe and resolution to work the best, you can enable on the Chart Widget the "Allow timeframe selection on dashboard" option you will find under Appearance. This will allow your customers to select the timeframe on the frontend and the resolution set up as default is the ideal resolution. Otherwise we recommend you skipping to the [#daily-trends-with-high-resolution](#daily-trends-with-high-resolution "mention") or [#weekly-or-monthly-overviews](#weekly-or-monthly-overviews "mention") ### Absolute Time Range Options You can also select an absolute time range, which means you can enter a specific date. However, this is only recommended if the time range selected is static. {% hint style="danger" %} Never select From: `*specific date*` -> Until: `now`. This will cause problems, since the specific date will stay static. Every day that passes will be one more added day of data that the dashboard will have to fetch, which might become unsustainable and your dashboard will start having extremely long loading times. {% endhint %} ### Daily Trends with High Resolution We recommend to use high resolution data (like resolutions within minutes, for example 5 minutes) only in combination with time frames that go back to maximum of 48 hours. So you could set up a chart for a high resolution trend for the last 24 hours with the following settings: `24 hours ago` to `now` with resolution of `5 minutes`.
### Weekly Or Monthly Overviews Once you have set up a chart with high resolution for the last 24 hours, you can duplicate that widget and set the time frame to a lower resolution with larger time frame, like `14 days ago` or `31 days ago` to `now` with a resolution of `24 hours`, `12 hours` or `4 hours`. {% hint style="success" %} If you set up a chart for a monthly overview we recommend using `24 hours` as the resolution. {% endhint %} {% hint style="info" %} You might want to select "Bar Chart" as the visualisation type as this makes more sense for higher resolutions. {% endhint %}
## Setting Resolution on Reports As per the resolution on widgets, resolution in reports determines the level of granularity of the data presented and plays a crucial role in both the accuracy of the information and the performance of the report. {% hint style="success" %} The chosen time range should align with the report’s purpose. Shorter time ranges can be combined with higher resolution to capture more data details. However, longer time ranges should be better combined with lower resolution to enhance performance and readability. {% endhint %}
{% hint style="warning" %} Only use "Raw Data" when selecting short time ranges (Max. 2 days, depending on the amount of data included in the report). Otherwise, your reports will take several minutes to be sent. {% endhint %} You can read more about Reports and it's configuration here: {% content-ref url="/pages/-MUPjRVVovUaQN8BYyAg" %} [Reports](/portal/reports) {% endcontent-ref %} ### Common Use Cases and Examples Datacake reports can serve various purposes. For instance, using reports as a **backup method** is a common practice. In those cases, where the main goal is to maintain a reliable record rather than detailed analysis, setting a lower resolution is necessary. Daily reports with lower resolution are recommended for backup purposes because they provide sufficient overview while minimising system load and storage requirements. For more analytical needs, where trends and changes over time are more critical, weekly, monthly, or even annual reports can be configured. In these cases, setting a higher resolution period is beneficial. For example, weekly reports might track more granular changes in a production process, monthly reports could monitor broader trends in sales performance, and annual reports might focus on year-over-year growth comparisons. Each of these reports would benefit from a resolution that matches the goal—capturing enough detail to inform decisions without overwhelming the system or the end-user with excessive data. ## Video {% embed url="" %} # Best practices: Dashboards Creating an effective dashboard on Datacake involves strategic decisions. This hands-on guide will walk you through the practical steps to ensure your dashboards are both functional and efficient. The fluid nature of data—its volume and variety—makes it challenging to prescribe a 'one-size-fits-all' formula for dashboard configuration, particularly concerning the number and type of widgets used. The performance of a dashboard's depends on the amount of datapoints it fetches, and the complexity of the calculations it performs. At the core of our platform is a time-series database, specifically engineered for handling data points indexed over time. This structure is ideal for the continuous data streams common in IoT scenarios, allowing for efficient queries and storage management. However, it's crucial to recognise that every widget interaction with this database—whether a simple fetch request or a complex calculation over a wide timeframe—requires system resources. As we proceed, this guide will focus on the practical steps for optimising your Datacake dashboards. You'll learn to select and configure widgets wisely, design with intention, and create efficient, visually appealing dashboards that harness the full potential of your IoT data without compromising performance. ## **Managing Widgets for Performance** ### **Limit Widget Quantity** Though you can add as many widgets as you want, restraint is crucial. More widgets mean more data fetching, which can slow down performance. Stick to necessary widgets that contribute critical insights. Always remember: it's not about the quantity of data presented but the quality and relevance of the information extracted. ### **Optimise Value Widgets** Value widgets show the current data or calculated averages, minimums, maximums, etc., over a selected timeframe. Real-time data loads quickly, but calculated data takes more time, since all of the datapoints need to be fetched from the time-series database and calculations need to be done. Be selective in the timeframe operations to avoid performance lags. While selecting timeframe operations, opt for a period of time that mirrors your need for insight without taxing your system. ### **Optimise Chart Widgets** * **Smart Timeframe Selection:** Charts allow for various timeframe selections, from one hour to custom periods. However, longer periods can overwhelm your display capabilities and hamper readability. Choose timeframes that align with your immediate analysis needs. Remember you can now select **Allow timeframe selection on dashboard** under Appearance, which allows to dynamically change the timeframe from the dashboard, without having to enter the dashboard editing modus. This is optimised to show only the necessary datapoints per timeframe. * **Resolution Matters:** When using custom timeframes, ensure the resolution matches. If you're looking at extended periods, adjust the resolution accordingly to avoid cramped, unreadable data points. * **Use Aggregation Functions:** For broad time windows, use average, minimum, or maximum calculations to simplify the data view. This approach reduces clutter and enhances data significance. ### **Use of Tabs in Global Dashboards** Add tabs to your Global Dashboards to have sub-dashboards inside of one single dashboard. These act like chapters in a book, each containing a different segment of your data story. By dividing your data across multiple views, you not only create a rhythm for your information flow but also enhance the dashboard's performance. {% hint style="info" %} **Distribute Widgets Wisely ->** Place your more data-intensive widgets across various tabs. This strategy spreads out the load, reducing the strain on any single view and thereby improving loading times. It's about allowing your data to breathe while ensuring users aren't waiting on slow, crowded visuals. {% endhint %} In the following video you'll see how to create tabs on your global dashboards. {% embed url="" %} ### **General Best Practices for Dashboard Efficiency** * **Sensible Aggregation:** For analysing larger timeframes, group data into more extended averages (e.g., 72-hour chunks) rather than shorter segments. It helps in identifying trends over noise. * **Avoid Overloading:** Don't overload dashboards with too much data. Instead, focus on key insights. If a widget doesn’t add immediate value, consider removing it. * **Test Performance:** After setting up, test your dashboard’s load time and responsiveness. If it's slow, review your widgets and timeframes, making adjustments for efficiency. * **Regular Reviews:** Periodically review your dashboard setup to remove outdated or unnecessary widgets and data, keeping the display relevant and functional. # Best practices: Reports Reports in Datacake are a powerful tool for sensor data management and analysis. They have two main uses within Datacake: 1. **Exporting data to keep backups.** Data stored in Datacake's time-series database is kept accessible for a period of up to one year. After this duration, the data begins to get deleted in order to manage storage capacity and maintain system efficiency. This approach is typical in data management systems, especially when dealing with large volumes of data generated by IoT devices and sensors. However, while this policy helps in managing the database efficiently, it also poses a challenge for long-term data preservation. This is where the role of reports becomes crucial. Reports in Datacake are not just tools for data visualisation and analysis; they also serve an essential function in data backup. By using reports, you can export and save the data collected by your sensors and devices before it reaches the end of its retention period. 2. **Automated data distribution:** Reports can be configured to periodically send updated data to a specified group of email recipients. This automated dissemination ensures that stakeholders, such as team members, managers, or customers, receive timely updates without manual intervention. ## Creating a report ### Report's name Make sure to give your report a sinful name. This will also appear as the subject on the automated emails. It will also help you identify it when you have more than one report configured in your workspace. ### Timezone & Schedule Select your timezone and schedule your report using the Schedule selector. You will have three options: * At a specific time: This will be triggered one or more days of the week, depending on your selection, at the specific time you choose. In the drop-down-list you will be able to select only full hours. If you want the report to be sent at customisable times, you will have to check out how to use crontab expressions. * Interval between times: This only makes sense when your report should be sent at regular intervals inside of a selected time window. For example, if your devices are in a factory, where temperature should stay at a constant value of 25°C, you will want to send periodically this data to the person in charge of ensuring this temperature conditions. This reports should be then sent inside of the factory working hours (lets say between 7am-5pm) every 30 mins to one hour. This way, the person in charge will receive a report with the data generated by the devices in those frames of time, only within the window of time selected. * Crontab expression: This function enables you to select in a flexible way the periods of time in which your reports are sent. Please check out the documentation New Rule Engine/Select Triggers/Timebased Schedule, for more examples on how to create your own crontab expressions. ### Report Receivers & Branding Once your report is created, you can add your Report Receivers. Please make sure you type in the correct email addresses of the desired recipients. It is as well important that you select the Branding. If you are the owner of a White Label Site, this step is extremely important for you. If Datacake is selected, the recipients will receive the email from a email address and not from your white labeled email address. # Best practices: Grouping Devices See how you can leverage workspace dashboard to allow Grouping Devices by Tags Datacake is a platform that simplifies device management. A recent tutorial explains how Datacake's features can transform device organization and interaction, especially by utilizing tags and dashboard groupings for better management. ## Introduction The tutorial commences with a walkthrough of the Datacake workspace, where a whopping total of 105 devices are showcased. The initial hurdle outlined is the daunting task of managing this sizable collection, all initially congregated in a single, overwhelming device list. This scenario begs for a more structured and manageable approach to device oversight. ## Video Please have a look at the following video for a complete overview. {% embed url="" %} ## Story ### Tags and Dashboards: The Organizational Backbone Addressing this need, the tutorial shines a light on the significance of tags and dashboard groupings. Tags emerge as a pivotal categorization tool, streamlining device management and monitoring. The video further introduces the concept of sidebar and workspace dashboards, key in segregating devices for an orderly and navigable workspace. ### Unveiling Grouping Capabilities A highlight of the tutorial is the introduction to grouping sidebar dashboards, a feature unveiled a few months before the tutorial's release. The presenter demonstrates the process of creating folders for different building levels—specifically, the first and second floors. This organizational tactic not only facilitates workspace navigation but also amplifies the efficiency of device monitoring based on their physical locations within a structure. ### Dashboard Creation and Customization At the tutorial's core is the process of crafting dashboards for specific tags. An illustrative example is the creation of a "cafeteria" dashboard, designated for devices tagged correspondingly. This segment meticulously walks viewers through selecting tags, dashboard creation, and widget addition to display pertinent data, such as device names and measurements like temperature and humidity. The tutorial carefully guides through the customization of widget appearance and configuration saving, ensuring a personalized dashboard experience. ### Enhancing the Organizational Framework Building on the cafeteria dashboard example, the tutorial extends the organizational framework to include additional dashboards for various tags, such as "export." Each dashboard is meticulously tailored to exhibit devices linked to its respective tag, showcasing Datacake's customization and organizational flexibility. The tutorial further explores the rearrangement of dashboards within folders, optimizing the structural organization. ### Advancing Widget Customization A notable tutorial segment delves into advanced widget customization techniques. It explains how to incorporate and organize multiple columns within widgets, including indicators for devices' online and offline statuses. This functionality mimics the overall device list's layout, offering a familiar and user-friendly interface for interaction. ### Wrapping Up: A Holistic Organizational Solution The tutorial concludes by highlighting how Datacake can serve as a comprehensive tool for creating a well-organized, efficient workspace for building device management. Through strategic tag use, dashboard groupings, and widget customization, users can achieve unparalleled organizational clarity, streamlining device management processes. This approach not only conserves time but also significantly improves monitoring and management efficiency, establishing Datacake as an essential resource for building management professionals and beyond. ### Essential Insights * Datacake's tag and dashboard grouping features present a robust solution for comprehensive device fleet management. * Establishing folders for different building levels and allocating dashboards to these folders fosters a highly structured workspace. * Customizable widgets afford granular control over the presentation of device data, meeting specific management requirements. * Effective device and dashboard grouping based on tags markedly enhances device management efficiency. By adhering to the guide provided in the tutorial, Datacake users can revolutionize their approach to device management, transforming a potentially cumbersome task into a manageable and streamlined operation. This tutorial not only showcases Datacake's capabilities but also underscores the importance of structured organization in the contemporary digital landscape. # Getting Started How to get started on Datacake using your own LoRaWAN Gateways and any LoRaWAN Device. ## About Datacake LNS Datacake LNS is designed to bridge a gap that customers often face when taking their first steps with LoRaWAN technology. Recognizing the challenges associated with connecting external LoRaWAN Network Servers (LNS) to Datacake, we decided to develop our own integrated LNS solution. This integration allows users to directly add their LoRaWAN gateways and devices to Datacake, eliminating the need for any external LNS. This development simplifies the process for users, making it more straightforward and accessible. ### Key Features * **Direct Integration:** Users can now add their own LoRaWAN gateways and any LoRaWAN device directly to Datacake without the need for an external LNS. * **Simplified Process:** Adding gateways and devices is done through the Datacake frontend, known for its user-friendly interface, making the process especially easy. * **No Gateway Required:** Don't have your own Gateway? You can still add devices to the Datacake LNS using over 20k public Gateways! ### Clarification on Datacake LNS Usage {% hint style="success" %} There are **no hard limits on the number of gateways or devices** when using Datacake LNS. Deployments can scale according to project requirements. {% endhint %} Datacake LNS is designed to provide a seamless LoRaWAN experience directly within the Datacake platform. It enables users to onboard gateways and devices quickly without requiring external network server infrastructure. Unlike traditional setups that rely on separate LoRaWAN Network Servers, Datacake LNS is fully integrated into the platform and can scale with your deployment. For many projects, Datacake LNS provides everything required to run a production LoRaWAN network, including gateway management, device connectivity, and direct integration with dashboards, automation, and analytics. Third-party LoRaWAN Network Servers such as The Things Stack, Loriot, or Actility remain fully supported for users who already operate networks on those platforms or require specific ecosystem integrations. ## How to get started ### Add your first LoRaWAN Gateway Learn how to add your first Gateway to Datacake by visiting the following subpage of this tutorial. {% content-ref url="/pages/4luxDyPRGBnPVW0sjHoO" %} [Gateways](/datacake-lns/gateways) {% endcontent-ref %} ### Add your first LoRaWAN Device Discover how to directly add LoRaWAN devices to Datacake by following the instructions provided on this subpage of the getting started guide. {% content-ref url="/pages/yeyHPO4rqSt8gibZ8kA3" %} [Devices](/datacake-lns/devices) {% endcontent-ref %} {% hint style="success" %} Don't have a gateway yet? If you are within range of a third-party Gateway, you can still use Datacake LNS. Check our tutorial here: [Add Devices without Gateway](/datacake-lns/add-devices-without-gateway) {% endhint %} ## Background Information You find a video showing you the background information about our LNS on the following subpage. {% content-ref url="/pages/oFZRbgdAtXb9mYofiKGk" %} [Add Devices without Gateway](/datacake-lns/add-devices-without-gateway) {% endcontent-ref %} # Gateways Everything you need to know about adding LoRaWAN Gateways to Datacakes own LoRaWAN Network Server. ## About In this tutorial, we are showing you how you can add any LoRaWAN Gateway to Datacake ## TL;DR If you don't have the time to read through this documentation, we have prepared a short intro video for you: {% embed url="" %} ## Requirements {% hint style="warning" %} Please make sure your LoRaWAN Gateway meets the following requirements. {% endhint %} Before proceeding with adding a LoRaWAN gateway to Datacake, it's essential to ensure that your gateway meets the following requirements: * **Gateway Compatibility:** The gateway must be compatible with LoRaWAN protocols and capable of being configured to communicate with an external LoRaWAN Network Server (LNS). * **URL Configuration:** You must configure the gateway to use Datacake's LNS URL. This is a critical step, as the gateway needs to point to Datacake's LNS to relay device data effectively. * **Resetting Gateway (If Necessary):** If your gateway is currently connected to a third-party LNS, you'll need to reset it before configuring it with Datacake's LNS URL. This ensures that the gateway is not simultaneously trying to connect to multiple network servers, which could lead to connectivity issues. ## How to Add LoRaWAN Gateways to Datacake In this comprehensive guide, we'll walk you through the process of adding your LoRaWAN gateways directly to DataCake, enhancing your workspace's capabilities. This tutorial is designed to make the addition of gateways as straightforward as possible, allowing you to efficiently manage your LoRaWAN devices. ### Gateway Tutorials We have provided step-by-step tutorials for common gateways. You can access them by clicking on the link in the following section. * [#tutorials](#tutorials "mention") ### Step 1: Accessing the Gateway Section * **Navigate to the Sidebar:** Within your Datacake workspace, locate the sidebar. Here, you'll find a new section labeled "Gateways" situated beneath the devices section. * **Enter the Gateway List View:** Click on the "Gateways" section. This action will take you to the gateway list view, which operates similarly to the device management section.
### Step 2: Adding a New Gateway * **Initiate Gateway Addition:** In the list view, look for and select the "Add Gateway" option. This will open a modal where you're prompted to provide specific details about your new gateway.
* **Provide Gateway Details:** 1. **Name of Your Gateway:** Enter a descriptive name for your gateway, such as "My First Gateway." 2. **Gateway EUI:** This unique identifier is usually found on a sticker on the back of your gateway or within its configuration interface. Enter the EUI as it is. 3. **Select Frequency:** Choose the appropriate frequency based on your location and the gateway's specifications. Initially, Datacake supports Europe and the United States frequencies, with plans to expand this selection.
### Step 3: Configuring and Understanding Gateway Connectivity * **Gateway Creation:** After selecting your frequency, click on "Create Gateway." Your gateway will be added to the list, and a new modal will appear providing further instructions. * **Connectivity Update:** A brief delay may occur before your gateway's online status updates due to status checks from the LoRaWAN network server occurring every minute. This means real-time status updates are not immediately available.
### Step 4: Gateway Server Configuration * **Copy Configuration Details:** From the modal, you'll receive the necessary configuration details, including the protocol (UDP packet forwarder initially), the gateway server address (e.g., eu1.datacake-lns.com for Europe), and the port number (1700). * **Apply Configuration to Gateway:** Use these details to configure your gateway, ensuring it points to the correct Datacake server address and port, based on the selected frequency. ### Step 5: Viewing and Setting Gateway Location * **Access Gateway Dashboard:** Clicking on "View Gateway" post-configuration will lead you to a dashboard displaying the gateway's status, connection times, uplink/downlink counts, and round-trip time.
* **Configure Location:** To set or adjust your gateway's location, navigate to the configuration tab. Here, you can input the latitude and longitude manually or use the map tool for convenience.
### Conclusion By following these steps, you can successfully add and configure your LoRaWAN gateways within Datacake, streamlining your IoT project setup. This guide ensures that you can efficiently manage your gateways, set their locations, and understand their connectivity status, all from within your Datacake workspace. ## Tutorials ### RAKwireless WisGate Edge Lite 2 {% content-ref url="/pages/fiMgyHgTHzdxdftAnMaq" %} [RAKwireless WisGate Edge Light 2](/datacake-lns/gateways/rakwireless-wisgate-edge-light-2) {% endcontent-ref %} # Milesight LoRaWAN Gateway - UG6x ## Introduction In this tutorial, we'll be guiding you through the process of adding the **Milesight LoRaWAN Gateway UG6x** Series to Datacake's LoRa Network Server (LNS).\ This step-by-step guide is designed to ensure a smooth setup process, allowing you to leverage the full capabilities of your LoRaWAN devices within the Datacake platform. Whether you're setting up a new workspace or looking to expand your current IoT network, this documentation will provide you with all the necessary instructions to successfully integrate your gateway with Datacake LNS.\ In this tutorial we are using [Milesight LoRaWAN Gateway UG65](https://www.milesight.com/iot/product/lorawan-gateway/ug65). ## Getting started ### Requirements 1. Make sure to have an account and a workspace at datacake. 2. Wire everything up. 3. Have every information of the Gateway next to you. ### Add a new gateway To commence the addition of your Milesight LoRaWAN Gateway, click on the "Gateway" section located on the sidebar of your workspace. This action will lead you to the gateways view, which, initially, will not list any gateways. Datacake provides comprehensive documentation for adding gateways, accessible via a designated button.
Additionally, you'll find a blue "Add Gateway" button positioned in the top right corner—click this to proceed. ### Configuring Gateway Information Upon clicking "Add Gateway," a model will appear, prompting you to enter specific details about your gateway.
These details include the Gateway Name, Gateway UI (Unique Identifier), and the operating Frequency. Here's how to approach each requirement: * **Gateway Name:** Assign a name to your gateway, such as "My Milesight Gateway," to easily identify it within your workspace. * **Gateway EUI:** This unique identifier is essential for integrating your gateway with the network. In the following section, we will cover how to retrieve the Gateway EUI from your Milesight device. * **Frequency:** The frequency selection must match your gateway's operational frequency. This is typically determined by your geographic location (e.g., Europe operates on the 868 MHz frequency band). ### Retrieving the Gateway EUI The Gateway EUI is a critical component for the integration process. This unique identifier can be found on your gateway's management platform. To access this, you'll need to switch to the management platform of your Milesight LoRaWAN Gateway UG65. #### Configuration of your Milesight LoRaWAN Gateway UG65 Your LoRaWAN gateway needs to be connected to the internet. You can plug the gateway into your home or company's network or using WiFi instead. You can find the tutorials from Milesight here: *Note: If you are using this gateway at your company's network you might want to talk to your IT department.* When connected to a network you can access the management platform / Web GUI of the gateway. You can find the tutorial from Milesight here: #### Copying the Gateway UI The EUI, typically starting with "24," resembles a MAC address and includes an additional character for identification. To proceed, click on the copy button next to the EUI and return to your Datacake gateway configuration page to paste the identifier.
#### Enter Gateway EUI on Datacake Copy and paste the Gateway EUI into Datacake's modal.
#### Setting the Frequency After inputting the Gateway UI, the final step in the model is to select the appropriate frequency for your gateway. This frequency must align with the operational frequency of your Milesight Gateway, which is indicated on the device's management platform. For instance, if your gateway is located in Germany, you would select the European frequency band (868 MHz).
#### Finalizing Gateway Addition With the gateway name, UI, and frequency correctly entered, you can finalize the addition of your Milesight Gateway to Datacake by clicking on the "Create Gateway" button. This action not only adds your gateway to the platform but also presents you with additional configuration information, such as the protocol, gateway server address, port number, and frequency summary.
Please don't close this modal yet, we do need to copy a few of those settings and information on the next steps. ## Configuring Milesight LoRaWAN Gateway Integrating your Milesight gateway with Datacake LNS requires a series of precise configurations within the gateway's configuration panel. 1. Log into the Mileshight Gateway management platform like you did to get the EUI. 2. Navigate to "Packet Forwarder" and scoll down to "Multi-Destination". 3. Add a new destination by clicking "+".
4. Make sure to enable the new destination, chose type "Semtech" and address to "custom". After you selected "custom" you are allowed to type in an address. Please select your Datacake LNS from the gateway information from Datacake. Make also sure that you have the same ports as in the gateway information from Datacake. Save afterwards.
5. Optional: Disable the default destination by clicking on the edit button (pencil) and removing the tick at "Enable". Save afterwards. ### Verify connectivity Once your gateway reboots, verify that it has successfully connected to Datacake LNS. You can do this by checking the gateway's status on the Datacake platform, ensuring it appears online and is actively communicating data. # RAKwireless WisGate Edge Light 2 ## Introduction In today's tutorial, we'll be guiding you through the process of adding the WisGate Edge Light 2 Gateway Series firmware to Datacake's LoRa Network Server (LNS) option. This step-by-step guide is designed to ensure a smooth setup process, allowing you to leverage the full capabilities of your LoRaWAN devices within the Datacake platform. Whether you're setting up a new workspace or looking to expand your current IoT network, this documentation will provide you with all the necessary instructions to successfully integrate your gateway with Datacake LNS. ### Video This video tutorial demonstrates all the necessary steps to follow if you prefer video guides. {% embed url="" %} ## Getting Started ### Registering on Datacake Before integrating your WisGate EdgeLight 2 Gateway, the first step is to register on Datacake. Navigate to the Datacake website and sign up to create a new workspace. Registration on Datacake is completely free, with no credit card information required. Once you have signed up, you will be directed to your new workspace, where you can begin the process of adding your devices and gateways. ### Add a new Gateway To commence the addition of your WisGate EdgeLight 2 Gateway, click on the "Gateway" section located on the sidebar of your workspace. This action will lead you to the gateways view, which, initially, will not list any gateways. Datacake provides comprehensive documentation for adding gateways, accessible via a designated button.
Additionally, you'll find a blue "Add Gateway" button positioned in the top right corner—click this to proceed. ### Configuring Gateway Information Upon clicking "Add Gateway," a model will appear, prompting you to enter specific details about your gateway.
These details include the Gateway Name, Gateway UI (Unique Identifier), and the operating Frequency. Here's how to approach each requirement: * **Gateway Name:** Assign a name to your gateway, such as "My RAKwireless Gateway," to easily identify it within your workspace. * **Gateway EUI:** This unique identifier is essential for integrating your gateway with the network. In the following section, we will cover how to retrieve the Gateway EUI from your WisGate device. * **Frequency:** The frequency selection must match your gateway's operational frequency. This is typically determined by your geographic location (e.g., Europe operates on the 868 MHz frequency band). ### Retrieving the Gateway EUI The Gateway EUI is a critical component for the integration process. This unique identifier can be found on your WisGate Edge Light 2 Gateway's management platform. To access this, you'll need to switch to the management platform of your Rack Wireless WisGate Edge 2. #### Configuration of your WisGate Edge Lite 2 Your LoRaWAN Gateway needs to be connected to the internet. To do this, you can plug the Gateway into your home wifi router or your company's internal network. When connected, the gateway will automatically request an IP address from the router. To access the web interface for management, you will need to find out the IP address of the gateway. This process is similar to accessing your router.\ \ Alternatively, if you switch on the RAKwireless WisGate Edge Lite 2, it will create a WiFi access point. You can then connect your device to the gateway by connecting to the WiFi hotspot.\ \ For more information on this topic, RAKwireless has some documentation available on the following webpage. {% embed url="" %} #### Accessing the Management Platform Your WisGate device integrates seamlessly with your local network, receiving an IP address via DHCP. By accessing the web interface of your WisGate Edge Lite 2, you can navigate to the overview section via the sidebar. This section displays various metadata about your device, including the serial number, model, and notably, the EUI.
#### Copying the Gateway UI The EUI, typically starting with "AC," resembles a MAC address and includes an additional character for identification. To proceed, click on the copy button next to the EUI and return to your Datacake gateway configuration page to paste the identifier.
#### Enter Gateway EUI on Datacake Copy and paste the Gateway EUI into Datacake's modal.
### Setting the Frequency After inputting the Gateway UI, the final step in the model is to select the appropriate frequency for your gateway. This frequency must align with the operational frequency of your WisGate EdgeLight 2, which is indicated on the device's management platform. For instance, if your gateway is located in Germany, you would select the European frequency band (868 MHz).
### Finalizing Gateway Addition With the gateway name, UI, and frequency correctly entered, you can finalize the addition of your WisGate EdgeLight 2 to Datacake by clicking on the "Create Gateway" button. This action not only adds your gateway to the platform but also presents you with additional configuration information, such as the protocol, gateway server address, port number, and frequency summary.
Please don't close this modal yet, we do need to copy a few of those settings and information on the next steps. ## Configuring WisGate Edge Light 2 Gateway Integrating your WisGate EdgeLight 2 Gateway with Datacake LNS requires a series of precise configurations within the WisGate Configuration Panel. ### Accessing the WisGate Configuration Panel 1. **Log into the WisGate Dashboard:** Begin by accessing the dashboard of your WisGate EdgeLight 2. This is typically done through a web browser, entering the IP address assigned to your gateway. 2. **Navigate to Configuration:** On the dashboard's sidebar, locate and click on the "Configuration" icon. This will open the configuration settings tab, where you can adjust various parameters to establish a connection with Datacake LNS.
### Configuring the Working Mode Within the configuration tab, you'll find options for setting your gateway's working mode. Select "Packet Forwarder," as it's the compatible mode for connecting your gateway to Datacake LNS.
Ensure that the frequency plan matches your geographical region's requirements. If your gateway is set in Germany, for instance, it should already be configured to the EU868 MHz frequency. This step is crucial for ensuring your gateway communicates on the correct frequency band. ### Defining the Protocol In the configuration settings, locate the protocol section. Here, you'll choose between two primary options for network communication: "Semtech UDP Gateway Management Protocol" and "LoRa Gateway MQTT Bridge."
For integration with Datacake LNS, opt for the "Semtech UDP Gateway Management Protocol." This protocol is designed for efficient communication between your gateway and the Datacake LNS platform. ### Setting UDP Protocol Parameters In the section below the protocol definition, you can find additional settings, such as server address or port.
1. **Identify the Server Address:** The UDP protocol parameters require a specific server address for your gateway to connect to Datacake LNS. If you're setting up the gateway for the first time, you might see a placeholder or a different server address that needs to be replaced. 2. **Copy Server Address from Datacake:** Log into your Datacake account and navigate to the section where your gateway's details are listed. Here, you'll find the appropriate server address for Datacake LNS (e.g., `eu1.datacake-lns.com`). Copy this address. 3. **Paste the Server Address:** Return to the WisGate Configuration Panel and paste the copied server address into the corresponding field under UDP protocol parameters.

Server and Port Settings on WisGate Edge Lite 2 LoRaWAN Gateway for Datacake LNS

### Adjusting Server Ports and Additional Settings 1. **Set Server Ports:** Ensure that both the server port up and server port down are set to 1700. This is a common configuration for Datacake LNS integration and facilitates the correct data transmission route between your gateway and the LNS. 2. **Review Additional Settings:** Other settings within the UDP protocol parameters, such as push timeout, keepalive interval, and options for datagram, MTU, auto-restart, and auto-data recovery, should generally be left at their default values unless Datacake specifies otherwise. ### Saving and Applying Changes 1. **Save Changes:** After entering all necessary information and ensuring the settings are correctly configured, look for the "Save Changes" button and click it. This action will reboot your WisGate Edge Light 2 Gateway and apply the new configurations. 2. **Verify Connectivity:** Once your gateway reboots, verify that it has successfully connected to Datacake LNS. You can do this by checking the gateway's status on the Datacake platform, ensuring it appears online and is actively communicating data. # Miromico miro Edge LoRaWAN Gateway ## Introduction In this tutorial, I will be guiding you through the process of integrating the Miromico miro Edge LoRaWAN Gateway into the Datacake LoRaWAN Network Server (LNS).\ This step-by-step guide is designed to ensure a smooth setup process, allowing you to leverage the full capabilities of your LoRaWAN devices within the Datacake platform. Whether you're setting up a new workspace or looking to expand your current IoT network, this documentation will provide you with all the necessary instructions to successfully integrate your gateway with Datacake LNS.\ In this tutorial we are using [Miromico's miro Edge LoRaWAN Gateway](https://docs.miromico.ch/gateways-cards/miro-edge/). ## Getting started ### Requirements 1. Make sure to have an account and a workspace for the Datacake application. 2. Wire up all of your hardware according to manufacturer specifications. 3. Have the Miromico Gateway user manual and datasheet prepared next to you. ### Add a new gateway To commence the addition of your miro Edge Gateway, click on the "Gateway" section located on the sidebar of your workspace. This action will lead you to the gateways view, which, initially, will not list any gateways. Datacake provides comprehensive documentation for adding gateways, accessible via a designated button.
Additionally, you'll find a blue "Add Gateway" button positioned in the top right corner—click this to proceed. ### Configuring Gateway Information Upon clicking "Add Gateway," a model will appear, prompting you to enter specific details about your gateway.
These details include the Gateway Name, Gateway UI (Unique Identifier), and the operating Frequency. Here's how to approach each requirement: * **Gateway Name:** Assign a name to your gateway, such as "My MiroGateway," to easily identify it within your workspace. * **Gateway EUI:** This unique identifier is essential for integrating your gateway with the network. In the following section, we will cover how to retrieve the Gateway EUI from your device. * **Frequency:** The frequency selection must match your gateway's operational frequency. This is typically determined by your geographic location (e.g., Europe operates on the 868 MHz frequency band). ### Retrieving the Gateway EUI The Gateway EUI is a critical component for the integration process. This unique identifier can be found on your gateway's management platform. To access this, you'll need to switch to the management platform of your Miromico miro Edge Gateway. #### Configuration of your Miromico miro Edge LoRaWAN Gateway Your LoRaWAN gateway needs to be connected to the internet. You can plug the gateway into your home or company's network or using WiFi instead. You can find the tutorials from Miromico here: *Note: If you are using this gateway at your company's network you might want to talk to your IT department.* When connected to a network you can access the management platform / Web GUI of the gateway. You can find the tutorial from Miromico here: #### Copying the Gateway UI The EUI, typically starting with "24," resembles a MAC address and includes an additional character for identification. To proceed, click on the copy button next to the EUI and return to your Datacake gateway configuration page to paste the identifier. For the miro Edge gateway, the gateway EUI is the gateway's MAC address + FFFE in the middle. For example, **112233FFFE445566** would be the gateway EUI for MAC address 112233445566. You can find the MAC address on the back of the gateway's housing. #### Enter Gateway EUI on Datacake Copy and paste the Gateway EUI into Datacake's modal.
#### Setting the Frequency After inputting the Gateway UI, the final step in the model is to select the appropriate frequency for your gateway. This frequency must align with the operational frequency of your Miromico Gateway, which is indicated on the device's management platform. For instance, if your gateway is located in Germany, you would select the European frequency band (868 MHz).
#### Finalizing Gateway Addition With the gateway name, UI, and frequency correctly entered, you can finalize the addition of your miro Edge Gateway to Datacake by clicking on the "Create Gateway" button. This action not only adds your gateway to the platform but also presents you with additional configuration information, such as the protocol, gateway server address, port number, and frequency summary.
Please don't close this modal yet, we do need to copy a few of those settings and information on the next steps. ## Configuring miro Edge LoRaWAN Gateway Integrating your **Miromico (miro Edge)** gateway with **Datacake LNS** requires setting specific parameters within the gateway's web configuration panel. #### Step 1: Log Into the Miromico Gateway 1. Power on the **miro Edge** gateway. 2. Connect your PC to the gateway via Ethernet, using the default link-local IP address `169.254.100.100`. 3. Open a browser and go to `http://169.254.100.100`. 4. Log in using your admin credentials.
#### Step 2: Navigate to the LoRaWAN® Configuration Once logged in: 1. Go to the **LoRaWAN** section from the main configuration page. 2. Select the appropriate band: * Choose **SubG (868/915 MHz)** for standard LoRaWAN networks.
#### Step 3: Configure the Packet Forwarder 1. Under **Forwarder Type**, select `Semtech`. 2. Set the **Semtech packet forwarder server address** to the **Datacake LNS address** provided in your Datacake workspace gateway details. 3. Set the **Semtech packet forwarder port** to match what’s shown in your Datacake gateway configuration panel (usually `1700` unless specified otherwise). 4. Click **Save** to apply the settings. #### Optional: Disable Default or Other Forwarders If another forwarder type is already active (e.g., Loriot), disable it by: 1. Setting the **Forwarder Type** explicitly to `Semtech`. 2. Ensuring no other packet forwarders are running concurrently. **Step 4: Verify Connectivity** Once configuration is complete and the gateway is connected to the internet: 1. Go to your **Datacake workspace**. 2. Navigate to the **Gateways** section. 3. Confirm the gateway appears **online** and is actively **sending data**. # Devices Everything you need to know about adding LoRaWAN Devices to Datacakes own LoRaWAN Network Server. ## TL;DR Here's a video in case you don't want to read our documentation: {% embed url="" %} ## How to Add Devices to Datacake LNS Welcome to our instructional series on leveraging the Datacake LNS for your LoRaWAN projects. This guide focuses on the seamless addition of devices to your network using the Datacake platform. Follow these steps to integrate LoRaWAN devices efficiently into your workspace. ### Step 1: Navigating to the Device Section * **Access the Device Section:** Start by navigating to the devices section from the sidebar in your Datacake workspace. This action will direct you to the device list view. * **Initiate Device Addition:** To add a new device, click on the "Add Device" button, located at the top right corner of the page. This will open a modal, similar to the gateway addition process.
### Step 2: Device Configuration * **LoRaWAN Preselection:** By default, LoRaWAN is preselected for device integration. Proceed by clicking "Next" to move forward with the configuration. * **Template Selection:** The next step involves selecting a device from the list of available templates. These templates correspond to various types of devices supported by Datacake. After selecting a suitable template, click "Next."
### Step 3: Network Server Selection * **Choosing a Network Server:** In this crucial step, you're prompted to select a network server. While Datacake supports integration with all third-party network servers, for a streamlined setup, you can choose the Datacake LNS option, which facilitates both uplinks and downlinks efficiently. * **Confirmation:** Confirm your network server selection by clicking "Next."
### Step 4: Entering Device Details * **Detail Entry:** You'll need to enter specific details of your LoRaWAN device, including: * **Dev EUI:** The unique identifier for your device. * **Name:** A descriptive name for the device. * **App EUI and App Key:** Essential for device authentication. * **Frequency:** Select between Europe or United States, depending on your location and device specifications. * **Device Class:** Choose between Class A and Class C. * **Location and Tags:** Optionally, set a location and assign tags for easier management.
### Step 5: Finalizing the Addition * **Application of Details:** After entering all necessary information, including a placeholder Dev EUI and App Key for demonstration, proceed by applying these details. * **Plan Selection:** Despite integrating directly with Datacake LNS, the platform continues to offer support for up to five devices free of charge, making it an accessible option for beginners. * **Device Configuration Review:** Upon adding your device to Datacake, you can review its configuration settings, including its association with the Datacake LNS and pre-configured downlinks. ### Important Considerations * **Modification Restrictions:** Unlike with third-party network servers, modifying certain settings such as Dev EUI and App EUI is not possible directly within the Datacake LNS option. To alter these details, you must remove and re-add the device. ### Conclusion By following these detailed instructions, you can effortlessly add and configure LoRaWAN devices within your Datacake workspace. This process is designed to provide a straightforward and efficient method for integrating devices, ensuring a smooth start with LoRaWAN technology using the Datacake LNS. # Add Devices without Gateway On this page we show you how you can leverage the Datacake LNS feature for LoRaWAN Devices, even if you don't have a Gateway in range. ## About Datacake LNS offers a unique and powerful feature that enables users to integrate LoRaWAN devices into their network without the necessity of owning or managing a physical gateway. This capability stems from Datacake's strategic decision to utilize a commercial instance of The Things Industries (TTI), which leverages the Packet Broker. This integration provides Datacake LNS with access to the extensive network of publicly available LoRaWAN gateways hosted on The Things Network (TTN) around the globe. ### TL;DR {% embed url="" %} ### Why Is This Possible? The backbone of this feature is the utilization of TTN's Packet Broker, allowing Datacake LNS to communicate with an array of public LoRaWAN gateways worldwide. If your devices are within the coverage area of TTN's vast network of gateways, you can directly connect your LoRaWAN devices to Datacake LNS without the need for a personal gateway. This capability is particularly beneficial in densely covered areas, such as major cities like Rotterdam or Amsterdam, where TTN's network infrastructure is robust. ## How to Connect Your LoRaWAN Device to Datacake LNS Without a Gateway 1. **Access the Add Device Modal:** Navigate to the device section of your Datacake workspace and initiate the process to add a new device by clicking on the "Add Device" button. 2. **Device and Template Selection:** * **LoRaWAN Preselection:** The modal will have LoRaWAN preselected as the communication protocol for your device. * **Template Selection:** Choose the appropriate template for your LoRaWAN device from the list of available templates. This ensures that the device is correctly configured with the necessary parameters for communication. 3. **Select Datacake LNS:** When prompted to choose a network server, select the Datacake LNS option. This enables your device to connect via the TTN network, utilizing available public gateways. 4. **Enter Device Details:** Provide the necessary details for your device, including: * **DevUI:** The unique identifier for your LoRaWAN device. * **AppUI and AppKey:** Essential credentials for securing the connection between your device and the network. * **Frequency:** Choose the frequency that corresponds to your device and geographical location. 5. **Leverage TTN Network:** After completing the device setup, your device can communicate through the TTN network without a dedicated gateway. This is made possible by the public LoRaWAN gateways available within TTN's extensive network coverage. ### How to know if coverage is available? To see if there is a nearby TTN Gateway, go take a look at the following webpage: {% embed url="" %} # Overview The Datacake AI Assistant is an intelligent assistant built into the Datacake platform. It helps you manage your IoT devices, analyze sensor data, build dashboards, create automation rules, troubleshoot decoders, and more - all through natural language conversation. > **Important Notice:** The AI Assistant is a fully functional feature that you can use in your daily workflows today. It delivers real results -- from answering questions about your devices to building complete dashboards. However, like all AI-powered tools, its responses are generated by a language model and may not always be accurate or complete. Always review the Assistant's output before acting on it, especially when making changes to your workspace. We are continuously expanding the Assistant's capabilities and improving its accuracy, but the responsibility to verify results remains with you. ## Getting Started ### Opening the Assistant The AI Assistant lives in a slide-out panel on the right side of the Datacake interface. Click the AI Assistant button to open it. You can resize the panel by dragging its left edge. #### Conversations and Threads Every conversation is a **thread**. You can: * **Start a new thread** by clicking the "New chat" button in the panel header. * **Switch between threads** using the thread switcher dropdown. Previous conversations are preserved so you can pick up where you left off. * **Delete threads** you no longer need from the thread switcher. All conversations are stored locally in your browser. They persist across sessions but are not synced between devices. ## Skills System The AI Assistant uses a **skills system** to stay focused and effective. Instead of loading every capability at once, the Assistant activates a specific skill based on what you're asking about. Each skill gives the Assistant a specialized set of tools and domain knowledge. There are seven skills available: | Skill | Description | | ------------------- | --------------------------------------------------------------------- | | **General** | General IoT questions, basic device lookup | | **Devices** | Deep device exploration -- fields, measurements, tags, custom queries | | **Analytics** | Fleet statistics, rankings, historical data analysis, trends | | **Rules** | Create and manage automation rules and notifications | | **Dashboards** | Build and edit workspace and device dashboards | | **Workspace** | Manage folders, tags, products, and claim devices | | **Decoder & Debug** | Troubleshoot payload decoders and inspect debug logs | ### How the Right Skill is Selected You don't need to think about skills in most cases. The Assistant handles skill selection automatically: 1. **Auto-detection on your first message.** When you start a new conversation, the Assistant classifies your message and activates the most relevant skill. For example, asking "What's the average temperature across my fleet?" activates the Analytics skill, while "Create a rule that alerts me when humidity exceeds 80%" activates the Rules skill. 2. **Manual selection.** You can also pick a skill yourself using the skill selector pills in the chat input area. This is useful when you know exactly what you want to do. 3. **Automatic mid-conversation switching.** If you change topics during a conversation, the Assistant can switch skills on the fly. For example, if you start by exploring devices and then ask to build a dashboard, the Assistant switches to the Dashboards skill and continues without interruption. #### How It Works Under the Hood When you send a message, the Assistant translates your natural language input into actions using Datacake's internal APIs. Each skill provides a set of tools that the Assistant can call -- these tools execute GraphQL queries and mutations against the Datacake API to read data, create resources, or modify configurations. The Assistant decides which tools to call, executes them in sequence, interprets the results, and responds in plain language. For complex questions, the Assistant may chain multiple tool calls together in a single turn to gather the information it needs. ### Page-Aware Context The AI Assistant is aware of which page you're currently viewing in Datacake. This means: * **On a device page:** The Assistant already knows the device ID. You can say "Show me the current temperature" without specifying which device. * **On a dashboard page:** The Assistant can load and edit that dashboard directly. Just say "Add a humidity chart" and it knows which dashboard you mean. * **On a rule page:** The Assistant can inspect or modify the rule you're looking at. * **On the devices list:** The Assistant knows you're browsing devices and can help you search, filter, or explore. This page context is shown in a small bar below the panel header so you always know what the Assistant sees. ## What You Can Do ### General IoT Questions The General skill handles broad IoT and Datacake questions. Use it when you need help understanding concepts or getting oriented. **Example prompts:** * "What is MQTT and how does it work with Datacake?" * "How do I set up a LoRaWAN device?" * "What's the difference between HTTP and MQTT integrations?" * "List all my devices" ### Explore Devices The Devices skill lets you dive deep into individual devices -- their configuration, measurement fields, current values, tags, and metadata. **Example prompts:** * "Show me all devices in my workspace" * "What fields does this device have?" * "What's the current battery level of my temperature sensors?" * "Find all devices tagged with 'building-a'" * "Show me the details of device XYZ" The Assistant can also run custom GraphQL queries against the Datacake API when the built-in tools aren't enough for a complex question. ### Analyze Your Fleet The Analytics skill is designed for questions about data across your entire fleet -- averages, rankings, outliers, trends, and historical analysis. **Example prompts:** * "What's the average temperature across all my sensors?" * "Which 5 devices have the lowest battery?" * "How many doors are currently open?" * "How often was CO2 above 1000 ppm last week in the office?" * "Compare humidity levels between Building A and Building B" * "Give me an overview of my workspace" * "What's the temperature trend for this device over the past month?" The Assistant understands natural language for sensor types -- "how warm is it" maps to temperature, "air quality" maps to CO2/VOC, "noise level" maps to loudness, and so on. **Historical analysis** is particularly powerful. The Assistant can compute statistics like averages, min/max, time above or below a threshold, and trend direction -- all without dumping raw data into the conversation. ### Create and Manage Rules The Rules skill lets you create, inspect, update, and delete automation rules through conversation. **Example prompts:** * "Create a rule that sends me an email when temperature exceeds 30 degrees" * "Show me all my active rules" * "What does this rule do?" (when viewing a rule page) * "Update this rule to also trigger on humidity above 80%" * "Delete the offline notification rule" When creating rules, the Assistant will ask whether you want a **product-level rule** (monitors all devices of a type -- more efficient) or a **device-level rule** (targets specific devices only) when it's relevant. ### Build and Edit Dashboards The Dashboards skill lets you build workspace dashboards and device dashboards by describing what you want in plain language. **Example prompts:** * "Build me a dashboard that shows temperature and humidity for all my sensors" * "Add a line chart showing the last 24 hours of power consumption" * "Create a table with all devices, their online status, and current temperature" * "Add a value widget for battery level with a gauge that shows green above 50% and red below 20%" * "Rearrange the widgets so the charts are full-width" * "Remove the old humidity widget" The Assistant builds dashboards iteratively -- adding, configuring, and positioning widgets one by one. All changes are collected in a draft, and you'll be asked to confirm before anything is saved. **Device dashboards** work the same way. When you're on a device page, the Assistant automatically works with that device's dashboard. ### Manage Your Workspace The Workspace skill helps you organize devices with folders and tags, manage products, and claim devices into workspaces. **Example prompts:** * "Create folders based on my device tags" * "What tags are available in this workspace?" * "Show me the current folder structure" * "Reorganize my folders by location" * "List all products in this workspace" * "Claim device ABC into my production workspace" ### Troubleshoot Decoders and Debug Logs The Decoder & Debug skill is your go-to for data ingestion issues. It can read debug logs, inspect decoder code, test decoders with sample payloads, and help you fix parsing errors. **Example prompts:** * "Show me the recent debug log for this device" * "Why isn't my device sending data?" * "Show me the payload decoder for this product" * "Test this decoder with the last received payload" * "Help me write a LoRaWAN decoder that parses temperature and humidity from a 4-byte payload" * "Fix the decoder -- it's parsing the wrong byte order" The Assistant understands the debug log format, can extract raw payloads, and will test any decoder changes before saving them. Since decoders are shared across all devices of the same product, the Assistant will remind you of this before making changes. ### Confirmation for Changes The AI Assistant distinguishes between **read operations** (looking up data, listing devices, checking status) and **write operations** (creating rules, saving dashboards, updating decoders, modifying folders). * **Read operations** execute automatically. The Assistant fetches the data it needs without asking. * **Write operations** always require your confirmation. Before any change is applied, the Assistant describes what it intends to do in plain language and waits for you to approve or deny. You'll see a confirmation prompt in the chat with "Confirm" and "Deny" buttons. This means you can safely ask the Assistant to do things like "create a rule" or "save this dashboard" without worrying about accidental changes -- you always get the final say. ## Advanced Controls ### Reasoning Effort Control how much the Assistant "thinks" before responding. Available in the chat input area: * **Low** -- Quick, concise answers. Best for simple lookups and straightforward questions. * **Medium** -- Balanced reasoning. Good default for most tasks. * **High** -- Deep reasoning. Use for complex analysis, multi-step workflows, or when you need the Assistant to think through a problem carefully. ### Text Verbosity Control how detailed the Assistant's responses are: * **Low** -- Brief, to-the-point responses. * **Medium** -- Standard detail level. * **High** -- Thorough explanations with more context. ### Code Interpreter When enabled, the Assistant can write and execute code to process data, perform calculations, or generate formatted outputs. This is useful for complex data transformations or custom analysis that goes beyond the built-in tools. ### Token Usage The panel displays token usage for the current thread, showing how many tokens have been consumed across all messages. This helps you keep track of resource usage during longer conversations. ## Pricing and Usage Limits ### Free Tier Every Datacake user receives **1,000,000 tokens** to use with the AI Assistant at no cost. This allowance is tracked automatically and applies across all conversations in your account. For most users, this is enough to explore the Assistant's capabilities extensively. You can monitor your token consumption in the usage bar displayed in the chat panel. #### What Happens When the Free Tier Is Exhausted Once your free token allowance is used up, the AI Assistant will no longer be available for new conversations. You will see a notification in the chat panel with a **contact button** to reach the Datacake team. ### Paid Plan To continue using the AI Assistant beyond the free tier, contact us to activate the paid plan: * **20 EUR per user per month** * Includes a virtually unlimited token allowance for regular usage #### Fair Use Policy {% hint style="warning" %} The paid plan is designed to support productive, regular use of the AI Assistant. Datacake reserves the right to limit or suspend access in cases of **excessive** or **abusive** usage that results in disproportionate costs. Such cases are rare under normal use and will be communicated to the affected user before any action is taken. {% endhint %} ## Tips and Best Practices * **Be specific.** "What's the average temperature in Building A this week?" works better than "Tell me about temperatures." * **Let page context work for you.** Navigate to the device, dashboard, or rule you want to work with before asking the Assistant about it. It picks up the context automatically. * **Use threads for different topics.** Start a new thread when switching to an unrelated task. This keeps conversations focused and helps the Assistant maintain context. * **Trust the skill system.** You usually don't need to select a skill manually. The Assistant picks the right one based on your question and switches when needed. * **Review before confirming.** When the Assistant proposes changes (creating rules, saving dashboards, updating decoders), read the summary carefully before confirming. The Assistant describes changes in plain language so you know exactly what will happen. * **Ask follow-up questions.** The Assistant remembers the full conversation. You can say "now do the same for humidity" or "change the threshold to 25" without repeating the full context. ## Known Limitations ### No Undo for Confirmed Actions Once you confirm a write operation (creating a rule, saving a dashboard, updating a decoder, modifying folders), the change is applied immediately. There is no built-in undo functionality. Always review the Assistant's summary carefully before confirming, and make sure you understand what will be changed. ### Large Fleets and Long Time Ranges Querying or analyzing data from a large number of devices simultaneously or over long historical time ranges may lead to: * Slow response times * Incomplete or truncated results * Failed queries due to timeouts For best results: * Limit analysis to a manageable subset of devices rather than the entire fleet at once. * Use shorter time windows (e.g. last 24 hours or last 7 days) instead of months or years. * Break large requests into smaller, more focused queries. The AI Assistant is optimized for targeted analysis and interactive exploration, not large-scale bulk data processing. ### Conversation Memory The Assistant maintains context within a conversation thread, but there are practical limits. Very long conversations may cause the Assistant to lose track of earlier details or exceed the model's context window. If you notice the Assistant forgetting earlier context, start a new thread and restate the key information. ### Dashboard Support The Assistant can build and modify workspace dashboards and device dashboards with a wide range of widget types. However, very complex or highly customized dashboard layouts may require manual fine-tuning after the Assistant has created the initial structure. ## Annex: Data Handling and Privacy ### AI Provider The Datacake AI Assistant is powered by **OpenAI**. All AI requests are routed through a Datacake AI proxy -- your browser never communicates directly with OpenAI's servers. The proxy authenticates requests on your behalf and relays them to the OpenAI API. ### Conversation Storage All conversation threads -- including messages, titles, tags, and usage statistics -- are stored **exclusively in your browser's local database** (IndexedDB). No conversation data is sent to or stored on Datacake servers. This means: * Your conversations are private to the browser and device you are using. * Conversations do **not** sync across devices or browsers. * Clearing your browser data (cache, site data) will permanently delete all conversations. * Datacake has no access to your conversation history. ### Data Sent to OpenAI When you send a message, the conversation context is transmitted to OpenAI through the Datacake proxy for processing. OpenAI may retain transient session data to enable multi-turn conversations within a session. Skill classification requests (used to auto-detect the right skill on your first message) are not retained by OpenAI. Datacake uses OpenAI's API tier, which means data sent through the API is **not used to train OpenAI's models** (per [OpenAI's API data usage policy](https://openai.com/enterprise-privacy/)). ### What Data is Transmitted The following data may be included in requests to the AI provider: * Your messages and the Assistant's responses * Workspace metadata (workspace name, workspace ID) for context * Device data, measurement values, or configuration details when you ask the Assistant to look something up (tool call results) * Navigation context (which page you are currently viewing) **Not transmitted:** Passwords, personal API keys, or authentication tokens are never included in the AI conversation context. ### No Server-Side Conversation Logging Datacake does not log, store, or persist your AI Assistant conversations on its own servers. The proxy relays requests and responses in real time without archiving conversation content. ### Your Responsibility: Sensitive Information While Datacake does not automatically transmit passwords, API keys, or other credentials to the AI provider, **anything you type into the chat is sent to OpenAI for processing**. This includes free-text messages and any information you voluntarily share in the conversation. **Do not enter sensitive, confidential, or personally identifiable information into the AI Assistant chat.** This includes, but is not limited to: * Passwords, secrets, or API keys * Personal data of third parties (names, addresses, contact details) * Financial information (credit card numbers, bank details) * Health or medical data * Trade secrets or proprietary business information not intended for third-party processing You are solely responsible for the content you submit to the AI Assistant. Datacake cannot control, filter, or redact information you choose to share in the chat before it is transmitted to the AI provider. ## Disclaimer of Liability Datacake provides the AI Assistant as a productivity tool on an "as is" basis. By using the AI Assistant, you acknowledge and agree that: 1. **No guarantee of accuracy.** The AI Assistant may produce incorrect, incomplete, or outdated responses. Always verify critical information independently before acting on it, especially for device configuration changes, automation rules, or decoder modifications. 2. **User-submitted content.** Datacake is not liable for any consequences arising from sensitive, confidential, or personal information that you voluntarily submit to the AI Assistant. It is your responsibility to ensure that the information you share complies with applicable data protection regulations and your organization's policies. 3. **Third-party processing.** By using the AI Assistant, you acknowledge that your messages are processed by OpenAI, a third-party provider, subject to their own terms of service and privacy policies. 4. **No liability for AI actions.** While write operations require explicit user confirmation, Datacake is not liable for any damages resulting from changes made to your workspace, devices, dashboards, rules, or decoders based on AI Assistant suggestions that you confirmed. ## Compliance Use of the AI Assistant is subject to the [Datacake Privacy Policy](https://datacake.co/legal/privacy-policy) and applicable data protection laws, including the General Data Protection Regulation (GDPR). * **Datacake infrastructure.** Datacake processes and stores workspace data within its own infrastructure, located in the European Union. * **Data transfer to the United States.** AI-related requests are processed via OpenAI API endpoints located in the United States. When using the AI Assistant, data may be transferred outside the European Union for the purpose of generating AI responses. * **Data Processing Agreement.** A Data Processing Agreement (DPA) with OpenAI is in place. Under this agreement, OpenAI acts as a data processor/sub-processor and is obligated to handle data in accordance with applicable data protection laws (GDPR). * **Data access.** Data may be accessed by Datacake systems (for feature functionality), the Datacake internal team (limited to debugging, support, and improvement), and OpenAI systems (for request processing only). For questions about data handling, compliance, or to request deletion of any transient data, contact Datacake support. # Overview The Datacake Wireless IoT Hub is an easy-to-use LoRaWAN gateway that integrates directly with the Datacake platform. It’s designed to get you up and running with IoT projects in just a few minutes – no setup, no subscriptions, no third-party tools required.
*** ### What's Included * LoRaWAN Gateway (Datacake Wireless IoT Hub) * Power adapter and indoor antenna (type of power adapter is based on IoT Hub version, e.g. EU) * Preinstalled SIM card with prepaid data * Setup instructions + device license code for 50 devices on the Datacake platform *** ### Key Features * Native integration with the Datacake LoRaWAN Network Server (LNS) * Cellular connectivity out of the box – no WiFi or Ethernet required * Plug & Play: no configuration needed * 50 free devices with full access to platform features (7-day data retention) * Works with 300+ supported LoRaWAN devices and templates * Optional data forwarding via Webhooks, MQTT, or HTTP * Ideal for fast deployments, demos, and real-world use cases *** ### Use Cases The Wireless IoT Hub is ideal for a wide range of applications, including: * Smart Building (environmental and occupancy monitoring) * Smart Farming (soil moisture, climate, irrigation) * Smart City (air quality, traffic, noise) * Cold Chain Monitoring (temperature-sensitive logistics) * Industrial Monitoring (predictive maintenance, machine data) *** ### How It Works 1. Order the gateway through your Datacake account 2. Unbox and power it up – SIM card is active 3. Log in or register at [datacake.io](https://datacake.io) 4. Go to **Gateways** in the sidebar, enter the included code 5. Add your LoRaWAN sensors – dashboards and data appear instantly *** ### Buying the Gateway The Datacake Wireless IoT Hub is available for purchase **directly inside the Datacake platform**. We’ve chosen this method to: * Automatically link the gateway to your account * Activate your included device licenses right away * Provide access to your invoices and order history via the Billing Center * Simplify support and onboarding > To buy, simply log in to your Datacake account and navigate to the **Gateways** section. *** ### SIM Card and Connectivity Each gateway includes a preinstalled SIM card with prepaid data.\ This allows the device to connect immediately without local internet access. * No WiFi or Ethernet required (though both are supported) * Data volume typically lasts several months to a year, depending on use * No automatic renewal or hidden charges – you'll be notified when it runs low * Top-ups and subscriptions will be offered later, with full transparency *** ### Support If you have any questions, feel free to: * Use the **contact form** on the platform * Reach out via the **live chat** * Or send us an email – we’re happy to help We’ll also contact you after your purchase with delivery updates and any further instructions. # Datasheet Technical datasheet The **Datacake Wireless IoT Hub** is based on the RAK7268V2/RAK7268CV2 WisGate Edge Lite 2 from RAKwireless and has been optimized for integration into the Datacake IoT platform. It provides a reliable and scalable solution for LoRaWAN® gateways in industrial and commercial applications. ## Description The **Datacake Wireless IoT Hub** is an indoor LoRaWAN® gateway with 8 channels, developed for seamless integration into the Datacake platform. It comes pre-configured with a SIM card that includes data volume, allowing for immediate operation without requiring any infrastructure at the deployment site. Simply place the gateway, connect it to power, and enter the registration number on the Datacake portal. The system will automatically recognize the gateway and register it, making it ready to use right away. This plug-and-play functionality ensures a smooth and hassle-free setup, with no need for additional network configuration, Wi-Fi, or Ethernet connections. It supports multiple communication interfaces, including Ethernet, Wi-Fi, and optional LTE, enabling smooth connectivity of LoRaWAN® sensors to the cloud. ### Use Cases * **Smart Buildings** * **Industrial IoT Applications** * **Asset Tracking** * **Environmental and Climate Monitoring** * **Energy and Resource Management** ## Technical Specifications ### Hardware | Feature | Specification | | ------------------ | ----------------------------------------------------------------------- | | Processor | MT7628 with 128 MB DDR2 RAM | | LoRaWAN® Module | Semtech SX1302 Mini PCIe card, 8 channels | | Wi-Fi | 2.4 GHz (802.11b/g/n), channels 1–13 | | Ethernet | 100M Base-T with Power over Ethernet (PoE) | | LTE (optional) | Nano-SIM, supports Quectel EG95-E/EG95-NA/EC25-J/EC25-AU/EC25-E (Cat 4) | | SD Card | For log backup and LoRa frame buffering in case of backhaul failure | | Antenna Connector | RP-SMA for LoRa, internal antennas for Wi-Fi/LTE | | Enclosure Material | Plastic (PC+ABS), IP30 | | Dimensions | 166 × 127.5 × 36 mm (without antenna and mount) | | Weight | 0.3 kg | | Mounting Options | Desktop, wall, and rail mounting options | ### Software The **Datacake Wireless IoT Hub** runs on WisGateOS 2, an OpenWRT-based platform with the following features: * **Pre-integrated with Datacake Platform**: The device comes with a SIM card and is pre-configured for immediate use with the Datacake platform. Simply connect the gateway, enter the registration number on the Datacake portal, and the gateway will be automatically recognized and set up. * **Wi-Fi Client/AP Mode** * **DHCP Server/Client, NAT, Firewall** * **Web-based User Interface (Web UI)** ### Environmental Conditions * **Operating Temperature:** –10°C to +55°C * **Storage Temperature:** –40°C to +85°C * **Operating Humidity:** 0–95% RH, non-condensing * **Storage Humidity:** 0–95% RH, non-condensing ### Certifications The **Datacake Wireless IoT Hub** complies with the following standards: * **LoRaWAN® 1.0.3** * **CE** * **RoHS** * **WEEE** ### Packaging Contents * 1x Datacake Wireless IoT Hub * 1x LoRa Antenna * 1x Power Adapter (12 VDC, 1 A) * 1x Mounting Kit (screws, dowels, bracket) * 1x Quick Start Guide # Getting Started Getting Started with the Datacake Wireless IoT Hub This guide will help you set up and activate your Datacake Wireless IoT Hub, link it to your workspace, and start connecting your LoRaWAN devices. ## 1. What you need To get started, you’ll need: * A Datacake account * A valid workspace (created during registration) * Your Datacake Wireless IoT Hub * The gateway ID (printed on the device and included in the package) ## 2. Create or log in to your Datacake account If you don’t have a Datacake account yet, go to and sign up – it’s free. Once registered, log in to access your **workspace.** *** ## 3. Navigate to the Gateway section
Inside your workspace: * Look at the left-hand **sidebar menu** * Click on **"Gateways"** This section is part of the integrated **Datacake LoRaWAN Network Server (LNS)** and allows you to add and manage gateways. For more information on the Datacake LNS, see: [Datacake LNS](/datacake-lns/getting-started) - For the next steps, it is not required to read about the LNS now. > You can add multiple gateways to a single workspace, but each gateway can only belong to one workspace at a time. *** ## 4. Register your Datacake Wireless IoT Hub
#### How to add your gateway: * Click **"Add Gateway"** * Enter the **Gateway ID**, which you’ll find: * On the back of your device * On the label included in the box Datacake will automatically detect that this is a **Datacake Wireless IoT Hub** and add it to your workspace. {% hint style="danger" %} **⚠️ Important:** **Make sure to register the gateway first, before connecting it to power.** This ensures that the device will appear as **online** once it starts sending data. {% endhint %} *** ## 5. Power on the gateway After successful registration: * Connect the device to power using the included adapter * Wait a few minutes The gateway will automatically connect to the Datacake platform using the built-in SIM card.
{% hint style="success" %} #### ⏱ When to expect data: * Initial status should appear within **10 minutes** * In some cases, allow up to **20 minutes** for first telemetry * The device will be marked **online** once data is received {% endhint %} *** ## 6. Add your LoRaWAN devices Once your gateway is online, you can begin adding end devices: * Navigate to **"Devices"** in the sidebar * Click **"Add Device"** * Use one of Datacake’s **300+ templates** to simplify setup Any standard LoRaWAN device is supported – for best results, use one that matches an existing template. *** ## 7. You’re ready to go Your gateway is now connected, and your workspace is live.\ From here, you can create dashboards, set alerts, forward data, and explore all the features of the Datacake platform. > Need help? Reach out via the in-platform **Live Chat** or see the full documentation at [docs.datacake.de](https://docs.datacake.de) # Product ## What is a Product? A product defines the fields in the database, the dashboard, the payload decoders, encoders for downlinks and product-specific settings, such as LoRaWAN network provider or other information concerning integrations. Each device created on Datacake belongs to a Product. Thus, the device inherits the number of fields, the specific downlinks, decoders and other settings during adding or creation. TL;DR. A product defines: * Database Fields * Dashboard * Payload Decoder * Downlinks A device inherits and overrides these settings and/or overwrites (or stores data into the database fields). ### Structure According to the above description, the Product-Device structure in Datacake is as follows: ![](/files/-MUgdsAGaUVyrAEoJ_gt) ### What are the benefits of using Products? With a product you define properties that you can apply to all devices that belong to that product. You can consider products as a kind of template that defines the functions, properties and other things. Thus, a product makes it easier to work with devices in large numbers. ## Creating a Product ![](/files/-MUgiU9-qFMngSBWE5JV) ### New Product from Template For many devices of the different integrations (Particle, LoRaWAN) Datacake offers prefabricated product templates. You can see if and which templates are available by selecting this option in the Add-Device modal. You should then see something like the following view: ![](/files/-MUgiGH4a6u0hKSn5vJY) ### Existing Product ![](/files/-MUgj55VaQ5LzKC3WcQa) ### New Product ![](/files/-MUgikwc4PY8VoYQNEdc) # Product Cloning Managing thousands of IoT devices efficiently requires standardised setups. In Datacake, this is achieved through **Products**, which define shared elements like dashboards, payload decoders, and downlinks. Previously, products created in one workspace were not available in others. With the **Product Cloning** feature, you can now duplicate products across workspaces, making it easier to manage large-scale deployments while retaining flexibility. ### The Challenge Before Cloning * Products were **workspace-bound**: each workspace had to create its own product from scratch or from the template catalog. * Products in the main workspace were not available in sub-workspaces. * This meant duplicating setup work whenever you added new workspaces. Product Cloning solves this limitation. It allows you to **copy an existing product** from one workspace into another. #### Key Benefits * Save time by reusing product definitions across multiple workspaces. * Maintain consistency in dashboards, payload decoders, and downlinks. * Retain flexibility: cloned products are independent of the original. If you prefer, you can watch our YouTube video: {% embed url="" %} ## How to Clone a Product ### 1. Create Your First Product Of course to clone a Product, there needs to be a Product first. The first time you create a product, it must be linked to a device, so: * Click on "**+Add Device"** * For LoRaWAN or API devices choose: * **New product from template** → Create a product based on one of Datacake’s templates (with dashboard, fields, decoders, etc.). * **New product** → Create an empty product from scratch. {% hint style="warning" %} The Cloning Product feature only works for LoRaWAN and API devices! {% endhint %} ### 2. You can add more devices later... When you want to add additional devices of the same kind: * Next time you +Add Devices, select "**Existing product"**. * This way, all devices stay linked through the **Product definition** and share: * Dashboards * Payload decoders * Downlinks * Fields ### 3. Now, Clone an Existing Product To clone a product into another workspace: 1. Go to one of the devices belonging to the product in the original workspace. 2. Open **Configuration/Product & Hardware**. 3. Scroll down to **Advanced Actions**. 4. Click **Clone Product**.
### 4. Configure the Clone When cloning, you can change the **product's name**. This will appear in the new workspace and can only be configured once, so be mindful! Then, select the **target workspace** (only workspaces where you have device permissions will be shown). Choose whether to copy **Integration settings** (LNS, MQTT, HTTP). {% hint style="warning" %} For devices using the **Datacake LNS**, the LNS configuration is always cloned automatically. {% endhint %} ### 5. Add Devices to the Cloned Product At first, the cloned product will not contain any devices. Don’t worry! * Go to **+Add Device** in the target workspace. * Select **LoRaWAN** or **API device**. * Choose **Existing product** → The cloned product will appear here. * Add your device keys and add devices to your cloned product. ## Remove a Product To remove a product from a workspace: * Delete all devices belonging to that product. * Once no devices are left, the product will be removed automatically as well. {% hint style="warning" %} Cloned products are **independent from the original products**: changes you make to dashboards, decoders, or downlinks in the cloned product will not affect the original. So the products are still workspace dependent! {% endhint %} That’s it! You can now quickly replicate your setups across multiple workspaces with **Product Cloning**. ## Example Use Case Imagine you manage multiple customer deployments across different workspaces. Instead of rebuilding products for each customer, you can: 1. Define a product once (including dashboard, decoder, downlinks). 2. Clone it into customer-specific workspaces. 3. Adjust cloned products locally, while keeping the base setup consistent. # Configuration Inside of your devices you will find several options (Dashboard, History, Downlinks, Configuration, Debug, Rules and Permissions). Following we will describe the Configuration section. ## ⚙️ General No matter what type of device, each device created can be configured under its general configuration tab. When navigating through the configuration of a device, the first item displayed is the summary of its general settings.
### Basic Details Inside of this section you will find the **basic details** of your device, like its name and the device location description. You can always go back and modify those. Please remember click "Save" at the end of the page. ### Visual Appearance You will also find some **visual appearance** configuration. You can assign an Icon, which will be shown inside of the Map widget, if there is no Marker selected ("None").
You can also upload an image, which will be shown next to the name of the device, at the top of the screen.
### Organization & Tags Here you can assign your own tags to your devices. These help you sort your devices better, as well as to configure map widgets and reports. To setup a tag, just type in the name of the tag on the "Add Tag" field. Click Enter and don't forget to Save the changes at the end! ### Metadata You can use metadata to add your own information to your devices, which does not necessarily have to be stored in a field of the database. You can also use metadata in some widgets on the dashboard, e.g. to create an overview of measured values in a table and colorise this table based on metadata. You first assign a Key name. Click "+Add" to add the metadata field. Now you can enter a value. Again, don't forget saving the changes at the end!
### Device Management In there you will find an Offline Notifications checkbox. When you click on that, you (and only you) will receive email notifications if the device goes offline. The [online timeout ](#online-timeout)defines when devices go offline (if they haven't sent an X amount of time). Email gets sent to the email address you are logged in with.
{% hint style="warning" %} This option enables sending offline-alerts for the currently logged in user (you). If you want other users to receive notifications as well - you must instruct them to enable this on their side / account as well. {% endhint %} You will also find Device Claiming, which allows you to enable the [Pincode Claiming](/device/claiming) functionality. You can also allow multiple claims, if that is what you want. Add a claim code and click on save. Now you can add your device to other workspaces using the Serial Number and the Claim Code.
## 🛠️ Product & Hardware ### Product Configuration You can now establish Product-wide configurations. Remember that [Products](/device/product) may contain several devices, so be mindful. ### **Icon** You can select an Icon for all devices of a specific product (that will save you time, in case you want to have the same icon for all devices). ### **Product Slug** This gets created the first time your product gets created. It cannot be changed! ### Online Timeout If no further measured values or other messages are transmitted from a device within the time specified here, the device is displayed as offline in the listing and in other places. ### LoRaWAN/API Configuration The next section depends on the type of device you have added to the platform. Please visit our documentation about how to create a connection to your Network Server for LoRaWAN devices [here](/lorawan/lns/thethingsindustries#downlinks). If you want to know more about the Serial Number for API devices, you will find it [here](/integrations/webhook#serial-number). ## Payload Decoder ### LoRaWAN devices
### API devices You will find a detailed guide on how to decode your device's payloads in the next article: {% content-ref url="/pages/-MWufF71wGFESRfgqPq9" %} [Incoming Webhooks](/integrations/webhook) {% endcontent-ref %}
You will be able to see the incoming messages on the right side button "Show logs". ## MQTT Configuration On API devices after Payload decoders you will see the MQTT configuration section. To learn more about it visit: {% content-ref url="/pages/-Lr9IHgyvE3aH6PH25fb" %} [MQTT Documentation](/api/internal-mqtt/mqtt) {% endcontent-ref %} ## 🗓️ Fields The fields are the measured values of your devices, which get stored in our time-series database. Depending on your subscription plan, a certain number of fields can be created per device. This are also the so-called "datapoints". To learn more about fields visit: {% content-ref url="/pages/-M-KFIeJjB8DdhrPGL7A" %} [Fields](/device/database/fields) {% endcontent-ref %} To learn more about datapoints and data retention times in our time-series database visit: {% content-ref url="/pages/werWJSv0okeQWYKnzoWh" %} [Data retention & Datapoints](/device/database/data-retention-and-datapoints) {% endcontent-ref %} ## Suggested Fields If your devices are receiving data, which gets processed by the payload decoder, but there are still no fields defined in the database, they will appear under Suggested Fields. You can add them to the platform by pressing "Create field", or you can remove them. ## Configuration Fields Configuration Fields allow you to create static variables that exist as a product-wide default and can be overwritten per device. To read more about how to use them visit the next link: {% content-ref url="/pages/XInZBIzeOW8ookNLfoiR" %} [Configuration Fields](/device/database/configuration-fields) {% endcontent-ref %} ## ⛓Integrations You will find all about our [internal MQTT broker](/api/internal-mqtt/mqtt) under Integrations.
## ⚠️ Danger Zone Lastly, you will find the Danger Zone. Be careful with those configurations, since they are critical. You can change the plan or subscription in which your devices are, as as see how many datapoints they have consumed in the past 24 hours. You can purge selected field's data in a specific time range. To completely delete your device from the platform, select Delete Device. But be mindful, as this is irreversible!
# Claiming ## What is Claiming? You can share your Datacake devices with others using a pin code and serial number without having to invite those persons.These persons only need to register for use on the Datacake Cloud. If you give the pin code and serial number to these persons, they can "claim" the device by entering both into their workspace. {% hint style="warning" %} Pincode claiming is only available for paid devices! {% endhint %} ### What is this for? With the help of pin code and serial numbers, devices can be delivered anonymously. The end user can insert the devices you have purchased into his workspace by entering the pin code and serial number. You do not need to know in advance who the person actually is. This is ideal for: * Selling or renting products without knowing who the end user will be. * Providing the functions of a device. * Sharing devices. * Involving dealers. Claiming gives another workspace access to a device that stays yours. If the device should stop being yours altogether, move it instead. {% content-ref url="/pages/PGGViWfIhOLcpRltmYPM" %} [Moving Devices](/device/moving-devices) {% endcontent-ref %} ## Set Pincode Open the configuration of your device that you want to share via the claiming. Inside of the General section, under "Device Claiming", select "Device can be claimed into other workspace".
{% hint style="success" %} As long as the pincode is not set, the device cannot be claimed by another user, even if he knows the serial number. {% endhint %} ### Claim Code In this text field you can enter any pin code. It can consist of numbers, letters or both. ## Claim a Device To understand how claiming works, we will also show you how to insert a device into a workspace using the combination of pin code and serial number. First of all navigate to your fleet view (Fleet / All Devices) via the sidebar (marked red in the following screenshot).
Now add a new device. To do so, please click on the button "Add Device". Now the following modal will appear:
Select "Pincode claiming" from the collection of available device types. You can also recognise this by the QR Code symbol. Please enter the serial number and the pin code in the corresponding text fields. To add the device, confirm your entry with either "Add Device" or "Add Device and configure" (the latter will take you directly to the configuration of the device). If the pin code and serial number have been entered correctly, the claiming was successful. The device is now available in your workspace. ## Managing Claims As the owner of a device you can see which workspaces have claimed it, and take those claims back. Open the configuration of the device. In the General section, under "Device Claiming", you will find a list called "Claimed by". Each entry shows the workspace that claimed the device and the organization that workspace belongs to. {% hint style="info" %} The list is only shown in the workspace that owns the device. If you are looking at a device that you claimed from somebody else, you will see a short note pointing you to the owning workspace instead. {% endhint %} {% hint style="warning" %} A claim gives a workspace access to the device, so make sure at all times that you make the claim code and serial number available only to selected persons. {% endhint %} ### Revoking a Claim Select "Revoke" next to a workspace and confirm. The workspace loses access to the device immediately. {% hint style="warning" %} The workspace you revoke is not notified. The device simply disappears from it. {% endhint %} ### Making the Device Claimable Again Revoking a claim does not make the device claimable again on its own. As described under [Auto-Deactivation](#auto-deactivation), claiming switches itself off once a device has been claimed, and stays off until you switch it back on. To hand the device to somebody else, select "Device can be claimed into other workspace" again and save. The configuration tells you when a device has a claim code but is not open for claiming, so you can see when this step is still needed. {% hint style="warning" %} The workspace you revoked probably still knows the claim code. If you make the device claimable again without changing the claim code, that workspace can simply claim the device back. Change the claim code first. {% endhint %} ## Security ### Auto-Deactivation Once a device has been claimed by a user into another workspace using the claiming function, that function is automatically deactivated. {% hint style="info" %} If the device is then to be claimed again, the function must be reactivated as described above. {% endhint %} ### Pin code override The pin code option is also available to your end customers. This means that the person who added one of your devices to his workspace via claiming can also reactivate the claiming and assign a different pin code. {% hint style="info" %} This pin code is bound to the device itself. This means that you can also see the changed pin code of the end user. {% endhint %} ### Selling Products If you use the claiming in your sales activities and you sell the products anonymously, you usually do not know who the end customer will be. If you still want to provide proactive support, then have your customers invite you to their workspace. In this way, your customers will have explicitly agreed to the access and are on the safe side as far as data protection is concerned. # Moving Devices How to hand devices over to another workspace, and how to review a move request that somebody sent to you. Moving hands devices over to another workspace for good. The devices leave your workspace and become the receiving workspace's devices, including the billing for them. Nothing happens right away. A move is a request first, and the devices stay exactly where they are until an administrator in the target workspace accepts it. {% hint style="warning" %} Moving is permanent. Once a move has been accepted, only the receiving workspace can move the devices back — you cannot undo it from your side. {% endhint %} ## Moving or Claiming? Use claiming if you want another workspace to have access to devices that stay yours. Use moving if the devices should stop being yours altogether. {% content-ref url="/pages/-M-JQQctuXfCo26MgDFn" %} [Claiming](/device/claiming) {% endcontent-ref %} ## Sending a Move Request 1. Navigate to your fleet view (Fleet / All Devices) and select the devices you want to move. 2. In the action bar that appears, select "Advanced" and then "Move to workspace". 3. Choose the target workspace. 4. Optionally tick "Copy integration settings" and add a message for the receiving workspace. 5. Confirm with "Send move request". You need the device permission in your workspace to send a request. ### Choosing the Target Workspace Search the field by name to find the workspaces you are a member of. To move devices to a workspace you are not a member of — a customer's workspace, for example — paste its workspace ID into the same field and select the "Use workspace ID" entry that appears. Ask an administrator of that workspace for the ID. ### What Is Not Moved Rules, webhooks and reports stay with your workspace. They are not moved and not copied, so recreate them in the target workspace if they are still needed there. Integration settings, such as network server or MQTT credentials and secrets, are only handed over if you tick "Copy integration settings" before sending the request. {% hint style="warning" %} **If you use the MQTT broker, your topics change.** The devices join a copy of their product in the target workspace, and that copy gets its own product slug — the part of the MQTT topic that identifies the product. Data still sent to the old topics no longer arrives, and anything subscribed to them stops receiving. Point both at the new topics after the move. {% endhint %} ## Reviewing an Incoming Request When another workspace wants to move devices to you, a banner appears above your device list. You can also open the list directly under Administration, in "Device move requests". On the "Incoming" tab, select "Review" to see who sent the request, which devices it covers and any message that came with it. Choose the plan the incoming devices should get in your workspace, then accept or reject. {% hint style="warning" %} Accepting a request means your workspace takes on the billing for those devices from that moment on. The accept button states how many devices that is. {% endhint %} Rejecting leaves the devices in the sending workspace. ## Tracking Requests You Sent The "Outgoing" tab lists the requests your workspace has sent. While a request is still pending you can withdraw it with "Cancel". By default only pending requests are shown. Select "Show all" to include the ones that have already been resolved — accepted, rejected, expired or failed. # Historical Data Use the graphical database viewer to visualize your measured values. Datacake has a database viewer that allows you to view and compare sensor data from your sensor. We also call this viewer the history of a device. ## Quick Start To open the history view, navigate to the history tab using the tab bar on the device view. ![](/files/Ti2kGaPEWeNc5K0tyibQ) You will see the following view. ![](/files/UUv0PGUu6Ynb1cBmw6Zt) When the history view is opened for the first time, no fields are selected yet to be visualized. To be able to select fields, please scroll further down. There you will find a list with all fields of the database. Now select the respective fields that you want to display on the history and simply click on the checkbox next to the respective field. ![](/files/QHFTkfTkjcE3Jy8Snkdr) If you now scroll up again, you will see that the visualization in the form of a chart for the respective fields is now displayed. ## Reference ### Time Range Using a drop-down, predefined time ranges can be selected for the display of the data. ![](/files/LzF1xXvq8Odu6QUhC2dw) Alternatively, individual time ranges can be defined. To do this, simply click on the text box that displays the current time range. A window opens for the graphical selection of a time range. ![](/files/W5GQGXVLLRT3YBoUR9BO) #### Skipping Time-Ranges You can use both the previous and next buttons next to the time range input field in order to jump to the next or previous time range. This works great if you for example have selected a time range preset like day, week or month and if you want to jump between days, weeks or month. If you have selected a custom time range these buttons will skip to the amount of time (and date) defined in the time range selector. ![](/files/pqNazGbGKUgi0qj5wj1B) ### Resolution The resolution defines the time intervals with which the data is queried by the API over the specified time range. ![](/files/U8oA7glSGNxJMvfzN5yZ) The settings are defined as follows. #### Auto-Resolution This works in a way that the Chart requests at least as much datapoints from the backend as pixels are available on the screen. #### Manual Resolution You can override the automatic resolution setting by specifying your own resolution. However, there is a maximum number of data points that can be retrieved from the backend to protect our API limits. #### Background So, if you selected the period of one year as an example, and set a resolution of 1 minute, the number of data points would lead to several million per selected field. Even if our servers were able to provide this number of data points, it does not make sense to request such a large amount, as the graphical representation will not have enough pixels on the screen to display it properly. So data points would be thrown away anyway. #### Interpolation If you select a resolution that is lower than the transmission frequency of your sensors, then all data points that lie within the resolution are combined and an average is formed. As an example think of a sensor that sends every `5 Minutes` and a Resolution set to `1 hour`, this makes: * 12 Messages per Hour * Average our 12 Messages = 1 Value for Resolution of `1 hour`. #### Effects of Resolution In the following screenshots, you can see the effects of the resolution. The first screenshot shows you a setting for Auto-Resolution. There are more pixels on the screen available than data points for the selected fields so the backend fills all pixels with repetition of data points. * The time range is set to `one week` and the Sensor sends about every one to two hours generally with shorter intervals on steeper value changes. * You can clearly see the quantization effects. * No averaging is applied here as there is more space than data points. ![Resolution Auto = More pixels than data points available](/files/hyyaKnGsJSYbuIqKmNvN) Now in the following screenshot, you see the same time range as above but with a resolution set to a manual value of 1 hour. ![Resolution 1 Hour = More Smoothing](/files/tSunYX5Pb6M9B83G0v0e) As most of the time, the sensor sends every one or two hours, there is still no averaging applied (no interpolation) but you can see that the quantization does look different. There are now less datapoints than pixels still but there is no fill happening. ### Gap Filling The filling of gaps works in conjunction with the resolution. To explain how it works we select the following settings: * Time range `1 week` * Resolution set to `30 Minutes` #### Gap Filling enabled As long as the filling of gaps is enabled you see a full line chart. ![](/files/J1y5Z8MlvnW7UBX3JZQP) #### Gap Filling disabled Now, if we deactivate the gap-filling option (which is enabled by default) we can see a change happening. ![](/files/82OhD8zVUBfdJw8NRqcW) You can see that the chart is no longer fully displayed and only a few areas show a chart. What does this mean? Remember that we have set the resolution to 30 minutes. If you uncheck the "Fill Gaps" option, all areas where there are data points with a time span greater than 30 minutes will be hidden. This means that the chart above shows only the area where there are data points whose time span is less than or equal to 30 minutes. ### Field Statistics Above the table for selecting the fields to be displayed on the history, there are additional column headers, which show you statistics for the respective fields. ![](/files/9AKuaZBouI6MzjNnPqCT) The following statistical information is available for each field. * Current Value * Average * Minimum * Maximum #### Time Range for Statistics The time range for each statistic (average, maximum, minimum) is defined by the time range of the history. #### Time for Maximum, Minimum If you hover over a Maximum or Minimum Value you can see the time this event has occurred. ![](/files/wjPuyhO5PE8rzgJY3idP) ### No-Data If you see a "No Data" tag or "null" sign on the list of fields this means that the field has not yet received any data or the decoder has not yet stored any information on that field. ![](/files/ViDLB7sidFcyxUqfSc1I) ### Exporting Data The "Download as CSV" feature in our portal allows users to easily export their data as CSV files. This documentation guide will walk you through the process of utilizing this feature, ensuring you can extract the data you need in a format that is compatible with external applications and analysis tools. #### Step 1 - Accessing the History View To begin, navigate to the History View in the portal. This view displays your data in a chart format, providing an overview of the selected timeframe, resolution, and fields.
#### Step 3 - Select Fields to Export Make sure you select the fields you want to export. The data that is considered for being exported matches the configuration of your history view.
#### Step 3 - Locating the Download Button Within the History View, you will find a distinct button placed adjacent to the text. This button is specifically designed for downloading your data as a CSV file.
#### Generating the CSV File Click the designated "Download" button to initiate the process of generating the CSV file. The system will automatically extract the data corresponding to the selected timeframe, resolution, and fields from the History View. #### Work with Data Once the CSV file is generated, it will be downloaded to your device. Depending on your browser settings, you may find the file in your default download folder or a location of your choice. It will be saved with a .csv extension, making it compatible with various spreadsheet applications. The downloaded CSV file contains the same data displayed in the History View chart. You can use this file for further analysis, import it into external applications, or integrate it with other systems. The structure and organization of the CSV file will mirror the selected timeframe, resolution, and fields from the History View. {% hint style="info" %} Note: It is essential to review the documentation specific to the external applications or tools you intend to use for further analysis. This will ensure a smooth import and interpretation of the downloaded CSV file. {% endhint %} Conclusion: The "Download as CSV" feature empowers users to effortlessly export their data from the portal. By following the steps outlined in this guide, you can extract the data you need and leverage it for various analytical and usage purposes. If you encounter any issues or have further questions, please reach out to our support team, who will be glad to assist you. Happy analyzing! # Database # Configuration Fields Configuration Fields allow you to create static variables that have a product-wide default and can be overwritten per device. ## Abstract Configuration Fields can be used for example if you have a large fleet of the same devices, where individual devices need to be configured with an individual value, for example a threshold. ## Create a Configuration Field Configuration Fields can be found in the Device's configuration at the bottom of the "Fields" panel. Create a new field by clicking the "Add Configuration Field" button on the top right. ![](/files/UizHX013cXBtB1fD5Dtw) This will open a modal where you can define the properties of the field: ![](/files/kbC6PdHOBId3l1plfAtK) ### Type You can choose between Number (which can store Integers as well as Floats), String and Boolean. {% hint style="warning" %} Once a field has been created, you can not change the type of the field. {% endhint %} ### Name This is the display name of the field, which has no strict requirements about the used characters. ### Identifier The identifier can only contain letters, numbers and underscores. It is unique per product and by default pre-populated from the entered name. {% hint style="info" %} Once a field has been created, you can not change the identifier of the field. {% endhint %} ### Description An optional description, can be used to explain the effect of the value to the user. ### Unit An optional unit, can be used to make the expected value more clear. ### Default Value This is the value of every device that has no explicit overwrite. ## Using Configuration Fields ![Overview of existing configuration fields](/files/BR6UX1uUPJi5YE1lb196) In the above example, I have created a field with the identifier `TEST_FIELD` and a default value of `2`. The `(x)` icon next to the value indicates that this is the default value, and the device has not set an explicit overwrite. ### Changing the value for a single device To set a value for a device different from the default, use the context-menu on the right and choose "Set Value". This will open a modal where you can set a value and also reset the value to the Product's default value. ![](/files/YSFY57O691h5Vo3vJ8ip) ### Using Configuration Fields in en- and decoders Configuration Values are available both in decoders as well as encoders (to configure downlinks) via the global `configurationValues` variable. It's an object with the field identifier as key and the value as value. An example decoder using the previously created variable could look like this: {% code lineNumbers="true" %} ```javascript function Decoder(bytes, port) { var configuredValue = configurationValues.TEST_FIELD; // configured value can now be used to modify the payload which we are not doing in this simple example return [ { field: "MY_FIELD", value: configuredValue, } ] } ``` {% endcode %} ### Configuration Fields in Downlink Encoders Configuration Fields can be used on Downlinks for a variety of things. See the following example on how to access those fields in your Downlink Decoder. {% hint style="success" %} The following example is valid for all Datacake device types. {% endhint %} #### Code ```javascript function Encoder(device, measurements) { // Read configuration field value var downlinkSerial = configurationValues["DOWNLINK_SERIAL"] if (downlinkSerial === "0") { console.log("Serial is not set for downlinks!") return; } var status = measurements.CONTROL_FIELD.value; var payload = { "serial": downlinkSerial, "command": 3, "value": status ? 1:0 } return {topic: 'device/down', payload: JSON.stringify(payload)}; } ``` #### Notes In the example above, there is no need to access configuration fields using a Datacake UUID (as shown in the examples below for decoders). This is because, on Downlinks, the encoder is initiated on the Datacake frontend or rule engine. Hence, we already know the device on which the downlink needs to run. Therefore, no device addressing is needed, and the configuration value is fetched from the scope automatically. ### Configuration Fields on MQTT Decoders Datacake provides a flexible way to handle incoming data from devices using MQTT or HTTP integrations. By using payload decoders, Datacake allows you to adapt to any incoming payload format without needing to modify the third-party payload. This is particularly useful for customers using their own serial numbers to identify devices. Configuration fields in Datacake can hold static values and be customized per device level. These fields are accessed within payload decoders using the Datacake UUID, which allows the retrieval of specific configuration settings and measurements. The following guide will walk you through the process of using configuration fields in combination with MQTT payload decoders. #### **Step-by-Step Guide** **Setup Configuration Fields in Datacake** * Navigate to the device's settings in Datacake. * Add a configuration field (e.g., `Temperature Offset`) with a unique identifier (`TEMPERATURE_OFFSET`). Set a default value, which can be overridden at the device level if necessary. Example from the screenshots.
* Name: `Temperature Offset` * Identifier: `TEMPERATURE_OFFSET` * Type: Number * Default Value: 2 #### **Define MQTT Topics and Payloads** Your device will send data to a specific topic. For example, `devices/mycustomserial01/data`, where `mycustomserial01` is the custom serial number of the device. Example Payload: ```json {"temp": 23.45} ``` #### **Create an MQTT Payload Decoder in Datacake** In the payload decoder, write a function to handle the incoming MQTT data. This function will parse the payload, retrieve configuration values, and compute the desired output. Example Decoder Function: ```javascript function Decoder(topic, payload) { // Convert MQTT payload to JSON var data = JSON.parse(payload); // Extract custom serial number from topic var serialNumber = topic.split("/")[1]; // Get UUID for custom serial number var datacakeUUID = deviceSerialToId[serialNumber]; // Access configuration value from device using UUID var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"]; // Optional: Access the current stored measurement value var oldTemp = measurements[datacakeUUID]["TEMPERATURE"].value; // Read new temperature from JSON and add configuration value offset var newTemp = data.temp + tempOffset; // Store the new value only if it has changed if (oldTemp != newTemp) { return [ { device: serialNumber, // Use custom Serial Number or Device UUID field: "TEMPERATURE", value: newTemp } ]; } } ``` #### **Explanation of the Decoder Function** * **Parsing the Payload:** The payload sent from the device is converted to a JSON object using `JSON.parse(payload)`. * **Extracting Serial Number:** The serial number is extracted from the MQTT topic, which helps map the custom serial number to the Datacake UUID using a predefined mapping (`deviceSerialToId`). * **Accessing Configuration Values:** The Datacake UUID is used to access the configuration values specific to that device. In this case, the `TEMPERATURE_OFFSET` is retrieved and used to adjust the incoming temperature reading. * **Handling Measurements:** The current temperature stored in the Datacake platform is accessed to compare with the new temperature reading. This comparison ensures that only changed values are updated, minimizing unnecessary storage and processing. * **Returning the Updated Value:** If the temperature has changed, the function returns the updated temperature value, which Datacake will store. #### Summary Accessing configuration fields is summarized within the following code concept: ```javascript // Access configuration value from device using UUID var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"]; ``` Suppose you are working with your own serial numbers. In that case, you can convert your own serial number to a Datacake UUID (which is needed to access configuration fields) using the following code: ```javascript // Get UUID for custom serial number var datacakeUUID = deviceSerialToId[serialNumber]; ``` #### **Notes** * **Device Identification:** Custom serial numbers allow flexibility but must be mapped to Datacake UUIDs for the platform to recognize and manage the data correctly. * **Configuration Values:** Stored at the product level but can have device-specific values. These values are accessed using the UUID, which is unique to each device. * **Measurements vs. Configuration Values:** Measurements can have historical data (values with timestamps), while configuration fields typically hold a single, static value. This setup provides a powerful way to manage and process device data efficiently, using Datacake's configuration fields and MQTT payload decoders to tailor the handling of each device's data based on its unique settings. {% hint style="danger" %} **Attention: Correct Access of Configuration Values in MQTT (or any other) Payload Decoder!** When accessing configuration values in payload decoders, ensure you do not use `.value` at the end of the access statement. Configuration fields are non-historical and store only a single value without timestamps. Therefore, access them directly: * **Correct**: `var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"];` * **Wrong:** `var tempOffset = configurationValues[datacakeUUID]["TEMPERATURE_OFFSET"].value;` Appending `.value` is only necessary for measurement values, which contain both a value and a timestamp due to their historical storage nature. {% endhint %} ### **Configuration Fields in HTTP Payload Decoders** Datacake's HTTP payload decoders offer a powerful way to integrate external devices and services by processing incoming data in a custom format. Using configuration fields in these decoders allows for dynamic behavior based on device-specific or product-level settings. Configuration fields can hold static values, like thresholds or calibration offsets, which can be utilized to enhance decision-making processes directly within the decoder logic. This section explains how to use configuration fields effectively in HTTP decoders. #### **Setting Up Configuration Fields** Before using configuration fields in an HTTP payload decoder, ensure that the necessary fields are configured in Datacake: 1. **Define Configuration Fields:** * Navigate to the device settings in Datacake. * Create a configuration field, for example, `Temperature Limit`, with a unique identifier (`TEMPERATURE_LIMIT`). * Assign a default value and, if necessary, customize this value at the individual device level. Example Configuration Field: * Name: `Temperature Limit` * Identifier: `TEMPERATURE_LIMIT` * Type: Number * Default Value: 30 2. **Ensure Device Mapping with UUID:** * Datacake uses a UUID to uniquely identify each device. If using custom serial numbers, a mapping from these serial numbers to Datacake UUIDs (`deviceSerialToId`) is necessary. #### **HTTP Payload Decoder Example** Below is an example of an HTTP payload decoder that demonstrates how to use configuration fields to process incoming data: ```javascript function Decoder(request) { /* This decoder expects JSON data in the format given below. Upon receiving the data, it decodes it and forwards it to the database. */ // Parse the incoming request body into a JSON object var payload = JSON.parse(request.body); // Extract the custom serial number from the incoming data var serialNumber = payload.device; // Convert the custom serial number to the Datacake UUID var datacakeUUID = deviceSerialToId[serialNumber]; // Example: Working with configuration fields try { // Access a configuration value using the Datacake UUID var temperatureLimit = configurationValues[datacakeUUID]["TEMPERATURE_LIMIT"]; // Check if the incoming temperature exceeds the configuration limit if (payload["temperature"] > temperatureLimit) { payload["temperature_limit_reached"] = true; } } catch (e) { console.log(JSON.stringify(e)); console.log("Error parsing Configuration Field"); } // Prepare the data to return to Datacake // Use the current Unix timestamp in seconds var timestamp = Math.floor(Date.now() / 1000); // Map the payload keys to Datacake's required format var result = Object.keys(payload).map(function(key) { if (key !== "device") { return { device: payload.device, field: key.toUpperCase(), value: payload[key], timestamp: timestamp }; } }); return result; } ``` #### Explanation of the Decoder Function * **Parsing the Request:** The incoming HTTP request body is parsed into a JSON object for easy manipulation. * **Serial Number Handling:** The custom serial number provided in the payload is extracted. This serial number is then mapped to a Datacake UUID using a predefined mapping (`deviceSerialToId`), allowing access to device-specific data. * **Accessing Configuration Fields:** * Using the Datacake UUID, the decoder accesses the configuration fields set up in Datacake. For instance, it retrieves the `TEMPERATURE_LIMIT` to perform checks against the incoming temperature data. * If the incoming temperature exceeds the configured limit, a flag (`temperature_limit_reached`) is added to the payload. * **Error Handling:** The decoder includes try-catch blocks to handle errors gracefully. If a configuration field does not exist or cannot be accessed, the decoder logs the error without crashing. * **Data Formatting and Returning:** The decoder formats the processed data into a structure compatible with Datacake's API, including optional timestamps for tracking. The data is then returned, ready to be stored or further processed by Datacake. #### **Best Practices** * **Use Configuration Fields for Dynamic Settings:** Configuration fields are ideal for thresholds, offsets, or any other settings that may change over time or vary per device. This provides flexibility in managing device behavior. * **Error Handling:** Always implement error handling when accessing configuration fields or measurements to ensure robustness against missing or misconfigured data. * **Keep Decoder Logic Simple:** While decoders can perform complex operations, keeping the logic straightforward helps maintain performance and readability. This approach to using configuration fields within HTTP payload decoders enhances the adaptability of device integrations, enabling customized responses based on real-time data and configurable settings. This flexibility is critical for applications that need to respond dynamically to changing environmental conditions or operational states. ## Further Examples ### Temperature Offset Calibration Temperatures often need calibration or offset added to the actual temperature value reported by the sensor. You could do this in the decoder hardcoded, but configuration fields are a nicer way when you, for example, work with 100s of devices and they all belong to the same product (and so share a single payload decoder). But even when working with a single sensor, usage of configuration fields make sense here. #### Code ```javascript function Decoder(bytes, port) { var decoded = {}; var temperature = (bytes[0] <<8 | bytes[1]) / 10.0; var offset = configurationValues.TEMPERATURE_OFFSET; decoded.temperature = temperature + offset; return decoded; } ``` ### Fill Level Offset When working with Fill Level Sensors you often need to convert or map the value range of the sensor to the actual height that you are measuring to derive the fill level (of the object, container, water level, and so on). Configuration fields can be used to create a fleet of 100s of fill level sensors and store these settings individually while still having the benefits of a shared product (same dashboard, payload decoder, database fields). #### Code ```javascript function Decoder(bytes, port) { var decoded = {}; decoded.battery = ((bytes[0]<<8 | bytes[1]) & 0x3FFF) / 1000; decoded.distance = bytes[2]<<8 | bytes[3]; try { var delta = configurationValues.SENSOR_LEVEL_EMPTY - configurationValues.SENSOR_LEVEL_FULL; var sensorRelative = configurationValues.SENSOR_LEVEL_EMPTY - decoded.distance; var fillLevel = Math.abs((sensorRelative / delta) * 100); if (fillLevel > 100) fillLevel = 100; else if (fillLevel < 0) fillLevel = 0; decoded.fill_level = fillLevel; } catch (e) { console.log(JSON.stringify(e)); } try { decoded.LORA_RSSI = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[0] && normalizedPayload.gateways[0].rssi) || 0; decoded.LORA_SNR = (!!normalizedPayload.gateways && !!normalizedPayload.gateways[0] && normalizedPayload.gateways[0].snr) || 0; decoded.LORA_DATARATE = normalizedPayload.data_rate; } catch (e) { console.log(JSON.stringify(e)); } return decoded; } ``` #### Field Configuration ![](/files/mrVgx9rMrobLzGnbFPkw) ## **Possible Issues and Best Practices** ### **Handling Measurement Values in Decoders** The following is not related to Configuration Fields in general, but helpful to add. When working with decoders, it's essential to handle the retrieval of measurement values carefully. One common issue arises when a field exists on a device but no data has been stored yet. Attempting to access such a measurement value without proper handling can cause the decoder to fail. To avoid this issue, it is a best practice to use a try-catch block when accessing measurement values. By encapsulating the code that reads from a measurement in a try-catch block, you can gracefully handle the situation where the field has no stored data. This approach ensures that the decoder continues to run smoothly, and you can use the opportunity to write an initial value into the field. For example: ```javascript try { var temperatureInDatabase = measurements[datacakeUUID]["TEMPERATURE"].value; // Further processing with temperatureInDatabase... } catch (e) { console.log("Measurement field is not yet initialized. Writing initial value."); // Code to write an initial value into the measurement field } ``` This strategy not only prevents errors but also provides a way to initialize fields dynamically, enhancing the robustness and reliability of your MQTT payload processing. # Fields ## What is a Field? In the Datacake Cloud the measured values of your devices are stored in "Fields". These are entries in our time-series database. Depending on your subscription plan, a certain number of fields can be created per device. This are also the so-called "datapoints". ## Creating a new Field To create your own field, open any device and navigate to its configuration area using the tab bar.
There you scroll down a little until you see the "Fields" panel:
Just click on the blue button "Add Field" to create a new field. The following dialog should appear:
## Type We support following field types: ### Integer Stores natural numbers, called in computer science integers, for example, `1234567`. ### Float Stores numbers with decimal places, even floating point, such as `1234.56`. This type is suitable for storing values with fractions, such as * Temperature * Pressure * Air quality ### String Save complete character strings. like `Sensor OK`, `Your own payload information`, `A83B8CFH38420`. These are being stored unprocessed in the database including a timestamp. Use this data type to store e.g.: * status messages * events * Your own payload data In addition, strings can be used in conjunction with mapping fields to convert numeric sensor values into a status via look-up table. ### Boolean Via Boolean fields you can store measured values of digital signals that are either only `0` or `1`, or `True` or `False`. Use these for: * Status-Signals of digital Inputs * True / False conditions * Events ### Geolocation This field type stores geolocation coordinates, which are provided by GPS modules, for example, and can be used to display positions on maps. If you choose to store coordinates using a location field, the field expects you to deliver the data as a string and formatted as follows: ```javascript "(latitude,longitude)" // Structure "(52.0123,4.124521)" // Example ``` ## Name This is the displayed, readable name as it can be used in the portal, e.g. to give widgets on dashboards a title or in other places. {% hint style="success" %} You can change this name at any time later. {% endhint %} ## Identifier The identifier is a unique designation that is used for storing data in the database. {% hint style="warning" %} Once the field is created, the identifier cannot be changed. If you still want to change it, you must delete the field. {% endhint %} ## Unit Use the input field to define the unit of the measured values that are being recorded into that field. Thanks to a free text field, you can define any units here, whether `°C`, `PPM`, `Bar`, `Fahrenheit` or `cake`, `biscuits`, whatever. ### Conversion {% hint style="success" %} You want to convert units into another one? No problem! Use mapping fields for the conversion of your measurement values via scaling, look-up table or linear scaling of a value range. Use Formula Option of a field to do simple mathematical operations. {% endhint %} {% content-ref url="/pages/-M-KooJ\_4-haz0fNqNCV" %} [Mapping Fields](/device/database/fields/mapping-fields) {% endcontent-ref %} {% content-ref url="/pages/-M-L52cCzL5K7CnhqRGr" %} [Formulas](/device/database/fields/formulas) {% endcontent-ref %} ## Role The roles assigned allow you to visualise the most important fields of your devices on the list, grid and map views. Learn more about them: {% content-ref url="/pages/Ab1hOAtBIy4qsy6AN0Nj" %} [Field Roles](/device/database/fields/field-roles) {% endcontent-ref %} ## Formula Each field has the function of a formula. Here, simple mathematical operations can be used to combine measured values from other fields or to perform special calculations. More on this topic is given in the following section: {% content-ref url="/pages/-M-L52cCzL5K7CnhqRGr" %} [Formulas](/device/database/fields/formulas) {% endcontent-ref %} # Manual input You can set manual inputs inside the fields. In the configuration overview of the fields, you can manually enter measured values for the following fields: * Integer * Float * String * Boolean {% hint style="info" %} If your devices get regularly data, the incoming data will replace your manual input. Take into consideration that any manual input will be saved in the database for as long as the data retention period covers, afterwards all values will get deleted, unless you setup a role. {% endhint %} Simply move your mouse cursor over the drop-down selector of your respective field and click on the "Set Value" item:
You will see the following Modal / View:
Now enter the desired measured value into the field and confirm it by clicking the "Set Value" button. Your measured value is now entered with a time stamp. ## Manual Input triggers API If you enter a measured value into the field in this way, it is passed on internally to the API via the backend and this measured value is also output automatically via MQTT. If you have created rules that monitor the measuring field, then these rules are now also informed about the entry. # Field Roles ## Basics The Field Role function allows you to assign a role to individual database fields. The following roles are available: * Primary * Secondary These roles are then used by widgets or lists to automatically display certain information from your sensors. For example, in the device list, you now have the option of displaying the favorite values of a sensor directly in the table or using the new grid view to display each device as a map with all information. ## Setting Field Role ### Existing Field Navigate into the database section of your Datacake device. ![](/files/x2EByNkUxI6nUj4KRRKr) Now click on the dots button at the right end of a field row. This will open up a context menu where you have to click on "Edit Field".
When you click on "Edit Field" this will open up a configuration modal where you can also set the Field Role. Click on "Role", this will open up a context menu that shows both available field roles. Simply select one and don't forget to press on "Update Field". Now, you have the option to also select a Field Semantic, which will automatically generate some KPIs in your Device Overview. For more information about that, please refer to: {% content-ref url="/pages/TmCOrosPLbxaXIz2OpLS" %} [Field Semantics](/field-semantics) {% endcontent-ref %} ### New Field If you are creating a new database field, you have the option to directly set the field role. ## Using Field Roles ### Device List Field roles can be used to display measured values of your sensor devices directly in the device list table. All you need to do is activate which field roles you want to display on the field list. Click on "Columns" and simply select the field roles. ![Datacake Device List Field Roles](/files/FzjbI7VgWNSfzn7sUDua) ### Device Gallery You can switch your device list from a table view to a grid layout that shows you all devices as cards in a gallery overview. ![Datacake Device Gallery View](/files/45v11X8ABe4osujQ2lNR) Inside of Image map and map widgets, you can also display your device's primary or secondary fields, to give users a better overview on their devices. # Formulas ## What is a Formula? Formulas can be used to perform basic mathematical operations and derive measurements based on the current values of other fields. At the moment, the supported operations are `+`, `-`, `*` and `/`. You can use both static expressions as well as other fields in your formula. For example, to calculate a measurement in celsius based on another field that holds the value in Fahrenheit, you would use the formula `(TEMPERATURE_F - 32) * (5/0)`, where `TEMPERATURE_F` is the field identifier of the Fahrenheit-field. ## Creating a Formula Defining a formula is very simple. Simply select one or more fields from the "Available Placeholders" list that should provide measured values for the conversion. Use this line also to enter the operations. ![](/files/-M-LAkTqnzbLbRfUrY7U) ## Examples ### Combining multiple fields into a single one You can use a formula to combine the measured values of different fields and perform calculations based on these values. This is suitable, for example, for setting up compound values or conditions, where the processing of several measured values is required. ![](/files/-M5xH1H0JyYll0aImDSX) ### Converting Celsius to Fahrenheit The following screenshot shows a newly created field and its configuration dialog including the formula for the conversion of a Celsius output value of another field into the unit Fahrenheit. ![](/files/-M-L9BQulRhn5FWGlYh3) Each time a new value is being recorded to the `TEMPERATURE` field, the formula is executed and the result (temperature in Fahrenheit) is written to the `TEMPERATURE_F` field. # Mapping Fields What is a Mapping Field? Any mapping fields can be added to any field in the database. These calculate the content of the original field into a desired target value using various functions. The conversion is performed each time a new measurement value is written to the base field. {% hint style="success" %} Mapping fields also store their contents in the database. {% endhint %} ### Usage Mapping Fields can be used for the most diverse tasks. Some of these are, for example: * Simple scaling of a measured value using a factor * Mapping of a value range to the value range of a sensor * Conversion of numeric value to a string (for status messages based on a number) via Look-Up-Table ### Examples Under the following links you will find some best practices and examples for different tasks. ## Add a new Mapping Field Mapping fields can be created by adding them to a base field. To do this, open the drop-down menu of a field and click on "Add Mapping Field".
After you have clicked the button, the following modal appears:
The modal itself is divided into three different areas: * Field Configuration (RED) * Mapping Type (GREEN) * Mapping Settings (BLUE) ### Field Configuration This area is identical to the field configuration of a basic field. Here you determine name, identifier, type and unit. Read more about this in the [**previous section**](/device/database#creating-a-new-field). ### Mapping Type and Settings The tab bar (Green) must be used to define the type of conversion. A checkmark behind the active element indicates which type of conversion is active.
The settings for the respective conversions are described in the following sections. They are located in the area (Blue) below the tab bar (Green). ## Linear Scale Mapping Use this option to convert a value range to a target value range.
In linear scaling, the measured value is converted based on a scale. You must enter two base (Source) and target (Target) values here. ### Use Boundaries If you activate this option, the value resulting from the conversion remains within the scale (Target). If the option is deactivated, negative values or values that lie outside the specified scale (Target) can result, but still be scaled based on the entered values (Target). {% hint style="info" %} If you need a simple conversion based on a factor, use the option "Factor". {% endhint %} ### Source This is the base-scale with which you specify the value range that is to be scaled to a new value range.
The two input fields below each other can be understood as "From" and "To" and describe the original value range. ### Target This describes the target value range.
Again, both input fields can be understood as "From" and "To". Enter the value range into which the original value range should be converted. #### Offset The offset can be used to achieve a static change of +/- the value specified in the text input field. It's added to the resulting value **after** the conversion has taken place. {% hint style="info" %} To subtract an offset, enter a negative value in the Text Input field. {% endhint %} ### Visual check To the settings you will find a graph that visually represents the conversion of the value range. Here you can visually check your input again. ### Limitation of types {% hint style="warning" %} Even if the choice of type is not limited. The "Linear Scale" option works only with the following types: * Integer * Float {% endhint %} ## Lookup Table Mapping #### Boolean You can map a field to a Boolean value using a Lookup table. You need to enter the exact value that will be then converted to "True" or "False". The Fallback is the "else", which means it will be the other value(s). The switch ON means "True", the switch OFF means "False".
## Factor Mapping The "Factor" option allows you to convert the output value using a factor. The output value is multiplied here by the specified factor.
### Limitation of types {% hint style="warning" %} Even if the choice of type is not limited. The "Factor" option only works with the following types: * Integer * Float {% endhint %} ## Save and Create {% hint style="success" %} To create the mapping field, confirm your entries with the "**Save**" button. Only after you do this the field is created. {% endhint %} If this step was successful, the newly created mapping field is displayed as a subordinate field of the original field. # How to Map Sensor Values to Ranges or Booleans, Strings using Mapping Fields Learn how to use Datacake IoT Platform to map numerical values like CO2 levels to string or boolean statuses for enhanced data monitoring and visualization. ## Introduction Welcome to this tutorial. In this guide, we will demonstrate how to use the Datacake IoT platform to map numerical values to meaningful representations. This includes converting numerical readings such as temperature, humidity, or CO2 levels into string statuses (e.g., "OK", "Too High", "Too Low") or boolean values (e.g., "Person Detected"). These mappings are useful for monitoring various metrics and displaying them effectively on your dashboard. ### What is a Mapping Field? Read more here: {% content-ref url="/pages/-M-KooJ\_4-haz0fNqNCV" %} [Mapping Fields](/device/database/fields/mapping-fields) {% endcontent-ref %} ## Start ### Steps to Add a Mapping Field #### 1. Access the Device Configuration 1. Log in to your Datacake account. 2. Navigate to the device you want to configure (e.g., LHT 65). 3. Go to the **Configuration** section of the device. #### 2. Locate the Payload Decoder and Fields 1. Scroll down to the **Payload Decoder** section. Note that while mapping can be done here, we'll use the **Fields** section for this tutorial. 2. Scroll to the **Fields** section to see the existing fields like battery, temperature (internal and external), humidity, and CO2. #### 3. Add a Mapping Field for Battery Status 1. Identify the field you want to map (e.g., battery voltage). 2. At the end of the field row, click on the three dots. 3. Select **Add Mapping Field**. #### 4. Configure the Mapping Field 1. Choose the field type (String, Integer, or Float). For battery status, select **String**. 2. Name the field (e.g., "Battery Status"). The identifier will be generated automatically but can be overridden. 3. Define the mapping logic using a lookup table: * Below or equal to 2.5V: "Battery Low" * Below or equal to 3.5V: "Battery Moderate" * Above 3.5V: "Battery OK" 4. Add these mappings and save the field. #### 5. Simulate Data to Verify Mapping 1. Enter the original field (e.g., battery voltage). 2. Manually input a value to see the mapping in action. For example, input 2.998V to check if it maps to "Battery Moderate". #### 6. Display the Mapped Field on the Dashboard 1. Go to the **Dashboard** for the device. 2. Enter **Edit Mode**. 3. Add a new widget: * Select **Value Widget**. * Choose the device and the newly created mapping field (e.g., "Battery Status"). 4. Save and place the widget on the dashboard. 5. Exit **Edit Mode** to see the live status. #### 7. Mapping CO2 Levels to Determine Presence 1. Identify the CO2 field that is fed by the sensor output. 2. Add a mapping field for CO2 detection. 3. Choose the field type **Boolean**. 4. Name the field (e.g., "Person Detected"). 5. Define the mapping logic: * Above 800 ppm: True (Person Detected) * Below 800 ppm: False (Person Not Detected) 6. Add this mapping and save the field. #### 8. Display the Boolean Field on the Dashboard 1. Go to the **Dashboard** for the device. 2. Enter **Edit Mode**. 3. Add a new widget: * Select **Value Widget** or **Status Widget**. * Choose the device and the newly created mapping field (e.g., "Person Detected"). 4. Save and place the widget on the dashboard. 5. Exit **Edit Mode** to see the live status. #### 9. Additional Examples and Uses You can apply similar steps to other fields such as temperature: 1. Add a mapping field for temperature. 2. Define breakpoints (e.g., below 15°C: "Too Cold", 15-25°C: "OK", above 25°C: "Too Hot"). 3. Display this status on the dashboard. #### 10. Using Linear Scaling for Percentage Display 1. Add a new mapping field and select **Linear Scale**. 2. Configure the scaling (e.g., for battery percentage from 2.5V to 4V). 3. Name the field (e.g., "Battery Percentage") and set the unit to %. 4. Define the source range (e.g., 2.5V = 0%, 4V = 100%). 5. Add boundaries to restrict values between 0% and 100%. 6. Display this field as a gauge on the dashboard. ### Conclusion Mapping fields in Datacake IoT Platform allows you to create meaningful representations of your data, improving monitoring and alerting capabilities. By following this guide, you can map numerical values to string statuses or boolean values and display them effectively on your dashboard. Thank you for following this tutorial. Stay tuned for more updates and tutorials on using Datacake IoT Platform. # Data retention & Datapoints ## What is data retention? Data retention refers to the period of time in which datapoints will be stored in our time-series database. ### So how much data retention do I need? Depending on the application, you may need to collect data for the next few months, or only data from the last few days. The database will begin to gradually discard the data. This means, that once the established data retention period is reached, the oldest packets will be dropped to make room for new packets received. ## What are datapoints? The datapoints are the measured values of your devices that gets stored as field entries into the Datacake database. Depending on your subscription plan, a certain number of fields or datapoints can be created per device. This means, that depending on the subscription, the devices will be allowed to store within the created fields a maximum amount of collected data, after which they will start dropping packages. This will lead to a delay in the display of new data on the interface. ### So how many datapoints do I need? That depends on your specific use case. Please take into account the amount of data your sensors will transmit, how often and in how many fields this information will be divided. We recommend that you review this before you start transmitting data. Below are the datapoints and data retention available per data subscription plan: | Free | Hobby | Light | Standard | Plus | | --------------------- | ------------------------ | ------------------------ | ------------------------ | ------------------------ | | 7 days data retention | 12 months data retention | 12 months data retention | 12 months data retention | 12 months data retention | | 500 datapoints/day | 1500 datapoints/day | 7500 datapoints/day | 7500 datapoints/day | 7500 datapoints/day | We used to have Pay-as-you-go plans, which are still available for old accounts. In each of those individual device subscription plans, the available datapoints and data retention days/months are listed below: | Free | Light | Standard | Plus | | --------------------- | ---------------------- | ----------------------- | ------------------------ | | 7 days data retention | 1 month data retention | 3 months data retention | 12 months data retention | | 500 datapoints/day | 1000 datapoints/day | 2500 datapoints/day | 7500 datapoints/day | {% hint style="success" %} The datapoint count restart each day at 00:00 UTC. You can check out the datapoints consumed inside of your device's Configuration/Danger Zone section. If your devices were claimed, the datapoint consumption won't be visible. {% endhint %} ## Change your device's plan Do you want to migrate your device to a better plan? Just follow this simple video: {% embed url="" %} # Examples # Mapping 4-20mA Signals ![](/files/-M-KHUxax25yuawwhLUj) ![](/files/-M-KHb8Ub7Q9yWD23lKi) # Converting Units ## Celsius to Fahrenheit First, create a mapping field below your temperature field (and name this Temperature Fahrenheit, for example). ![](/files/-MUShVuDryG1zVkLfXjV) You then set this mapping as shown in the following screenshot. ![](/files/-MUShdUEgzmXDjfztugp) ## Watthours / Kilowatthours If you have a field that stores watt-hours, then you can create a mapping field that will then convert the values to kilowatt-hours. ![](/files/-MUSk8Pqk08RCsOOh_q3) To do this, create a new mapping field and then set up the configuration as follows: ![](/files/-MUSkXSI4aGE7vPrlgBC) # Field Semantics ## Intro Field Semantics is a powerful new feature in Datacake that introduces context-awareness into your IoT data. It enables the platform to understand the meaning behind each measurement field (e.g., temperature, humidity, CO₂), allowing automated generation of dashboards, KPIs, and device overviews at scale. This documentation explains the concept, how to use it, and how it enhances the overall Datacake experience. ### Video {% embed url="" %} *** ## 🚀 What Are Field Semantics? Field Semantics are predefined labels or roles that you can assign to measurement fields on your devices. These semantics tell the Datacake platform what kind of data a field represents. #### Examples of current numerical semantics: * Temperature * Humidity * CO₂ * Fill Level * Soil Moisture * Air Pollution * Ambient Light * Energy Consumption Assigning these semantics helps Datacake: * Automatically generate KPI dashboards * Visualize sensor metrics across workspaces and device groups * Enable context-specific views (e.g. CO₂ health analysis) *** ## 🔧 How to Use Field Semantics #### Step 1: Navigate to Device Configuration * Go to your device in Datacake * Click the **Configuration** tab * Select **Fields** under "Product & Hardware" #### Step 2: Edit Field and Assign Semantic * Click the three-dot menu next to a field (e.g., CO₂) * Choose **Edit Field** * In the **Semantic** dropdown, select the appropriate semantic (e.g., CO₂, Temperature) * Save by clicking **Update Field** ![Access Field Settings](/files/OFsg4Y5PM0MY1m3EUp0i)

Set Field Semantic

*** ### 📊 Automatic KPI Dashboards Once semantics are assigned, you gain immediate access to: * **Workspace-level metrics** (min/max/avg per semantic) * **Semantic-specific KPI views** (e.g., detailed CO₂ quality breakdown) * **Device filtering by semantic** (e.g., all temperature sensors) This means less manual configuration and quicker rollout of projects at scale.

CO2 Semantic Overview

*** ### 🧩 Cross-Product Compatibility Semantics work across different products and devices. If multiple devices have a field assigned with the same semantic (e.g., CO₂), they are automatically aggregated in dashboards and KPI cards — regardless of whether the devices belong to the same product. This also enables global insights, such as: * Average temperature across an entire building * CO₂ levels on all floors * Alerting based on grouped sensor semantics *** ### 📁 Semantic-Based Device Groups (Coming Soon) Upcoming features will allow you to: * Create **device groups** (e.g., rooms, floors) * Apply **tags** and group filters to dashboards * Use semantics within these groups to generate group-specific KPIs This supports fully automated monitoring of spaces without needing custom dashboards. *** ## 💡 Summary Field Semantics help you: * Add meaningful context to raw IoT data * Automate the creation of dashboards and KPIs * Scale projects faster and more reliably * Enable cross-product data harmonization Start using it today by assigning semantics to your fields in the device configuration section. Feedback is welcome – we’re continuously improving this feature! *** For more help, check our [Documentation](https://docs.datacake.de/) or contact [Support](mailto:support@datacake.de). *Stay tuned for more semantic types and automation capabilities coming soon!* # Global Dashboards Workspaces do have the option to create global Dashboards. These are different from those dashboards that you create in your devices but share the same workspace builder. These differences are: * Use multiple devices within your builder * Use Table-Widgets to create overviews * Sort Dashboards using Tabs You can create your own global dashboards by adding a new one under the Dashboard-Section in the Administration Group in the left sidebar.
## Copy-Paste a Dashboard You can copy an existing global dashboard into a new global dashboard by going to Edit Mode and hovering over "More", the drop-down-list next to the Desktop/Mobile view. Click on Copy Dashboard. It will get copied to your clipboard, so you can paste it by using the keyboard CTL+V (CMD+V on macbook). Make sure there are no empty spaces or extra symbols. The base64 string you will see being pasted is actually an encoded JSON that contains all information about your dashboard, its widgets, the sources, etc. {% hint style="warning" %} If you are copy-pasting a dashboard within the same workspace, the sources will be automatically selected. But if you are copying a dashboard from one workspace to another, you will have to select the sources manually. This is because the device list may differ and the sources will be diferent. {% endhint %} {% hint style="danger" %} You cannot copy device dashboards to global dashboards and global dashboards to device dashboards. There are some differences when it comes to available widgets and how those are configured, so they are not interchangeable. {% endhint %} ### Sidebar Configuration Once the desired Dashboards have been added, it is possible to sort them in different folders. To do so, click on the configuration icon next to Add Dashboard — the cog labelled **Manage dashboards & folders**.
The sidebar configuration allows to create folders, edit and delete them. Type the Folder name and click on Create. Once created the folders you can edit their names using the pencil. You can order them and order the dashboards inside of them by drag and drop. If you want to delete a folder, just click on the bin on the right side of the folder. Don't forget to save the changes you have made! Removing a folder does not delete the dashboards inside it — they simply move back out to the top level of the sidebar. Creating folders, renaming and reordering are only stored when you click **Save**, so **Cancel** discards them if you change your mind.
### Deleting a Dashboard The same screen is where you delete a global dashboard, using the bin next to the dashboard name. To confirm, type the dashboard's name — there is a **Copy name** button beside it so you don't have to retype a long one by hand. Before you confirm, the dialog tells you what else the deletion takes with it: * how many **public share links** point at this dashboard and will stop working * how many **workspace members** the dashboard is shared with and will lose access Your devices and their measurement data are never affected. Only the dashboard itself is removed, along with its tabs, widgets and share links. {% hint style="danger" %} Unlike folder changes, deleting a dashboard takes effect immediately and **Cancel** will not bring it back. Anything you have dragged around but not saved yet is kept, so you can carry on rearranging afterwards and save as usual. {% endhint %} Deleting a dashboard needs the same **Dashboards** workspace permission as adding one. You can still delete a dashboard from inside it as well, through Edit Mode and its settings. ## Sharing Global Dashboards You can modify who gets access to your global dashboards by modifying the Access. You can share a dashboard with all members of a workspace, selected members of a workspace or anyone with a link. In that case, the link will be created after saving the dashboard.
To access the link or modify the configurations you have to go to Edit Mode, Edit Dashboard Metadata and there you will be able to copy the public link.

Remember clicking on Update Dashboard to save your configurations!

### Public Links Public Links enable sharing dashboards with external users who do not require a Datacake account. A public link provides access via a unique URL and can optionally be protected with a password. #### Creating a Public Link 1. Open the Global Dashboard you want to share. 2. Click **Share** :link: in the top right, then **Manage Public Links**. 3. If no public links exist yet, you will see a message indicating that no links have been created. 4. Click **Add Public Link**. 5. In the *Add New Public Link* dialog: * **Display Name** (optional): Enter a name to help you identify this link later (for example, *Customer View* or *Management Overview*). * **Password** (optional): Set a password if you want to restrict access. 6. Click **Add New Public Link** to create the link. Once created, the public link will appear in the list and includes: * A shareable **URL** (with a copy button) * A **QR code** that can be downloaded * An indicator showing the access level (for Global Dashboards this is always *Read Only*) You can create multiple public links for the same Global Dashboard, each with its own name and password.
*** ### Access Level: Read‑Only Public Links for **Global Dashboards are always read‑only**. This means that external users can: * View charts, values, and historical data * Interact with time ranges and filters (where applicable) They **cannot**: * Change widget configurations * Send downlinks * Modify device values or measurements This behavior is intentional and differs from Device Dashboards. *** ### Difference to Device Dashboards Device Dashboards can be shared via Public Links in either: * **Read‑only mode**, or * **Read & Write mode** (if explicitly enabled) This is possible because Device Dashboards: * Are tied to a **single device** * Have a clear and unambiguous target for actions such as downlinks or value changes * Allow fine‑grained control over what external users are permitted to do In short: * **Global Dashboards** → overview & monitoring → *read‑only* * **Device Dashboards** → device‑specific interaction → *read‑only or read & write* *** ### Best Practices * Use Global Dashboard public links for **reporting, monitoring, and high‑level sharing**. * Use Device Dashboard public links when **interaction or control** is required. * Always consider adding a **password** when sharing dashboards externally. # Setting Homepage ## Setting Your Workspace Dashboard as the Homepage in Datacake In this documentation, we introduce a highly requested feature that enhances the navigation and usability of your Datacake workspaces. The ability to set a workspace dashboard as the homepage of your workspace streamlines your workflow, allowing you to access your most important information immediately upon login or workspace switch. Below, we guide you through the steps to utilize this new feature effectively. ## Video {% embed url="" %} ## Introduction to the New Feature Datacake has rolled out a feature update enabling users to set a workspace dashboard as the homepage of their workspaces. Traditionally, accessing a Datacake workspace directed users to the device list by default. While this view is essential, the flexibility to land directly on a customized workspace dashboard can significantly enhance user experience, especially for those who rely on dashboard visuals to monitor their operations immediately. ## How to Set a Workspace Dashboard as Your Homepage 1. **Access the Workspace Dashboard**: Navigate to the workspace where you wish to set the dashboard as the homepage. Workspaces in Datacake typically start with a device list view, showcasing various devices organized, potentially, into folders (e.g., first floor, second floor) each with its device list. 2. **Edit Dashboard Metadata**: In the desired workspace, enter the edit mode for the dashboard you want to set as the homepage. You can do this by selecting "Edit Dashboard Metadata." This option allows you to modify the dashboard settings and attributes. 3. **Activate the Home Dashboard Option**: Within the dashboard editing interface, look for an option to mark the dashboard as the home dashboard. This is usually a switch or checkbox labeled appropriately. Enabling this option designates your current dashboard as the workspace's homepage. 4. **Save Your Changes**: After enabling the home dashboard option, ensure to save your changes by clicking on "Update Dashboard." This action confirms your preference and applies the changes to your workspace. 5. **Verify the Change**: Post-update, you can verify that the dashboard is now set as the homepage by looking for a small house icon next to the dashboard name in the sidebar. This icon indicates that the dashboard is now the homepage of the workspace. #### Switching Between Workspaces After setting a workspace dashboard as the homepage, the new setting enhances how you navigate between workspaces: * **Initial Access**: Upon logging in or switching to a workspace with a designated homepage dashboard, Datacake will direct you straight to this dashboard instead of the default device list view. * **Navigating to Other Workspaces**: When you switch to another workspace that doesn’t have a home dashboard set, Datacake will display the device list as usual. However, returning to a workspace with a home dashboard set will direct you immediately to that dashboard. * **Flexibility**: Each workspace can have its own designated home dashboard. This flexibility allows for customized navigation that suits the specific needs of different projects or operational areas within Datacake. # Climate Monitoring Dashboards The **Climate Monitoring Dashboard** is a pre-built dashboard template that allows you to monitor temperature, humidity, CO₂ and related compliance metrics across multiple devices and locations, all with just a few clicks. It is designed for use cases such as indoor air quality monitoring, storage compliance, and facility climate oversight. *** ### Create a Climate Monitoring Dashboard Creating a climate monitoring dashboard only takes a few steps. #### Step 1: Create a new dashboard 1. Navigate to **Dashboards** in the left-hand menu. 2. Click **Add Dashboard**. 3. Select **Climate Monitoring** as the dashboard type. 4. Click **Next**.
This template comes with pre-configured analytics, compliance logic, and visualizations optimized for climate data. *** #### Step 2: Configure the dashboard 1. Enter a **Dashboard Name** (for example: *Climate Monitoring Dashboard*). 2. Click **Create Dashboard**. The dashboard will be created and shared with all workspace members by default, though you can choose to select access permissions to specific users. *** #### Step 3: Select devices After creation, the dashboard will prompt you to select devices. 1. Click **Select Devices**. 2. Choose devices that provide **temperature and humidity** measurements. 3. Use search, tags, or locations to filter devices if needed. 4. Click **Save Selection**.
Once devices are selected, the dashboard automatically starts calculating scores and analytics. *** ### Dashboard Sections The Climate Monitoring Dashboard is organised into several tabs, each focusing on a different aspect of climate monitoring. *** ### Overview
The **Overview** tab provides a high-level summary of the climate situation across all selected devices. It includes: * **Global Climate Score** – Overall climate performance across all areas * **Time-in-Range (TIR)** – Percentage of time values stayed within defined thresholds * **Dewpoint Safety** – Condensation risk assessment * **Mold Risk Score** – Risk evaluation for fungal growth * **Climate score trends** over time * **Score distribution** and **area performance comparisons** This view is ideal for quickly identifying problem areas or general performance trends.
#### Recommendations The **Recommendations** section automatically highlights **climate issues, risk areas, and suggested actions** based on your dashboard data. Recommendations are generated from: * Climate scores * Time-in-Range (TIR) performance * Dewpoint safety and mold risk * Area performance * Device connectivity They help you quickly understand **what needs attention** and **where to act**. #### Recommendation types * **Critical Climate Performance** Triggered when the **overall climate score** is critically low, indicating severe compliance issues. **Typical actions:** Review HVAC settings, check equipment functionality. *** * **Critical Time-in-Range (TIR) Performance** Triggered when values rarely stay within defined thresholds. **Typical actions:** Inspect HVAC systems, verify sensor calibration and placement. *** * **TIR Issues in Specific Areas** Identifies areas with poor TIR performance. **Typical actions:** Check local HVAC, insulation, airflow, or heat sources. *** * **Condensation Risk Detected** Indicates potential condensation based on dewpoint analysis. **Typical actions:** Improve air circulation, check insulation and surface temperatures. *** * **Problem Areas Identified** Highlights areas with consistently poor climate performance. **Typical actions:** Focus maintenance efforts on affected areas. *** * **Offline Devices Detected** Shows devices that are currently not reporting data. **Typical actions:** Check connectivity, batteries, and gateways. *** * **Devices with Poor TIR Performance** Lists individual devices with low Time-in-Range values. **Typical actions:** Inspect local conditions and device placement.
*** ### Climate The **Climate** tab focuses on raw environmental measurements and distributions. You can view: * Average temperature and humidity * Min–max temperature and humidity ranges * Temperature and humidity trends over time * Distribution charts for temperature and humidity * Area-based climate summaries This section helps you analyse environmental behaviour in detail and compare different areas or floors.
*** ### Compliance
The **Compliance** tab provides a detailed compliance analysis based on your defined thresholds. It includes: * Overall compliance score * TIR compliance * Dewpoint safety compliance * Mold prevention compliance * Breach counts and total breach durations * Area-level compliance breakdown You can also **export a compliance report** directly from this tab for auditing or documentation purposes.
*** ### Events
The **Events** tab lists all climate-related events and breaches. Features include: * Search by device, location, or description * Filter by event type and severity * Event summaries (breach, resolution, critical events) * **Export events** in CSV, Excel, or PDF format This tab is especially useful for incident tracking and historical analysis.
*** ### Device List
The **Device List** tab provides a device-level overview of climate performance. For each device, you can see: * Climate score * Time-in-Range (TIR) score * Mold risk score * Current readings * Last communication timestamp Visual score bars make it easy to quickly identify underperforming devices.
*** ### Climate Monitoring Dashboard Settings The **Climate Monitoring Settings** allow you to customise how climate data is calculated, evaluated, and displayed in the dashboard.\ You can access the settings via **Dashboard → Settings**. The settings are organised into three tabs: **General**, **Calculation**, and **Devices**. *** #### General The **General** tab contains basic dashboard information. You can: * Edit the **dashboard name** * Select a **dashboard icon** (shown in the sidebar) * View technical details such as: * Dashboard ID * Dashboard type * Dashboard URL The **Danger Zone** at the bottom allows you to permanently delete the dashboard.
*** #### Calculation The **Calculation** tab defines how climate scores and compliance metrics are calculated. Here you can configure: * **Dewpoint thresholds** (warning and alarm levels) * **Surface temperature delta** for condensation detection * **Mold risk settings**, including: * Temperature range * Humidity warning and alarm levels * **Score classification thresholds** (Excellent, Good, Poor) * **Aggregation mode** for combining device scores (e.g. Average) A summary at the bottom shows the **weighting** of each component (TIR, Dewpoint, Mold).
*** #### Devices The **Devices** tab controls which devices are included in climate monitoring calculations. You can: * View all selected devices * See device status (online/offline) * Add or remove devices from the dashboard * Verify device location, tags, and serial numbers Only devices listed here are used for: * Climate score calculations * Compliance analysis * Events and recommendations
*** ### Summary The Climate Monitoring Dashboard allows you to: * Create a complete climate monitoring setup in minutes * Automatically visualize trends, scores, and compliance * Monitor multiple devices and areas at scale * Export reports and events for audits and documentation It is the fastest way to turn climate sensor data into actionable insights. # Device Dashboards Your devices come with the option to create a specific dashboard with the values registered. ## Edit mode To enter Edit mode of your dashboard press on the Icon on the rightmost side of your screen, after to Permissions.
You can add new widgets, move the ones already there or edit the widgets' configuration on edit mode. All device dashboards have also a Mobile view. You can create it basing it on the desktop version, by pressing More and selecting "Create from 'Desktop". then all widgets with their configurations will be copied into the Mobile version. You only need to rearrange them and that is it. ## Copy-Paste a Dashboard You can copy a device dashboard into another device's dashboard by going to Edit Mode and hovering over "More", the drop-down-list next to the Mobile/Desktop view. Click on Copy Dashboard. It will get copied to your clipboard, so you can paste it by using the keyboard CTL+V (CMD+V on macbook). Make sure there are no empty spaces or extra symbols. The base64 string you will see being pasted is actually an encoded JSON that contains all information about your dashboard, its widgets, the sources, etc. {% hint style="warning" %} If you are copy-pasting a dashboard from two devices of the same kind, the sources will be automatically selected. But if the devices differ, you will have to select the sources manually. {% endhint %} {% hint style="danger" %} You cannot copy device dashboards to global dashboards and global dashboards to device dashboards. There are some differences when it comes to available widgets and how those are configured, so they are not interchangeable. {% endhint %} ## Create a Public Link to share your Dashboard On your Device Dashboard click on the Edit Mode Button. ![](/files/-MfNkE3MMvVFD4NtNNEg) This will bring up a new Button "Public Link". ![](/files/-MfNkIgejBE0v5K1NVxJ) If you click on this button you will see a modal popping up. Here you can activate and create a public link for your device by clicking on it. ![](/files/-MfNkN8JCBYr04ub3yf8) This will change the view of the modal and bring up some input fields. To create and activate the Link to your device dashboards first of all simply press on "Create Public Link" Button as shown below. ![](/files/-MfNkS0GCsjL1bZJmvSL) Once done a saving-notification will pop up on top right and you will also see the QR-Code of the newly created link appearing. ![](/files/-MfNkWjbK6ItWamtQ2t9) That's it. The Link has successfully been created and your Dashboard is now publicly available. You can now move on and set an optional password or set permissions. More about this in the next chapter. ## Download QR-Code Once your Public Link has been created you can download a QR-Code of the link that leads to your public dashboard. ![Download QR-Code](/files/-MfNnqQt1HYMk4mjceDR) ### Deleting Public Link By deleting a public link you deactivate the QR-Code as well. {% hint style="danger" %} Attention. If you delete your Public Link (and reactivate it) the QR-Code will be regenerated and so all printed QR-Codes (as stickers, whatever) will no longer work. {% endhint %} ### Revoke Access If you want to restrict or disable access to your Dashboard you should work with passwords and change or set passwords instead of deleting and re-activating a public dashboard link. ## Branding If you are on a White Label package your QR-Code shows the White Label branding Fav-Icon instead of the standard Datacake Icon. ![White Label Branding on QR-Code (how cool is that?)](/files/-MfNmqXO501guHJ8M10_) ### Domain / URL The URL of your shared Device Dashboard is also available on any of your White Label sites and will be something like: `https://whitelabel.domain.com/pd/b5cc34b2-evil-dead-beef-d7911a7899d8` ### Set Branding If your QR-Codes do not show a correct branding you likely forgot to set the Fav-Icon on your White-Label Site. You can do this by navigating into the White Label settings on your Datacake Account. ![QR-Code branding is using Fav-Icon](/files/-MfNnQ3tDIqm2zlUUcDi) Datacake uses the Favicon-Setting on your White Label site as the source for the QR-Code branding. ## Password Protection Datacake allows you to set an optional password for public device dashboards. User that access a password protected public device dashboard are asked for a password. ### Set Password Dashboard Passwords can be set in the setup dialog of a public link. Simply open up the public link settings and set a password in the "Password" input field like shown below: ![](/files/-MfNkvdF59_t_1JxtB97) In order to set the password please don't forget to save your edits. ### Enter Password When you or your users open up a pulic device dashboard via link and if this dashboard is protected by a password (like shown above) you (or your users) are required to provide the password. ![](/files/-MfNlEAM-XFgv9q6j8j7) ## Set Permissions In your public link settings you can also choose a working-mode that defines the capabilities and permissions of a public dashboard. ![](/files/-MfNpYAE4_nH_429CVp2) ### Read only Choose this mode if you only want to allow viewing a dashboard but not changing stuff, entering measurement values, and/or triggering downlinks. {% hint style="success" %} Even if your shared dashboard does have widgets that allow inputs or triggering downlinks, these will not work in public if the mode is set to "Read Only". {% endhint %} ### Read & Write Choose thise mode if you also want to allow users to change things, enter values, and/or trigger downlinks. {% hint style="danger" %} It might be a good idea to work with a password when setting "Read & Write" on a Dashboard as every person that has access to a public link can control the device linked to it. {% endhint %} ### Downlinks {% hint style="info" %} Downlink Buttons are currently not working on public device dashboards. Use Input Widgets (as switch or slider) instead and work with field-triggers in your downlinks. {% endhint %} # Sub-Device Dashboards Create several dashboards for your devices and how to hide selected ones for your customers. ## Introduction This feature allows enterprise customers to create multiple dashboards for their devices, with the ability to hide specific dashboards from end customers on white-labeled sites. This functionality provides greater control over what data is visible to different users. ### Video {% embed url="" %} *** ## Key Features 1. **Multiple Dashboards** * You can now create multiple dashboard pages (or tabs) for a single device. * Each dashboard can contain different widgets, including device fields, charts, and downlinks. 2. **Visibility Control** * Dashboards can be marked as hidden on white-labeled sites, allowing you to create internal dashboards for service or management purposes. 3. **White Label Customization** * Only dashboards not marked as hidden will be visible to end customers on white-labeled sites. * The default dashboard remains mandatory and visible. 4. **Public Link Support** * Public links are only supported for the main (default) dashboard. *** ## How to Use ### Adding a New Dashboard 1. Navigate to the **Edit Mode** of your device dashboard. 2. Click the new **Add Dashboard** button. 3. In the modal that appears: * Provide a name for the new dashboard (e.g., "Service Dashboard"). * Toggle the option to **Hide this Dashboard on White Label** if required. 4. Click **Add Dashboard**. 5. Your new dashboard will appear as a separate tab alongside the default dashboard. ### Adding Widgets to a Dashboard 1. Select the dashboard you want to edit. 2. Use the **Add Widget** button to add widgets such as: * Device fields * Chart widgets * Text widgets * Downlinks (optional) 3. Configure the widgets to suit the purpose of the dashboard. ### Managing Dashboard Visibility * Dashboards marked as **Hidden on White Label** will not be visible to end customers accessing the white-labeled site. * You can manage visibility for each dashboard independently. *** ## Example Use Cases 1. **Service Dashboards** * Create dashboards with detailed, complex data for internal teams (e.g., service or management staff). * Hide these dashboards from end customers. 2. **Customer-Facing Dashboards** * Design dashboards specifically for end customers, ensuring simplicity and relevance. 3. **Hybrid Dashboards** * Create dashboards visible to both internal teams and customers, containing shared data. *** ## Limitations * The default dashboard cannot be removed and must always be visible. * Public links are only supported for the main (default) dashboard. # Widgets # Value Widget Learn how to use the Value Widget on Device and Global Dashboards ## Overview The value widget allows you to visualise data in an easy and straight forward way. Whether it is actual raw data coming in from your devices, or operations performed on data accumulated over a specific period of time.
## Configuration To configure your widget, enter your dashboard's edit mode, by clicking in the switch to the right of your screen. If you still don't have widgets, please select +Add widget. Search for your "Value widget" or you will find it under the "Display" category.
To edit the widget click on the pencil icon.
### Basics We now have some widget presets. Those will enlighten the whole configuration process, so if you find a preset that fits to your application, just select it. {% hint style="success" %} The title is also in the Basics section. If you don't fill it, the platform will automatically take the name of the field selected in the section "Data". You can proceed and use the placeholder { device\_name } inside of Global Dashboards to add the name of the device to the title as well. {% endhint %} ### Data To configure the value widget on a **device's dashboard** you will be able to select the Field you want to display on the Data tab. To configure your value widget within a **global dashboard** select the desired device and field. Inside of the Data tab you will also be able to configure the unit and decimal places (for float values). ### Appearance Under the tab Appearance you are able to setup: * **Value widget color based on state:** When you setup a Circular Gauge, the value on the widget with take the corresponding color. * **Hide background:** If you want the background to be transparent activate this option. * **Hide last update:** If you don't want to include the last time the device sent data. * **Abbreviate large values:** When a number field or a string is too large, this option will solve it. * **Show Range Legend:** When enabled, displays the gauge ranges as a legend next to the gauge. Only available when sufficient space is available. * Show current Range Name: When enabled it will appear under the value. It displays the current range name (e.g., 'Hot', 'Cold') as a coloured bubble on the gauge As visual setting you can configure: * Font size: Set maximum font size **for string values**. * Tint Color: Changes the color of the background on the widget. * Highlight Color: Changes the color of the Title on the widget. * Icon: Select from a list of icons one that represents that value the best. ### Gauge If you selected a Preset, you might have it easier to configure the gauge. The presets already set value ranges for different values, among with their colours and names. Feel free to change them according to your application/use case. You can select the **Gauge Type** options: Linear, Vertical, Circular, Fill Level, Compass or Gradient Ramp:
### Timeframe For a step-by-step guide on using the timeframe selection in our value widget to display consumption changes in your dashboards, be sure to check out our video tutorial ⬇️ {% embed url="" %} #### Current Value You can select Current Value, which will show you the last value sent by your device. #### Timerange Operation * Operation: When you select Timerange Operation you are able to select to display **Minimum, Maximum, Average, Sum, Change (absolute) or Change (percentage)** from your device's field in a specific time range. * From: You can use the following strings to define the starting period of your time range: `startOfHour, startOfDay, startOfYesterday, startOfWeek, startOfLastWeek, startOfMonth, startOfLastMonth, startOfYear, startOfLastYear, an hour ago, a day ago, 7 days ago, a week ago, a month ago, last year.` {% hint style="info" %} You can as well setup a specific date, however, take into consideration that the widget will have to make the operation using the datapoints generated in the time window set. {% endhint %} * Until: In most cases you will use the variable `now`, but you can also use the time ranges mentioned above to calculate e.g. consumption or maximum temperatures from yesterday, last week or other fixed time ranges. {% hint style="info" %} Always setup dates that exist! If the date you setup is in the future, probably no data is available. {% endhint %} * Timezone: Select between a list of timezones. If no timezone is selected, Datacake will take the timezone based on the browser's timezone, which means that customers around the world will be able to see the values in their own timezone. # Chart Widget Learn how to use the chart widget on Device and Global Dashboards. ## Overview The chart widget allows to visualise data using a graphical representation that tells how the fields have evolved within a period of time. It allows you to improve the understanding of large amounts of data.
You will find a quick guide to our chart widget here: {% embed url="" %} ## Configuration ### Basics & Data On Basics enter a desired Title. Underneath, add any additional language translations for the title you may want to include. Then on Data, select Add Field to configure the fields on your device that you want to display for **device dashboards**, or select Add Device to configure the device + field that you want to display for **global dashboards**. {% hint style="success" %} **Pro tip:** Once you configured the device's "Data" sources on your **Global Dashboard** Chart Widget, you can click on Save and see your chart widget in action. If you have more than one data source, you can click on the source's name (the field's name), which will help you filter out all other fields. {% endhint %}
#### Values Absolute & Change Once selected Fields or Devices, you can choose if you want to show absolute values coming from your devices or only the changes registered in the period of time setup under Timeframe. You can as well select to display both Absolute and Change. This might be useful for example, to monitor an electric consumption.
You can as well setup a label, the kind of graph you want to display (line chart, area chart or bar chart), the color, interpolation type and the Y Axis. {% hint style="info" %} When you select the line chart, it allows you to select the line thickness. {% endhint %} #### Interpolation type The interpolation types determine how data points are connected between measurements in a time series. The method chosen affects the appearance of the graph, particularly in areas where there are no data points, influencing the shape of the curve between known points. Here’s an explanation of each of the interpolation methods available on Datacake: 1\. Linear Interpolation * **How it works**: Linear interpolation draws straight lines between each pair of data points. * **Graph appearance**: It results in a piecewise linear graph with sharp transitions at each data point. * **When to use**: This is best when the changes between points are relatively simple and do not require smoothing. 2\. Natural Interpolation (Cubic Spline) * **How it works**: Natural interpolation creates a smooth curve using a piecewise cubic function that minimizes abrupt changes in the curve's slope. * **Graph appearance**: The curve is smooth and continuous with no sharp angles, and it adjusts naturally through the data points. * **When to use**: This is suitable when the data has a smooth, continuous trend, and you want a natural-looking curve that fits all points exactly. 3\. Basis Interpolation * **How it works**: Basis interpolation creates a smooth curve, similar to a spline, but it does not pass through all the data points. It’s more like an "average" path through the points. * **Graph appearance**: The result is a very smooth curve, but the curve may not touch the data points exactly. * **When to use**: Basis interpolation is ideal when you are more concerned with having a smooth-looking trend than exact accuracy to the data points. 4\. Monotone Interpolation (Monotonic Cubic Hermite) * **How it works**: Monotone interpolation ensures that the curve between points does not oscillate and preserves the original trend of the data, so the curve never overshoots the data points. * **Graph appearance**: It results in a smooth curve that respects the natural ups and downs of the data without creating peaks or valleys that don’t exist in the original data. * **When to use**: Best for time series data where it’s important to maintain the original trend without creating artificial extremes. It's ideal for data that should increase or decrease smoothly. 5\. Step Interpolation * **How it works**: Step interpolation creates a series of flat, horizontal steps between each pair of data points. The value stays constant between two points until the next point, where it jumps to the new value. * **Graph appearance**: The result is a graph with sharp, rectangular steps rather than smooth lines. * **When to use**: This is commonly used when data changes abruptly or you want to highlight the discrete jumps in value over time (e.g., stock prices or event-triggered data). #### Y Axis When you add more than one measurement to your chart widget, make sure to select a new axis for each one of them. This way you ensure that the values get plotted correctly. ### Appearance There are four toggle buttons which let you adjust the appearance of the Chart display. Choose to display or hide a button that lets a user export the current view. Displaying the timeframe selection on the widget allows a user to use default or create custom time stretches to show reporting field values. You may also hide the background to make it transparent, or hide the last update from the selected device. Here you may also select the Tint Color, which is the background color or the Highlight Color, which is the color of the Title. ### Axes You can define the Axis orientation (left or right), define a unit, hide de Y axis and define the domain. If you want you can hide the X axis as well. Make sure to define the Date Format on the X axis, since this is not done automatically once defined the Timeframe. A recently introduced feature is a toggle switch that enables color filling in the bar chart based on specific values. As illustrated below, you can assign different colors to as many values as needed.
You may also change the date format here using the dropdown menu. ### Timeframe The chart widget comes with a time range presets, similar to the value widget, that can be overridden. Here a small list of the options you can use on both "From" and "Until": 1. `startOfHour` 2. `startOfDay` 3. `startOfYesterday` 4. `startOfWeek` 5. `startOfLastWeek` 6. `startOfMonth` 7. `startOfLastMonth` 8. `startOfYear` 9. `startOfLastYear` 10. `a minute ago` 11. `an hour ago` 12. `a day ago` 13. `7 days ago` 14. `a week ago` 15. `a month ago` 16. `last year` 17. `now` {% hint style="warning" %} You can as well setup a specific date, however, take into consideration that the widget will have to make the operation using the datapoints generated in the time window set. This can have extremely high calculation costs, which will result in degradation of the performance of your dashboards. {% endhint %} {% hint style="warning" %} Always setup dates that exist! If the date you setup is in the future, the widget won't be able to find the data and the dashboard will crash. {% endhint %} * Resolution: You will find an additional parameter to specify the resolution in which the data is displayed on the widget. This settings specifies the time window size in which the datapoints within the given time range will be fetched from the database. {% hint style="warning" %} A high resolution leads to significantly longer loading times, since the data must first be retrieved from the server. We therefore suggest setting up daily trends with a higher resolution, in case needed and only weekly or monthly overviews with lower resolution. This will improve the overall performance of your workspaces. {% endhint %} {% hint style="info" %} Remember Datacake has a time-series database that does not store all entries, but optimises the storage by taking chunks of it and relating them to a timestamp. This enables the platform to fetch information very quickly and improve the overall performance of the visualisation. {% endhint %} * Timezone: Select between a list of timezones. If no timezone is selected, Datacake will take the timezone based on the browser's timezone, which means that customers around the world will be able to see the values in their own timezone. In the following video, we explain best practices for setting up time ranges on chart widgets, if you want further information. {% embed url="" %} ### Reference Lines You can add reference lines on the charts, to be able to compare, reference or observe the values being stored in the database with a defined value. This will be represented as an horizontal line in the chart. You can define the color, select if the line should be solid or dashed, setup the value as well as a title (Line Text). ## Events #### Introduction Datacake now offers a new feature in the chart widget that allows you to display events. This functionality enhances data visualization by enabling users to represent boolean field changes (events) on their charts. Below, we provide a step-by-step guide to using this feature.
*** ### Supported Devices and Events This feature is particularly useful for devices generating events based on sensor values. For example: * **CO2 Monitor, Flood Sensor, Parking Space, Events**: Monitors environmental parameters such as temperature, CO2 levels, humidity, light, and mold risk. * Events like general alerts, CO2 alerts, temperature alerts, and humidity alerts can be derived and displayed as boolean values. * **Everything that has a boolean field.** Boolean fields indicate specific conditions, such as whether an alert is active (`true`) or inactive (`false`). *** ### Steps to Display Events on the Chart Widget #### 1. Configuring Events 1. **Access the Events Tab**: * In the chart editor, locate the **Events** tab, positioned next to **Reference Lines**. 2. **Add an Event Source**: * Click the **Add** button to create a new event. * Select a boolean field (e.g., `Motion Alert`) as the event source. 3. **Customize Event Display**: * Change the line thickness, color, and type. * Optionally, add a label (e.g., "Motion") for clarity. *** #### 2. Fine-Tuning Event Properties * **Adjust Time Frame**: * Use the time frame selector to display events over a specific duration (e.g., one day or one week). * **Define Event Points**: * **Start**: Marks when the boolean field becomes `true`. * **End**: Marks when the boolean field becomes `false`. * **Start and End**: Displays both the starting and ending points of the event. * **Color and Style**: * Customize event lines with different colors and styles for better visualization. #### Coloring both Start and End individually
### Example Use Case: Monitoring Motion Alerts 1. Add a **Motion Alert** as the boolean field source. 2. Display the motion alert as a line event on the chart: * Set the thickness and color. * Add a label (e.g., "Motion"). 3. Observe the motion alert events, aligned with the selected time frame, on the chart. *** ### Benefits of Event Display on the Chart Widget * Improved visualization of boolean-based events. * Clear representation of alert start and end points. * Flexibility to overlay multiple event sources on the same chart. *** ### Time Slots This tab helps you visually plan different times of the day—for example, to show work shifts. In the "Edit Time" mode, simply click and drag across the calendar to quickly set the time blocks you need. You can select different colours to represent different time slots. ### Conclusion Displaying events on the chart widget provides a powerful way to visualize alerts and changes in your IoT data. By leveraging boolean fields, you can effectively represent event-driven insights directly on your dashboards. For further assistance, explore our documentation or contact support. Thank you for using Datacake! # Image Map Place your sensors on floor plans and other images. ## Overview The Image Map widget allows you to put your sensors on images, such as: * Floor Plans * Industrial Flow Charts * Any other kind of map or plan ![](/files/LLTxT6VocaEzNCTPMsgT) ![](/files/eSILhiL3GbSEdMjSICyO) ![](/files/LRJngUrmw06fhTRb0VrV) ## Basics ### Title You can set a custom title for your image map widget. ### Upload Image By clicking on the change button of an image map widget you can upload a custom image into the widget. ![](/files/PzgjLNTPX7WcWjmUy5zD) #### Supported Images * JPG * PNG ### Delete or Change Image Simply upload a new image to override the existing one. ## Add Sensors or Devices In order to add your Datacake Devices to an Image Map Widget you need to navigate into the "Data" tab. We have created a short video that shows you how you can add Sensors to your images. Please have a look at the following video: {% embed url="" %} How to Add Sensors to Image Map Widget {% endembed %} ### Choose Device Using a drop-down you can select one of the devices from your current workspace. ### Select Field Next, you have to select the field which you want to display. #### Supported Types Currently, we support the following field types: * Integer, Float (Numerical) * String * Boolean States ### Set Label You can also set a custom label which will be shown when you hover over an icon on the image map widget. Default is set to Field Name. ### Set Unit Optionally you can also provide a unit to the value. ### Edit Position In order to place an icon on the map, you have to click on the "Edit Position" Button. ![](/files/FQaDuOBkooR4IFnMe1hn) This will open up another view of the image where you can drag the icon to any position within the image map widget. #### Icon Size In the position editor, you also find a slider that allows you to change the size of the device widget on the map. ### Edit Appearance #### Numerical Values By enabling the option "Marker color based on state" you can define a value range and color for the icon. The icon border is colorized based on the colors you define here. #### Boolean When the selected field is of type "Boolean" you can set a text and color for either the True or False state of that field. ## Appearance The Image Map Widget supports overriding a few of the default appearance settings. ![](/files/khKsdbKhyikuX1XgEGht) ### Change Colors You can override the default colors. #### Text Color Sets an individual color for the text of an icon. {% hint style="info" %} This is not valid for Boolean Fields. Colors you set on boolean appearance will override these settings. {% endhint %} #### Icon Color Sets an individual color for the icon background color. The default is black. You might want to use brighter colors for darker images and vice versa. ### Public Dashboards By enabling the "Show Device Details on public Dashboards" option, you allow Device Icons on Images to be clickable on a publically shared Dashboard. ### Full Height Images By enabling this your Image Map Widget will always scale to the maximum height possible, no matter which height you have set on the dashboards designer. {% hint style="warning" %} Please make sure you don't place any widgets below the Image Map when enabling this option as they would be covered by the full height option. {% endhint %} # Map Widget Quick-Start and Reference to the Datacake Map Widget ## Overview The Datacake Dashboard Editor features a widget to show one or many positions, including the option to show historical routes and interactivity. ![](/files/Ee5hqcSrG7w9fvAWoOJa) ![](/files/W6ntdpVEqSpHj1IZYtLG) ![](/files/bhxzFtRa9XwbEILFSff2) ## Working with Maps In order to start with a map widget, you need to add it to a dashboard. The map widget works like mostly all of the widgets on both device and workspace dashboards. ### Placing a Map Bring your dashboard editor into edit mode and add a new widget. This will open up the widget picker and in here you select the "Map" widget type. ![](/files/vnF31msn5sZiOfOdtapZ) This will add the widget to the dashboard and it will open up the widget editor.
### Geolocation Data & Device Location role Map Widgets only support database fields of the type "Geolocation". Most of your devices do have a location field available. If you want to learn more about geolocation data types please head over to the database section of this documentation. It is necessary that you set the role of that Geolocation field as Device Location. For that, go to your device's configuration. Under fields select Edit Field and set the Semantic to Location.
## Adding Data The location data from your devices that posses a geolocation field will be automatically fed to the map widget. However, if you want to filter which devices get to be shown on a map, you can use tags to select the devices to be shown.
### Any tag or All tags The option "Any tag" represents an OR function, which means that the map widget will display all devices that have any of the selected tags picked from the drop-down-list above. The option All tags performs an AND function, which means the map will display the devices that have all tags selected on the drop-down-list. *** ## Markers The **Markers** tab in the updated **Map Widget** allows you to control what information appears on each device marker displayed on the map. This helps users quickly identify device status, sensor readings, or key operational values at a glance. *** ### **Marker Value** The **Marker Value** setting determines *which field from your device* is shown directly on the map marker. This value is pulled from the Device Fields Configuration and can be any field you have semantically defined. #### **What it Displays** You can choose from any of the following semantic field types: * **Device Signal**\ Shows the device’s current connection or RSSI/signal strength value. * **Device Battery**\ Displays the battery level of the device (percentage or voltage, depending on device configuration). * **Primary Field**\ The field you have designated as the **Primary Value** in your device’s field configuration.\ This is typically the most important sensor reading (e.g., temperature, tank level, position accuracy). * **Secondary Field**\ The field you set as the **Secondary Value**.\ This might be an additional reading that complements the primary data (e.g., humidity, secondary sensor metrics).
You may edit these values by navigating to your device --> Configuration tab --> Field settings. #### **Marker Mode** In **Marker Mode**, each device appears on the map as an individual marker. This mode is ideal when you want to: * Display device values directly on the map * See detailed information per device * Use color or gradients to highlight device states * Show or hide device names * Cluster or separate markers Marker values (e.g., signal, battery, primary/secondary fields) can be configured under the **Markers** section. #### **Heatmap Mode** Switching to **Heatmap Mode** changes the visualization from individual markers to a density-based heatmap. This is useful when: * A large number of devices overlap geographically * You want to identify hotspots of activity or presence * Individual device values are less important than spatial distribution Heatmap mode emphasizes **density**, not per-device metadata.
## **Marker Customization Options** Below the Map Mode dropdown are several toggles that allow you to tailor how device markers appear. **Show Device Name** **Enabling this toggle displays each device's name next to its marker** on the map. Use this when: * Devices are sparsely distributed * Identification of specific devices is important * You prefer human-readable labels instead of numeric or sensor-based values Turn it off to reduce visual clutter when many devices overlap. *** #### **Disable Clustering** By default, markers that appear close together are grouped into a **cluster bubble**.\ **Enabling “Disable Clustering” forces each device to appear individually**, even when tightly grouped. Useful for: * Precise spatial inspection * Debugging device position accuracy * Maps with small device counts Not recommended for dense deployments due to readability issues. *** #### **Color Markers Based on Device Values** This option colors each marker based on the **Marker Value** you have selected (e.g., temperature, battery, signal). What it does: * Applies a color scale (e.g., low → high) * Gives quick visual insight into device status * Useful for dashboards focused on trends or anomalies If your marker value is a semantic field like **battery** or **signal**, colorization becomes especially meaningful. *** #### **Use Value-Based Text Colors** When enabled, the **text inside the marker (the value)** changes color based on the selected value scale. This is helpful when: * You want dual visibility: colored marker + colored text * Markers are small, and text color helps differentiate state Works best when used together with colorized markers. *** #### **Use Gradient Color Transitions** This toggle enables smooth color transitions instead of fixed color blocks. #### Benefits: * More visually appealing data gradient * Easier to distinguish subtle differences * Ideal for metrics with wide numeric ranges (e.g., temperature, CO₂ levels) Gradient transitions apply to marker color when **Color Markers Based on Device Values** is active. #### **Marker Size** Select the default marker size (Small–X-Large). This setting is used when dynamic sizing is disabled. *** #### **Use Dynamic Sizing** Enables automatic marker size scaling based on the selected **Marker Value**. * **Dynamic Sizing Start** – The smallest marker size in the scale * **Dynamic Sizing End** – The largest marker size in the scale Marker sizes adjust proportionally according to the device’s value. *** #### **Marker Transparency** Controls how opaque the markers appear on the map.\ Lower percentages make markers solid; higher percentages increase transparency. *** #### **Enable Marker Blending** When enabled, overlapping markers visually blend together. This makes dense areas easier to interpret. *** #### **Display On Color** Sets the color (and optional text label) for markers when they represent an **active/true/on** state. #### **Display Off Color** Sets the color (and optional text label) for markers when they represent an **inactive/false/off** state. *** ## **Map Tab** The **Map** tab controls the starting position and visual style of the map displayed in your widget.
*** ### **Manual Start Location** When enabled, you can manually set the initial center position and zoom level of the map.\ The widget will always load using this defined starting view, regardless of device locations. When disabled, the map automatically adjusts to fit all displayed devices. *** ### **Map Style** Choose the visual style for the map background. Available styles include: * **Light** – Clean, bright map with minimal contrast * **Dark** – Dark-themed map ideal for dashboards with darker UI * **Streets** – Detailed street-level mapping * **Outdoor** – Terrain-focused style suitable for environmental or field deployments * **Satellite** – High-resolution satellite imagery * **Basic** – Simplified map with essential geographic outlines Selecting a style updates the appearance immediately in the preview at the top.
*** ## Appearance The Appearance section allows you to control behaviour and override default settings such as colours or set a different icon. *** ### Show Device Details on Public Dashboard Tint Color Colorises the widget itself.
### **Show Device Details on Public Dashboard** When enabled, device details (such as name and values) will be visible to anyone viewing a **public** dashboard.\ Disable this option if you want to keep device information private. *** ### **Hide Background** Removes the widget’s background panel, allowing the map to blend with the dashboard behind it.\ Useful when creating clean or minimal dashboard layouts. *** ### **Show Filtering Panel** Displays a filter panel at the top of the widget, allowing users to filter the devices shown on the map (e.g., by tags).\ Turn this off if you prefer a minimal, uncluttered widget. ### Full Height Maps Sometimes you just want to have a single map on a dashboard, and you may want to display it in fullscreen on a wide variety of screen sizes. However, since our dashboard designer is grid-based, this is not directly possible, as the grids represent an absolute height. Even if you place and scale the widget on the grid in a way that it fully extends to the bottom of your screen, it won't do that on a different screen. ![](/files/2FG3btJoWfhMrOXD1XRV) To work around this we have added an option to the map widget that allows you to have the map widget automatically scale to the bottom of the browser window. In the Appearance section on the map widget settings, you can find an option called "Use full screen height".
After enabling this option and exiting the edit mode of the dashboard editor, the map widget will autoscale to the bottom of the available screen size and/or browser window. ![](/files/T6D6l4hM55Zsb1kVsaDU) #### Placing additional Widgets {% hint style="info" %} You just have to make sure that no other widget is below the map widget. They would stay in their position and be overdrawn by the automatically scaling map widget. {% endhint %} Placing Widgets above, left, or right next to the map widget is no problem. #### Creating a Heatmap You now have the ability to create a heatmap directly from the Map widget and colour it based on the conditions of your sensors. Below is a tutorial on how to achieve this:
{% embed url="" %} ### Sidebar Dashboards When you click on a device on a map, the so-called sidebar menu shows on the right side of the browser window. ![](/files/W6ntdpVEqSpHj1IZYtLG) #### Editing Sidebar Dashboards For the display of the sidebar dashboard, we use the mobile dashboard layout of a device. This means that you can create or customize the Sidebar Dashboard yourself. To do this, you have to activate the edit mode of the dashboard in your device and activate the mobile layout. ![](/files/viuTszBvGDhIxZMLK1XJ) #### Sidebar Dashboards on Public Dashboard If you share your global workspace dashboards with others and you want to use the sidebar dashboard feature, you have to enable this first. To do so, please access the "Appearance" view using the tab bar on the widget editor and enable the option "**Show Device Details on Public Dashboard**" just as shown in the following screenshot. ![](/files/nhMy13F59v9tdcxgquNA)
## Historical Data **Only** the map widget on your **Device's dashboard** allows you to show historical geolocation data in the form of "routes". You can enable this setting in the map widget editor, under Timeframe. This will unfold a time frame picker and you only need to select one of the available time frame presets.
### High-Resolution Routes If you select one of our presets we define the number of data points shown on the map, so for example if you select "Day" as a time frame preset we only show a new data point on the map when 15 minutes have passed to the previous one. This can lead to the fact that we are skipping important route points. {% hint style="info" %} To manually override the resolution parameter please first select a time frame preset and additionally click on "custom". This will open up an editor where you can set the resolution down to as low as 1 minute. {% endhint %} ![](/files/tUBr4iJlI2fBcZ6fsi9o) # Menu Widget Welcome to the Datacake Menu Widget tutorial! This guide walks you through how to use the Menu Widget to create custom navigation systems inside your Datacake dashboards. The Menu Widget allows you to redirect customers to internal dashboards, external websites, documentation portals, support pages, and more, helping you build a seamless customer navigation experience. ## Getting Started with the Menu Widget To begin, navigate to your dashboard in Datacake and enter edit mode by clicking on the **Edit Mode** button. Once enabled, you’ll be able to add and configure widgets on your dashboard. *** ## Adding a Menu Widget 1. Click the **Add Widget** button. 2. The widget picker modal will appear. 3. Select the **Menu** widget to continue. The Menu Widget can be found under the general widget collection. Selecting the Menu Widget *** ## Configuring Your Menu Widget After selecting the Menu Widget, you’ll be taken to the widget editor where you can configure your navigation menu. The editor is divided into three sections: * **Content** * **Layout** * **Colours** *** ## Creating Navigation Entries Inside the **Content** tab, you can create custom navigation items. Each navigation entry supports: * A custom label * A destination URL * An icon * Optional “Open in New Tab” behaviour so URLs aren't loaded in the same screen You can use these links to direct users to: * Other Datacake dashboards * External websites * Documentation portals * Customer support systems * Internal tools To add a new navigation item, click the **Add** button at the bottom of the editor. Navigation Entries *** ## Configuring Navigation Links For every menu item, configure the following: ### Label The visible text displayed in the navigation menu. Examples: * Home * Dashboard * Documentation * Support *** ### URL The destination URL users will be redirected to when clicking the navigation item. Examples: * `https://example.com` {% hint style="warning" %} Please make sure the *full* URL address is pasted, otherwise the navigation may not work correctly. {% endhint %} *** ### Open in New Tab Enable this option if you want external links to open in a separate browser tab. This is especially useful for: * Documentation portals * External company websites * Support systems *** ## Layout Configuration The **Layout** tab allows you to control how the navigation menu is displayed on the dashboard. Available layout options: * **Sidebar (Vertical)**\ Displays navigation items vertically. * **Top Bar (Horizontal)**\ Displays navigation items horizontally. You can also adjust the navigation font size to better match your dashboard design. Layout Settings *** ## Styling and Customisation The **Colours** tab allows you to customise the appearance of the Menu Widget to match your dashboard branding. Available styling options include: * Background Colour * Link Text Colour * Hover Background Colour * Hide Background Toggle These settings make it possible to create fully branded customer navigation systems. Colour Settings *** ## Example Use Cases The Menu Widget can be used in a variety of ways: * Creating navigation between multiple dashboards * Building customer portal navigation * Linking to documentation websites * Redirecting users to support systems * Creating white-labeled customer experiences * Linking external tools and applications *** ## Best Practices ### Keep Labels Short Use short and descriptive labels to improve readability and navigation clarity. Good examples include: * Home * Devices * Reports * Documentation * Support *** ### Use Icons Consistently Using consistent icons helps customers quickly identify navigation destinations. *** ### Open External URLs in New Tabs For external websites and portals, enabling **Open in New Tab** provides a smoother dashboard experience. *** ### Match Your Branding Use the colour customisation settings to align the Menu Widget with your company branding and dashboard theme. *** ## Workspace Dashboard Support The Menu Widget can also be used inside workspace dashboards. This allows you to create centralised navigation systems that link: * Multiple dashboards * Workspace pages * Documentation portals * External applications This is especially useful for enterprise and customer-facing dashboard environments. *** ## Saving Your Widget Once you’ve finished configuring your Menu Widget: 1. Click **Save** inside the widget editor. 2. Rearrange the widget as needed on your dashboard. 3. Exit edit mode to publish your changes. # Text Widget A concise guide on using Datacake's Text Widget to create custom, sensor-integrated dashboard widgets with markdown support. ## Datacake Text Widget Welcome to the Datacake Text Widget tutorial! This guide will walk you through the process of leveraging the Text Widget in Datacake to create custom widgets on your dashboard. The Text Widget supports markdown and the inclusion of sensor values like humidity, temperature, and more, allowing you to design widgets tailored to your needs. ## Video Watch an interactive tutorial on using the text widget in this video. {% embed url="" %} ## Getting Started with the Text Widget To begin, navigate to your device dashboard on Datacake and enter edit mode by clicking on the "Edit Mode" button. The dashboard will switch to edit mode, enabling you to add new widgets. ### Adding a Text Widget 1. Click on the "Add Widget" button, represented by a blue button. 2. A modal will appear, displaying the widget picker. Select the "Text Widget" to proceed. 3. You'll be directed to the Text Widget editor, where you can provide your text and see a preview. The editor supports basic markdown, allowing you to include headlines, bullet point lists, and various text styles. ### Configuring Your Text Widget * **Markdown Usage**: Utilize markdown to structure your content with headlines, lists, and text formatting. * **Saving**: Once you've finished editing, click "Save" to add the widget to your dashboard. You can rearrange your widgets as needed. To save your changes and exit edit mode, click the now yellow "Exit Edit Mode" button. ### Including Sensor Values Datacake allows you to integrate real-time sensor data into your Text Widget: 1. Re-enter edit mode and click on the pencil icon of the Text Widget to edit it. 2. To include sensor values, start by giving your section a title, like "Sensor Overview". 3. As you type a sensor name (e.g., "Temperature"), Datacake suggests fields matching your input. Select the desired field to include it. 4. You can also specify units for each sensor value to provide clear information (e.g., degrees Celsius for temperature, % for humidity). ### Styling and Customization * **Markdown for Styling**: Enhance the presentation by using markdown to bold important figures or organize data efficiently. * **Experimentation**: The flexibility of the Text Widget and markdown allows for a range of visual customizations, encouraging experimentation. ### Workspace Dashboard Widgets Creating Text Widgets in a workspace dashboard involves an additional step: 1. Add a new dashboard via the sidebar and name it (e.g., "Text Widget Demo"). 2. In the workspace dashboard, when adding a Text Widget, you must include the devices from which you want to access measurement values. 3. After specifying devices, you can proceed to write your content and include sensor values as described above. ## Support and Feedback If you encounter any issues or have questions while setting up your Text Widget, feel free to reach out to Datacake support. We value your feedback and are here to assist with any inquiries. Thank you for following this tutorial on how to effectively use the Text Widget in Datacake. Stay tuned for more tips and updates! # SOS Widget The SOS Widget is an interactive feature designed to display the status of alarm devices, particularly useful for devices like the IO Things IO Button. This widget provides a clear visual indicator when an SOS signal is received, and includes a unique interactive feature for managing the SOS state.
## Key Features * **Interactive Boolean Display**: The SOS Widget functions similarly to a Boolean widget, displaying `true` or `false` states. However, it includes additional interactive capabilities. * **SOS State Indicator**: When a device sends a `true` value for the SOS field, the widget displays this as an active SOS state, alerting operators to an emergency. * **Clear Button**: Unique to the SOS Widget is the "Clear" button. This button allows operators to manually reset the SOS state. Upon clicking, the selected field's value is set to `false`, clearing the SOS alert on the widget. ## Usage 1. **SOS Signal**: When an SOS device, such as the IO Button, sends a `true` value indicating an SOS event, the SOS Widget will display this state on the dashboard. 2. **Resetting SOS State**: To acknowledge and clear the SOS alert, an operator can click the "Clear" button on the widget. This action sends a `false` value to the field, resetting the SOS state displayed. ## Application The SOS Widget is ideal for monitoring emergency signals from devices that do not automatically reset their SOS status. It provides a reliable method for operators to manage and document the resolution of SOS events. ## Video Watch an interactive tutorial on using the SOS widget in this video. {% embed url="" %} # Boolean Widget The Boolean Widget in Datacake is a simple yet powerful tool designed to display binary data, where the value can be either `true` or `false`. This widget is ideal for representing data points such as device status, switch states, or any other binary indicators. By offering customizable settings, the Boolean Widget allows you to clearly and visually present the status of your devices or systems on your dashboard.
You will find a quick guide to our boolean widget here: {% embed url="" %} ## **Configuring the Boolean Widget** ## **1. Basics** **Title** * **Purpose:** The title helps you identify the widget on your dashboard. * **How to Configure:** Enter the desired title in the "Title" field during the widget setup. This title will be displayed above the widget on the dashboard. **Icon** * **Purpose:** Customize the widget’s appearance to match your dashboard’s theme or to emphasize the use case. * **How to Configure:** In the basic settings, you can choose different icons. #### **2. Data Source Selection** You can select the device and field. You will notice that only Boolean Fields are available in the selector. This restriction ensures that the widget functions correctly by displaying either `true` or `false` values. #### **3. Appearance Settings** **Display On Text & Display Off Text** "On" can be understood as when the boolean value is on a "True" state (1). "Off" can be understoos as when the boolean value is on a "False" state (0). For each case, it might mean different things (In some cases "False" can mean a positive thing, e.g. Open door = False, being positive). You may want to personalise the text displayed on the widget. **Widget color based on state** When enabling, the whole widget appears in the colour set below. **Display On Color & Display Off Color** You can set specific colours for when the value is `true` and different colours for when the value is `false`. This is helpful for making important states more noticeable (e.g., green for true, red for false). ### **Example Use Cases** * **Device Status Monitoring:** Display whether a device is online (true) or offline (false). * **System Alarms:** Indicate whether a system alarm is active (true) or inactive (false). * **Switch State Representation:** Show the state of a physical or virtual switch as on (true) or off (false). * **Door status** * **Parking spot availability** # iFrame Widget ## **Overview** The iFrame widget in Datacake is a versatile tool that allows you to embed external content directly into your dashboard. Whether it's a website, a live data feed, or any web-based application that supports iFrame embedding, this widget enables seamless integration and display within your Datacake environment.
You will find a quick guide to our iFrame widget here: {% embed url="" %} ### **Adding the iFrame Widget** To add the iFrame widget to your dashboard, follow these steps: 1. **Navigate to your dashboard**: Open the dashboard where you want to add the iFrame widget. 2. **Add a new widget**: Click on the 'Add Widget' button at the top of your dashboard. 3. **Select iFrame Widget**: From the list of available widgets, choose the iFrame widget. ### **Configuring the Basics** Once the iFrame widget is added to your dashboard, you'll need to configure it: 1. **Set the Title**: In the settings panel, you will see an option to give your widget a title. 2. **Enter the Source URL**: Paste the URL of the website or application you want to embed into the 'Source' field. Ensure that the site supports embedding in an iFrame; otherwise, it may not display correctly.
### **Appearance** The iFrame widget offers several customization options to ensure it fits perfectly with your dashboard's design: 1. **Tint Color**: You can change the background color of the widget card to match your dashboard’s theme. 2. **Hide Background**: For a cleaner, more streamlined look, you can choose to hide the background of the iFrame widget. 3. **Full Screen Height**: You can set the widget to use the full screen height, which is particularly useful if the iFrame is the only widget on your dashboard. ### **Practical Use Cases** The iFrame widget can be used in various scenarios to enhance your dashboard: * **Real-Time Weather Reports**: Embed a live weather report from a weather website to keep track of weather conditions. * **Google Maps**: Integrate a Google Map to display a specific location or provide interactive navigation. * **Live Data Feeds**: Embed a live data feed from an external source, such as stock prices or IoT device status, for real-time monitoring. ### **Troubleshooting and Tips** * **iFrame Restrictions**: Some websites may have restrictions that prevent their content from being embedded in an iFrame. If you encounter this issue, consider using another source or contacting the website administrator. * **Responsive Design**: Ensure that the website or application you're embedding is responsive so that it displays correctly across different devices and screen sizes. * **Testing**: Always test the iFrame widget after embedding to ensure it displays and functions as expected within your dashboard. # Downlink Widget ## **Overview** The Downlink Widget in Datacake allows you to send commands or data directly to your IoT devices from your dashboard. This powerful tool is essential for interacting with your devices, enabling you to trigger actions, change settings, or send data remotely. This documentation will guide you through setting up the widget, configuring its data source, customizing its appearance, and making the most out of this feature.
### **Key Features** * **Direct Device Interaction**: Send downlink messages to trigger actions or change settings on your devices. * **Confirmed Downlink**: Integrated into Datacake's LNS (LoRaWAN Network Server), as well as the Actility integration to ensure commands are successfully received by the device, reducing the need for redundancy. * **Customizable Appearance**: Tailor the widget's look to match your dashboard's theme. ## Video Watch an interactive tutorial on using the downlink widget in this video. {% embed url="" %} ## **Setting Up the Downlink Widget** ### **1. Adding the Downlink Widget to Your Dashboard** To add the Downlink Widget: 1. **Navigate to your Dashboard**: Open the dashboard where you want to add the widget. 2. **Add a New Widget**: Click on the 'Add Widget' button. 3. **Select the Downlink Widget**: From the list of available widgets, choose the Downlink Widget. The widget will now appear on your dashboard, ready for configuration. ### **2. Configuring the Widget** * **Set a Title**: Assign a title to your widget that reflects its purpose or the device it controls. Examples include "Interval = 1 min" or "Reboot". * **Select Data Source**: Choose the device you want to send the downlink to. The widget will display a list of devices with available downlink definitions. Select the appropriate device and downlink command. * **Multiple Devices**: Datacake allows you to control multiple downlinks with a single button. To do this, click on “+Add” and select additional devices and downlinks.
### **3. Customizing Appearance** Under the 'Appearance' tab, you can customize the look of your Downlink Widget: * **Tint Color**: Adjust the background color of the widget card to align with your dashboard's theme. * **Highlight Color**: Change the font color to ensure visibility, especially if using a darker tint color. * **Hide Background**: For a more minimalist appearance, you can hide the widget's background, allowing it to blend seamlessly with your dashboard. Test the widget by clicking on it to send the selected downlink command. If configured correctly, your device should respond, and the widget will confirm that the command was sent successfully. ## **Tips and Best Practices** * **Ensure Proper Configuration**: Verify that your downlink definitions are correctly set up on the device side for smooth communication. * **Regular Testing**: Regularly test your downlinks to ensure they function as expected. * **Use Appearance Customization**: Customize the appearance of your widget to make your dashboard not only functional but also visually appealing. # Set Value Widget ## **Overview** The Set Value Widget in Datacake provides an easy way to manually update a specific field of a device directly from the dashboard. This widget is useful for setting or adjusting values in real time, making it an efficient tool for interactive control over device parameters. ## Video Watch an interactive tutorial on using the Set Value widget in this video. ## **Setting Up the Set Value Widget** To get started, add the Set Value Widget to your dashboard. This widget allows you to set values manually, making it ideal for applications where you need to adjust device settings on demand.
### **What should you configure?** * **Title**: In the Basics section, you can customise the title of your widget. This could be specific to the function you’ll be controlling, such as "Set Target Temperature" or "Set Driver," to make it clear what the widget is for. {% hint style="info" %} Pro tip: You can add a Value Widget next to the Set Value Widget. That will allow you control the value that was set via the Set Value Widget. {% endhint %} * **Data Source**: Under the Data section, select the device and the field that you want to control. This selection enables you to target exactly the value that needs updating, giving you precise control over the device’s settings from the dashboard. * The Appearance tab offers color customisation, allowing you to change the widget’s color scheme. ### **Using the Reset Feature** The SOS widget includes a reset function, allowing users to deactivate the alarm directly from the dashboard. This feature is ideal for managing alerts and ensuring that alarms return to a default state after being addressed. ## **Practical Use Cases** **1. Temperature and Environment Control:** In environmental applications, the Set Value Widget can be used to set target temperatures, humidity levels, or other environmental conditions for devices like climate controllers, HVAC systems, or smart thermostats. **2. Threshold Adjustments:** Use the widget to update operational thresholds for monitoring systems. For example, in an industrial setting, it could adjust the threshold for alerts related to machinery performance, such as vibration or temperature limits. **3. Irrigation or Resource Management:** In agriculture, the widget could control irrigation systems by setting watering intervals or duration, allowing precise management of resource allocation based on crop needs. **4. Lighting and Energy Management:** The widget can be used in building management to set lighting intensity levels or energy-saving thresholds, enabling quick adjustments to optimize energy use. # Measurement List Widget The Measurement List Widget allows you to display historical data with timestamps directly on your dashboard. It is ideal for tracking sensor readings, monitoring system performance, and analysing trends over time.
It is available on both device and global dashboards. ## **Configuration** Once you’ve added the widget, a configuration menu will appear with the following tabs: **1. Basics** * Add your widget's title. This will help you identify the data source or the type of data displayed in it. * You can add translations of that title. 2. Data * Select the device from which you want to pull data. * On device dashboards, simply select the data field you want to display. On global dashboards you can select the device and the field you want to display. * You may also control here how many rows of data are displayed per page on your widget. * Toggle whether or not you would like to colour values or booleans based on ranges you provide * You can highlight different value ranges or different booleans (True or False) to correspond with preferred results. * For the Custom Booleans, you can customise exactly what your True and False represent * For example, you can set a range of undesirable temperature ranges as Red, and desirable target temperatures as Green:
* The widget will automatically populate with historical values and their corresponding timestamps. ## **Practical Applications** * **Trend Analysis:** Easily identify patterns in your data over time. * **Anomaly Detection:** Quickly spot any irregularities in the data. * **Historical Review:** Keep an eye on past readings for deeper insights. # Heatmap Widget ## Introduction The Heatmap Widget is a newly released feature for the Datacake IoT platform. It is available for both **device dashboards** and **workspace dashboards** and provides a visual representation of data over time using color gradients. This document outlines how to set up and configure the Heatmap Widget. ### Video What is better than 1000 words? Correct, a video! {% embed url="" %} *** ## Adding the Heatmap Widget To add the Heatmap Widget to your dashboard: 1. **Enable Edit Mode**: Open your dashboard and activate the edit mode. 2. **Add a New Widget**: Click on **"Add Widget"**. 3. **Select Heatmap Widget**: Scroll down and select the **"Heatmap"** widget. 4. **Configure Basic Settings**: * Enter a **Title** for the widget. * Provide **translations** (optional). *** ## Configuring Data Sources 1. **Select Data Source Mode - Static Devices**: * Choose the device fields to display. * Example: Select **Temperature**, **Max Temperature**, and **Min Temperature**. 2. **Select Data Source Mode - Semantics:** 1. Choose a semantic field to display 2. Example: select CO2, then further filter the devices that report on CO2 by tag 3. **Save Configuration** to apply the changes. *** ## Timeframe 1. Open the widget **Configuration**. 2. Click on **"Timeframe"**. 3. Choose between: * **Hourly**: Each cell represents an **hour**. * **Daily**: Each cell represents a **day**. *** ## Appearance Settings 1. **Cell Size**: * **Small**: Ideal for large datasets. * **Normal**: Displays numeric values inside the cells. 2. **Adjust the number of cells:** * Example: Set to **14 days** to show the last 14 days of data. * If data storage is limited (e.g., 7 days), older cells will appear empty. 3. **Custom Colorization**: * Define specific thresholds for color mapping. * Example: * **-10°C** = Blue (Cold) * **15°C** = Green (Moderate) * **35°C** = Red (Hot) * Adjust values as needed to improve readability. #### Mark stale data By default, every cell in the heatmap shows the most recent measurement that falls inside its bucket. When a device stops reporting, for example because it goes offline, runs out of battery, or loses connectivity, Datacake will keep filling the cells with the last known value so the heatmap remains continuous. Visually this can look identical to a device that is reporting steadily, even though no new data has arrived in hours or days. Enable **Mark stale data** to make those forward-filled cells stand out: * Cells that contain a fresh measurement render normally. * Cells that simply repeat the last known value are drawn with a diagonal hatched overlay and a slightly dimmed value label. * Hovering a stale cell shows an additional tooltip line ("No new measurement in this period") so you can tell at a glance which periods are real and which are filled forward. This is especially useful for: * Spotting offline devices on dashboards that compare many sensors side by side, a stretch of hatched cells on the right edge of a row immediately signals "this device stopped reporting". * Investigating gaps in long timeframes (e.g. a 30-day temperature heatmap) where missing readings would otherwise blend into the surrounding values. * SLA / uptime reviews, where the difference between "the value is stable" and "the device hasn't checked in" matters. The toggle defaults to off, so existing dashboards keep their current look until you opt in. You can switch it on per heatmap widget under the Appearance tab in the widget settings. {% hint style="info" %} Cells with no value at all (for example, when no forward-fill is available) stay blank. The stale indicator only applies to cells that do show a value but that value is repeated from an earlier reading. The widget's "Last update" timestamp in the header continues to reflect the most recent real measurement received from any of the selected devices. {% endhint %} *** ## Workspace Dashboard Configuration The Heatmap Widget can also be used in **Workspace Dashboards**: 1. **Navigate to a Workspace Dashboard**. 2. **Add the Heatmap Widget** following the same steps as for device dashboards. 3. **Add Multiple Devices**: * Example: Weather stations from different cities (Athens, Barcelona, Berlin, Milan, Seville, Marrakesh, etc.). * Each row represents a location with its respective temperature data. 4. **Configure Timeframe and Appearance**: * Example: Set to **7 days**, **normal cell size**, and **daily timeframe**. # Table Widget ## Overview The Table Widget in Datacake is **only available in global dashboards**. The Table widget displays certain values of multiple devices. You are able to filter for tags or names to only get a group of devices. It is perfect to get an overview about values of a group of devices. It also gives the possibility to set conditions so you see devices which are measuring problematic values. ## Video You can check out our video about the Table Widget here: ## Setting up the Table Widget To get started, create a [global dashboard](/dashboards/global-dashboard), and add the Table Widget to your dashboard.
## Configuration #### **Devices** In this section you create a filter of which devices you will list in your table. You can filter by Tags or parts of the device names. While filtering you will see a short list of devices in the preview on the bottom. #### **Columns** Here you can add what to display per device. To identify the device, we recommend to start with *Meta* information like the Device Name (linked). Inside of the *Meta* fields you will find elements like the **Online Status** of your device, the **Serial Number**, the **Date last heard from**, **Device Location** (description) and **Metadata** created on the device (if existing, you will find those inside of your Device's configuration section).
The next columns should be some *Measurements* like values you want to see. Those are the "Fields" created on your device. #### **Appearance** You can set some preferences about pagination, default sorting and some colouring. Feel free to adjust things as you like! #### **Conditional Formatting** If you have configured something in the columns tab, you are able to set up rules to get a visual difference on some devices/rows. You can set up the condition of that rule as you like. You have the option to activate "Limit to this column", which will only apply the conditional formatting to the specific column to which the condition was applied. For example, if you define a conditional formatting if TEMPERATURE<=5°C, only the device in the column TEMPERATURE will be coloured. ## Example configuration
# Image Widget ## Overview The Image Widget allows you to upload any image you have into your dashboard. You can also add a link to an external (or internal) site to your image. Powerful tool to add photos of your devices, location, branding, etc. ## Configuration When adding a new Image Widget, you will simply get the option to upload an image from your local storage. You can either drag-and-drop an image onto the lined square, or click on "Change". A folder will open on your PC. Browse until you find the proper image (it can be a diagram, logo, photo, or whatever image you want). {% hint style="info" %} Supported formats are gif, .jpg, .jpeg, .png, .svg, .webp. The maximum size permitted is 10 Mb. The platform will escale the image for performance purposes. {% endhint %} You can then select how the image should be displayed. Select either "Contain", to let the image take the platform scale the image to fit into the widget, or "Cover", to stretch out the image to fill out the full size of the widget.
Finally decide if you want to Hide background or Add a link to your image. When selecting to "Add link" you will be presented with an empty field, where you can simply paste the URL (exactly as you would enter it on your browser, with https\:// and everything). You can then enable the option to "Open the link in a new tab", or not. Tint color option allows you to color the background of the widget, as always. Save the changes and you are ready to enjoy your image in your dashboard! # Histogram Widget ## Overview ### Video {% embed url="" %} ### What Is the Histogram Widget? The Histogram Widget is Datacake’s new, multi-purpose chart component for summarising numeric telemetry across many devices.\ It combines: * **Bar charts** – classic column view of each data source. * **Interactive statistics table** – min | max | average with live highlighting. * **Pie charts** – *first time ever on Datacake!* – for quick distribution insights. * **Value Ranges** – rule-based colouring (and optional grouping in Pie mode). Use it to visualise anything from city-by-city temperatures to battery-level bands across your fleet. *** ### Quick Start | Step | Action | | ---- | -------------------------------------------------------------------- | | 1 | **Add Widget** → choose **Histogram** | | 2 | Give it a title (e.g. *Temperature Histogram*) | | 3 | Open **Data** tab → add the telemetry fields you want to compare | | 4 | (Optional) set a **Unit** (°C, %, V, …) | | 5 | Fine-tune look & behaviour under **Appearance** and **Value Ranges** | | 6 | **Save** and resize the widget on your dashboard | *** ## Data Configuration ### Adding Data Sources Each bar (or pie slice) starts with a **Data Source**: pick one or more device fields.\ Future releases will support *semantic shortcuts* (e.g. “All temperatures”) – for now, select manually. ### Naming & Units * Rename each source for a readable legend label. * Add a **Unit** so the y-axis, tooltips and statistics table share a consistent suffix. *** ## Appearance Options ### Chart Type | Option | Use-case | Notes | | ----------------------- | ------------------------------------------------- | -------------------------------------------- | | **Bar Chart** (default) | Compare absolute values between sources | Shows value labels above each bar if enabled | | **Pie Chart** | Show distribution (source-based *or* range-based) | First appearance on Datacake | Switch type anytime in **Appearance → Chart Type**. ### Display Toggles * **Show Statistics Table** – reveals interactive Min/Max/Avg grid. * **Show Values on Bars** – numeric labels directly on bars. * **Hide Background** – transparent widget for dark dashboards. ### Decimal Places Control global rounding (0 – 4 decimals) for bars, tooltips and table cells. ## Value Ranges Value Ranges let you: 1. **Colorise** bars or slices according to thresholds. 2. **Group** devices into bands when Pie Chart mode is active. | Field | Description | | ------------- | ----------------------------------------------- | | **Name** | Friendly label (e.g. *Cold*, *Warm*, *Extreme*) | | **From / To** | Inclusive numeric limits | | **Color** | Hex picker for range colour | Enable them under **Value Ranges → “Enable Value Ranges”**. ### **Range Colouring (Bar Mode)** Bars keep their individual height (device value) but adopt the colour of the range they fall into – fast visual QA of outliers. ### **Range Grouping (Pie Mode) – *****Key Concept*** *Without* ranges, a pie shows one slice per **data source**.\ \&#xNAN;*With* ranges **enabled**, the pie swaps to **distribution mode**: * Each slice is a **range**, not a device. * Slice size = *number of devices* inside that range (percentage shown on hover & in legend). This turns the same telemetry into an instant “how many devices are cold / warm / hot?” insight. *** ## Interactivity * **Hover a bar** → highlights corresponding row in the statistics table. * **Hover a table row** → flashes the matching bar. * **Hover a pie slice** → tooltip with range name + device count + percentage. * Supports real-time updates when the dashboard is in *Live Data* mode. *** ## Best Practices & Tips | Scenario | Recommendation | | -------------------------------- | ----------------------------------------------------------------------------- | | Fleet health distribution | Use **Pie + Value Ranges** to spot clusters (e.g. battery 0–20 %, 20–50 %, …) | | Comparing absolute sensor values | Stick to **Bar** with value labels and stats table | | Many devices (> 20) | Ranges become essential – otherwise the legend gets crowded | | Dark dashboards | Enable **Hide Background** and pick high-contrast range colours | | Multi-metric page | Duplicate the widget, then edit Data tab only – ranges & styling carry over | *** ## FAQ #### Q: Why does my pie chart still show device names instead of ranges? A: Make sure **Enable Value Ranges** is toggled **on** *and* at least one range is defined. #### Q: How are slice percentages calculated? A: *(Device count in range ÷ Total device count) × 100 %*.\ Individual values are **not** summed in range mode. #### Q: Can I disable the statistics table? A: Yes – Appearance → toggle **Show Statistics Table**. #### Q: Will semantic data selection be available? A: Yes, upcoming releases will auto-suggest fields (e.g. *all “temperature” sensors*). # ASHRAE Chart Widget The ASHRAE Chart Widget helps visualise temperature or relative humidity measurements against the environmental classes defined in the ASHRAE Handbook for museums, galleries, archives, and libraries. It allows facility managers, conservators, and collection-care professionals to assess how closely environmental conditions align with a selected preservation class over time. ## Overview The widget compares a single metric, either temperature or relative humidity, against one of the ASHRAE museum climate classes and displays compliance percentages for each class. The supported classes are based on: **ASHRAE Handbook – HVAC Applications**\ Chapter: **Museums, Galleries, Archives, and Libraries** The widget is intended for: * Museums * Galleries * Archives * Libraries * Collection storage facilities {% hint style="info" %} **Important:** This widget is not based on ASHRAE TC 9.9 and should not be used to evaluate data-center environmental compliance. {% endhint %} ### Supported ASHRAE Classes | Class | Description | | ----- | ---------------------------------------------------------------- | | AA | Precision control with minimal fluctuation and no seasonal drift | | A | Precision control with limited seasonal drift | | As | Wider temperature drift with tighter humidity requirements | | B | Broad seasonal drift and relaxed control | | C | Fixed acceptable range | | D | Relative humidity maintained below 75% | *** ### What Can Be Visualised? Each widget instance displays a single metric: * Temperature * Relative Humidity To monitor both metrics, add two separate widget instances to your dashboard. ### Not Supported The widget does not calculate or display: * Dew Point * Wet Bulb Temperature * Psychrometric Relationships * Temperature/Humidity Correlation * ASHRAE TC 9.9 Recommended or Allowable Zones ## Configuration ### Data Select the device and field containing temperature data, or relative humidity data. Only one metric can be displayed per widget. ### Setpoint The setpoint represents the desired target value around which the ASHRAE class boundaries are calculated. Examples: * 20 °C for temperature * 50 % RH for humidity #### Seasonal Curve The widget supports three seasonal adjustment models: **Sine:** A smooth annual transition between summer and winter conditions. **Step:** Summer and winter conditions switch abruptly: * April–September: Summer * October–March: Winter **Step with transition:** Similar to Step, but includes approximately 30-day transition periods between seasons. #### **Drift AA Class with Season** When enabled, the AA class envelope follows the selected seasonal curve and shifts throughout the year. When disabled, the AA class remains centred around the configured setpoint and does not apply seasonal drift. {% hint style="info" %} This option only affects the AA class visualization and compliance calculation. Other classes continue to follow their respective ASHRAE definitions. {% endhint %} ### Classes Select the desired preservation class: * AA * A * As * B * C * D The selected class determines: * The visual compliance envelope * Compliance percentage calculations * Optional out-of-range indicators ### Understanding Compliance Percentages The percentages shown below the chart indicate how many samples fall within each ASHRAE class. For relative classes (AA, A, As, and B), Datacake evaluates compliance using the widest possible envelope of the class. This guarantees cumulative results: ``` AA ≤ A ≤ As ≤ B ``` For example: | Class | Compliance | | ----- | ---------- | | AA | 72% | | A | 85% | | As | 94% | | B | 99% | Since each class is progressively less restrictive, compliance percentages can only increase. ### Understanding Seasonal Drift For classes AA, A, As, and B, the acceptable range changes throughout the year. The center of the acceptable band is calculated using: ``` center(t) = setpoint + seasonalFactor(t) × seasonalAmplitude ``` The allowed range around that center is determined by the class-specific fluctuation limits. Classes C and D use fixed absolute limits and are not affected by seasonal drift. ### Indicator #### Out-of-Target Indicators Optional red outline markers can be displayed for samples that fall outside the selected target class. When enabled, the widget displays markers on all samples that fall outside the chosen target class at the corresponding timestamp. This can help quickly identify periods where environmental conditions exceeded the allowed limits. #### Target Class Select the ASHRAE class that should be used as the compliance reference for the out-of-class indicators. #### Compliance Enable **Show compliance percentages below chart** to display compliance statistics for each ASHRAE class. The percentages indicate how many measurements within the selected timeframe comply with each class. ### Intended Use Cases The ASHRAE Chart Widget is designed for: * Museum collection preservation * Archive climate monitoring * Library environmental control * Historic building conservation * Art storage facilities It provides a convenient way to assess long-term environmental stability and preservation compliance. ### Limitations The widget is not suitable for evaluating: * Data-center environmental compliance * ASHRAE TC 9.9 conformance * IT equipment inlet conditions * Cooling optimization strategies * Dew-point based assessments These use cases require psychrometric analysis and simultaneous evaluation of temperature and humidity. # Scatter Plot Widget The Scatter Plot Widget allows you to visualise the relationship between two data fields by plotting one field on the X-axis and another on the Y-axis. This is useful for identifying correlations, trends, and patterns between measurements over time. ## Configuration ### Basics **Title:** Assign a custom title to the widget. ### Data **X-Axis Device and Field** Select the device and field that will be plotted on the X-axis. **Y-Axis Device and Field** Select the device and field that will be plotted on the Y-axis. {% hint style="info" %} Example: Plot room temperature on the X-axis and room humidity on the Y-axis to visualize how both values relate to each other. {% endhint %} ### **Timeframe** Choose the period of historical data to display in the scatter plot (default to the last hour, the last day, week, 2 weeks, last month or personalise your timeframe). ### Appearance **Show Trail Line:** Connects consecutive data points with a line, making it easier to visualise the progression of values over time. **Trail Width:** Adjust the thickness of the trail line. **Point Size:** Define the size of the plotted data points. **Color Mode:** Choose how points are colored: * **Single Color** – All points use the same color. * **Color by Y-Value (Gradient)** – Points are coloured based on their Y value using a color gradient. When Color by **Y-Value (Gradient)** is enabled, the following options become available: * **Gradient Start** – Color used for the first value. * **Gradient End** – Color used for the last value. * **Min (Optional)** – Define the lower bound of the gradient scale. * **Max (Optional)** – Define the upper bound of the gradient scale. Both minimum and maximum values must be numerical. **Tint Color:** Customize the widget's primary accent color. **Highlight Color:** Customize the color used for highlighted elements. **Hide Background:** Removes the widget background for a cleaner appearance. **Hide Last Update:** Hides the timestamp showing when the widget was last updated. ### References Reference lines can be added to help identify thresholds or target values. **X-Axis Reference Value** Add a numerical reference value on the X-axis. * Creates a **vertical line** at the specified value. * Useful for marking limits, thresholds, or target values. * A custom color can be assigned to the reference line. **Y-Axis Reference Value** Add a numerical reference value on the Y-axis. * Creates a **horizontal line** at the specified value. * Useful for highlighting limits, thresholds, or target values. * A custom color can be assigned to the reference line. ### Saving Changes After configuring the widget, click **Save Changes** to apply the settings and display the scatter plot on your dashboard. # Cooling Health Widget Turn fridge, freezer or cold room temperature data into a health score with status, KPIs and actionable insights. The Cooling Health Widget monitors refrigeration equipment — fridges, freezers, cold rooms and similar appliances — and condenses their temperature (and optionally humidity) data into a single **health score from 0 to 100**. Instead of reading raw temperature charts, you see at a glance whether an appliance is operating safely, how stable it runs, and what is going wrong when it isn't. The widget is available on both **device dashboards** and **workspace dashboards**.

The Cooling Health Widget with score ring, status, KPIs, timeline and insights

The widget combines: * A **score ring** with the overall health score and a status pill (**Healthy**, **Warning** or **Critical**), plus the individual sub-scores. * **KPI cards** showing average and maximum temperature, time spent above the warning threshold, stability (standard deviation) and recovery time. * A **timeline** plotting the temperature (and humidity) band against your thresholds. * An **insights feed** that translates the metrics into plain-language findings, such as frequent door openings or condensation risk. *** ## Adding the Widget 1. Open your dashboard and enable **Edit Mode**. 2. Click **"Add Widget"**. 3. Select the **"Cooling Health"** widget. 4. Configure the widget as described below and click **Save**. *** ## Basics

Basics tab with title and appliance type

**Title:** Assign a custom title to the widget, with optional translations. **Appliance type:** Choose the kind of cooling equipment the widget monitors. Selecting an appliance type fills the target range, thresholds and humidity range on the **Targets** tab with sensible defaults: | Appliance type | Target range (°C) | Warning (°C) | Critical (°C) | Humidity range (%) | | --------------- | ----------------- | ------------ | ------------- | ------------------ | | Fridge | 2 – 8 | 7 | 8 | 30 – 70 | | Freezer | −25 – −15 | −14 | −10 | — | | Cold Room | 0 – 10 | 9 | 12 | 30 – 80 | | Medical Fridge | 2 – 8 | 7 | 8 | 30 – 60 | | Lab Fridge | 2 – 10 | 9 | 12 | — | | Food Storage | 0 – 5 | 5 | 7 | 30 – 75 | | Cooling Cabinet | 0 – 10 | 9 | 12 | — | {% hint style="warning" %} The presets are conservative starting points based on common refrigeration practice. Every value can be overridden on the **Targets** tab. They are **not regulatory or compliance advice** — the widget is an operational insight tool; always apply the target ranges and thresholds that your own regulations and processes require. {% endhint %} **Compact mode:** Shows only the score ring, status and the three most important KPIs — useful for small widgets or overview dashboards. The widget also switches to the compact layout automatically when it is sized too small to fit the full view. *** ## Data

Data tab with automatic field selection

**Field source:** Choose how the widget finds its temperature and humidity data: * **Automatic (by sensor type):** Datacake automatically uses the device's **temperature** and **humidity** fields based on their field semantics. You only select the device — on a device dashboard even that is filled in automatically, so the widget works with zero data configuration. Tick **Include humidity** to add humidity-based metrics (condensation risk, humidity spikes). * **Manual:** Pick the exact device and field for temperature, and optionally for humidity. Use this when a device has several temperature fields (for example multiple probes) and you want to monitor a specific one. {% content-ref url="/pages/TmCOrosPLbxaXIz2OpLS" %} [Field Semantics](/field-semantics) {% endcontent-ref %} *** ## Targets

Targets tab with target range, thresholds and humidity range

**Target min / Target max:** The acceptable temperature range during normal operation. Time spent outside this range counts against the health score. **Warning threshold:** Marks the start of out-of-range time. Time above this temperature is tracked in the **Above warn** KPI and reduces the safety score. **Critical threshold:** Marks unsafe periods. Any time above the critical threshold strongly penalises the safety score and immediately sets the widget status to **Critical**, regardless of the overall score. **Humidity min / Humidity max** (only shown when humidity is configured)**:** Humidity readings outside this range contribute to the condensation-risk heuristic. *** ## The Health Score The overall score is a weighted combination of individual sub-scores, each looking at a different aspect of how the appliance operates: * **Safety** — how much time the temperature spent above the warning and critical thresholds. This is the most heavily weighted sub-score. * **Stability** — how much the temperature fluctuates relative to your target range. A steadily running appliance scores high; one that constantly swings scores low. * **Recovery** — how quickly the temperature returns to normal after a warm event (for example after the door was opened or new goods were loaded). * **Excursion** — how frequently the temperature spikes above the warning threshold. * **Drift** — whether the temperature slowly trends upwards or downwards over time, which can indicate a struggling cooling system. * **Humidity** — humidity stability and condensation risk (only when humidity is configured). Sub-scores that don't apply — for example Recovery when no excursion occurred, or Humidity without a humidity field — are left out of the calculation rather than counting against the score. The status pill follows the score: | Status | Condition | | ------------ | ------------------------------------------------------------------ | | **Healthy** | Score 80 or higher | | **Warning** | Score 60 – 79 | | **Critical** | Score below 60, **or** any time spent above the critical threshold | | **Unknown** | No data in the selected timeframe | *** ## Sensitivity **Sensitivity** controls how strictly deviations are penalised and how early insights are raised: * **Low:** More lenient — suited to appliances in heavy daily use (frequent door openings) where short spikes are expected. * **Medium:** Balanced default for most applications. * **High:** Stricter — deviations reduce the score faster and insights trigger earlier. Suited to sensitive goods such as medical supplies. **Show insights:** Toggles the insights feed below the timeline. **Show timeline:** Toggles the temperature/humidity timeline chart. *** ## Insights When enabled, the widget analyses the metrics and shows plain-language findings, each marked as info, warning or critical: * Time spent above the **warning** or **critical** threshold. * **Frequent short temperature spikes** — often a sign of repeated door openings. * **Slow recovery** after warm events — the appliance takes longer than expected to cool back down. * **Temperature drift** — the temperature is trending up or down over time, which may mean the cooling system is working harder than usual. * **Humidity spikes** — combined with temperature spikes this often indicates door activity. * **Condensation / icing risk** — sustained high humidity at low temperatures. * When everything is fine, the widget simply reports that the temperature is stable and within the expected range. *** ## Timeline and Excursions The timeline plots the temperature band (min/max per interval) against your target range and thresholds, with the humidity band on a second axis when configured. The resolution follows the widget's **Timeframe** setting (default: the last 24 hours at 5-minute resolution). When excursions occurred in the selected timeframe, the **Above warn** KPI card becomes clickable and opens a detailed list of all excursion events, including when each one started, its peak temperature, how long it lasted and how long the appliance took to recover. *** ## Timeframe Choose the period of historical data the health score is calculated over — for example the last 24 hours, the last week, or a custom timeframe — and the resolution of the timeline. {% hint style="info" %} The health score always describes the **selected timeframe**. A fridge that had a critical excursion yesterday will show a Critical status on a 7-day timeframe, but may already be Healthy again on a 24-hour timeframe. {% endhint %} *** ## Appearance **Tint Color:** Customize the widget's primary accent color. **Highlight Color:** Customize the color used for highlighted elements. **Hide Background:** Removes the widget background for a cleaner appearance. **Hide Last Update:** Hides the timestamp showing when the widget was last updated. # Dashboard History We’ve introduced **Dashboard History** for manual dashboards, available on both **Global Dashboards** and **Device Dashboards**. This feature allows you to track, review, and restore changes made to your dashboards over time.
{% hint style="warning" %} Dashboard history is *only* available for manually created dashboards. This means pre-configured dashboards, such as the Climate Monitoring Dashboard, will not have this feature available. {% endhint %} ### Overview With history, every change to a dashboard is recorded, giving you full visibility into its changes over time. This includes actions such as: * Adding or duplicating widgets * Editing widget content or layout * Creating or modifying tabs * Restoring previous versions Each change creates a new entry in the dashboard history. ### Accessing the Audit Log While in **Edit Mode**, click the **“History”** button in the top toolbar to open the dashboard history panel. From there, you can: * View a chronological list of all changes * See who made the change and when * Review optional change descriptions * Restore any previous version of the dashboard
### Change Descriptions When saving a dashboard, you have the option to add a **change description**. * This helps document what was modified (e.g. *“Added second widget”*) * If left empty, a default message like *“Dashboard updated”* will be used
### Restoring Previous Versions You can restore any previous state of the dashboard with a single click. * Click **“Restore”** on any history entry * The dashboard will revert to that version * The restore action itself is also logged as a new history entry This makes it easy to undo mistakes or roll back changes.
### Behaviour Across Dashboard Types The history functionality works consistently across: * **Global Dashboards** * **Device Dashboards** All changes are tracked using the same logic, regardless of dashboard type. ### Key Benefits * **Full transparency** of dashboard changes * **Version control** without manual backups * **Easy rollback** to previous states * **Improved collaboration** across teams # Overview The **Organization Overview** gives administrators a centralized view of all Rules, Reports, and Exports across every workspace inside an organization.\ It helps teams quickly monitor activity, identify inactive configurations, and manage automation items from a single location. {% hint style="info" %} To be able to access the Overview section, Members need to have "Manage workspaces" as a permission inside of the Administrators section. {% endhint %} ## Accessing the Organization Overview To open the Overview scroll down to the Organization section inside your workspace and access overview. {% hint style="success" %} Make sure you are an Administrator with "Manage workspaces" permission. Otherwise, you won't see the Overview section! {% endhint %} The Overview page displays organization-wide information aggregated across all accessible workspaces.
At the top of the page, you will find summary cards displaying: * **Workspaces:** Total number of workspaces inside the organization * **Rules:** Total number of organization rules, including paused items * **Reports:** Total number of reports across all workspaces * **Exports:** Total number of exports configured in the organization These cards provide quick insight into the scale and activity of your organization. ### Top Workspaces by Activity This section highlights the most active workspaces based on the total number of configured items. Each workspace entry displays: * Number of Rules * Number of Reports * Number of Exports This helps identify which workspaces are most actively used. ### Health & Insights The **Health & Insights** panel automatically surfaces important information about your organization configuration. Examples include: * Rules that have not triggered recently * Paused Rules, Reports, or Exports * Workspaces without configured automation items These insights help administrators maintain clean and active environments. ## Rules The **Rules** tab provides a centralized list of all Rules across all accessible workspaces. Rules are grouped by workspace for easier navigation.
Each rule entry displays: * Rule name * Rule type (New meaning "Rule Engine" and Classic meaning "Rules") * Last triggered timestamp * Active/Paused status Administrators can enable or disable rules directly from this tab. They can also open the related workspace using the link next to the workspace name. The tab allows to filter rules using the options "All", "Active" and "Paused". Use the Search bar to navigate and look for specific rules. Use the Export button to export the current rule list as an Excel or CSV file. ## Reports The **Reports** tab displays all reports configured throughout the organization. Exactly as with Rules, reports are grouped by workspace.
Each report entry includes the report name, the next scheduled run and its Active/Paused status. Administrators can enable or disable reports directly from this tab. They can also open the related workspace using the link next to the workspace name. The tab allows to filter reports using the options "All", "Active" and "Paused". Use the Search bar to navigate and look for specific reports. Use the Export button to export the current report list as an Excel or CSV file. ## Exports The **Exports** tab provides visibility into all configured exports across the organization. Exports are grouped by workspace.
Each export entry displays the export name, export type (Automatic or Manual), the next scheduled run and its Active/Paused status. Administrators can enable or disable exports directly from this tab. They can also open the related workspace using the link next to the workspace name. The tab allows to filter exports using the options "All", "Active" and "Paused". Use the Search bar to navigate and look for specific exports. Use the Export button to export the current export list as an Excel or CSV file. ## Permissions The Organization Overview only displays: * Workspaces the current user has access to * Rules, Reports, and Exports within those accessible workspaces Users without sufficient permissions will not see restricted items. ## Benefits of the Organization Overview The Organization Overview helps administrators: * Monitor automation activity across the organization * Identify inactive or unused configurations * Manage Rules, Reports, and Exports centrally * Improve organization-wide visibility * Reduce time spent navigating between workspaces # Billing Located in the sidebar, the Billing section allows you to manage your account's financial aspects.
## Organization-Based Billing {% hint style="info" %} **New Feature Post-April 2024**: Workspaces are linked to organizations to consolidate billing and device management. {% endhint %} **Starting from April 2024**, Datacake has introduced organization-based billing. This allows you to: * Create a billing account on your first starting workspace. * When creating a new workspace, use the existing organization for billing the new workspace. * Consolidate the billing of all workspaces under a single organization. * If you create a new workspace without assigning it to an existing organization, you can create a new organization and then create separate workspaces under different organizations. * Have multiple organizations, each with multiple workspaces. * Share billing within an organization. For example, purchases like SMS credits and extra features are shared throughout the organization. ## Your Plan You will be able to see your plan, the amount of devices you have used and if the device quota is shared or assigned to each workspace individually.
In this section, you will be able to upgrade your package. Just select the one you want to purchase and click on "Subscribe". If you have a current payment method added to the "Manage Billing" section, it will be taken by default. Otherwise, you will need to complete your billing information and click on "Add Payment Method" and then on "Buy now for..." You can either go for our Monthly subscriptions, or you can subscribe annually. For annual subscriptions, you will receive a **free month**. In case you have existing devices within that organization, all of them will be migrated to your plan. {% hint style="info" %} We only support payments via bank transfer (Invoice payment) for annual subscriptions. If you wish to go for the annual subscription via bank tranfer, please get in contact with us to . We will be happy to assist you. {% endhint %} ## Manage Billing Within the Billing section, users can update billing name, address, Tax ID, and payment methods.
To update your Billing Name, Billing Address and Tax ID, click on "Update". {% hint style="info" %} Datacake utilizes **Stripe** for billing purposes. {% endhint %} To access our Stripe billing centre, click on "Manage Billing". A new tab will open, where you will be able to manage your payment methods, change billing information and have access to your invoice history. Within the Billing Information, make sure you set up an email address (by default it is set to the email address of your account). The email address set is the one that will receive invoices and receipts automatically.
Inside of the Invoice History, you have the option to navigate, search for specific invoices and download them at any time. ### Cancelation If you want to cancel your subscriptions, here are the following guidelines: * To delete a single device subscription, you can delete the device or downgrade its current device plan. * To cancel an upgrade like a white label or Cake Red, go to its particular page on the sidebar and cancel the selected product. ### Cancelation of package within an Organization To cancel subscriptions for your entire organization, go to the billing section, scroll down to the bottom, and use the button for canceling all subscriptions. {% hint style="danger" %} Please note that this action will cancel all subscriptions of your organization, including all workspaces within it. **By choosing this option, all paid devices and associated data will be permanently deleted.** This action cannot be undone. {% endhint %} If you are sure you want to cancel, enter the name of the workspace you are in and click on "Cancel All Subscriptions". ## Update Payment Method If you need to update a credit card, add a second one, or change the credit card, navigate to "Manage Billing" to access the Stripe Billing Center. There, you can update your credit cards and payment details as needed. ## Purchase SMS Credits SMS credits can be purchased on the billing section. Simply use the sidebar to enter the billing section, click on "+Top up Credits," and choose a desired package. ### SMS Quota Distribution Mode If you purchased a SMS package within your organization and your organization has more than one workspace, the SMS credits are available for all workspaces and you can choose the distribution mode.
#### Share credits between all workspaces The SMS package purchased will be available for all workspaces in your organization. That means, that all of them can use them equally. E.g. if you have 200 SMS credits and 2 workspaces, Workspace A and Workspace B, both will have 200 credits available. If Workspace A consumes 50 and Workspace B consumes 20, both have 140 SMS credits available. #### Assign credits to workspaces manually You can assign manually how many credits each workspace gets. With this option, you have more control over how many SMS credits each workspace can use. To assign SMS credits, you can multi-select workspaces using the tick box to the left and click on "Choose Action". You have the following options: * Set Total Credits: will set the total amount of credits (regardless of what was set before). * Add Additional Credits: will add an amount to the existing credits. * Remove credits: will substract an amount to the existing credits. There is an icon to the right side of each workspace, that allows you to "Set Total Credits" for an individual workspace. Here a short video showing you how to use this section: {% embed url="" %} As you can see, you have a table that shows you the workspaces inside of your organization, with the SMS credits used last month, this month and the SMS quota available at the moment. You can download an Excel or CSV file containing that information. ## Device Quota Just as SMS credit assignation, we now support Device Quota assignation. You will see the total amount of devices included in your package and are able to select a Device Quota Distribution Mode: #### Share quota between all workspaces The device quota available on your purchased package will be available for all workspaces in your organization. That means, that all of them can use them equally. E.g. if you have 200 devices in your Standard package 2 workspaces, Workspace A and Workspace B, both will have 200 devices available. If Workspace A adds 50 devices and Workspace B adds 20 devices, both have 140 devices left to add. #### Assign quota to workspace manually You can assign manually how many devices each workspace gets. With this option, you have more control over how many devices each workspace can add. To assign device quota, you can multi-select workspaces using the tick box to the left and click on "Set Quota". Set Quota will allow you to set the total amount of devices (regardless of what was set before). There is an icon to the right side of each workspace, that allows you to "Set Device Quota" for an individual workspace. You cannot explicitly remove device quota from a device, but you can always set a lower amount of quota, or set a quota of "0" devices. Here a short video showing you how to use this section: {% embed url="" %} You have, as with the SMS credits, a table that shows you the workspaces inside of your organization, the current devices they have (existing devices), device quota (total assigned) and the quota remaining (Device Quota - Current Devices). You can download an Excel or CSV file containing that information. ## Adding Workspace to Organization When you add a new workspace, starting in April 2024, you now have the option to add that workspace to an existing organization.
Once a workspace is added to an organization, the billing that is set on the organization is shared across all workspaces. Additionally, SMS credits and updates like Rule Engine are also shared between workspaces. ### Disconnecting Workspace from Organization Right now, it is not possible to disconnect an existing workspace from an organization once it has been added to that organization. ### Independent Workspace If you still need to have independent workspaces, you should create a new workspace without adding it to an existing organization. This also has the benefit of creating a new organization, providing you with two independent organizations that can be used for separate billing systems shared among distinct sets of workspaces. ## Individual Pay-as-you-Go Billing Since February 2nd 2026, there are no individual pay-as-you-go devices available at the platform. This applies for all new accounts, as well as for all new organizations. ### Change Device Plan If you have old pay-as-you-go devices, you can still change the plan for your devices. You can do this by accessing the configuration tab of the device and navigate to the Danger Zone. Here's a video showing you how: {% embed url="" %} Alternatively, you can also use the context menu of a device entry on the device list.

Context menu on device list entry. Change plan.

Changing of an individual device subscription

# Support Packages ## Overview | | **Free** | **Standard** | **Premium** | | -------------------------- | ----------- | -------------------- | -------------------- | | **Pricing** | Free | **200.00 €** | **500.00 €** | | Payment Interval | | monthly | monthly | | Discount on yearly payment | | 5% | 15% | | | | | | | **Response Time** | Best Effort | < 5 Hours | < 60 Minutes | | | | Within working hours | Within working hours | | | | | | | **Support Channels** | | | | | E-Mail | Yes | Yes | Yes | | Live-Chat | Yes | Yes | Yes | | Slack | No | No | Yes | | Monthly Update Calls | No | No | Yes | | | | | | | **Ticket Escalation** | No | No | Yes | | | | | | | **Development Support** | | | | | Device Templates | Best Effort | < 7 days | < 1 day | | Custom Decoder Development | No | Yes | Yes | | Dashboards | No | No | Yes | | | | | | | **Onboarding Services** | | | | | Import Devices | No | No | Yes | | Create Customer Dashboards | No | No | Yes | | | | | | ## Explanation ### Pricing * The interval of payment is monthly, and an option of annual prepayment is available (see "Discount Yearly") #### Discount Yearly * Percentage discount on the total price for annual prepayment of the monthly fee. ### Response Time * The time it takes Datacake to respond to the support ticket. #### Best Effort * The support request is created as a ticket in our CRM system when using the email or live chat communication channel. * Without a support plan, the request will be processed on a best-effort basis. * Requests or tickets of a user from a higher support plan will be prioritized. #### Resolution of tickets * A response to the support ticket does not automatically include the resolution of a problem. * If (depending on the support plan) a response is guaranteed within a certain time, this does not automatically mean that a solution to a problem will also be found and implemented in the same time. * The time needed to resolve a problem or implement a specific request is considered individually depending on the severity, impact and scope and is communicated with the customer. ### Support Channels * All channels are subject to the response time specified in the respective plans! #### E-mail * Creation of a service ticket via #### Live chat * Use of live chat on the Datacake platform (inside of your Workspace) or website #### Slack * Invitation of the user to the company-wide Slack (alternatively Discord or Teams, requires separate clarification) #### Monthly Update Calls * A Customer Support Manager at Datacake is having a regular videocall with the customer on a monthly basis. ### Ticket Escalation * The customer has the right to have their tickets prioritized with immediate effect. * Remaining tickets must give way to the escalated ticket. * The advantage for the customer is the immediate processing of his support request including solution finding. ### Development Support #### New Device Template * Every customer can ask Datacake to create a device that is not yet supported by a template. * If no support plan is available, Datacake creates a ticket for this request, which is then processed according to availability. * With the respective higher support plans, the template is created in a maximum of 7 or a maximum of 1 day. {% hint style="info" %} The prerequisite for this is that the device is Datacake-compatible and the creation of a template is therefore possible. {% endhint %} #### Custom Decoder Development * Includes the adaptation or modification of a decoder / Datacake product of the customer, which was created in advance on the basis of a template or by the customer. * These adaptations include, for example, the extension of the decoder to include special analysis functions, database access, or similar functions. #### Dashboards * Datacake handles the creation of new or customization of existing device dashboards for the customer. ### Onboarding Services #### Import Devices * Customer provides CSV or Excel for import of devices. * Datacake takes care of creating the devices, creating respective products. #### Create Customer Dashboards * Datacake will assist customer in creating dashboards for device and workspace for deployment to end customer. ## Support Plan Exclusion * The following activities are excluded from a support plan: * Programming of individual functions or extension, which are in the context of the application implemented by the customer. * If specific functions are to be implemented for the customer, then this requires a separate agreement and the services will be charged in the form of a classic service. # VAT Exemption / Tax ID ## Background In most cases, charges are subject to German VAT ("Umsatzsteuer"). There are a few cases where there is an exemption, though: ### Outside EU **You are a registered company outside the EU** If you update your billing address to include your company's name and address outside of the EU, no VAT will be charged. ### Inside EU with Tax ID **You are a registered company outside of Germany and can provide a European tax id** If you update your billing address to include your company's name, the address and provide a valid tax id, reverse charge will apply and no VAT is added. ## Setup If you want to store your tax information in Datacake, you can do so through the billing settings. To do this, navigate to the billing settings using the sidebar. ![](/files/B9JuiIxWEBPHiw1xHgvJ) In the Billing Section, now click on "Update Information" to change the provided information, including Tax-Settings. ![](/files/w4x3lkgLDpx4zRvCpyaA) This will bring up the following modal, where you can enter your custom Tax-ID: ![](/files/BBpeZjLXb51S8J8Cgg7m) Now enter a valid VAT-ID and press "Save". This will enable reverse-charge or tax exemption. ## FAQs ### I have already received an Invoice but forgot to set up the Tax-Exemption. What can I do? Simply continue entering the Tax ID as described above. The invoices will be adjusted from now on. We cannot change invoices backward directly. If you need further assistance or have any questions, please feel free to contact us. # SMS Credits In order to send SMS messages using the Rule Engine, you need SMS credits. You can buy prepaid bundles of SMS credits directly inside of the platform, on the Billing section. If you send an SMS message, the credit will decrease accordingly. ## Topup SMS credits To see your current SMS credits or to add credits to your workspace, go to "Billing".
Check if you have set up a billing method. If not, go to "Manage Billing" follow the instructions or simply continue with "Topup Credits".
If you do not have valid billing methods, you can now put in everything necessary. Billing has been set up, simply chose the amount of credits and click "Buy".
## Manage SMS Credits among the workspaces in your Organization You can now decide if you want to "Share credits between all workspaces" in your Organization, or "Assign Credits to Workspaces Manually". #### Share credits between all workspaces This option allows you as before to share credits within all of your workspaces. Meaning, you only need to Top Up Credits once. All of them will be available for all of your workspaces. {% hint style="success" %} If you are going from "Assign Credits to Workspace Manually" to "Share credits between all workspaces", all of the current individual workspace quotas will be automatically transferred back to the organization and will be shared within all workspaces. {% endhint %} #### Automatic SMS Credit Top-Up Enabling **Automatic Top-Up** allows you to automatically purchase SMS credits when your balance drops below a defined threshold, ensuring uninterrupted message delivery. You can configure this under **Workspace → Administration → Billing → SMS Credits**.
**Configuration options:** * **Package** – Select how many credits are purchased per top-up: * 100 credits – €12 * 200 credits – €22 * 500 credits – €48 * 1000 credits – €84 * **Top-up threshold** – Define the balance level that triggers a purchase * **Monthly limit (optional)** – Set a maximum monthly spend for auto top-ups Once enabled, Datacake continuously monitors your SMS credit balance and automatically purchases the selected package when the threshold is reached. This helps prevent failed notifications due to insufficient credits and reduces the need for manual top-ups. Please note, automatic top-up can only be enabled if valid **billing information and address** are provided {% hint style="warning" %} Automatic SMS Top-Up is **only** available when credits are shared across all workspaces - it cannot be utilised if credits are assigned manually. {% endhint %} #### Assign Credits to Workspaces Manually When selecting this option, you will be provided with a tool to assign SMS credits to each of the workspaces belonging to your Organization. You will need to Top Up Credits to your Organization's quota and then manually assign it, so please be careful to always assign it, if the limits have been reached. A table showing all of your workspaces, with the SMS credits used last month, this month and the current SMS quota is shown. That way, you are able to control the amount of SMS credits used in each of your workspaces. You can multi-select workspaces to perform different actions: * Set Total Credits: It resets what is currently assigned and sets the new credits. * Add Additional Credits: Option to add new additional credits to the current credit amount. * Remove Credits: Option to remove all current assigned SMS credits. {% embed url="" %} {% hint style="success" %} If you are going from "Share credits between all workspaces" to "Assign Credits to Workspace Manually", all of your workspaces will start with 0 credits, so you must assign SMS quota immediately. Otherwise, no SMS can be sent until credits are distributed. {% endhint %} ## SMS Log & Configuration To consult your SMS Log, visit the "Workspace" section in your sidebar. Click on the "SMS" tab (between "General" and "Products").
In here you find the settings for truncation mode and replace non-GSM7 characters, as shown on the screenshot above. ## Long SMS Mode {% hint style="success" %} The following configurations you will find under the option "Workspace". {% endhint %} When you send an SMS message over 160 characters, the message will be split and result in multiple messages. You can choose if you want to truncate the message to 160 characters to make sure only at max one credit is deducted per message from your balance or if you always want to receive the full message which can result in multiple message credits being deducted. The SMS standard says that large messages are segmented into 153 character segments and sent individually then rebuilt on the recipients device. This means that a 161 character message would result in two segments being deducted. If you include non-GSM characters in your message, those messages have to be sent using the so-called UCS-2 encoding. Messages containing any non-GSM-character are limited to 70 characters. See a list of all GSM characters here: {% hint style="warning" %} Unfortunately, our beloved emojis are not part of the GSM character set. Messages containing emojis are thus limited to 70 characters 😭 {% endhint %} ## Replace non-GSM7-characters The SMS Character Replacement feature automatically substitutes special characters, symbols, and accents with their standard alternatives to optimise your message delivery. ### How It Works When enabled, this feature replaces non-standard characters (such as emojis, accented letters, and special symbols) with their closest standard equivalents that conform to the GSM7 character set.

Character replace mode toggle

### Benefits * **Reduced Costs**: Messages containing non-standard characters require more segments to send, increasing costs. By replacing these characters, your messages use fewer segments. * **More Efficient Delivery**: Standard GSM7 characters are more reliably delivered across all mobile networks. * **Predictable Billing**: Avoid unexpected increases in SMS segments due to special characters. ### Examples of Character Replacement | Original character | Replaced with | | ------------------ | ------------- | | ê, ë, ĕ | e | | ħ | h | | ™ | (tm) | ### When to Use This Feature Enable this option if: * You want to minimize SMS costs * Your messages frequently contain non-Latin characters, emojis, or special symbols * You prioritize delivery efficiency over exact character preservation Leave it disabled if: * Exact character preservation is critical to your communication * Your brand identity requires specific symbols or characters * You communicate primarily in languages requiring non-GSM7 characters ## SMS Log You can see a list of the last 100 SMS messages including their segment count. # Access Invoices ## Description You can conveniently download your Datacake invoices directly from our billing provider [Stripe](https://stripe.com/de). The invoices are created automatically and contain the address data you have defined in the billing settings. ## Access Invoices Use the sidebar to navigate to the Billing section. In the section "Manage Billing" there is a button "Manage Billing" which leads to the administration of your billing methods and your invoices.
# Unused time and Remaining time in Invoices (Prorations) The following documentation describes the meaning of "Remaining time on..." and "Unused time on..." inside Stripe generated invoices. The subscriptions are billed in a cyclic way. This means that customers that created a subscription (created devices on the platform) will always be billed the same day of the creation. However, changes to a subscription in the middle of the billing period, such as upgrading or downgrading can result in prorating charges. For example, if a customer upgrades from the Light subscription (1 € per month per device) to the Standard subscription (3 € per month per device), they’re charged prorated amounts for the time spent on each option. Assuming the change occurred halfway through the billing period, the customer is billed an additional **1 €**: -0.5 € for unused time on the initial price, and 1.5 € for the remaining time on the new price. The prorated amount is calculated as soon as the API updates the subscription. The current billing period’s start and end times are used to calculate the cost of the subscription before and after the change. # Codes If you have a discount code for Datacake Billing, then you can enter it while creating a device to use the code to pay for the device. Simply enter the code in the following input field: ![](/files/-Mc9u0PE8wjV-RSx-1IP) Next press on "Apply" to enable the code. If the code is valid, a new Plan will appear in the List of choseable plans. Select this and press on "Add 1 Device" to add the device based on the discounted device subscription plan. # Administrators Learn how you can assign Administrators, move Ownerships of Accounts, and define Members across multiple Workspaces using our Administrator Section on Organizations. ## Overview This document explains the new **Administrators** feature added to the **Organization** section in Datacake, allowing for streamlined management of organization administrators, permissions, and workspace inheritance. This feature is located in the **Organizations** group on the sidebar, which is accessible on the left side of the Datacake interface. ### Video {% embed url="" %} ## How it works ### 1. Accessing the Administrators Section To access this feature: 1. Navigate to the **Organizations** section in the sidebar. 2. Select **Administrators** from the options within the Organization group. 3. You will see a list of current administrators, with options to add, remove, or change administrator permissions. ### Key Features and Capabilities #### Organization-Based Administrator Management This feature provides a centralized management tool, allowing administrators to set permissions and transfer ownership across workspaces within an organization. Key highlights include: * **Organization-Level Control:** Previously, members had to be individually added to each workspace, making cross-workspace management difficult. Now, administrators and owners can manage members and permissions organization-wide, streamlining the user management process. * **Automatic Inheritance:** Workspaces created under an organization automatically inherit quotas and resources, such as devices and SMS allocations, eliminating manual configuration. #### Assigning and Managing Permissions Administrators can be added by: 1. Clicking **Add Member** and entering their **email**. The member must have an existing Datacake account. 2. Assigning one or more of the following permissions: * **Workspaces:** Manage workspace-related permissions. * **Members:** Handle member access and roles. * **Billing:** Manage billing settings and information. * **White Label:** Configure white-label settings. This flexibility allows the assignment of specific roles, such as a **Billing Administrator**, without granting unnecessary access to other areas. #### Ownership Transfer For organizational needs, ownership transfer is now possible: 1. In the **Administrators** list, open the **context menu** next to any administrator. 2. Select **Transfer Ownership**. 3. After transferring ownership, the original owner can remove themselves from the administrator list. ## Usage Guide 1. **Adding an Administrator** * Go to **Organizations > Administrators**. * Click **Add Member**. * Enter the member’s email and set their permissions. 2. **Removing an Administrator** * In the **Administrators** list, find the administrator. * Open the **context menu** and select **Remove**. 3. **Changing Administrator Permissions** * In the **Administrators** list, select the administrator. * Adjust their permissions as needed. 4. **Transferring Ownership** * Use the **Transfer Ownership** option from the context menu. # White Label Datacake allows you to run a copy of the portal on your own domain with your own branding. ## What is White Label Simply put, the white label option allows you to make a 1:1 copy of the Datacake platform and place it on your desired domain, upload a custom logo and browser icon, and hook up a personal E-Mail for sign-up, password reset and notifications. You can see your white label as a mask on top of Datacake. Configure the areas that are important for your customers and hide the ones that aren't. ### What does it include? The functionality of the platform under the white label is completely the same as Datacake. Additionally you can configure the access your users have to specific areas on the platform as well as allow or disallow certain capabilities they have across te platform., There are several options available to you, which are further described in the section [Capabilities](#capabilities). More details about our white label service can be found here: {% embed url="" %} ## Requirements To set up your white-label site, you need to be in possession of a domain name and have access to its DNS server configuration. You also need an active email address from which you want the portal to send emails. * Domain Name * Active E-Mail Address * Access to DNS Server Configuration ## Getting started To get started with your first white label site, make sure you have the sufficient permissions (Billing and White Label) on the workspace you want to manage your white label solution from. Take into consideration that all configurations and cancelation will only be available on the workspace you create the white label from, so choose the workspace wisely. {% hint style="success" %} While white-label sites are not tied to a workspace, the billing information from the currently active workspace is being used to create the site. This means that the white label solution will be charged on the workspace's invoice you create it from. {% endhint %} Click on "White Label" from the left sidebar navigation and select "Add white label site" on the top right corner. You will see a modal outlining the benefits of a white label site. Click "Get started" and you will see a form asking for:
### **Name** This is the name of your white-label site. It is used as the page title as well as in all email communication. ### Domain The domain can either be a top level domain (e.g. `eggtregg.com`) or a subdomain (e.g. `iot.eggtregg.com`). {% hint style="info" %} After the creation of the white label site, you will see the necessary DNS records you have to create. {% endhint %} ### Email "From" Your white label site will send transactional emails such as signup confirmation or device alerts from this email address. {% hint style="warning" %} This has to be an active email address since our email service **Postmark** will send a confirmation email to this address in the next step. {% endhint %} ### Email "From" name This is the display name of the email's sender. It can for example be the name of your site or the name of your company. When you're done entering the information, click "Next". On the following screen, you will find the payment details such as the payment method and billing address. When done, click "Buy white label site". ## Setup & Configuration After you have created your white label site, you can do further adjustments such as uploading a logo and favicon, under the General tab. Always remember to Save your changes. ## Domain ### DNS setup Under the Domain tab you will be able to see the domain you selected to be used with your white label site. You will have to configure your domain's DNS Server to be able to use it. There are two options for pointing a root domain to your white label site. * **Point ANAME or ALIAS record to whitelabel.datacake.co**: Use a DNS provider that supports ANAME or ALIAS records. * **Point A record to 164.90.242.26**: Create an A record for your domain pointing to our load balancer's IP address. Once done this, allow up to 24 hours for the changes to propagate. If this does not work after 24 hours, please contact . {% hint style="warning" %} Please note that DNS propagations can take up to 24 hours. {% endhint %} ## E-Mail In order to send emails from your own domain you need to verify the setup email by clicking the link on the confirmation email your received from our service provider **Postmark.** ## Appearance ### Branding The Branding section allows you to define the visual identity of your white label site. You can set a custom name, which will be displayed as the page title and used in email communications, ensuring a consistent experience for your users. Additionally, you can upload a logo that appears on the login screen and serves as a fallback for workspaces without their own logo. A favicon can also be configured to personalise the browser tab, helping reinforce your brand presence across the platform.
### Authentication Screen The Authentication Screen settings let you customize the appearance of your login and sign-up pages. You can choose from two different layout options, card or split screen, to match your branding style and user experience preferences. Furthermore, you can upload a custom image that will be displayed on the authentication screen, allowing you to create a more engaging and professional first impression for your users.
### Banner You can configure a banner on your white label site. Select the size of the banner, the text and background colours. You can add links as a menu item by adding a title and an URL. {% hint style="info" %} Don't forget to press on "+" to add it to the list and don't forget to save the changes! {% endhint %}
Setup a logo as well and that is it. Refresh your white label site to see the changes reflected. ## Connectivity ### Domain & Email The Domain & Email section allows you to consult the custom domain your white label site is served from, as well as the email address used for outgoing communications. {% hint style="warning" %} Once you create your white label site, you cannot change the (sub-) domain or email you chose. In case you need to make any corrections, you will have to contact us to {% endhint %} You can connect your own domain by updating your DNS settings, and once configured correctly, the platform will verify and confirm the setup. For email sending, you can define a sender address that will be used for system notifications and user communication. To ensure reliable delivery and improve inbox placement, it is recommended to authenticate your domain by adding DKIM and Return-Path DNS records. Once verified, your emails will be sent using your branded domain, providing a more professional and trustworthy experience for your users.
### API You will be able to use our GraphQL API to make queries and/or mutations, ingest or export data out of the platform, using your white label. This means that you get your own proxy and MQTT broker name with your branding.
## Devices ### Device Types You can choose what kind of devices your white label users are able to add on to the white label site. This setting can be adjusted on the Device Types tab
#### Pin Code This option is set by default and allows the users of your white label site to add new devices to his workspace via pin code. You must first create devices on one of your workspaces on Datacake (or your white label site) and set an individual pin code on that device. Read more about how to do that here: {% content-ref url="/pages/-M-JQQctuXfCo26MgDFn" %} [Claiming](/device/claiming) {% endcontent-ref %} You can then send these devices to your customer and include the pin code and serial number. Your customer can then use this information to register the device on their desired workspace. #### LoRaWAN If you activate this option the users of your white label site will see the same LoRaWAN Section (which includes templates, network servers, and device plans) that you see when you add a device on the Datacake Platform. {% content-ref url="/pages/-M6ACJSn7S8bUWugprHz" %} [LoRaWAN](/lorawan/get-started) {% endcontent-ref %} #### API By activating this option, the users of your white label site can add new API devices that will receive their measurements over API or MQTT. More information about receiving measurements via API here: {% content-ref url="/pages/-M6nAh4XKJHvdXVq7N0F" %} [Record Measurements via API](/api/record-measurements-via-api) {% endcontent-ref %} ### General Configuration You have the option to enable or disable access to different areas of the platform on your white label site. Under General Configuration, you can hide aspects of the General Configuration of your devices.
The above areas are to be found inside of any of your devices, under Configuration/General. If you chose to disable any of them, they won't be available for your white label users.
### Device Tabs You can chose to hide certain tabs found on your devices.
If you chose to hide them, the following tabs/options won't appear on your white label site:
If you chose to "Hide product configuration", the following part will be hidden:
If you select to hide "devices overview" or "device map", the following options will be removed:
### Features & Integrations The Features & Integrations section allows you to enable or disable optional platform capabilities for users of your white label site. This includes integrations such as Cake Red (Datacake’s managed Node-RED service) and MQTT, as well as workspace-level integrations that let users connect external services like webhooks, LoRaWAN network servers, or custom MQTT brokers. By controlling these options, you can tailor the platform to match your specific use case and limit access to only the features your users need.
In addition, you can configure monitoring and data management features such as gateway monitoring, reports, exports, and zones. These options determine whether users can receive connectivity alerts, generate reports, export data, or organize devices into zones. This level of control helps you simplify the user experience while still providing access to advanced functionality where required. The Rules section further allows you to manage automation capabilities within your white label environment. You can enable legacy rules, the Rule Engine, and rule notifications independently, giving you flexibility in how users interact with automation features. This ensures that you can support both simple notification use cases and more complex automation workflows, depending on your project requirements. ### Sign-up & Login * **Allow Sign-up:** Your users are able to create a user and account for the platform. * **Restrict Login**: If enabled, users are only able to login to your white label site, not app.datacake.de. This is enabled by default for new white label sites. * **Allow Adding Workspace:** Your users are allowed to create new workspaces on the white label site. * **Auto-assign signups to this organization:** If enabled, users that sign up on your white label site will have their workspace placed under your organization, sharing its billing, instead of getting a new organization of their own. This is useful when you want to manage and pay for all of your customers' usage centrally rather than having each user bill themselves. * **Billing:** If enabled, your users will be able to see the Billing section on the left-side menu. {% hint style="info" %} With **Auto-assign signups to this organization** enabled, new sign-ups draw from your organization's existing quota. Make sure your plan provides enough quota for the workspaces and devices your users will create. {% endhint %} ### Single Sign-On The Single Sign-On tab, available in **Enterprise packages**, lets your users sign in with your own identity provider (Okta, Microsoft Entra ID, Google Workspace and others) instead of a Datacake email and password. You verify your users' email domains via DNS, connect your identity provider, and can optionally switch the password login off entirely so Single Sign-On becomes the only way in. {% content-ref url="/pages/1mdQ1aM7vcv0BLi3diLM" %} [Enterprise Single Sign-On](/organization/white-label/enterprise-single-sign-on) {% endcontent-ref %} ### Legal
When your users log in to your white label, the Terms of Service and Privacy Policy are displayed. These are still set to the Datacake Terms by default after the creation of the white label. With the following mask you can add a link to your own terms. ### Users The Users section, available in **Enterprise packages**, provides an overview of all users within your white label environment. It displays key information such as user email addresses, names, the date they joined the platform, and their last activity. This allows administrators to easily monitor user access, track engagement, and manage their user base efficiently. The simplified view ensures you have full visibility over who is using your platform without unnecessary complexity. ### Audit Log The Audit Log, also available in **Enterprise packages**, offers detailed tracking of user and system activity across your white label site. It records important events such as: * logins, * password changes, * user invitations or removals, * device and * product configuration changes, * permission updates, and * downlink actions You can filter events by including or excluding specific activity types, making it easier to focus on relevant information. Additionally, the audit log can be exported as an Excel or CSV file, enabling further analysis, reporting, or compliance documentation. ## Multi-Tenancy Another important fact is that the Multi-Tenancy Feature of Datacake is also available on white label sites. This means that you or your users on your white label site can sign themselves up, register devices and create separate tenants (workspaces). This also means that you still get: * The workspace quota available in your plan * Unlimited Members inside of those workspaces {% hint style="success" %} This is a huge difference to other solutions out there as mostly all of them only allow white label to take place on a single tenant only! {% endhint %} ## Billing By letting your users add LoRaWAN or API Devices on your white label site, they do this in the same way that you do this on Datacake. This means that your end users have 5 devices free but need to pick a plan after they have used up all free devices. Picking a plan requires your end users to provide a credit card on your white label site in order to create more than two free devices. In case you don't want your users to use the billing system, we highly recommend you to use the pin code system, in which you add and configure your devices into your master workspace and your users create a copy of it in their own workspace. This way, your user pays you and you manage the platform billing yourself. ## Canceling your white label site If you no longer need your white label site, you can click the "Cancel White Label site" button and cancel your subscription any time. ### Reactivation When a white label site is canceled, it will remain accessible for the current billing cycle as stated in the confirmation message. {% hint style="success" %} During this period, you are able to reactivate the subscription to prevent a final deletion of the white label site. {% endhint %} ## Rules If a [rule](/portal/rule-engine) is created on a white label site, when the rule gets triggered, it will send out the notification under the white label's configuration. This means that if you create a rule that sends our emails, they will be sent through the email you configured on your white label site. If you are on app.datacake.de, create a rule and have the permissions on a workspace, you have the option to choose the branding for this rule in the editor. ![On app.datacake.de, you can choose the branding for emails sent by a rule.](/files/-MJlymQdDh3OT0PXiDr8) ## Best Practices ### User Accounts As a Datacake white label site is just a proxy for branding the platform and optionally taking out various elements, your user accounts that work on `app.datacake.de` also work on your white label site. This means that you will be able to see all workspaces you have been added as a member also on your white label site. ### Administration We recommend that you use the `app.datacake.de` portal for the administration and management of your devices, as well as your white label site. ### Customers Onboard your customers on your white label site. This way they will get the email invitations, as well as any notifications with your branding and through your setup email. # Enterprise Single Sign-On Let users of your white label site sign in with your own identity provider, such as Okta, Microsoft Entra ID or Google Workspace. ## What is Enterprise Single Sign-On Enterprise Single Sign-On (SSO) lets the users of your white label site sign in with your organization's identity provider instead of a Datacake email and password. Once SSO is enabled, a **Sign in with Single Sign-On** button appears on the login page of your white label site. If you want to, you can go one step further and switch the password login off entirely, so that Single Sign-On becomes the only way in. Datacake supports any identity provider that speaks SAML or OIDC, including Okta, Microsoft Entra ID (Azure AD), Google Workspace, OneLogin, JumpCloud and Ping Identity. {% hint style="info" %} One identity provider is connected per white label site. The connection belongs to the organization that owns the site, so all users signing in through that site use the same identity provider. {% endhint %} ## Requirements * **Enterprise Single Sign-On** included in your plan or booked as an add-on package. If it is not included, the Single Sign-On settings are visible but disabled — contact your account manager to add it to your subscription. * The **White Label** permission on the workspace that manages your white label site. * An identity provider that supports SAML or OIDC, and administrative access to it. * Access to the DNS configuration of every email domain your users sign in with. ## Step 1: Enable Single Sign-On Open **White Label** from the left sidebar navigation, select your site and switch to the **Single Sign-On** tab. Enable **Single Sign-On**. This makes the Single Sign-On button appear on the login page of your white label site and unlocks the rest of the configuration below. ## Step 2: Add and verify your email domains Before your identity provider can be connected, you have to prove that you own the email domains your users sign in with. In the **Verified domains** section, enter a domain (for example `techcorp.com`) and click **Add**. {% hint style="warning" %} These are the **email domains of your users**, not the web address your white label site is served on. The two are usually different, and you can add more than one if your organization uses several email domains. {% endhint %} Free email providers such as `gmail.com`, `outlook.com` or `gmx.de` cannot be used. A Single Sign-On domain routes every account at that domain to one organization, so consumer domains are rejected. If another organization has already claimed the domain you entered, adding it fails as well — please reach out to support in that case. ### Publish the DNS record After adding a domain it shows the status **Pending verification**. Click **Show record** to reveal the DNS record you have to publish at your DNS provider: | Field | Value | | --------- | ------------------------------------------------------------------------------------------------------------------ | | **Type** | `TXT` | | **Name** | `@` — the root of the domain. Some DNS providers write this as `@`, others expect the host field to be left empty. | | **Value** | `verification_token=…` — copy the value exactly as shown, including the `verification_token=` prefix. | Verification runs automatically. Once the record is live, the domain flips from **Pending verification** to **Verified** within a few minutes, without you having to do anything. The list refreshes itself while a domain is pending; you can also use **Refresh** to check immediately. {% hint style="warning" %} Leave the TXT record in place. Verification is re-checked over time, so if the record is deleted — for instance while cleaning up or rebuilding a DNS zone — the domain drops back to **Pending verification** and stops counting as verified. {% endhint %} ## Step 3: Connect your identity provider With at least one verified domain in place, click **Configure Single Sign-On** under **Configure your identity provider**. A configuration portal opens in a new tab, where you pick your identity provider and follow its specific setup instructions — typically exchanging metadata URLs or certificates between the portal and your identity provider's admin console. {% hint style="info" %} The configuration portal is hosted by WorkOS, our identity infrastructure provider. You will be redirected to a `workos.com` address — this is expected. The link is valid for a few minutes; if it expires, just click the button again. {% endhint %} The portal opens in a new tab so your white label settings stay open in the background. Once the connection is live in the portal, users can sign in. ## Step 4 (optional): Require Single Sign-On By default, users can still sign in with an email address and password alongside Single Sign-On. To make Single Sign-On the only option, disable **Allow password login**. On a site with password login disabled: * the password fields, the "forgot password" link and the public sign-up are hidden from the login page, * the standalone password reset and public sign-up pages redirect away, * invitation-based sign-up still works, so you can keep inviting users. {% hint style="success" %} **Allow password login** only takes effect while Single Sign-On is enabled. If you switch Single Sign-On off again, password login comes back automatically, so a site can never be left with no way to sign in. The setting also applies to your white label domain only — `app.datacake.de` is never affected. {% endhint %} ## What your users see Users open the login page on your white label domain and click **Sign in with Single Sign-On**. They are sent to your identity provider, authenticate there, and land back on your domain, signed in. If you disabled password login, the Single Sign-On button is the only thing on the login page. Signing in for the first time creates the user's Datacake account automatically — there is no separate registration step. ## Accounts and organizations Because accounts are created on first sign-in, it is worth checking how new users are placed before you roll Single Sign-On out to a larger group. {% hint style="warning" %} If **Auto-assign signups to this organization** is switched off in the **Sign-up & Login** settings, every user who signs in via Single Sign-On for the first time gets their **own new organization**, with its own billing. To have your users share your organization and your billing, enable that setting before inviting people to sign in. See [Sign-up & Login](/organization/white-label#sign-up-and-login). {% endhint %} A few more interactions to keep in mind: * **Allow sign-up** does not gate Single Sign-On. Even with sign-up switched off, a user who authenticates successfully through your identity provider gets an account. The setting only governs the email and password sign-up form. * **Restrict Login** still applies. A user whose account belongs to a different white label site and is restricted to it cannot sign in through your site. * If a user already has an account **on this site** with the email address your identity provider reports, that existing account is used — nothing is duplicated. ### Email addresses already in use elsewhere If the email address reported by your identity provider already belongs to a Datacake account **outside** your site — on `app.datacake.de`, on another white label site, or a private account — the sign-in is refused instead of taking over that account. Datacake never claims an existing account based on an identity provider's assertion alone. {% hint style="danger" %} There is currently no self-service way to merge such an account. The error message on screen suggests signing in with a password to link Single Sign-On, but that flow does not exist yet — please contact support, who can resolve the conflict for you. {% endhint %} ## Troubleshooting | Message on the login page | What happened | What to do | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | We could not complete sign-in with your identity provider. | The exchange with the identity provider failed, for example because the connection is incomplete or was changed. | Try again. If it persists, reopen **Configure Single Sign-On** and check that the connection is complete and active. | | Your identity provider authenticated you for a different organization. | The user was authenticated against a different organization than the one this white label site belongs to. | Check that the user signs in on the correct white label domain, and that only one connection is configured for your site. | | Your account is restricted to a different site. | The user's account belongs to another white label site that has **Restrict Login** enabled. | The user has to sign in on their own site, or their account needs to be moved. | | An account already exists for this email. | The email address is already used by a Datacake account outside your site. | Contact support — see [Email addresses already in use elsewhere](#email-addresses-already-in-use-elsewhere). | **A domain stays on "Pending verification".** Confirm that the TXT record is published on the **root** of the domain and that the value includes the `verification_token=` prefix exactly as shown. DNS changes can take a while to propagate; use **Refresh** to check again. If your DNS provider appends the domain name to the host automatically, leave the host field empty rather than entering `@`. ## Limits * One identity provider per white label site. * An email domain can be claimed by one organization only. If your domain is already taken, contact support. * Users are not assigned to workspaces based on groups or roles from your identity provider. Workspace membership and permissions are managed in Datacake. # Set your White Label Site as Default Branding As you might know, when working with your white label site, you need to still use app.datacake.de to manage it. To avoid struggles and common mistakes, you can now set the default branding for your Reports, Rules and invitations to be your own branding. ## Overview The new **Default Branding** feature allows administrators to set a **workspace-specific** branding that is automatically applied across multiple areas of the platform. This prevents accidental use of the standard Datacake branding and saves time when inviting members, creating reports, or setting up rules. This functionality is part of the **White Label** option, which requires **administrator rights with white label and workspace permissions**. ### How It Works * **Previously**:\ Every time you created a report or rule, or invited a member to a workspace, you needed to manually select your white label branding. By default, the system pre-selected the standard Datacake branding. This often led to mistakes if the white label site was not chosen. * **Now**:\ With default branding at the workspace level, your chosen white label site is automatically pre-selected across all supported areas. This ensures consistency and reduces human error. ## Setting the Default Branding 1. Go to **Workspace → Default Branding**. 2. Select your desired **white label site** from the list. If you only own one white label site, you will see your white label in the drop-down-list. 3. Save your changes. 4. When creating a new workspace, select your white label site as **Default Branding**. That can always be changed inside of the **Workspace** section on the left-side menu. From this point on, all newly created reports, rules, and member invitations within that workspace will use this branding by default. {% hint style="success" %} Currently, this is a setting on the Workspace Level, not Organization Level, so you still need to set it in each workspace. {% endhint %} # Multi-Tenancy (Workspaces) ## What are Workspaces? Workspaces combine all elements and functions of the Datacake platform in one group. * Devices * Rules and Rule-Engine * Reports * Global Dashboards * Members
### What should I use workspaces for? You use workspaces to implement the function of multi-tenant capability. Create separate areas in the platform for your customers, distributors, technicians, or other persons, to grant them access to your IoT device's information. The workspace will share access to devices, global dashboards, reports, rules, etc. ## Your first workspace When you register on the Datacake platform and create a user account for the first time, a new workspace, with its respective organization is automatically created for you. You can give it a name (which will also be the workspace slug, on the URL). Otherwise, the platform will create a workspace with your name. ### Workspace Settings To change the current settings of your workspace, navigate to the "Workspace" item using the sidebar. You will be able to change the name of your workspace. You can setup a workspace logo, which will be shown on top of the navigation, replacing the "Datacake" logo. The workspace slug is a unique identifier, that also appears on the URL to access to your workspace. {% hint style="info" %} Take into consideration, the **"Workspace slug"** gets created when you create a workspace. It is based in the workspace's name and it cannot be changed afterwards. Choose the name wisely. You can later change the name of the workspace, but this won't change the slug. {% endhint %}
You can delete your workspace, but please take care, this is an irreversible change. You cannot delete your workspace if there are pending subscriptions on it, so you have to firstly cancel all existing subscriptions in the Billing section. ## Long SMS Mode and SMS Log You will now find the SMS log and the Long SMS Mode configuration on your workspace section. This will help you to manage SMS notifications locally using the workspace definition to separate from other tenants. A single SMS message supports up to 160 characters, or up to 70 if the message contains one or more Unicode characters (such as emoji or Chinese characters). On **Long SMS Mode** you can choose between these options: * Truncate: The option will cut the content of the SMS to fit the 160 character limit. * Charge: When you send an SMS message containing more than 160 characters, the message is split into smaller messages for transmission. All of those are charged as individual SMS. Datacake now supports **SMS quotas**, allowing Organization administrators to control how SMS credits are distributed across their workspaces. Instead of all workspaces consuming from the same pool, administrators can allocate a specific amount of SMS credits to each workspace, ensuring that usage stays within defined limits. This helps organizations manage SMS costs and prevent a single workspace from consuming all available credits. You can learn more about configuring SMS quotas and managing credit distribution in the [**SMS credits documentation**](https://docs.datacake.de/portal/billing/sms-credits)**.** ## Switch between Workspaces If you have more than one workspace, or you have been invited into a workspace by another user, you can switch to other workspaces at any time using the Workspace Selector. Move your mouse over the workspace's name on the up-left corner, at the top of the sidebar. A pop-up menu opens, which lists all workspaces in which you are a member.
You can search for your workspace's name, or navigate using your keyboard. To switch to another workspace, simply click with the mouse on one of the entries in the list or press "Enter" when navigating with the keyboard. ## Device & Members Management The Datacake platform allows you to create your own additional workspaces. They can be created within the same "Organization", to allow them to share Billing details, SMS credits, add-ons, white label site configuration, between others. Each workspace will have their own device and members section, independent from other workspaces.
## Create additional Workspaces To create another workspace, move your mouse pointer over the Workspace Selector at the top of the left sidebar.
You can then select "Add Workspace". A new modal will open to name your workspace and select its Organization. Activate "Add new workspace to existing organization" to include the workspace inside of an already existing organization. This is recommended when you want workspaces to share billing, SMS credits, add-ons, like the rule engine, and white label configuration.
You can always create a new organization, if you want to keep billing separate. You can also apply **white-label branding** instead of the default Datacake branding, if it is included in your subscription. When selected in the dropdown menu, the workspace will automatically inherit the configured white-label logo and domain settings of your choice, ensuring it appears under your white-label branding as soon as it is created. That's it. Your new workspace is now created and you or your user account has been automatically added to the workspace as a member with all rights. You can now continue and create your own devices or add already existing devices using the Claiming functionality. ## Invite People into your Workspace To load additional users into your workspaces, use the sidebar to navigate to the "Members" item under the "Administration" group. There you will find a list of all members currently in the workspace, as well as the current rights of each member. With the button "Add Member" you can load further persons into your workspace. More details about these process, how to assign rights, and what effects this has on the person can be found in the following section: {% content-ref url="/pages/-M-JQIrbSj0vI9NmTYGU" %} [Members](/portal/members) {% endcontent-ref %} ## Moving Devices between Workspaces Currently, the only option to move a device between workspaces is to set a Pincode on your device and claim it into a different workspace by entering this code on the "Add Device" dialog. We have written up more information and a tutorial on how to do that here: {% content-ref url="/pages/-M-JQQctuXfCo26MgDFn" %} [Claiming](/device/claiming) {% endcontent-ref %} ### Ownership If you place a device in multiple workspaces, then the workspace that originally created the device is also the ultimate owner of that device. If you want to transfer the ownership to another workspace, then this is currently only possible by removing the device and adding it into the desired workspace. # Folders ### Overview The **Folders** feature allows you to create subsets of devices inside your workspace. This makes it easier to organize, filter, and view devices based on tags. Instead of handling one long list of devices, you can now manage them in dedicated folders with customized viewing and filtering options. Check out Simon's video here: {% embed url="" %} ### Creating a Folder 1. Navigate to your **Workspace**. 2. Select **Manage Folders,** underneath "Devices". 3. Click the **➕** appearing to the right when you hover over All Devices. That is the **Add Folder** button. 4. Configure the folder: * **Name**: e.g., *Group A Devices, Building A, Temperature Sensors*, or whatever you like. * **Folder Icon**: Choose from preset options (folder, building, energy, home, etc.). * **Description**: Add context such as *Devices in Building A, floor 1*. 5. Define device filters: * Filter by **tags** (single or multiple). If you select *Match all tags*, devices must include **all** selected tags. If you select *Match at least one tag*, devices can include **any** of the tags added. * Optionally, display **online devices only**. 6. Choose **Display & Viewing Options**: * Select which views to enable: **Overview**, **List**, **Grid**, and/or **Map**. * Define the **default view** that opens when entering the folder. 7. Save your changes. Your folder is now ready and will appear in the sidebar under your device list. ### Edit, Remove or Sort your Folders You can always go back and edit, remove or sort your existing folders. * Click on **Manage Folders**. * Hover over your folder and you will see the icons ↓➕🗑️ to the right of your folder's name. * ↑↓ allow you to move your folder up or down the list. * ➕ you can create a new folder, either down the "All Devices" category, or as a sub-category of an existing folder. * 🗑️ to remove your folder. Select any of your folders and edit their details, the filtering method, or the display & viewing options any time you want. Don't forget to save the changes. ### Folder Display & Viewing Options Each folder can start with a different visualization style: * **Overview** → Displays aggregated metrics (e.g., average temperature, battery level). Those are based on the[ Field Semantics](/field-semantics). * **List** → Tabular list of devices with key data. * **Grid** → Card-style layout for quick scanning. * **Map** → Geographic visualization (only available if devices have locations). You can also hide irrelevant views (e.g., remove **Map** for devices without location data). ### Benefits * **Simplified Device Management**: Keep workspaces organized by logical groups. * **Custom Visualization**: Choose the best view for each folder. * **Quick Access to Metrics**: See aggregated min/max/average data for any subset of devices. * **Flexible Filters**: Use tags to dynamically group devices without manual reorganization. ✅ That’s it! With **Folders**, organizing devices in Datacake becomes fast, intuitive, and scalable. # Reports Create periodic CSV exports of your sensor data The Datacake platform allows you to create periodic exports of the data from your devices. With the Reports feature you can: * Set your own time ranges for automatic report generation (hourly, daily, weekly). * Select one or more devices by group, day, or by name. * Set file format. In this section of our documentation we will show you exactly how to do this. For a step-by-step guide on our Reports and how to create them, be sure to check out our video tutorial ⬇️ {% embed url="" %} ## Your First Report To create your first report, navigate to the section of the same name using the sidebar. ![](/files/-MUPlRsYS-cLKoBCKjun) After clicking, the content view will switch to a list of reports. As long as you or someone else in your workspace has not yet created any reports, this list is empty and looks something like the screenshot above. To create your first report, please click on the button "Add Report". The following modal appears: ![](/files/-MUPldVwpFgKKMrisdaI) ### Report Name Here you can assign a name for your reports. This will also be displayed in the table on the overview page. ### Report Type As a next step, select the type of export. Currently the report engine supports the following types: * Simple CSV - "Export multiple device data to CSV" #### Simple CSV * Export historical readings of selected devices in your workspace as a CSV file. * Define individual time periods for the length of the historical data. * Export the Report as a single CSV file per device or a summarized file. ### Schedule Select here a period for the recurring execution of the export. #### Timezone The reports are executed on our server systems, which work with UTC and therefore it is important that you define a time zone for the report job. #### Next executions For your review, here we show you the next three executions of your report. ## Detailed Settings After clicking on the "Create Report" button in the modal, your report job will be created and a detailed view will open where you can define the further settings. This looks like the following: ![](/files/-MUSJ5Hcs-2MNkFV2AN2) In the first section on the overview you will see the settings that you had already set in the modal. You can edit them here afterwards. ## Report Receivers In the basic settings you can also specify the recipients of your reports by specifying an e-mail address. ![](/files/-MUSgMsngKolmGCVGYzB) ### Download and Attachment All recipients specified here will receive a mail with a link to the download and CSV file as a direct file attachment. ## Simple CSV If you now scroll down a little, you will see the settings and information relevant for the respective report type. ![](/files/-MUSIcAzRzLf6AIBURkW) ### Filter by Device Name With the help of the name filter you determine the devices included in the export by specifying a text. All devices with this text in their name will be listed. The name only has to contain this character string, regardless of its position or whether it is written in upper or lower case. ![](/files/-MUSSx6i65VUikR0pD6Z) So if the devices you are going to use for export all carry "Temperature X" as their name (where X is a sequential number), then simply enter "temperature" here. This way, all devices that have "temperature" anywhere in their name will be included in the export. ### Filter by Tag If you have assigned a tag to your devices, then the export provides a listing of these tags. Then simply select one of the tags and from now on all devices assigned to this tag will be taken into the export. ![](/files/-MUST6eHCdc_pUXPZ8Om) If you define more than one tag, then the devices must be assigned to both tags from now on. So it is an AND operation. ### Preview Below the filter section you can see the number of devices found by the exporter, as well as a short listing. ### Include Database Fields After you have defined the devices, you can now select the database fields whose values are to be exported. To do this, simply select the corresponding fields via the drop-down menu. ![](/files/-MUSTMvuOz6TfplepRr6) In this drop-down menu, the fields of all devices are visible, including fields that are cross-device. You can also select fields that are not shared by every device. The respective fields are then displayed as a list and can be removed or additional fields added at any time. ![](/files/-MUSTHtmws2Rx66c5LAz) ### Select Timerange ![](/files/-MUSTVw16f93sGa80-jW) #### From / Until Determines the time period over which the historical data of the sensors and its fields are loaded. Here you define the start and end range of the historical data export. Each time the report is now created, it uses the information specified here for loading the data. {% hint style="info" %} It therefore makes sense that you work here only with relative time specifications, such as "24 hours ago" to "now", since an absolute date would not change with a continuous, periodic report. {% endhint %} #### Timezone {% hint style="info" %} If you use an absolute time in the time range specification (such as "Midnight" or even an actual date), then you must specify your time zone so that the report loads the data from the database according to the appropriate time zone. {% endhint %} As already mentioned, this is due to the fact that the reports are run in the background on our servers, and that they work with UTC time. So, specifying the time zone is important for absolute times. However, if you work with relative times ("24 hours ago" to "now"), then the time zone does not need to be specified. ### Resolution Resolution allows you to specify quantization of the data at regular intervals or to export the raw data from the sensors. Normally, the data export is performed as "Raw Data", i.e. the data in the export corresponds to the data as sent to Datacake by your devices. However, in an export with a larger time range, this can create very long CSV files. The solution here is to specify a "Resolution", i.e. a quantization (or summary) of the data according to time segments. ![](/files/-MUSTbGIsL8NBN7jw5Dk) To do this, click on the drop-down and select an appropriate time range (minutes or hours) and then specify this as a numerical value using the text field. #### Example Let's assume that the Devices you selected send measurement data at intervals of 5 minutes. You now select a time range of one day. The result would be `24 * (60 / 5) = 288` lines per export. If you now specify a resolution of 60 minutes, the number of lines is reduced to: `24 * (60 / 60) = 24` lines, since one measurement per hour. #### Operation The operation of the summary is currently: * `Float / Integer`: Average over given Resolution-Interval * `Counter`: Sum over given Resolution-Interval (Start / End) - or delta of (End - Start) * `Boolean`: The value that occurred most often (if 55% "True" and 45% "False" occurred within the resolution period, then the specified value is "True") * `Geolocation`: The value from the time center is taken. So if the resolution is set to 60 minutes, then the value is taken that lies in the time center, i.e. at +30 minutes. We will add more options in the future. ### Output File Type The "Simple CSV" export allows two methods of file output: * One file per device * All devices combined in a single file You can select the method by chosing one of the available option by clicking on the correspoding radio-button entry: ![](/files/-MUS_YQCHqd3rzUKOpTS) ### File Name In the last part you can still individualize the file name and/or specify placeholders for dynamic information (such as date or device number), which are then set to the current value per export. Simply use the text box available here and individualize the file names. ![](/files/-MUSaz6iTxN2qNNKcX7y) The available placeholders can be found below the text box for the file name. ## Manually Run Report If you want to check the result of your report, then you don't have to wait for the execution for this, but you can start the execution manually at any time. To do this, navigate to the overview of reports and click on the icon at the right end of the report entry in the table of the listing. A context menu will open and here you can perform the manual execution. ![](/files/-MUSeHWrNxHVqwDDSmrj) ## Download Reports In addition to the option to have the reports emailed to any recipient, you can find the past reports as a listing in the report's detail view. ![](/files/-MUSfSInpiVN_xdsZeh9) To do this, open this view and scroll to the end, you will then see the following section: ![](/files/-MUSfXJa5g5jT0wH86aK) # Report Builder (PDF Reports) The PDF Report Builder allows you to create customized reports containing device data, KPIs, charts, and tables. Reports can be generated automatically according to a schedule and delivered to selected recipients by email. ### Opening the Report Builder To open the Report Builder: 1. Open the relevant workspace. 2. Select **Reports** from the workspace navigation. 3. Open the **Report Builder** tab. The Reports section contains the following tabs: * **Report Builder** – Creates configurable PDF and web-based reports. * **Simple CSV** – Displays reports created using the previous CSV reporting feature. This tab only appears if the workspace already has legacy CSV reports. * **Energy Reports** – Creates reports intended specifically for energy-monitoring applications.
{% hint style="info" %} The previous Simple CSV reporting feature has been deprecated. Raw data exports can now be configured from the separate **Exports** section. {% endhint %} ### Configurations and generated reports The Report Builder contains two tabs:
#### Configurations The **Configurations** tab contains the report configurations created for the workspace. From here, you can create, open, and manage your scheduled reports. #### Generated Reports The **Generated Reports** tab contains the individual reports that have already been generated. For every generated report, you can see information including: * Generation status * Report name * Available artefacts * Creation date * Expiration date Click an artefact to open or download it. You can also search the list using the report name or report ID. ### Creating a PDF report To create a report: 1. Open **Reports**. 2. Select **Report Builder**. 3. Open the **Configurations** tab. 4. Click **Add Report**. 5. Select **PDF Report**. 6. Enter a name for the report. 7. Optionally, select an existing template. 8. Configure which devices should be included. Devices can be selected directly or filtered using device names and tags. Using tags is especially helpful when the report should automatically cover a particular group of devices. After creating the configuration, the Report Editor opens.
### Working with the Report Editor The Report Editor allows you to configure the report and build its contents. The editor includes a report preview so that you can review the structure while working on it. The report Settings determines: * When the report is generated * Which period of data is included * How the data is aggregated * Which devices and fields are used * Which content appears in the report * How the finished report is delivered
### Configuring the schedule Reports can be generated automatically according to a recurring schedule. Depending on the selected frequency, configure the relevant scheduling settings, such as: * Frequency, for example weekly * Day of generation * Time of generation * Time zone The selected time zone determines when the scheduled report is generated and how dates and times are represented.
### Configuring the report period Select the period of data that each report should cover. For example, a weekly report can be configured to include the data collected during the previous week. You can also select a resolution for the report data. Available resolutions include intervals such as: * 15 minutes * 30 minutes * One hour * One day The resolution determines how the source data is grouped. It can also affect the size of tables and the level of detail shown in charts. A smaller interval produces more data points and longer tables. A larger interval produces a more condensed overview. ### Choosing the output format The report can be made available in the following formats: * **PDF document** – Generates a downloadable PDF file. * **Interactive web view** – Generates a browser-based version of the report. * **PDF and web view** – Generates both formats.
### Language and regional formatting Use the locale setting to select the language and regional formatting used in the report. The selected locale can affect elements such as: * Dates * Times * Numbers * Automatically generated labels ### Configuring email delivery Generated reports can be delivered automatically by email. Add the email addresses that should receive a notification when the report is ready. The email contains a link through which the recipient can access the generated report. When sharing reports externally, confirm that the selected devices and report contents are appropriate for every recipient.
### Password protection Reports can optionally be protected with a password. This provides additional protection when reports contain sensitive information or are distributed outside your organization. Recipients must know the configured password to access a protected report. ### Handling gaps in the data The Report Builder includes settings for handling periods in which no data is available. Choose the appropriate behavior based on the report’s purpose and the expected reporting frequency of your devices. Be particularly careful when filling data gaps in reports used for compliance or operational decision-making, as generated values may not represent actual measurements.
### Adding content to the report Reports are built by adding widgets to the report layout.
#### KPI widget The KPI widget displays a summarized value for a selected field. Use KPI widgets to highlight important measurements such as: * Average temperature * Minimum or maximum values * Energy consumption * Average humidity * Device performance indicators Configure the device, field, and aggregation that should be used for the calculation.
#### Time Series Chart The Time Series Chart visualizes how one or more measurements changed during the report period. Use it to show: * Environmental trends * Temperature changes * Energy consumption over time * Comparisons between devices or fields * Unusual peaks or drops
#### Time Series Table The Time Series Table displays historical measurements in a table. The number of rows depends on the report period and selected data resolution. For example, a report using a 30-minute resolution contains more rows than the same report using a daily resolution. Consider using a larger resolution if the table becomes too long for the report.
### Creating sections for each device Use a **Device Loop** when the same report structure should be repeated for multiple devices. Widgets placed inside the Device Loop are generated once for every selected device. For example, a loop can contain: * A device heading * A KPI summary * A Time Series Chart * A detailed data table This is particularly useful when reporting on multiple rooms, locations, sensors, or assets using a consistent layout. The devices included in the loop are determined by the report’s device selection or filters. When device tags are used, newly added devices with matching tags can be included without rebuilding the complete report structure.
### Saving and activating the report Once the report has been configured: 1. Review the report settings and preview. 2. Save the report configuration. 3. Confirm that the schedule is enabled. 4. Return to the **Configurations** tab to verify that the report appears in the list. The report will then run automatically according to its configured schedule. When generation is complete: * The result appears under **Generated Reports**. * Configured recipients receive an email notification. * The available PDF or web artifact can be opened from the report list.
### Beta limitations The Report Builder is currently in beta. Keep the following points in mind: * The interface and available widgets may change. * Generated reports have an expiration date. * Report length depends on the number of devices, widgets, selected period, and data resolution. * Large tables or Device Loops containing many devices can produce long reports. * Data can only be displayed when measurements are available for the selected fields and period. * The initial version focuses on configurable data presentation and does not automatically provide compliance assessments or alert summaries. This draft still needs the exact names of the data-gap options, supported locales, and availability by plan. I would also add screenshots for the Reports overview, schedule settings, editor, widget menu, Device Loop, and Generated Reports page. # Energy Report Energy Reports in Datacake enable automated, scheduled reporting of device consumption data. Reports are delivered via email and provide detailed energy consumption analysis across different time peri ### Creating an Energy Report 1. Navigate to the Reports section and click "Create Report" 2. Select "Energy" as the Report Type 3. Configure basic settings: * Report Name: Provide a descriptive name * Timezone: Select appropriate timezone * Schedule: Set execution time and days

Basic Settings

### Report Configuration #### Email Settings * Add recipient email addresses * Select email branding template if you have one or more [White Label sites](/organization/white-label) #### Device Selection * Choose between: * Explicit: Select specific devices * Product: Include all devices from a product #### Timeframe Options **Preset Timeframes** * Last 7 days (bucketed by day) * Last 30 days (bucketed by week) * This month (bucketed by week) * This year (bucketed by month) * Custom range (configurable bucket width) **Custom Range Configuration** * From: Start date (e.g., "7 days ago") * Until: End date (e.g., "now") * Bucket width: Day/Week/Month

Energy Report Settings

### Understanding Time Bucketing Time bucketing determines how data is aggregated in the report. Each bucket represents a time period with opening and closing values. #### Example Data and Bucket Calculation

Sample Data

With monthly buckets, the Excel report generates: **January Sheet:** * Open: 3 (First value in January) * Close: 12 (First value in February) **February Sheet:** * Open: 12 (First value in February) * Close: 18 (First value in April, as March has no data) **March Sheet:** * Open: 18 (Last known value) * Close: 18 (Next available value) **April Sheet:** * Open: 18 (First value in April) * Close: N/A (Since no data newer than April exists)

Report Data

#### Bucket Calculation Rules 1. Open Value = First value in bucket period 2. Close Value = First value in next bucket period 3. If no data exists in bucket, use next available value for both open/close 4. Consumption = Close - Open #### Time Bucketing Process 1. Raw data points are collected 2. Points are grouped by bucket width (day/week/month) 3. Each bucket becomes a sheet in Excel 4. Devices listed as rows in each sheet 5. Open/close values calculated per bucket 6. Consumption computed as difference between close and open # Exports The **Exports** feature allows you to export raw device data from the platform. It replaces the previous simple CSV report inside of the Reports and provides more flexibility for exporting data manually or automatically. Exports can be used for: * Debugging device data * Creating manual backups * Generating recurring data backups * Exporting specific device fields or semantic data You can access the feature from the **Exports** section in the left-side navigation menu. ## Overview The Exports page contains two main tabs: #### 1. Export Configurations This tab is used to create and manage export configurations.
Export configurations define: * Which **devices** should be included * Which **fields** should be exported * The **timezone** * Whether the export is **manual or automatic** * The **schedule** (for automatic exports) * For automatic exports, the next run is also shown #### 2. Generated Exports This tab lists all exports that have already been generated. From here you can: * View previously generated export files * Download exported data You can multi-select and download exports.
## Create Export ### Manual Exports Manual exports allow you to export device data for a **specific timeframe**. This is useful when you want to: * Debug device reporting issues * Check whether data was written correctly to the database * Export historical data for analysis * Create a one-time backup for a specific time period #### How Manual Exports Work
When creating a manual export, first set your Export's name. This will help you identify it in the future. #### Devices Then you need to choose the device selection. You can choose between: * **All devices**: will include the data from all of your devices in your workspace. If there's more than 100 devices, each file will represent maximal 100 devices, * **Devices by tag:** this is the default selection. Filter the devices to be included by tags, or * **Devices by name**: you can filter your devices by name. You don't need to type in the whole name, but parts of the name will filter all devices that contain certain words. You can click on "**Show included devices**" to make sure your device selection worked properly. #### Timeframe Then select the data timeframe of your interest. You can do so using the calendar selector. Depending on your package, you will have a certain number of days into the past that you can manually download data from. #### Timezone Then you can select your timezone. That will make sure the timestamps included in the report are in your timezone. #### Fields The next step is to select the **Fields** from the chosen devices. For that, you can choose between three options: * **All fields:** this will automatically select all fields from the chosen devices. Choose these option carefully. The bigger the amount of fields, the longer it will take to generate your export. * **Field names:** this option will enable a drop-down-list with your device's fields. You can manually select the fields you are interested in. Please make sure you select ALL desired fields manually. Sometimes, if your devices selected belong to different products, there might be more than one field of interested (for example, if one device has a field TEMP and the other a field called TEMPERATURE, you need to manually select both fields to appear in the export). * **Semantics:** they allow you to select the semantic of interest. This option avoids having to select all fields manually. In the example mentioned in the point before, if you select the semantic TEMPERATURE, all temperatures will be included in the export, regardless of their name. #### Format Finally, you can select between **CSV** or **Excel (XLSX)** format. {% hint style="info" %} Excel format is only available in packages starting in the Light plan. {% endhint %} If you selected CSV as format, you have two more options to chose from: * Select the CSV date format: **Year-Month-Day Hour:Minute:Second** or **ISO 8601** * Finally, select the CSV file delimiter: Comma-delimited CSV or Semicolon-delimited CSV Once you click on "Create Export", you should be able to see the created export directly inside of the "Generated Exports" section. You can go ahead and download it from there. The exported file will include: * **Timestamp** * **Raw data points stored in the database for all fields included in the export** This allows you to inspect exactly what data was recorded during the selected time period. #### Example Use Case If a device stopped reporting data or behaved unexpectedly, you can export the raw data for that device during the affected time window and analyse the recorded values. Manual exports are available to **all users**. ## Automatic Exports Automatic exports allow you to generate **recurring backups of your device data**. Instead of manually exporting data, the system will generate exports automatically based on a schedule.
The same as for the manual exports, the automatic exports allow you to select which devices and fields should be included in your exports. #### Devices You can choose between: * **All devices**: will include the data from all of your devices in your workspace. If there's more than 100 devices, each file will represent maximal 100 devices, * **Devices by tag:** this is the default selection. Filter the devices to be included by tags, or * **Devices by name**: you can filter your devices by name. You don't need to type in the whole name, but parts of the name will filter all devices that contain certain words. You can click on "**Show included devices**" to make sure your device selection worked properly. #### Scheduling Options Automatic exports can run on a: * **Daily** * **Weekly** * **Monthly** basis. {% hint style="info" %} Availability: Automatic exports are available only on **paid plans**, starting with the **Light plan**. For Light and Standard plans you have daily and weekly exports available. For Plus and Enterprise plans you also have monthly exports available. {% endhint %} Each scheduled export will generate a file containing the selected device data for the defined time interval. You can specify the **time zone** used for the timestamps in the export file. This ensures exported timestamps match your preferred timezone. #### Fields You can choose between three options: * **All fields:** this will automatically select all fields from the chosen devices. Choose these option carefully. The bigger the amount of fields, the longer it will take to generate your export. * **Field names:** this option will enable a drop-down-list with your device's fields. You can manually select the fields you are interested in. Please make sure you select ALL desired fields manually. Sometimes, if your devices selected belong to different products, there might be more than one field of interested (for example, if one device has a field TEMP and the other a field called TEMPERATURE, you need to manually select both fields to appear in the export). * **Semantics:** Using semantics allows the system to **normalize data across different device types**, making exports easier to analyze and compare. {% hint style="info" %} Depending on the export frequency, the next export will be scheduled to run on the "Next run", pointed at the right corner of the "Export Configurations" tab. You will receive {% endhint %} #### Email notifications Set one or more recipients. They will receive a notification that the export was generated (**NOT THE EXPORT DIRECTLY**). To download it, you need to go to "Generated exports" and manually download the files. #### Format You can select between **CSV** or **Excel (XLSX)** format. {% hint style="info" %} Excel format is only available in packages starting in the Light plan. {% endhint %} If you selected CSV as format, you have two more options to chose from: * Select the CSV date format: **Year-Month-Day Hour:Minute:Second** or **ISO 8601** * Finally, select the CSV file delimiter: Comma-delimited CSV or Semicolon-delimited CSV Once you click on "Create Export", you should be able to see the created export directly inside of the "Generated Exports" section. You can go ahead and download it from there. The exported file will include: * **Timestamp** * **Raw data points stored in the database for all fields included in the export** This allows you to inspect exactly what data was recorded during the selected time period. # Members ## What are Members? Members are User-Accounts that have access to a given Workspace. You can add multiple members into your workspace and define rights and roles and the devices the user is allowed to see, control, change. For a step-by-step guide on our Members section, be sure to check out our video tutorial ⬇️ {% embed url="" %} ### Different Types of Members Currently there are two types of Members: 1. **Normal Users** - which are physical Users that have a User-Account on the Datacake Plattform and that log in using E-Mail / Password combination.
2. **API Users** - which have the same mechanisms like rights and role management for devices and functions but instead of having a user-account, API users can be created dynamically and provide a Token that you can use for the REST-API or Datacake MQTT Broker. Read more about API Users here: {% content-ref url="/pages/-M4isfwhIv2qppzqVYI-" %} [API Users](/portal/members/apiuser) {% endcontent-ref %} ## Add a new Member To invite new members to your workspace, use the sidebar to navigate to the "Member" item under the "Administration" group. You should now see the following content in your browser ![](/files/-M4LIHn80Db1TE8WHqYu) To create a new member, click on the button "Add Member". You will find this button in the upper right corner of the "Members" panel. The following dialog will then appear: ![](/files/-M4LJp-GRtcoEPAg5EIX) ### Invite via E-Mail You always add members by entering the e-mail of the desired user. This user will then receive an invitation by e-mail, which he/she must confirm in order to finally register. If the invited person is already a member of the Datacake platform, they will be added to your workspace immediately. ### Set Workspace permissions With the workspace permissions you control what rights the user has in your workspace. Basically, you can define here very finely what is allowed - and what is not. However, you do not necessarily have to activate an option and can invite the user to the platform as an "observer". The following workspace permissions are currently available for selection: ![](/files/-M4LJvuWt7NCRVCXBjzc) #### Basic Sets basic permission to edit the name and logo of the current workspace. #### Billing This option gives the user access to the statements, invoices and payment settings in your workspace. #### Devices If this option is activated, the user may create new devices or remove existing ones. #### Members By activating this option, the user can also invite or remove other members, create or remove own teams and define permissions. #### Workspaces Activate this option if you want the user to be allowed to create their own workspaces. #### Rules Allows the user to use the rule engine and create, edit and remove rules for devices. ### Add Devices At the time of inviting a new user, you can already determine which devices the user is allowed to access. To do this, simply type the device name into the search field below "Device Permissions" and confirm the device you are looking for by clicking on it in the search results. ![](/files/-M4O2IKx2T3Fp2CGICiv) ### Set Device Permissions Once you have selected the device(s), a new panel appears in the dialog for each device. Here you can define the rights for the respective device and thus determine what the newly invited user may do with the device: ![](/files/-M4O2awIdxQJRJYV92yJ) #### Can view the Device and its data This permission is always activated. It allows the user to view - but not edit - the device and its measured values. #### Can edit the device definition Allows the user to customize general settings like name, location and description. #### Can edit device metadata Specifies that the user may modify the metadata and create his own metafields. #### Can record measurements If this option is activated, the user can set measurement data via his token (API or MQTT) or the manual input of measured values. # API Users ## What are API Users? API User are a special type of user accounts. ![](/files/-M4it5hjb8Yboi3eiRlE) ## Create your first API User To create an API user, navigate to the members' settings using the sidebar. You will find these under the group "Administration" and the item "Members". Use the tab bar in the members panel and click on the item "API Users". This will take you to the API Users section, which lists all API users, if any are available. To create a new API user, click on the button "Add API User". You will find this button at the top right of the panel after clicking on "API Users" in the tab bar. ![](/files/-M4itNH3pp5o6iW83d64) Your should now see the following dialog: ![](/files/-M4itQOOVGutXLrgY6m3) ## Set Workspace Permissions This section defines what the access token may do within the workspace. In other words, all non-Device-specific things, such as administration or creating actions in the Rule Engine. Simply select the things you need for the token. A typical use case is when you need a token for the administration of your workspace, but not for individual devices. The Options are identical to those you device when inviting a new member into your workspace. If you want to read more about the available options and what they do, read: {% content-ref url="/pages/-M-JQIrbSj0vI9NmTYGU" %} [Members](/portal/members) {% endcontent-ref %} ## Set Device Permissions When you create an API user, you can select during the definition which device the token is allowed to access and how this access is staggered. Use the search field to enter the name of the respective Device, select it and then use the checkboxes to select the rights for the respective Device. ![](/files/-M4itfdsUUON-JGMqstd) # Security & Privacy ## Privacy Policy Our privacy policy is hosted on our website. You can view it via the following link: #### [Privacy Policy](https://datacake.co/privacy-policy-2/) ## Data Storage Your data is stored within the European Union. We use two different data centers to run the Datacake platform: * Frankfurt, DE (main data center) * Amsterdam, NL (Backup) ### Frankfurt All servers for the operation of the Datacake platform and the data storage of the measurement data are located on servers in this location (Frankfurt, Germany). ### Amsterdam The data center in Amsterdam is used solely for the outsourcing of backups and as a failover if the Frankfurt site is damaged (e.g. by fire), although this is rather unlikely. ### Backups We run backups of the entire infrastructure on a daily basis, but we do vary slightly in priority. Measurement data is backed up with priority. Data such as user name or tenant information is only backed up once a day since we assume that hardly any data is changed once the data is created. #### I have deleted my data by mistake. Can you restore them? Yes, but if you delete data or devices despite being warned that the data will be deleted afterward, the recovery of the data will be charged by a fee. {% hint style="warning" %} Therefore, please make sure that you only delete the data if you are really sure that you want it to be deleted. {% endhint %} If you still want to use this service, [please contact us](https://datacake.co/contact). ## How we handle your data ### Ownership If you use our platform as a basis for your devices and their measurement data (and all other data), the data remains completely in your ownership. ### Access Control If you create a workspace on Our Platform, as it happens automatically the first time you log in, then only you will have access to this workspace. Neither employees of Datacake nor any other person can view the data of your workspace. If you want to share access to your workspace with other people, you must explicitly invite those people to your workspace. This also applies if you ask a member of the Datacake support team for advice and assistance. This person will only have access to your workspace if you add them as members of that workspace. ### Scope This behavior (ownership and access control) applies to all things within your workspace, including * All devices in your workspace. * All sub-workspaces and their data / devices. * Simply everything within your workspace. ## How we handle the data coming from your Devices You can use the following integrations to connect your devices to the Datacake Portal: * MQTT * REST-API * LoRaWAN * Particle.io You can read more about Integrations here: {% content-ref url="/pages/-Lq\_8LJgAFuzNzoI4-Ge" %} [Integrations](/integrations/mqtt) {% endcontent-ref %} And about LoRaWAN here: {% content-ref url="/pages/-M6ACJSn7S8bUWugprHz" %} [LoRaWAN](/lorawan/get-started) {% endcontent-ref %} ### Anonymous data transmission The following description applies equally to all integrations and describes how the data flows from your devices into the portal and how we handle this data: If your device records data into our systems via one of the mentioned device types above, this is always done anonymously. This means that no personal or workspace-related data is transferred during transmission. For the association of the measurement data to your device and its workspace, an ID number is used, which has high entropy and therefore cannot be decoded and thus contains no personal data. This means that even if someone would be able to read out this information it would still be useless as it would not contain any description of what kind of data this is. When you open the portal via the front-end or the smartphone app on your mobile device, the ID number of your workspace is transferred to the server as a request. The server then transmits a list of all devices. The data in this list is still anonymous. This information is then combined in a table in the frontend. This assignment does not take place on our servers, it is only implemented using the graphical arrangement of the front-end. All data of your devices and their measurement data are always anonymous and do not show any personal information. ## FAQs ### Do you share my data? No. The data on your equipment remains your property and Datacake will never share this data with any third party. ### Who can see my data? On the Datacake platform, every action requires an access token. Each token has a scope, i.e. an area that this token can control. The token defines which devices are assigned to it (with corresponding rights), but also which workspaces it is allowed to view and which different roles this token has in the portal. In Datacake, the users are based on this token, which means that each user has their own token. ### Can another user see my data? No. As long as you do not explicitly allow another user to view the data of your (single or multiple) devices, it is not possible for a user to view your data. ### Where are the vulnerabilities? Basic vulnerabilities are the use of tokens, e.g. as API tokens on your IoT devices. Here we cannot see what security our customers implement on their devices and this can then lead to a third party gaining access to the access tokens of the device. Also, third-party IoT devices may not use encryption to transport your data. This means that the token is potentially transmitted in plain text and can be tapped by a "man in the middle". However, Datacake itself does not allow any incoming connections from unencrypted connections. However, what happens e.g. on foreign MQTT brokers or third-party services, we cannot influence. ### What does Datacake do about it? What measures are in place? Datacake supports the creation of individual tokens (per workspace), which in the ideal case (automated via API) are then created individually per registered device, i.e.: each device on Datacake gets its own token. In addition, we allow fine-grained settings on the tokens. Thus, for example, only read or read-write permissions for one (or more) device can be determined, while at the same time the permissions for other devices and actions in the workspace are deactivated. In this way, we separate the data and permissions of the devices from the platform. And when using per-device tokens, we can selectively disable and swap tokens. ### What does this look like with LoRaWAN or other IoT platforms? LoRaWAN network servers or third-party IoT platforms send us data via webhook. Even if we only allow encrypted connections here, there can be so-called replay attacks or it comes to the import of false measurement data. The Datacake platform offers the option of validating an incoming webhook. Here again a token is created for each webhook. This token then only has access to the respective devices, which also ensures that no other devices or data can be read if the token is lost. # Rules With rules you can setup notifications or trigger downlinks in an automated way. # Legacy Rule Engine The Legacy Rule Engine allows you to create rules for specific devices. ## Introduction Rules allow you to act on events caused by a device's measurements. They allow you to set different triggers and alarms, such as: * Send notification messages via email or sms * Call external services via webhooks * Send downlinks to LoRa devices * and much more ## Getting started Rules can be created and accessed from the workspace's sidebar menu. Rules that are related to a device (one or more conditions reference the device) are additionally shown in the device's Rules tab. Create your first rule by clicking the "Add Rule" button in the top right. ![An empty rule](/files/-MMI21c2pYP_EagxUTf0) Here you can set a name for the rule and add one or more conditions and actions. Choose a device and field from the first dropdown and then select the condition. In the following case, I want the rule to trigger when the value of the field Testfield on the API Test device falls below 20: ![A simple condition](/files/-MMI2gh9o44ktc6wWBQ1) ### Choosing a time range A rule can check the current value of a field or alternatively the sum or average over a specified timeframe. The timeframe can be chosen using natural language. ![This condition evaluates the average of the field](/files/-MMI34MBFwmtboeWWvke) ### Using hysteresis Setting a hysteresis allows you to handle values that jump around a threshold. Imagine a temperature sensor that isn't so accurate and outputs a series of values like 19.9ºC, 20.1ºC, 19.8ºC, 20.2ºC. Setting the condition to "larger than 20ºC" would cause the rule to trigger two times in the above series. Setting a hysteresis of 1ºC would require the value to drop below 20-1 = 19ºC before the rule can trigger again. The following chart further visualises the function of a hysteresis: ![](/files/-MMI3x9OClbV_XLWx9Kn) ## Actions ### Email The email action allows you to send an email to one or more recipients. You can set the subject as well as a rich formatted message. Using "Insert Placeholder" you can also insert measurements from your devices. ![](/files/-MMI4dVGzSn09NKIj25S) ### SMS Similar to the email action, the SMS action allows you to send text messages to one or more recipients. Please note that your workspace needs to have SMS credits which can be purchased in the workspace's billing section. ![](/files/-MMI58D8F-LDOVuJdM69) ### Webhook External systems that support incoming webhooks can be notified by using the webhook action. You can set an URL, custom headers as well as a custom body that can contain placeholders. ![](/files/-MMI5auQLRzdg4tYdxaR) ### Send LoRa Downlink You can send predefined downlink messages to your LoRa devices using this action. ### Execute D Zero OS function If you own a Datacake Industrial Gateway, you can use this action to execute functions on the device. ## Limiting the execution ### Retriggering By default, the rule is only triggered once after a condition becomes true. It is only triggered again once the condition becomes false and true again (see the hysteresis section above). You can change this by activating the "Allow retriggering" option. ### Rate limiting You can set a number of seconds that have to pass before the subsequent execution of a rule. # Sending notifications via Telegram This guide shows you how to send notifications triggered by rules to a Telegram user using the pushmore.io service While the Datacake Rules Engine does not have a dedicated Telegram action yet, it is still possible to send notifications thanks the the [Push More](https://pushmore.io/) service from [Marc Köhlbrugge](https://twitter.com/marckohlbrugge). {% embed url="" %} ## Create Rule First, create your Rule like you normally would (either via the device's Rules tab or the Workspace Rules section), for example like this: ![Rule with a condition](/files/-MdRAEyHpw61TTiO5m0c) ## Create Telegram Action Go to and click the "Add to Telegram" button. This will send a `/start` message to their bot, which will respond with a unique URL (something in the format of ). Copy this URL and on the Datacake Rule, click the "Add Action" button. Choose the "Call a webhook" option and paste your URL into the URL field. You can remove the "Content-Type" header using the (x) button on the right. The "Payload" is the message that will be sent, so you can clear it, type your own message and optionally insert placeholders, for example like this: ![Webhook Action](/files/-MdRCC93b0kWbXZbv0Ek) You can then click the "Try Webhook" button, which should send a message to your Telegram account. Finally, save the rule, and you're all set 🚀 # New Rule Engine ## Introduction With the New Rule Engine you can create rules for your IoT devices, which enable you to receive notifications via email, SMS, or [mobile push notification](/portal/rule-engine/new-rule-engine/actions/push-notification), as well as trigger downlinks and control third-party systems through webhooks when defined conditions are achieved. One single rule allows you to monitor up to 1000 devices, receive notifications when devices go offline and online, as well as define time windows for receiving notifications and triggering downlinks, ensuring efficient and resource-saving operations. ### Quick Start Guides We have prepared some guides for you to help you set up rules for specific scenarios. [#online-status-notification](#online-status-notification "mention") [#message-counter](#message-counter "mention") [#e-mail-reporter](#e-mail-reporter "mention") Now it's time to provide a detailed guide that will walk you through the steps required to set up rules. ## Overview ### Choose Product As the first step in setting up the rule, you need to select the product on which the rule should be created. To do this, you need to know that every device on Datacake belongs to a [product](/device/product). A product can have one or more devices, and the definition for the dashboard, decoder, and database fields are at the product level. All devices in the product have the same settings but can store data individually. [Configuration fields](/device/database/configuration-fields) also lie in the product definition and allow for a default value that can be overridden at the device level. These can also be used in the rule, but more on that later. #### Why is this important? As mentioned, rules are defined at the product level. This has the advantage that I only have to create one rule for a fleet of several hundred devices instead of creating a separate rule for each device. This has enormous advantages in scalability. Once selected the product you are able to choose if you want to setup the rule to "Excecute rule for all devices of this product" or if you want to "Excecute rule only for selected devices of this product", which allows you to filter devices on a product with a specific tag. Press on "Show Devices" to see a list of the devices that will be taken into consideration at the moment of configuring the rule.
#### Match at least one tag Here the rule is executed for those devices that have at least one of the defined tags. #### Match all tags Here the rule is only executed for those devices that have all the defined tags at the same time. ## Select Triggers Once the product and grouping are selected, you can now choose the trigger that defines how and when the rule is executed.
### New Measurement The rule's defined condition gets reviewed when a device receives a new measurement. ### Device goes Offline When the defined [online timeout](#device-goes-offline) gets exceeded, the rule gets triggered. ### Device goes Online If the device has been offline and then it comes back online the rule gets triggered. ### Timebased Schedule When you select the timebased schedule you get the option to configure a rule to be evaluated using the following settings: #### At a specific time You select the exact time at which the rule should be triggered. For example, if you want to send an email every morning at 8:00 am with the measurements from your devices. #### Interval between times The condition setup will be reviewed only with the values coming between the defined window of time. #### Custom crontab expression You can setup the custom crontab expression, which enables you to setup a very personalised Timeframe in which your rules should be reviewed. You can create your own crontab expressions using the following reference:
You can as well use the following characters to setup the expressions: * "\*" -> Any value * "," -> Value list separator * "-" -> Range of values * "/" -> Step values So if for example, you would like to setup a time-based schedule that reviews the rule at 00:00 on day-of-month 1 and 15, your crontab expression would look like `0 0 1,15 * *` . Or, for example, your rule should be reviewed at 22:00 on every day-of-week from Monday through Friday, your crontab expression would look like `0 22 * * 1-5`. In the following video you will learn how to use the different options for time-based schedules on the new rule engine. {% embed url="" %} ## Define Conditions {% hint style="success" %} **Conditions are optional!** For your information in advance: it is not mandatory to define conditions. No conditions are required for triggers such as Online, Offline, and Timebased Schedule. {% endhint %} {% hint style="warning" %} **Attention**: if you have chosen New Measurement as a trigger, you should also define a condition in addition, otherwise the rule will always be executed when new measurements are stored in any of the devices belonging to the product. {% endhint %} When you add a new condition, a detail view opens on the right side of the screen. This is where you can set up the condition.
### Description You can optionally enter a description here, or leave it empty so Datacake can autogenerate it for you. ### Measurement Field This is where you can select the fields that are defined in the product (and are therefore also present on the devices you want to monitor). ### Timerange Operation The next step is to select the operation that will be used to analyse the data of the field. The following options are available. #### Current This is the measurement value as it was last written to the field. It is the current measured value. #### Average When you select this option, another field opens where you can define a time range that will be used to load the data as a time average from the database when evaluating. #### Min Also like Average only this option returns the minimum value for the defined time range. #### Max Here it is the maximum value over defined time range. #### Relative Change Relative Change returns the change over the defined time range. Here two measured values are loaded, once for the start of the time range and once for the end of the range. Then a delta is formed, the change, which is then used for the evaluation of the rule. #### Absolute Change Like Relative Change, except that the change is not absolute but a percentage change over the time range. #### Sum Using Sum, all measured values that lie within the defined time range are added up and used as a source for the rule. #### Count This returns the number of measurement points in the selected time range. This can be used to register abnormalities in the transmission behaviour or also for counting events. ### Operation This field allows you to select what type of action to be taken to activate the rule. Following options are available: * Equals * Equals not * Less than * Less than or equal * Greater than * Greater than or equal * Inside range * Outside range ### Compare To Once you have selected the operation you can select which type of values will be compared. Following options are available: * Constant Number Value: Once this selected next thing is to set the constant number to be used. If you select Constant Number value last thing to do is to setup a [hysteresis](/portal/rule-engine/legacy-rule-engine#using-hysteresis). * Measurement field from triggering device: You will have to select the desired field. * Configuration field from triggering device: You will have to select the configuration field. * Measurement field from another device: You will have to select the device, as well as the field to be used. ## Guides ### Online Status Notification To create an online status notification of your devices follow the next steps: 1. **Create a New Rule**: * On the Rule Engine click on +Add Rule on the right side of the screen. 1. **Set Rule Criteria**: * **Rule Name**: Give your rule a name, e.g., "Device Online Status". This field is obligatory. * **Timezone**: Set the timezone your rule should consider. If you create a time-based schedule this field is important. Otherwise the rule engine will take UTC as the default timezone. * **Branding**: Choose the branding. If you have a white label site, you will see it as an option on the drop-down-list. If you don't, default will be Datacake's branding. 2. **Choose a Product:** Select the product that your triggering devices belong to. * **Execute rule for all devices of this product:** The rule will take ALL devices on that workspace belonging to the previously selected product. * **Execute rule only for selected devices of this product:** The rule will take only the devices with a specific tag or multiple tags selected on this step. {% hint style="info" %} Rules work on a product level, which means that you need to create one rule per product. {% endhint %} 3. **Select the Trigger**: As trigger you will select "Device Goes Offline" and/or "Device goes Online". Selecting the **"Device Goes Offline"** trigger will enable you to receive notifications when any device associated with the defined product loses its connection (see Online timeout). On the other hand, the **"Device Goes Online"** trigger ensures that you are alerted when previously offline devices re-establish their connection.
{% hint style="info" %} It's important to approach this feature with caution. For instance, if you have 50 devices linked to the product and 10 of them go offline, the system will dispatch individual notifications for each device. This means in such a scenario, you'd receive 10 separate notifications. So, be prepared to manage the volume of alerts accordingly. {% endhint %} 3. **Define the Actions**: * Upon meeting the condition, you'd want the rule to perform an action. This is where you specify what the action is. * Choose "E-Mail" or "SMS" to send a text notifications. If you select "SMS" make sure you have enough credits on the Billing section. You can also choose ["Push Notification"](/portal/rule-engine/new-rule-engine/actions/push-notification) to send a notification to selected workspace members through the Datacake mobile app. * Select your receivers: In case of an E-Mail notification, setup the email addresses of your receivers. For SMS notifications, setup the phone numbers of your receivers. For Push Notifications, pick the workspace members who should receive the notification. * Craft your notification message: Draft the content of your message. Ensure it's clear. For example: "Alert! Device **{{ triggering\_device\["name"] }}** has gone offline." Start typing "triggering\_device..." to get a bunch of suggested fields you can add to your notification as well. Now your Offline/Online notification is setup and ready to use! ### Message Counter ### E-Mail Reporter # Rule Engine Table Overview You can add columns to your Rule Engine Overview to have a better management in your notification and automation centre. Datacake now allows you to add columns and search **by name** inside of the Rule Engine. You can also sort ascending or descending by columns, just like in the Device List overview. The column options as for March 2025 are: * **Enabled:** Green tick symbol (✅) if rule is enabled, gray cross symbol (╳) if it is disabled. * **Name:** Assign a name to your rule in the Edit Rule mode. * **Description:** Assign a sinful description to your rule in the Edit Rule mode. * **Product:** Now you will be able to see the products selected as triggers inside of your rules. * **Actions:** We have icons for email, SMS, webhook, single device downlink and multi-device downlink actions, which now you can see without having to enter the Edit Rule mode. Check out a short video about the feature here: {% embed url="" %} # Copy/Paste and Template Functionality How to duplicate, copy and paste rules and work with rule templates on the new rule engine. ## Intro You can easily copy and paste rules within your workspaces. This feature simplifies the process of replicating configurations, saving time and effort. ### Video See everything covered on this video: {% embed url="" %} ## How to Copy and Paste a Rule 1. **Navigate to the Rule Engine**: Select the rule you would like to replicate. Ensure the rule is configured with the triggers, conditions and actions (e.g., Webhook, Email notification) as needed. 2. **Hover to Access Copy/Paste Option**: Hover over the button "More", next to the Enabled switch on the right corner. You will see the options to **Copy rule configuration** and **Paste rule configuration**.
3. **Select a Target Workspace**: Before pasting the rule, ensure that the target device for the rule exists within the workspace where you want to paste the rule. If not, claim the device in the workspace. 1. If you don't have access to the product or device, you can still copy and paste the rule and reuse conditions and actions, such as email templates, webhooks, etc. 4. **Paste the Rule**: * Go to the target workspace’s Rule Engine. * Click **Add Rule** and select **Paste rule configuration** instead of manually configuring a new rule. * The copied rule will be pasted with the original trigger, condition, and action. 5. **Customisation Options**: * When pasting, you will have the option to **replace certain elements**. For instance, you can deselect actions or triggers if you want to configure your own actions. * You can modify details like the recipient in an Email action or other specifics based on your needs. 6. **Enable and Save the Rule**: After making any necessary adjustments, enable the rule and save it. Your copied rule is now active and ready to use. ## JSON Export for Templates One of the advanced features of the Copy/Paste functionality is the ability to work with the rule’s **JSON structure**. When copying a rule, you can see the JSON representation on your clipboard, which contains all the rule’s configuration data. You can: * **Save the JSON** externally for future use, creating reusable templates. * **Modify the JSON** to make changes like swapping out email recipients or adjusting triggers without needing to reconfigure everything from scratch. This provides a powerful way to manage and distribute rule configurations, especially when working with multiple devices, workspaces or complex setups. ## Creating and Using Rule Templates ### Understanding Rule Templates * Rules in the Datacake IoT platform are represented as JSON objects. By copying and modifying these JSON structures, users can create reusable rule templates. * Rule templates can be shared across workspaces, making it easy to replicate rules for multiple devices or projects without needing to recreate them from scratch. ### Creating a Template 1. **Analyze the JSON Structure**: * Each rule’s configuration can be viewed and modified using the JSON format. Understand the structure and identify fields that need to be adjusted, such as triggers, actions, and product identifiers. 2. **Modify and Save as Template**: * Make necessary changes to the JSON configuration and save it as a template for future use. 3. **Importing a Template**: * When creating a new rule, paste the template’s JSON configuration and adjust any product-specific fields as needed. ### Sharing Templates Across Workspaces * When using templates across different workspaces, ensure that the product fields are appropriately configured, as products might differ between workspaces. * Templates can be shared with other users or within different workspaces by copying and pasting the JSON configuration. ## JSON Configuration Reference * The rule engine’s JSON configuration allows for detailed customization of rules. Documentation is available with explanations of different JSON tags and their meanings. * By utilizing JSON configurations, users can fine-tune rules, automate processes, and create sophisticated automation strategies. ```json RULE_CONDITION_SCHEMA = { "$schema": "http://json-schema.org/schema#", "definitions": { "timerangeOperation": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "AVERAGE", "MIN", "MAX", "ABSOLUTE_CHANGE", "RELATIVE_CHANGE", "SUM", "COUNT", ], }, "start": {"type": "string"}, "end": {"type": "string"}, }, "additionalProperties": False, "required": ["kind", "start", "end"], }, "leftOperand": { "type": "object", "properties": { "kind": {"type": "string", "enum": ["TRIGGERING_DEVICE_FIELD_VALUE"]}, "fieldId": {"type": "string", "format": "uuid"}, "timerangeOperation": {"$ref": "#/definitions/timerangeOperation"}, }, "additionalProperties": False, "required": ["kind", "fieldId"], }, "staticNumberValue": { "type": "object", "properties": { "kind": {"const": "STATIC_NUMBER_VALUE"}, "numberValue": {"type": "number"}, "hysteresis": {"type": "number", "minimum": 0}, }, "additionalProperties": False, "required": ["kind", "numberValue"], }, "staticRangeValue": { "type": "object", "properties": { "kind": {"const": "STATIC_RANGE_VALUE"}, "rangeValue": { "type": "object", "properties": { "start": {"type": "number"}, "end": {"type": "number"}, "includeBoundaries": {"type": "boolean"}, }, "additionalProperties": False, "required": ["start", "end", "includeBoundaries"], }, "hysteresis": {"type": "number"}, }, "additionalProperties": False, "required": ["kind", "rangeValue"], }, "staticBooleanValue": { "type": "object", "properties": { "kind": {"const": "STATIC_BOOLEAN_VALUE"}, "booleanValue": {"type": "boolean"}, }, "additionalProperties": False, "required": ["kind", "booleanValue"], }, "staticStringValue": { "type": "object", "properties": { "kind": {"const": "STATIC_STRING_VALUE"}, "stringValue": {"type": "string"}, }, "additionalProperties": False, "required": ["kind", "stringValue"], }, "staticGeofenceValue": { "type": "object", "properties": { "kind": {"const": "STATIC_GEOFENCE_VALUE"}, "geofenceValue": {"type": "string"}, }, "additionalProperties": False, "required": ["kind", "geofenceValue"], }, "dynamicTriggeringDeviceFieldValue": { "type": "object", "properties": { "kind": {"const": "DYNAMIC_TRIGGERING_DEVICE_FIELD_VALUE"}, "fieldId": {"type": "string", "format": "uuid"}, }, "additionalProperties": False, "required": ["kind", "fieldId"], }, "dynamicDeviceFieldValue": { "type": "object", "properties": { "kind": {"const": "DYNAMIC_DEVICE_FIELD_VALUE"}, "fieldId": {"type": "string", "format": "uuid"}, "deviceId": {"type": "string", "format": "uuid"}, }, "additionalProperties": False, "required": ["kind", "fieldId", "deviceId"], }, "dynamicConfigurationFieldValue": { "type": "object", "properties": { "kind": {"const": "DYNAMIC_CONFIGURATION_FIELD_VALUE"}, "fieldId": {"type": "string", "format": "uuid"}, }, "additionalProperties": False, "required": ["kind", "fieldId"], }, "rightOperand": { "type": "object", "oneOf": [ {"$ref": "#/definitions/staticNumberValue"}, {"$ref": "#/definitions/staticRangeValue"}, {"$ref": "#/definitions/staticBooleanValue"}, {"$ref": "#/definitions/staticStringValue"}, {"$ref": "#/definitions/staticGeofenceValue"}, {"$ref": "#/definitions/dynamicTriggeringDeviceFieldValue"}, {"$ref": "#/definitions/dynamicDeviceFieldValue"}, {"$ref": "#/definitions/dynamicConfigurationFieldValue"}, ], }, }, "type": "object", "properties": { "id": {"type": "string", "format": "uuid"}, "description": {"type": "string"}, "conjunction": {"type": "string", "enum": ["AND", "OR"]}, "kind": { "type": "string", "enum": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "NOT_CONTAINS", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL", "INSIDE_RANGE", "OUTSIDE_RANGE", "INSIDE_GEOFENCE", "OUTSIDE_GEOFENCE", ], }, "leftOperand": {"$ref": "#/definitions/leftOperand"}, "rightOperand": {"$ref": "#/definitions/rightOperand"}, }, "additionalProperties": False, "required": ["id", "description", "kind", "leftOperand", "rightOperand"], } CONDITION_EVALUATION_SUBRESULTS_SCHEMA = { "$schema": "http://json-schema.org/schema#", "type": "object", "propertyNames": {"format": "uuid"}, "unevaluatedProperties": {"type": ["boolean", "null"]}, "additionalProperties": False, } WEBHOOK_ACTION_HEADER_SCHEMA = { "$schema": "http://json-schema.org/schema#", "type": "object", "properties": { "key": { "type": "string", }, "value": { "type": "string", }, }, "required": ["key", "value"], "additionalProperties": False, } ``` # Advanced Rule Engine E-Mail and Webhook Templates This guide shows you how you can use the rule engines template language to create custom alerting messages that include sensor information. ## Introduction The Rule Engine in our Datacake IoT platform is a powerful feature that enables you to automate actions and send notifications based on data from your IoT devices. As of July 4, 2023, our Rule Engine supports the inclusion of measurement timestamps in notifications. This document guides you through the utilization of the Django Template Language within the Rule Engine for crafting highly informative and customized notification content. ### **Why Use Template Language?** When sending notifications, whether it's an email, SMS, or webhook, it’s often necessary to include data from sensors, and timestamps, and sometimes perform some conditional logic. This might include formatting dates, displaying values, or sending different messages based on sensor readings. The Django Template Language allows for dynamic inclusion and manipulation of content, based on the data and logic you specify. ### **What Can You Do with Template Language in Notifications?** * **Dynamic Content**: Include real-time sensor data and timestamps in your notifications. * **Formatting**: Customize the formatting of timestamps to make them more readable or to conform to specific standards. * **Conditional Logic**: Use if-else statements to send different messages depending on the data. * **Loops**: Loop through lists of data, such as multiple sensor readings. * **Combining Information**: Craft comprehensive messages by combining multiple pieces of information. * **Adding Hyperlinks**: Include links to dashboards or additional resources. ### **Getting Started** This document contains examples and syntax that will help you get started with using the Django Template Language in Rule Engine notifications. From simply displaying sensor data to more advanced conditional logic, these examples will guide you through creating informative and dynamic notifications. Please proceed through the examples to understand the various features and possibilities. Keep in mind that while this documentation provides a strong foundation, the Django Template Language is very versatile and you may find even more creative ways to utilize it in your notifications. ## **Including Sensor Data** Include the value of a sensor measurement in your notification. When writing templates for webhooks or emails, it’s important to use the correct path to access your device data. Some ways of referencing the measured values of your devices is: ```html Temperature: {{ triggering_device["values"]["TEMPERATURE"] }}°C ``` But it could also be: ``` Temperature: {{ triggering_device["measurements"]["TEMPERATURE"] }}°C ``` {% hint style="success" %} **💡 Tip: Use `debug_keys` to Inspect Your Data** To figure out the correct paths for your template, add a temporary key to your payload that prints the entire `triggering_device` object or a subset like `measurements`.\ Add `"debug_keys": "{{ triggering_device }}"` to your webhook to include the full device object in your outgoing webhook or email, so you can visually confirm the structure and keys available at runtime. Once you’ve identified the correct paths, you can safely remove the debug line. {% endhint %} ## **Including Measurement Timestamp in UTC** Include the timestamp of the measurement in UTC ISO format. ```html Measurement Time (UTC): {{ triggering_device["timestamps"]["TEMPERATURE"] }} ``` ## **Including Measurement Timestamp in Local Timezone** Include the timestamp of the measurement in the rule's timezone using the `datetime` filter. ```html Measurement Time (Local): {{ triggering_device["timestamps"]["TEMPERATURE"] | datetime }} ``` {% hint style="warning" %} Timestamp is provided in the time zone you selected on your rule! Make sure to select the correct one. {% endhint %} ## **Custom Date Formatting** Customize the date format using strftime syntax. ```html Measurement Time (Formatted): {{ triggering_device["timestamps"]["TEMPERATURE"] | datetime("%A, %B %d, %Y %I:%M %p") }} ``` ## **Combining Information** Combine multiple pieces of information into a single message. ```html Temperature is {{ triggering_device["values"]["TEMPERATURE"] }}°C, measured at {{ triggering_device["timestamps"]["TEMPERATURE"] | datetime }} ({{ triggering_device['timestamps']['TEMPERATURE']|date:"c"|timesince }} ago). ``` ## **Including Hyperlinks** Include a hyperlink, possibly to a dashboard or additional resources. ```html For more details, visit the dashboard. ``` Note: You can combine these examples and syntax to create complex and informative notifications according to your requirements. # How to check if a value stays above or below limits for given time Learn how to configure Datacake to monitor if a sensor value remains above or below a specified limit for a set duration, ensuring accurate, time-based condition alerts. #### Documentation for Datacake Rule Engine: Monitoring a Temperature Field for Values Below -10°C for at Least 15 Minutes This guide outlines how to set up a rule in Datacake to monitor the internal temperature of a device and trigger an email notification if the temperature remains below -10°C for at least 15 minutes. ## **Steps:** ### **Creating the Rule:** * Go to the **Rules** section in Datacake. * Click on **New Rule**. * Name the rule (e.g., "Temperature below -10°C for 15 Minutes"). * Select the appropriate **Timezone** (e.g., Amsterdam, Berlin). * Choose the **Branding** option for the email notification (e.g., Default Datacake branding). ### **Select the Product:** * Under the **FOR** section, choose the **Product** you want this rule to apply to (e.g., Fridge). * Decide if the rule should apply to **all devices** of this product or only specific devices. ### **Set Trigger**
* Select "New Measurement" as trigger (this triggers the rule and the time-based checking of conditions) based on new measurement of any devices associated to the product. **Important Hint on Trigger Selection:** {% hint style="warning" %} When using the **New Measurement** trigger, keep in mind that this trigger only works if the device sends measurements consistently. For example, if you want to check if the temperature is above 10°C for at least 15 minutes, the device needs to send data at least every 15 minutes (or more frequently). If the sending interval is longer than the condition’s time range, the rule may not activate as expected. Ensure the time range you set for checking conditions is longer than or equal to the device’s sending interval for accurate monitoring. {% endhint %} ### Condition Setup * Click on **Add Condition**. * Set the **Measurement Field** to (for example) `Temperature`. * For **Timerange Operation**, select `Max`. * Specify the time range as **from 15 minutes ago until now**. * Under **Operation**, choose `< (Less than)`. * Set the **Comparison Value** to `-10°C`. * This condition checks if the maximum temperature over the last 15 minutes was below -10°C, ensuring the temperature has stayed below this threshold consistently.
### **Select Trigger:** * Under the **WHEN** section, choose **New Measurement**. * This trigger will activate the rule each time a new measurement is received for the internal temperature field. ### **Configure the Email Notification Action:**
* Click on **Add New Action** and select **E-Mail Action**. * In the **Receivers** field, add the recipient's email addresses. * Set a **Subject** for the email, such as `Fridge {{triggering_device["name"]}} is below -10°C for 15 minutes`. * Write a **Message** that includes relevant information about the triggering device and rule (e.g., `"This is an automatic notification to inform you that the device {{triggering_device["name"]}} activated the rule {{rule["name"]}}"`). 1. **Save and Enable the Rule:** * Once configured, save the rule and ensure it is **Enabled** to start monitoring. ### **Example Email Notification Content:** * **Subject**: Fridge `Device Name` is below -10°C for 15 minutes * **Message**: ``` Dear recipient, This is an automatic notification to inform you that the device `Device Name` has been below -10°C for 15 minutes, activating the rule `Temperature below -10°C for 15 Minutes`. ``` This setup will monitor the temperature and alert designated recipients if the temperature remains below -10°C for the specified duration, ensuring prompt response to critical temperature changes. ## How it works In the Datacake Rule Engine, the concept of "min" and "max" for timeranges can be a bit tricky to understand when you're trying to set up conditions like "Temperature above 10°C for at least 30 minutes" or "Temperature below -10°C for at least 60 minutes." Here’s how it works: ### Explanation of Timerange "Min" and "Max" Operations The **Min** and **Max** operations allow you to check the minimum or maximum value of a field (like temperature) over a specified time range, such as the last 30 minutes or 60 minutes. However, these operations don’t directly check if a condition (like “above 10°C” or “below -10°C”) is continuously true for the entire time period. Instead: * **Max** checks the **highest value** recorded in the selected time range. * **Min** checks the **lowest value** recorded in the selected time range. Because of this, we can still use Min and Max to simulate conditions like "above 10°C for 30 minutes" or "below -10°C for 60 minutes," but it requires a slight shift in thinking. ### How to Use "Min" and "Max" for Continuous Conditions To check if the temperature has been above or below a certain threshold for an entire duration, we set a condition based on the **Min** or **Max** value across that period. Here’s how this translates for each scenario: 1. **Temperature above 10°C for at least 30 minutes:** * **Set the Timerange Operation to "Min."** * **Specify the range as "from 30 minutes ago until now."** * **Condition:** If the **Min** temperature over the last 30 minutes is greater than 10°C, it means that the temperature has been **continuously above 10°C** for the entire duration. * **Why This Works:** If the lowest recorded temperature in the last 30 minutes is still above 10°C, then all measurements within this range were above 10°C, meeting your condition. 2. **Temperature below -10°C for at least 60 minutes:** * **Set the Timerange Operation to "Max."** * **Specify the range as "from 60 minutes ago until now."** * **Condition:** If the **Max** temperature over the last 60 minutes is less than -10°C, it means that the temperature has been **continuously below -10°C** for the entire period. * **Why This Works:** If the highest recorded temperature over the last 60 minutes is still below -10°C, then all measurements within this range were below -10°C, satisfying your condition. ### Why This Method Works By using "Min" and "Max," you’re effectively setting a rule that requires all measurements within the specified time range to stay above or below the threshold. This way, **Min** or **Max** indirectly ensures that the condition was met continuously over the entire time period. #### Summary Table | Desired Condition | Timerange Operation | Time Range | Condition | | -------------------------------------- | ------------------- | ----------------------------- | ----------------------- | | Temperature above 10°C for 30 minutes | Min | From 30 minutes ago until now | Min temperature > 10°C | | Temperature below -10°C for 60 minutes | Max | From 60 minutes ago until now | Max temperature < -10°C | ### Important Notes for Customers * **Conceptual Shift:** Think of "Min" and "Max" as a way to ensure the temperature stayed within a certain range for the entire period. If the **Min** is above a threshold, it means the temperature never went below that threshold. Similarly, if the **Max** is below a threshold, the temperature never rose above it. * **Limitation:** This approach does not directly check for the duration of a single measurement but instead verifies that every measurement within the range meets the condition, effectively fulfilling the "continuous" requirement. This method allows you to set up rules that monitor conditions over time, even though the terms “Min” and “Max” don’t directly imply continuous monitoring at first glance. ## Rule Templates You can copy the following JSON templates for the rule engine and paste those on a new rule. This will allow you to work with ready-to-go example rules for the complex setup.
### Template: Alert for Temperature Between 6°C and 10°C Persisting for 30 Minutes ```json {"name":"Rule: Alert for Temperature Between 6°C and 10°C Persisting for 30 Minutes","enabled":true,"tagsFilter":[],"timezone":"Europe/Berlin","productId":"5c2700ee-f046-4810-ac01-5d7aa70aff87","tagsFilterConjunction":"","triggerOnMeasurement":true,"triggerOnSchedule":false,"triggerOnDeviceGoesOffline":false,"triggerOnDeviceGoesOnline":false,"scheduleTriggerCrontab":"","triggerOnZoneEntry":false,"triggerOnZoneExit":false,"triggerOnZoneLengthOfStay":false,"zoneLengthOfStayTriggerMinutes":null,"zoneTagsFilter":[],"zoneTagsFilterConjunction":"","conditions":[{"rightOperand":{"hysteresis":0,"numberValue":6,"kind":"STATIC_NUMBER_VALUE"},"kind":"GREATER_THAN_OR_EQUAL","leftOperand":{"kind":"TRIGGERING_DEVICE_FIELD_VALUE","fieldId":"40fb7707-f315-42b3-b050-efae81a62335","timerangeOperation":{"start":"30 minutes ago","end":"now","kind":"MIN"}},"id":"3442a021-1f35-4b92-9cc2-6c28320b2f1e","conjunction":"AND","description":""},{"rightOperand":{"hysteresis":0,"numberValue":10,"kind":"STATIC_NUMBER_VALUE"},"kind":"LESS_THAN_OR_EQUAL","leftOperand":{"kind":"TRIGGERING_DEVICE_FIELD_VALUE","fieldId":"40fb7707-f315-42b3-b050-efae81a62335","timerangeOperation":{"start":"30 minutes ago","end":"now","kind":"MAX"}},"id":"a054728b-ea4d-4497-a52f-a16a69d03733","conjunction":"AND","description":""}],"whitelabelSiteId":"","createActions":[{"kind":"EMAIL","emailSubject":"Fridge {{ triggering_device[\"name\"] }} - Temperature Between 6°C and 10°C Persisting for 30 Minutes","emailReceivers":["simon+datacake@datacake.de"],"emailBody":"Dear recipient,\n\nthis is an automatic notification to inform you that the device **{{ triggering_device[\"name\"] }}** activated the rule {{ rule[\"name\"] }}.","description":"","fireWhenConditionsBecomeHot":true,"fireWhenConditionsStayHot":true,"minSecondsBetweenHotConditions":0,"fireWhenConditionsBecomeCold":false}],"updateActions":[]} ``` ### Template: Alert if Temperature is Above 10°C for 30 Minutes ```json {"name":"Rule: Alert if Temperature is Above 10°C for 30 Minutes","enabled":true,"timezone":"Europe/Berlin","tagsFilter":[],"tagsFilterConjunction":"","triggerOnMeasurement":true,"triggerOnDeviceGoesOffline":false,"triggerOnDeviceGoesOnline":false,"triggerOnSchedule":false,"scheduleTriggerCrontab":"","triggerOnZoneEntry":false,"triggerOnZoneExit":false,"triggerOnZoneLengthOfStay":false,"zoneTagsFilter":[],"zoneTagsFilterConjunction":"","productId":"5c2700ee-f046-4810-ac01-5d7aa70aff87","zoneLengthOfStayTriggerMinutes":null,"conditions":[{"leftOperand":{"kind":"TRIGGERING_DEVICE_FIELD_VALUE","fieldId":"40fb7707-f315-42b3-b050-efae81a62335","timerangeOperation":{"kind":"MIN","start":"30 minutes ago","end":"now"}},"rightOperand":{"kind":"STATIC_NUMBER_VALUE","numberValue":10,"hysteresis":0},"id":"229418d8-a235-4ae4-9b0a-f5e09d1e1338","description":"","conjunction":"AND","kind":"GREATER_THAN"}],"createActions":[],"updateActions":[{"kind":"EMAIL","emailBody":"Dear recipient,\n\nthis is an automatic notification to inform you that the device **{{ triggering_device[\"name\"] }}** activated the rule {{ rule[\"name\"] }}.","emailReceivers":["noreply@datacake.de"],"emailSubject":"Fridge {{ triggering_device[\"name\"] }} - Temperature is Above 10°C for 30 Minutes","id":"cbe7fe40-f097-4d0f-8eae-7acb49a5176a","description":"","fireWhenConditionsBecomeHot":true,"fireWhenConditionsStayHot":true,"fireWhenConditionsBecomeCold":false,"minSecondsBetweenHotConditions":0}],"deleteActions":[],"whitelabelSiteId":""} ``` # Time Restrictions This guide explains how you can set up time based weekday restrictions for individual actions on Datacake Rule Engine. ## Overview This document provides an overview of the **Time Restrictions** feature within the **Datacake Rule Engine**. This feature allows users to specify time frames during which particular actions within a rule are permitted to trigger. If an action's associated time restriction is not met, the action will not execute, even if the rule's conditions are satisfied. ### Practical Use Cases * **Work Shift Notifications**: Set up rules to notify specific team members based on shift times. * **Off-Hours Monitoring**: Limit notifications to business hours or specific time frames to reduce unnecessary alerts outside working hours. * **Daily or Weekly Alerts**: Schedule notifications or actions to occur only on certain days, for example, to align with weekly reporting needs. ### Video-Guide {% embed url="" %} ## Setting Up Time Restrictions ### **Create a Rule** * Begin by selecting the **product** for which you want to create a rule. This rule will apply to all devices within that product. * Choose a **trigger** condition (e.g., when a new measurement is received). * Set the rule’s conditions, such as “temperature is less than 10°C.” **Select an Action** * Choose an action type (e.g., **Email**, **Webhook**, **SMS**, or **Downlink**) to execute when the rule’s conditions are met. * Customize the action details, such as the recipient for an email. ### **Configure Time Restrictions**
* In **Advanced Settings**, enable **Time Restrictions**. * Define the time frame for the action, specifying: * **Days of the Week**: Select specific days (e.g., Monday through Friday). * **Time Range**: Set the start and end times for each selected day. * Example: Configure an email notification to send only from **12 a.m. to 8 a.m., Monday through Friday**. Notifications outside this period will not be sent. ### **Multiple Time Frames** * For actions requiring more complex schedules, you can add multiple time restrictions. For example, create multiple time ranges within the same day. ### Using Multiple Actions with Individual Time Restrictions The Time Restrictions feature allows you to configure different time frames for each action within a single rule: * **Example**: Set an **Email** action to trigger only during a specified night shift (e.g., 12 a.m. to 8 a.m.) and a **Webhook** action to trigger at any time. * This is ideal for workflows involving **shift-based alerts** or **targeted notifications** based on time-sensitive needs. # Rule Logs Overview A guide on understanding, debugging, and auditing your automation rules Rule Engine Logs provide full visibility into how your automations behave on Datacake.\ Every time a rule is evaluated or executed, Datacake records a detailed log entry.\ This gives you a transparent audit trail that is especially helpful for debugging, monitoring large fleets, and meeting compliance requirements. *** ### Where to find Rule Logs Rule Logs are available to those who have access to the Advanced Rule Engine. This comes as a feature in our Standard, Plus, and Enterprise subscription plans (more details can be found on our [Pricing](https://datacake.co/pricing) page). Please reach out to to enable the feature. #### 1. Open the Rule Engine Navigate to:\ **Workspace → Rule Engine → Logs** as shown below.
#### 2. Select a Rule Each rule entry offers an option to open its log history. #### 3. Inspect Log Details Inside a log entry you can: * Expand the trigger information * Inspect each executed action * Check communication results (emails, webhooks, downlinks) * See the conditions that were or were not fulfilled #### 4. Use Filtering & Search Depending on your workspace size, logs can grow quickly.\ The UI lets you filter by: * Time Frame * Device * An action that has been executed more than once (toggle switch)
*** ### What’s Included in a Log Entry Each log entry captures several categories of information:
#### **Rule Metadata** * Rule name * Product or device the rule applied to * Time of action * Whether it was executed or not (in the form of a check or cross symbol) #### **Actions Executed** For each action, the log shows: * Whether the action ran successfully * Any returned data or diagnostics This is particularly helpful when troubleshooting integrations. #### **Execution & System Info** Additional metadata includes: * Evaluation timestamp * Any warnings or error messages * Information about skipped actions (e.g. “Action Not Executed”)
*** ### Example Use Cases #### **Debugging an Alert Rule** You can quickly see: * Which measurement triggered the rule * Whether the condition evaluated correctly * Why an alert email was sent (or not sent) #### **Auditing Device Behavior** For compliance-heavy environments, you can track: * When devices reported certain values * When automated actions (like downlinks) were sent * The exact data used during rule evaluation #### **Troubleshooting Scheduled Jobs** If a task did not run, logs allow you to determine: * Whether the schedule was evaluated * Whether execution was skipped # Actions You have different options to trigger actions inside of rules. You don't need to set up specific conditions to trigger a rule (it can be a simple scheduled rule), but you always need actions performed by the rule. Up to June 2026, we have the following options: **Notifications** * Email * SMS * Webhook * [Push Notification](/portal/rule-engine/new-rule-engine/actions/push-notification) Automations * Single device downlink * [Multi-device downlink](/portal/rule-engine/new-rule-engine/actions/schedule-mass-downlinks-multicast) * [Set Value](/portal/rule-engine/new-rule-engine/actions/set-value) # Push Notification Send a mobile push notification to selected workspace members through the Datacake app when a rule fires. The **Push Notification** action sends a mobile push notification to selected members of your workspace through the Datacake app. It sits alongside the **Email**, **SMS**, and **Webhook** actions in the New Rule Engine and is a good fit when you want an alert to reach people instantly on their phone — without managing a list of email addresses or spending SMS credits. Use it when: * You want on-call colleagues to be notified the moment a device goes offline or a threshold is crossed. * Your recipients already use the Datacake mobile app and prefer a push over email/SMS. ## Prerequisites Before you can set up a Push Notification action, make sure that: * **Recipients have the Datacake mobile app installed and are signed in.** A member can only receive a push once they have an active, signed-in app for the relevant branding. Members without the app can still be selected — they simply start receiving notifications once they install it and sign in. * **You have the `rules` permission** in the workspace. This is the same permission required to edit rules — no separate "members" permission is needed to pick recipients. * **Your rule's branding supports mobile push.** The action is only offered under the default Datacake branding, or under a white-label brand that has the **Mobile Push** integration enabled. See [#i-dont-see-the-push-notification-option](#i-dont-see-the-push-notification-option "mention") below. ## Setting up the action This walkthrough sets up a rule that notifies your team when a device goes offline. 1. **Create or open a rule** in the New Rule Engine and configure its trigger and conditions as usual. For an offline alert, use the **Device Goes Offline** trigger. 2. Under **Configure Actions**, click **Add Action**, open the **Notifications** category, and choose the **Push Notification** card.

The Push Notification card in the Add Action picker, under the Notifications category.

3. **Pick your recipients.** Click the **Recipients** field and search the list of workspace members by name or email. Select everyone who should receive the push. At least one recipient is required to save the action.

The recipient picker lists workspace members; search by name or email and tick everyone who should receive the push.

4. **Write the Title and Message.** Both fields come pre-filled with a sensible default that already uses variables, for example a title of `Device {{ triggering_device["name"] }} activated rule {{ rule["name"] }}`. Edit them to suit your alert. You can insert variables such as the device name or rule name through the variable autocomplete — start typing `triggering_device...` to see the available fields. {% hint style="info" %} Both **Title** and **Message** are required and are limited to **255 characters** each. A live character counter is shown beneath each field and turns red when you go over the limit; saving is blocked until you shorten the text. {% endhint %}

The Push Notification action editor, with Recipients, Title, and Message fields and the per-field character counter.

5. Adjust the **Advanced Settings** and **Time Restrictions** if needed — these behave exactly like the other actions (see [Advanced Settings](/portal/rule-engine/new-rule-engine/actions/advanced-settings) and [Time Restrictions](/portal/rule-engine/new-rule-engine/time-restrictions)). 6. **Save** the action and the rule. ### Using variables in the Title and Message The Title and Message support the same Jinja-style placeholders as the Email and Webhook actions. For example: ``` Device {{ triggering_device["name"] }} has gone offline. ``` For the full list of available variables and advanced templating, see: {% content-ref url="/pages/5siE7WEl5v6Yo4cB6Ctp" %} [Advanced Rule Engine E-Mail and Webhook Templates](/portal/rule-engine/new-rule-engine/advanced-rule-engine-e-mail-and-webhook-templates) {% endcontent-ref %} ## Understanding the recipient list Unlike Email and SMS, where you type free-text addresses or phone numbers, the Push Notification action lets you pick **actual workspace members**. Each member is shown with their name and email. Members who **cannot currently receive a push** — because they have no Datacake app installed, or no registered device for the relevant brand — are shown **greyed out with an amber warning icon**. They are **still selectable**: hovering the icon explains that the member has not installed the app yet and won't receive a push until they do. Once they install the app and sign in, they start receiving the notifications automatically.

A reachable member (top) and an unreachable member shown greyed out with an amber warning icon (bottom). Unreachable members can still be selected.

{% hint style="info" %} This lets you set up the rule **before** your colleagues have installed the app. If every selected recipient is currently unreachable, a soft amber warning appears — but the rule still saves. {% endhint %} ### Recipients stay valid over time If a selected member later leaves the workspace, the rule remains valid — that person is simply dropped from the recipients automatically. There is no error and the rule does not break. ## Troubleshooting ### I don't see the Push Notification option The Push Notification card is only shown when the rule's **branding** supports mobile push: * **Default Datacake branding** → push is always available. * **A white-label brand** → push is only available if that brand has the **Mobile Push** integration enabled. If it isn't, the card is hidden. This is the most common reason the option is missing. If your rule uses a white-label brand without Mobile Push, either switch the rule's branding to one that supports push, or enable the Mobile Push integration for that brand. If a push action already exists under an unsupported brand, the editor shows a warning that the action will not fire.

Under a white-label brand without Mobile Push, the Add Action picker only offers E-Mail, SMS, and Webhook — the Push Notification card is hidden.

{% content-ref url="/pages/-MIu\_y73tt\_jnbJeiIMZ" %} [White Label](/organization/white-label) {% endcontent-ref %} ### A recipient isn't getting notifications The most likely cause is that the member is currently **unreachable** — they have not installed the Datacake mobile app, are not signed in, or have no active registered device for the rule's brand. In the recipient picker they appear greyed out with an amber warning icon. Ask them to install the app and sign in; they will then start receiving the notifications. ### Saving is blocked * **Title or Message over 255 characters** — the character counter turns red and saving is blocked. Shorten the text. * **No recipients selected** — at least one recipient is required to save the action. # Schedule Mass-Downlinks (Multicast) This document provides a detailed guide on triggering mass downlinks (multicast/broadcast) on a time-based schedule using the Datacake Rule Engine, allowing you to send downlinks to multiple devices. ## Overview This document provides a detailed guide on how to trigger mass downlinks (also known as multicast or broadcast downlinks) on a time-based schedule using the Datacake Rule Engine. This capability allows you to define a schedule for sending downlinks to multiple devices at once, addressing a common and critical use case for many customers. ### Video Guide {% embed url="" %} ## Differences Between Single-Device Downlink and Multi-Device Downlink {% hint style="warning" %} It is very important that you read this section before we start showing you how setting up downlink schedulers or multicast downlink works. {% endhint %} On the Datacake rule engine, we have two different types of actions for downlinks: Single device downlink and multi-device downlink. Essentially, single device sends a single downlink and multi-device sends a downlink to a group of devices. You might assume that for sending a multicast downlink, you would choose the multi-device downlink. However, this is only the case if you are not working with time-based actions. We will explain the difference between the two, but it is important to read this section beforehand. ### Single-Device Downlink A single-device downlink is used when the product you create the rule on contains multiple devices. This setup is common for time-based schedules. For instance, if you set a rule to trigger every morning at 9 AM for a product with 100 devices, the rule will execute for all these devices simultaneously. When configuring the action for a single-device downlink: * **Select "Single Device Downlink"**: This is necessary because the rule will apply to each device in the product. * **Choose "Triggering Device"**: The triggering device is the device or all the devices on which the rule is executed. Each device in the product triggers the downlink action individually according to the schedule. This approach ensures that each device in the product receives the downlink at the specified time. ### Multi-Device Downlink Multi-device downlinks are used when the product you are creating the rule on does not contain the devices you want to send the downlink to. This scenario typically occurs with measurement-based triggers from an external sensor. For example, you might have an outdoor temperature sensor and set a condition that if the temperature falls below 10 degrees, you want to switch off all heating devices. Since the triggering device is the single temperature sensor, you need to: * **Select "Multi-Device Downlink"**: This allows you to send a downlink to multiple devices based on the condition met by a single triggering device. * **Select the Target Product**: Instead of specifying each device individually, you can select a product (group of devices) and define a single downlink action. In both single-device and multi-device downlink cases, this setup ensures that you can control a large number of devices (hundreds or even thousands) with a single rule. This method is efficient and scalable, making it easy to manage extensive IoT deployments with minimal effort. ## Scheduling Mass Downlinks on a Time-Based Schedule ### Step 1: Create a New Rule 1. **Log in to the Datacake platform** and navigate to the workspace containing your devices. 2. **Click on "Rules"** in the left-hand menu. 3. **Click on "Create New Rule"**. ### Step 2: Select the Product 1. **Choose the product** that includes the devices you want to control. For instance, select the "McClymit Viki" product, which contains all 108 devices you want to manage. 2. **Optional:** Define device groups using tags if you only want the rule to apply to specific subsets of devices. ### Step 3: Define the Time-Based Trigger 1. **Select "Time-Based Schedule"** as the trigger type. 2. **Configure the Schedule:** * Deselect "Saturday" and "Sunday" if you do not want the rule to run on weekends. * Set the time to `5:00 AM` for the rule to execute each weekday morning. 3. **Confirm the Trigger:** Ensure the rule is set to activate at the specified time for all selected devices. ### Step 4: Configure the Mass Downlink Action 1. **Add a New Action** and select "Single Device Downlink". 2. **Configure the Downlink:** * Select the downlink type relevant to your needs (e.g., "Set Temperature"). * Define the parameters for the downlink (e.g., set the temperature to 22 degrees). 3. **Set the Action Scope:** * Since the rule is triggered based on a time schedule for all devices in the selected product, the downlink will be sent to all devices. 4. **Name the Action:** For example, "Weekday Morning Temperature Set". 5. **Save the Rule:** Click "Save" to finalize the rule. ### Summary By following these steps, you will have created a rule that automatically sends a downlink to all selected devices at 5 AM on weekdays, setting the temperature to 22 degrees. ## Multi-Device Downlink based on external Measurements ### Step 1: Create a New Rule 1. **Log in to the Datacake platform** and navigate to the workspace containing your devices. 2. **Click on "Rules"** in the left-hand menu. 3. **Click on "Create New Rule"**. ### Step 2: Select a Product 1. **Choose the product** that contains the external sensor. For example, select the "SenseCAP" product which has an outdoor temperature sensor. ### Step 3: Define the Trigger 1. **Select "New Measurement"** as the trigger type. 2. **Define the Condition:** * Choose "Average of Last Hour" for the temperature measurement. * Set the condition to "greater than 15 degrees". ### Step 4: Configure the Action 1. **Add a New Action** and select "Multi Device Downlink". 2. **Configure the Downlink:** * Select the target product (e.g., "McClymit Viki"). * Define the downlink parameters (e.g., set temperature to 12 degrees). 3. **Name the Action:** For example, "External Temperature Shutdown". 4. **Save the Rule.** ### Summary This rule will monitor the external temperature sensor and, if the average temperature over the last hour exceeds 15 degrees, it will send a downlink to all devices in the selected product to set the temperature to 12 degrees. ## Example Scenario: Morning Temperature Adjustment ### Objective Set all "Mclimate Vicki" devices to a specific temperature every weekday morning at 5 AM. ### Steps 1. **Create a Time-Based Rule:** * Navigate to "Rules" and create a new rule. 2. **Select the Product:** * Choose "Mclimate Vicki Product" which includes all relevant devices. 3. **Define the Time-Based Trigger:** * Set the schedule to weekdays at 5 AM. 4. **Configure the Downlink Action:** * Select Single Device Downlink * Set the action to adjust the temperature to 22 degrees. * Name the action and save the rule. ### Result At 5 AM every weekday, all "McClymit Viki" devices will automatically receive a downlink to set their temperature to 22 degrees. ### Conclusion The Datacake Rule Engine's capability to schedule mass downlinks on a time-based schedule is a powerful feature for managing large groups of devices. By following the steps in this documentation, users can efficiently create rules that automate downlink scheduling, ensuring consistent and synchronized control over their IoT devices. This functionality is crucial for applications requiring regular and simultaneous updates across multiple devices. # Set Value ## Set Value This guide shows you how you can use the set value feature. ### Overview The action "Set Value" is a very powerful feature in the rule engine. You can set a value of a specific field regarding a measurement of another one. In the example below you can see how to use this for alarming. We have a short video reviewing the feature: {% embed url="" %} #### General * **Description** is meant to be used for documenting and better understanding of you own rules. * At **Set value on the triggering device** you can select a field where you want to set a value to. If you have selected a field, you can set a value afterwards. * If you want to **set a value on a specific device** you can define which value should be applied to which field of a single device. This can be useful if you have an overall alarming/monitoring device for several devices combined.
#### Advanced Settings * **Execute action when conditions are becoming fulfilled**: If enabled, the action is executed when conditions are becoming fulfilled. * **Execute action when conditions are fulfilled consecutively**: If enabled, the action is executed a second, third, etc., time when conditions are fulfilled consecutively. * **Timeout between multiple executions when conditions are fulfilled**: Set the minimum amount of time in seconds that must pass before the action is executed again. * **Execute action when conditions are no longer fulfilled**: If enabled, the action is executed when conditions are no longer fulfilled. This setting can be used to revert actions, e.g., to send an all-clear notification.
#### Time restrictions See [Time Restrictions](/portal/rule-engine/new-rule-engine/time-restrictions) for detailed information. ### Example #### Video Guide Video will be attached shortly. #### Step by step If you have no rule created yet, create a new rule by navigating to **Rule Engine -> Add Rule**.
In this example we will react to a new device measurement so select the template for **New Measurement Recorded**.
Choose a **name** for your new rule. Set a preferred **filter for the devices** so that you can apply this rule to a single device or specific group of devices.
The "Selected Triggers" are set for "New Measurement" by default in this template. You only need to define which fields you want to observe. So please choose a field for **"Trigger Only On Specific Measurements"**.\ In the next step you define the conditions when to set a value. Please **define a condition for a field** you chose earlier.
Last but not least, you can define an Action to be executed when the condition become true. Please click "Add Action" and select "Set Value". Then click on next.
Select the field you want a value to be set, define the value and hit "Update Action". Now you are ready to go!
Summarized in the shown example we observe the field "Temperature". When a new measurement is recorded, there is a check if the new measured Temperature is below or equal to 0°. If this is true, we set another field "ALARM\_TEMPERATURE" to true. --- [Next Page](/llms-full.txt/1)