Data Studio: Overview

Content

---

Data Studio – Mapping Rule Configuration Guide

The Data Studio tool in the Platform allows users to define mapping rules that connect raw data streams from external systems (e.g. FTP, API) to structured internal device and reading models. It enables automated creation of devices, assignment of readings, and structuring of device hierarchies — all by interpreting datastream key patterns.

---

Mapping Rules

A mapping rule defines how one or more raw data streams — usually sourced from datalogger devices — are mapped into internal device types and associated reading types, metadata, and status codes in the Platform.

---

Source Devices

• Only dataloggers should be selected in the Source Devices selector.
• They are the only valid input for raw data streams.
• All other device types should be ignored in this step.

---

Rule Structure & Behavior

Each mapping rule allows the following:

• Match one or more devices of a target device type.
• Create those devices and assign them relevant readings and metadata.
• Define how raw keys are interpreted using regex/string expressions.
• Set hierarchical relationships between components (e.g. MPPT → Inverter).

Important: Once a rule is executed, the internal device identifiers become persistent.

If devices are later deleted and you want to re-run the rule, you must use new unique internal identifiers and update any Parent Identifier references accordingly.

---

Preview Before Apply – The Simulation Mode

The “Simulate” button lets users preview the result of a mapping rule without executing it.

• Visualizes which devices would be created.
• Displays reading types, metadata fields, and status codes matched from raw streams.
• Helps confirm rule correctness before applying changes.

Simulation Output Example

WR-ES20A0000421

Readings:
- ES20A0000421/P_AC → Active Power (÷1000)
- ES20A0000421/I_AC1 → AC Current L1
- ...

Metadata:
- WR1 → Name
- ES20A0000421 → Serial Number
- SUN2000-100KTL-M1 → Model

Status Codes:
- ES20A0000421/STATE1 → Prefix: S1
- ES20A0000421/ERROR1 → Prefix: E1

---

Rule Editor UI

When creating a new rule, the interface presents:

• Source Devices selector
• Expression input field
• Raw datastream list (with type and latest value)
• Device Type dropdown
• Device Name, Internal Identifier, and Parent Identifier fields
• “+ Add Mapping” button to define:
  • Reading Type
  • Metadata
  • Status Code

---

Using Internal Identifiers for Hierarchy

Internal identifiers support cross-rule references to build structured component hierarchies.

Example:

• INV$1 → Inverter
• MPP$2 → MPPT (with Parent Identifier: INV$1)

---

Expressions and Captured Groups

Expressions use regex or string patterns to extract groups from raw data stream keys. These are essential for building dynamic and reusable mapping rules.

Captured groups (e.g. $1, $2) can be reused throughout the rule for:

• deviceIdentifier
• parentIdentifier
• readingTypes
• metadataValues

Example Expression:

(6T.+)\\/

Captured $1:

6T20A9033051

Matched Streams:

6T20A9033051/E_DAY
6T20A9033051/I_AC1
...

---

Write Regrex with ChatGPT

If you're unsure how to write a regex to extract what you need, ChatGPT can generate one for you. Just describe your stream pattern and what you want to extract.

Example Prompt to Ask ChatGPT:

I have data stream keys like:
"6T20A9033051/E_DAY"
"ES3400921001/I_AC1"
"2INV002/PAC"

I want to capture the device identifier before the first slash. Can you give me a regex that extracts it as a group?

ChatGPT might suggest:

(.+)/

This captures the part before the first / as $1.

---

Refining or Debugging Expressions

Sometimes, your regex might not behave as expected — maybe it captures the wrong part, misses some streams, or matches too broadly. ChatGPT can help you fix it.

Example Prompt to Debug an Expression:

I’m using this regex: (^2.+|6T.+|ES.+)/
It works for some keys like “6T20A9033051/E_DAY”, but not for others like “2INV002/PAC”.
I only want to capture the device ID before the slash for device IDs that start with 2, 6T, or ES.
Can you help me fix or simplify the expression?

ChatGPT might respond with a more precise version:

^(2[^/]+|6T[^/]+|ES[^/]+)/

Or help you break the problem down step-by-step.

You can also paste a few sample stream keys and ask ChatGPT:

“Which regex pattern will extract this specific part across all these keys?”

---

Reading Type Mappings

Each reading mapping contains:

Field	Description
Expression	Substring in the key to match (e.g. P_AC)
Map To	Internal reading type (e.g. Active Power, Energy (Daily))
Divide By	Optional scaling factor (1000, -1, etc.)

Example:

• Expression: E_DAY
• Map To: Energy (Daily)
• Divide By: 1000
• Result:
  • 6T20A9033051/E_DAY → Inverter-$1-Energy (Daily)

---

Metadata Mappings

Metadata mappings define auxiliary properties for the created device(s).

Field	Description
Expression	Substring to match from data stream key
Target Field	Field to populate (e.g. Name, Model, Serial Number, etc.)
Value	Optional override using captured groups (e.g. $1, $PARENTNAME)
Divide By	Optional scaling factor

---

Status Code Mappings

Status code mappings allow alarms or fault states to be tracked.

Field	Description
Expression	Substring to match from key
Prefix	Prefix to attach to the status code (e.g. E1, S1)
Source	Where the status code comes from: "name" or "value"
Status Type	Either "number" or "bitmask"

---

Summary

• Create mapping rules per device type based on raw datastreams from dataloggers.
• Use expressions to extract device identifiers and match readings, metadata, or status codes.
• Visualize results with simulation mode before applying.
• Ensure unique internal identifiers if devices are deleted and re-created.
• Use group capture ($1, $2, ...) and placeholders in values, names, and links.

---

Adherence to Standards is Mandatory

To ensure platform stability, long-term maintainability, and cross-project consistency, it is absolutely essential to follow the standards defined in the following page:

Data Studio Mapping Rule Standards

These standards cover naming conventions, hierarchy rules, identifier formats, and structural requirements that are critical for:

• Correct simulation and rule execution
• Clean data aggregation and device relationships
• Reusability across systems
• Avoiding platform-breaking configurations

---

Need More Help?

If you encountered any difficulties or need further assistance, here are some steps you can take:

Contact Support:

• Email: Reach out to our support team by emailing us at support@amperecloud.com. Provide as much detail as possible about the issue you're facing.

• Fill out a form: Complete our online support form. Please include all relevant information about your request, and our team will get back to you as soon as possible.

---

Share Your Feedback

If this article didn’t meet your needs or if you have suggestions on how we can improve, please let us know by submitting feedback. Your input helps us enhance our resources and support.