Click to download this document.

Revision History

1. Overview

1.1 Scope

This guide applies to the E2C Trinity product family (E2C Factory, E2C Field, E2C Facility). Except for the "Private Protocols" module, which is supported only by E2C Factory, all script modules are identical across the three products.

Intended Audience: Users with basic JavaScript programming skills.

1.2 Script Engine

1.3 Features and Constraints

• Language Support: Supports ECMAScript 5.1, with partial ES6 support (let/const/arrow functions/template literals/destructuring/Promise, etc.). async/await is not supported.
• No DOM / BOM: No browser environment. window, document, setTimeout, fetch and other browser APIs are not available.
• No Node.js Standard Library: require(), import, fs, http and other Node.js modules are not supported. IO operations must be performed through the built-in Edge object.
• Synchronous Calls: All built-in APIs are synchronous. Scripts must also execute synchronously.
• Exception Handling: try/catch is supported. Uncaught exceptions are captured by the engine and treated as execution failures.
• State Isolation: Different business modules use independent execution environments. Global variables are not shared across modules. Within the same module, execution instances may be reused. Do not rely on global variable state across script executions. Use Edge.SetKey / Edge.GetKey to persist state across executions.
• Execution Timeout: There is no built-in timeout for individual script execution. Avoid infinite loops or long-blocking logic in scripts.
• Memory Safety: Avoid creating large closures or large objects in scripts to prevent memory growth.

1.4 Data Type Mapping

The script runtime follows these data type rules:

Note: Since all numeric values are unified as floating-point, large integers may lose precision. When handling integers exceeding 2^53, pass them as strings.

2. Quick Start

2.1 Accessing the Script Editor

Script functionality is embedded in each business module — no separate installation or activation is required. Access the script editor through the following paths depending on the target module:

After entering the corresponding feature page, locate the script editing area in the configuration interface to write JavaScript scripts.

2.2 Writing Your First Script

Using "Data to Cloud — Normal Group Payload Transform" as an example, the following steps guide you through your first script:

Step 1: Configure a device group in Data to Cloud as the data source for cloud reporting.

Step 2: Go to "Data to Cloud", add an MQTT cloud service. Refer to the E2C Factory / E2C Field user manual for detailed configuration.

Step 3: On the MQTT service configuration page, add a Publish to enter the script editor.

Step 4: Paste the following code into the script editor:

 1 var payload = msg.payload;
 2 var dataList = [];
 3  
 4 for (var key in payload) {
 5     if (payload.hasOwnProperty(key)) {
 6         var p = payload[key];
 7         dataList.push({
 8             name: p.tag,
 9             value: parseFloat(p.value) || p.value,
10             time: p.time,
11             device: p.deviceName
12         });
13     }
14 }
15  
16 return {
17     messageId: msg.messageId,
18     reportTime: msg.groupTime,
19     group: msg.groupName,
20     metrics: dataList
21 };

Step 5: Save the script configuration and ensure the MQTT cloud service status is "Enabled".

Step 6: Wait for one reporting cycle, then verify on the MQTT Broker side that the transformed data has been received. The expected JSON output should look like:

1 {
2   "messageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
3   "reportTime": 1718000000000,
4   "group": "workshop_A_temp_humidity",
5   "metrics": [
6     { "name": "temperature", "value": 25.3, "time": 1718000000000, "device": "PLC01" },
7     { "name": "humidity",    "value": 60.1, "time": 1718000000000, "device": "PLC01" }
8   ]
9 }

For more examples, see Section 6.

2.3 Viewing Logs and Debugging

During script execution, logs and debug information can be viewed through the following methods:

Debug Logs (Recommended):

Use Edge.Log("your message") to output logs, view in real‑time in the "Debug Log" menu

System Log:

Use log("your message") to output to the system log, view in real‑time via the menu "System Settings‑Logs".

Debugging Tips:

1. Add Edge.Log("input: " + JSON.stringify(msg)); at the script entry to confirm the input structure
2. Add logs after key processing steps to trace data flow
3. Add Edge.Log("output: " + JSON.stringify(result)); before returning to confirm the output
4. Wrap potentially failing operations with try/catch and log exception details in the catch block

2.4 Script Lifecycle

Note: Script changes take effect immediately upon save — no gateway restart required. However, modifying production scripts during low-traffic periods is recommended.

3. General Conventions

3.1 Input Parameter

• If a script accepts input, the parameter name is always msg.
• The type of msg is determined by the business module. See Section 4 for details.
• The script content itself serves as the function body. The engine automatically wraps it into a function for execution, so you can use msg directly — no need to declare a function yourself.

3.2 Return Value

• There is no enforced return type; each business module consumes the return value differently.
• Cloud publishing modules (MQTT/HTTP) serialize the return value to JSON before sending. Returning an object or array is recommended.
• Driver parsing modules (network/serial drivers) require a return value in the format { "pointName": value, ... }.
• Action management modules ignore the return value; scripts focus on side effects (writing tags, calling APIs, etc.).
• When no data modification is needed, simply return msg; — the engine will skip script execution and pass through the original data.

3.3 Logging

Scripts can output logs in two ways:

1 // Output to system log
2 log("hello from script");
3  
4 // Publish to Debug Logs, visible in the frontend real-time log view
5 Edge.Log("script executed successfully");

4. Business Module Input Reference

4.1 Cloud Service — HTTP

Feature Access: Data to Cloud → Add HTTP → Packet Reassembly

Trigger: Group data is reported on cycle or on change, processed by the script, and sent to the cloud via HTTP.

Input Type: Object

Top-level Structure:

1 {
2   "messageId":   "uuid string",
3   "messageType": "normal | speed | pkg",
4   "groupName":   "group_name",
5   "groupTime":   1718000000000,
6   "payload":     "<see payload structures below>"
7 }

payload — Normal Tag Group (messageType = normal)

payload is an object keyed by tag name, each containing the following fields:

 1 {
 2   "temperature": {
 3     "tag":        "temperature",
 4     "value":      "25.3",
 5     "time":       1718000000000,
 6     "deviceName": "PLC01"
 7   },
 8   "humidity": {
 9     "tag":        "humidity",
10     "value":      "60",
11     "time":       1718000000000,
12     "deviceName": "PLC01"
13   }
14 }

If a tag has no collected value (e.g., device offline), value is null and time is 0.

payload — High-Speed Acquisition Group (messageType = speed)

High-speed groups are batched. payload is an array, each element is a snapshot frame, keyed by tag name:

 1 [
 2   {
 3     "temperature": { "tag": "temperature", "value": "25.1", "time": 1718000000100, "deviceName": "PLC01" },
 4     "humidity":    { "tag": "humidity",    "value": "60",   "time": 1718000000100, "deviceName": "PLC01" }
 5   },
 6   {
 7     "temperature": { "tag": "temperature", "value": "25.3", "time": 1718000000200, "deviceName": "PLC01" },
 8     "humidity":    { "tag": "humidity",    "value": "61",   "time": 1718000000200, "deviceName": "PLC01" }
 9   }
10 ]

Each array element corresponds to one high-speed sampling snapshot and may contain multiple consecutive sampling frames.

payload — Data Table Group (messageType = pkg)

Data table groups read the most recent N records from a data table for batch reporting. payload is an array, each element is a record, keyed by field code:

 1 [
 2   {
 3     "field_code_1": { "tag": "field_code_1", "value": "100", "time": 1718000000000, "deviceName": "PLC01" },
 4     "field_code_2": { "tag": "field_code_2", "value": "200", "time": 1718000000000, "deviceName": "PLC01" }
 5   },
 6   {
 7     "field_code_1": { "tag": "field_code_1", "value": "110", "time": 1717999000000, "deviceName": "PLC01" },
 8     "field_code_2": { "tag": "field_code_2", "value": "210", "time": 1717999000000, "deviceName": "PLC01" }
 9   }
10 ]

See examples 6.1, 6.2, 6.3.

4.2 Cloud Service — MQTT Publish

Feature Access: Data to Cloud → Add MQTT → Message Management → Add Publish

Trigger: Group data is reported on cycle or on change, processed by the script, and published to an MQTT Broker.

Input Type: Object

Input Structure: Identical to HTTP Cloud Service. The top-level fields and the three payload types (normal / speed / pkg) share the same structure. See Section 4.1.

Note: SparkplugB protocol publishing bypasses script processing and uses the standard SparkplugB payload format directly.

See examples 6.1, 6.2, 6.3.

4.3 Cloud Service — MQTT Subscription

Feature Access: Data to Cloud → Add MQTT → Message Management → Add Subscription

Trigger: The cloud sends a message to the device via MQTT. Upon arrival, Scenario Management (Cloud Command strategy) triggers the associated action for execution.

Input Type: string (raw MQTT payload content, received as a string in the script)

Format: No fixed format. Content is defined by the cloud side and must be parsed by the user. Typically a JSON string.

Processing Subscription Messages in Actions:

The Execute Function type action associated with the subscription-triggered strategy receives the raw MQTT payload string.

See example 6.4.

4.4 Scenario Management — Action Management (Execute Function Type)

Feature Access: Scenario Management → Action Management → Execute Function

Trigger: When a strategy is triggered (Scheduled Control, Cycle Control, Power-on Execution, Cloud Command), the associated "Execute Function" type action is executed.

Input Type: Object or null

• When triggered by Scheduled Control / Cycle Control / Power-on Execution: msg is null (no data).
• When triggered by Cloud Command: msg is the raw MQTT payload string.

See examples 6.5 and 6.4.

4.5 Tag Change Script

Feature Access: Tag Management → Tag Change Script

Trigger: Triggered when a device tag's collected value changes (change event).

Input Type: Object

Input Structure:

1 {
2   "deviceName": "PLC01",
3   "tag":        "temperature",
4   "value":      "25.3",
5   "time":       1718000000000
6 }

See example 6.6.

4.6 Private Protocols — Uplink Parsing

E2C Factory only.

Feature Access: Private Protocols → Uplink Protocol Parsing

Trigger: A device reports raw byte data, which is unpacked and passed to the script for parsing into tag key-value pairs.

Input Type: Uint8Array (unpacked raw byte frame)

Return Value: Must return an object in the format { "tagCode": value, ... }. If a non-object type is returned, the driver discards the parsing result.

See example 6.7.

4.7 Private Protocols — Downlink Command

E2C Factory only.

Feature Access: Private Protocols → Downlink Command

Downlink scripts are divided into two types with different input and return value requirements:

Acquisition Command / Heartbeat Command

Trigger: Polling drivers send acquisition commands in configured order; subscription drivers send heartbeat commands at the configured heartbeat interval.

Input: Empty string "" (no input, can be ignored)

Return Value: Must return Uint8Array. The driver writes it directly to the connection.

1 // No input; return command bytes directly
2 return new Uint8Array([0x00, 0x01]);

Write Command (Write Tag)

Trigger: Triggered when the system performs a write operation on a device tag.

Input Type: Array containing exactly one command object with the following fields:

Return Value: Must return Uint8Array. The driver automatically converts and writes it to the connection. Returning other types (e.g., plain array, string) will cause conversion failure.

See example 6.7.

5. Built-in API Reference

In addition to JavaScript native functions (JSON, Math, String, Array, Date, etc.), the script runtime provides the following built-in objects and functions.

5.1 Global Functions

5.2 Edge Object

The Edge object provides interaction with system modules. All methods are synchronous.

Device Tag Read/Write

1 Edge.ReadTags(deviceName, tags) -> []{ tag, value } | null

Reads the current values of multiple tags from a specified device.

• deviceName: Device name (string)
• tags: Array of tag names, e.g., ["temperature", "humidity"]
• Returns: [{ "tag": "temperature", "value": "25.3" }, ...], or null on failure or no data

1 Edge.WriteTags(deviceName, tagValues) -> bool

Writes multiple tag values to a specified device.

• tagValues: [{ "tag": "pointName", "value": "val" }, ...]
• Returns: true on success, false on failure

1 Edge.WriteData(deviceName, bytes) -> bool

Writes raw byte data to a specified device (for custom protocol devices).

1 Edge.ReadDataTags(tableCode, tags) -> []{ tag, value } | null

Reads the latest field values from a data table (for the Data Management module).

• tableCode: Data table code
• tags: Array of field names

1 Edge.WriteDataTags(tableCode, tagValues) -> bool

Writes a record to a data table.

• tagValues: [{ "tag": "fieldName", "value": "val" }, ...]

System Parameters

1 Edge.GetParam(paramName) -> { name, value } | {}

Reads a system custom parameter value.

1 Edge.SetParam(paramName, value) -> bool

Updates a system custom parameter value.

Global Cache (Key-Value)

1 Edge.SetKey(key, value) -> bool

Stores a key-value pair in memory (process-global, lost on restart). Suitable for passing temporary state across script executions.

1 Edge.GetKey(key) -> value | null

Retrieves a value from the cache.

Logging

1 Edge.Log(content)

Publishes a log message to the Debug Logs, click the Debug Log menu to view it on the page.

HTTP Requests

1 Edge.PostJson(url, head, data) -> string

Sends a POST request (Content-Type: application/json), 2-second timeout.

• head: Request header object, e.g., { "Authorization": "Bearer xxx" }
• data: Request body, any object, will be serialized to JSON
• Returns: Response body string, or error message string on failure

1 Edge.GetJson(url, head) -> string

Sends a GET request, 2-second timeout. Returns the response body string.

1 Edge.HttpClient(url, method, body, headParam) -> string

General-purpose HTTP client, supports custom methods and parameters.

• body: Request body parameter object
• headParam: Request header object

MQTT Publishing

1 Edge.MqttPub(clientId, topic, msg) -> bool

Publishes an MQTT message through a specified cloud service client.

• clientId: Cloud service Client ID (defined in system cloud service configuration)
• topic: Target Topic
• msg: Message content string
• Returns: true if published successfully (confirmed within 2 seconds), false otherwise

1 Edge.MqttResp(clientId, topic, msg) -> bool

Publishes a response message through a cloud service. clientId and topic support system parameter placeholder substitution (e.g., {$deviceSn}).

File Transfer

1 Edge.DownloadFromHTTP(url, fileName, method, headParam) -> bool

Downloads a file from an HTTP URL to local storage.

1 Edge.UploadFileToHTTP(url, fileName, headParam) -> bool

Uploads a local file to an HTTP URL.

1 Edge.DownloadFromFTP(serverAddr, username, pwd, remotePath, localFile, fileProtocol) -> bool

Downloads a file from an FTP/SFTP server. fileProtocol is "ftp" or "sftp".

1 Edge.UploadToFTP(serverAddr, username, pwd, remotePath, localFile, fileProtocol) -> bool

Uploads a local file to an FTP/SFTP server.

1 Edge.GatewayConfigImportHTTP(url, fileName, method, headParam) -> bool

Downloads a file from an HTTP URL and imports it as gateway configuration.

Encryption / Decryption

1 Edge.EncryptRSAString(publicKey, contentStr) -> string

Encrypts a string using an RSA public key. Returns the encrypted result. Returns an empty string on failure.

1 Edge.DecryptRSAString(privateKey, contentStr) -> string

Decrypts a string using an RSA private key. Returns the decrypted result. Returns an empty string on failure.

Gateway Hardware Information

1 Edge.GetGatewayInfo() -> Object | null

Retrieves gateway basic information. Return fields:

1 Edge.GetSimStatus() -> Object | null

Retrieves SIM card and signal status. Return fields:

1 Edge.GetTraffic() -> Object | null

Retrieves SIM card traffic information. Return fields:

DI/DO Control

1 Edge.GetDiStatus(di) -> int

Reads the digital input (DI) level status. Returns 0/1, or -1 on failure.

1 Edge.GetDoStatus(do) -> int

Reads the current digital output (DO) status.

1 Edge.SetDoStatus(do, value) -> Object | null

Sets the digital output (DO) status. value is "0" or "1".

6. Example Scripts

6.1 Cloud Service — Normal Group Payload Transform (messageType = normal)

Applicable modules: 4.1 HTTP Cloud Service / 4.2 MQTT Publish

Scenario: Normal cycle/change reporting. payload is an object keyed by tag name, each containing tag, value, time, deviceName. The script transforms it into a list format required by the cloud.

 1 // msg top-level structure:
 2 // {
 3 //   messageId:   "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 4 //   messageType: "normal",
 5 //   groupName:   "workshop_A_temp_humidity",
 6 //   groupTime:   1718000000000,
 7 //   payload: {
 8 //     "temperature": { tag: "temperature", value: "25.3", time: 1718000000000, deviceName: "PLC01" },
 9 //     "humidity":    { tag: "humidity",    value: "60.1", time: 1718000000000, deviceName: "PLC01" }
10 //   }
11 // }
12  
13 var payload  = msg.payload;
14 var dataList = [];
15  
16 // Flatten keyed payload into an array
17 for (var key in payload) {
18     if (payload.hasOwnProperty(key)) {
19         var p = payload[key];
20         dataList.push({
21             name:   p.tag,
22             value:  parseFloat(p.value) || p.value,
23             time:   p.time,
24             device: p.deviceName
25         });
26     }
27 }
28  
29 return {
30     messageId:  msg.messageId,
31     reportTime: msg.groupTime,
32     group:      msg.groupName,
33     metrics:    dataList
34 };

6.2 Cloud Service — High-Speed Group Payload Transform (messageType = speed)

Applicable modules: 4.1 HTTP Cloud Service / 4.2 MQTT Publish

Scenario: High-speed acquisition. payload is an array, each element is a sampling snapshot frame (same format as a single normal entry). The script converts multiple frames into a batch reporting structure.

 1 // msg top-level structure:
 2 // {
 3 //   messageId:   "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 4 //   messageType: "speed",
 5 //   groupName:   "high_speed_group",
 6 //   groupTime:   1718000000000,
 7 //   payload: [
 8 //     { "temperature": { tag, value, time, deviceName }, "humidity": { ... } },
 9 //     { "temperature": { tag, value, time, deviceName }, "humidity": { ... } }
10 //   ]
11 // }
12  
13 var payload = msg.payload;
14 var frames  = [];
15  
16 // Each element in payload is one snapshot frame
17 for (var i = 0; i < payload.length; i++) {
18     var frame  = payload[i];
19     var points = [];
20     for (var key in frame) {
21         if (frame.hasOwnProperty(key)) {
22             points.push({
23                 name:  key,
24                 value: frame[key].value,
25                 time:  frame[key].time
26             });
27         }
28     }
29     frames.push(points);
30 }
31  
32 return {
33     messageId: msg.messageId,
34     group:     msg.groupName,
35     frames:    frames
36 };

6.3 Cloud Service — Data Table Group Payload Transform (messageType = pkg)

Applicable modules: 4.1 HTTP Cloud Service / 4.2 MQTT Publish

Scenario: Data table group reporting. Reads the most recent N records from a data table for batch upload. payload is an array, each element is a table record keyed by field code. The script expands it into a row-column structure required by the cloud.

 1 // msg top-level structure:
 2 // {
 3 //   messageId:   "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 4 //   messageType: "pkg",
 5 //   groupName:   "production_stats",
 6 //   groupTime:   1718000000000,
 7 //   payload: [
 8 //     { "field_code_1": { tag, value, time, deviceName }, "field_code_2": { ... } },
 9 //     { "field_code_1": { tag, value, time, deviceName }, "field_code_2": { ... } }
10 //   ]
11 // }
12  
13 var payload = msg.payload;
14 var records = [];
15  
16 // Each element in payload is one table record
17 for (var i = 0; i < payload.length; i++) {
18     var record = payload[i];
19     var row    = { _time: 0 };
20     for (var key in record) {
21         if (record.hasOwnProperty(key)) {
22             row[key]   = record[key].value;
23             // Use the timestamp of the first field as the record time
24             if (row._time === 0) {
25                 row._time = record[key].time;
26             }
27         }
28     }
29     records.push(row);
30 }
31  
32 return {
33     messageId: msg.messageId,
34     group:     msg.groupName,
35     records:   records
36 };

6.4 MQTT Subscription — Parse Command and Write Device Tags

Applicable modules: 4.3 MQTT Subscription / 4.4 Action Management (Cloud Command trigger)

Scenario: The cloud sends a control command (JSON) via MQTT. The subscription message is parsed, and the corresponding device tags are written. The result is replied to the cloud via MQTT.

Cloud command format:

1 {
2   "command":    "write",
3   "deviceName": "PLC01",
4   "tags": [
5     { "tag": "setpoint_temp", "value": "75" },
6     { "tag": "enable_fan",    "value": "1"  }
7   ]
8 }

 1 // msg is the raw MQTT payload string
 2 var data;
 3 try {
 4     data = JSON.parse(msg);
 5 } catch (e) {
 6     // Parse failed, log raw content
 7     Edge.Log("parse error: " + e.message + " raw=" + msg);
 8     return;
 9 }
10  
11 if (data.command !== "write") {
12     // Unknown command, discard
13     Edge.Log("unknown command: " + data.command);
14     return;
15 }
16  
17 // Write tags to the target device
18 var ok = Edge.WriteTags(data.deviceName, data.tags);
19 if (ok) {
20     Edge.Log("write ok device=" + data.deviceName + " count=" + data.tags.length);
21 } else {
22     Edge.Log("write failed device=" + data.deviceName);
23 }
24  
25 // Reply with execution result via MQTT
26 var ack = JSON.stringify({
27     command:    "writeAck",
28     deviceName: data.deviceName,
29     success:    ok,
30     timestamp:  new Date().getTime()
31 });
32 Edge.MqttResp("clientId", "device/response", ack);

6.5 Cycle Strategy Action — Scheduled Acquisition and Reporting

Applicable modules: 4.4 Action Management (Cycle Control / Scheduled Control / Power-on Execution trigger)

Scenario: Reads key tags from multiple devices every minute, aggregates them, and reports to a business system via HTTP POST.

 1 // msg is null when triggered by cycle / scheduled / power-on strategy
 2  
 3 var devices    = ["Chiller_01", "Chiller_02", "Chiller_03"];
 4 var pointNames = ["inlet_temp", "outlet_temp", "flow_rate", "power"];
 5  
 6 var report = {
 7     timestamp: new Date().getTime(),
 8     chillers:  []
 9 };
10  
11 for (var i = 0; i < devices.length; i++) {
12     var tags = Edge.ReadTags(devices[i], pointNames);
13     if (tags == null) {
14         // Read failed, skip this device
15         Edge.Log("read failed device=" + devices[i]);
16         continue;
17     }
18     // Build per-device data object
19     var item = { deviceName: devices[i] };
20     for (var j = 0; j < tags.length; j++) {
21         item[tags[j].tag] = tags[j].value;
22     }
23     report.chillers.push(item);
24 }
25  
26 // Fetch API token from system params
27 var token = Edge.GetParam("api_token");
28 var resp  = Edge.PostJson(
29     "https://api.example.com/chiller/report",
30     { "Authorization": "Bearer " + (token ? token.value : "") },
31     report
32 );
33  
34 Edge.Log("report done resp=" + resp);

6.6 Tag Change Script — Threshold-Based Linkage Control

Applicable modules: 4.5 Tag Change Script

Scenario: When a temperature tag exceeds a threshold, automatically write a control tag to turn on a fan and notify the cloud via HTTP. A debounce mechanism ensures at most one report per minute.

 1 // msg: { deviceName, tag, value, time }
 2 var temp = parseFloat(msg.value);
 3  
 4 // Skip non-numeric values
 5 if (isNaN(temp)) {
 6     return;
 7 }
 8  
 9 var threshold = 80.0;
10  
11 if (temp > threshold) {
12     // Turn on the cooling fan
13     Edge.WriteTags(msg.deviceName, [{ tag: "fan_control", value: "1" }]);
14     Edge.Log("high temp: " + temp + " >" + threshold + " fan on");
15  
16     // Debounce: report at most once per minute
17     var lastAlarm = Edge.GetKey("fan_alarm_time");
18     var now       = msg.time;
19     if (lastAlarm == null || (now - lastAlarm) > 60000) {
20         Edge.SetKey("fan_alarm_time", now);
21         // Notify the cloud platform
22         Edge.PostJson("https://api.example.com/alarm", {}, {
23             device: msg.deviceName,
24             point:  msg.tag,
25             value:  temp,
26             time:   now
27         });
28     }
29 }

6.7 Private Protocol Script — Temperature and Humidity Sensor Protocol (Uplink Parsing + Downlink Write)

Applicable modules: 4.6 Private Protocols (Uplink Parsing) / 4.7 Private Protocols (Downlink Command)

Device Protocol

Tag-to-Protocol Field Mapping

Uplink Parsing Script (Module 4.6)

Unpacking mode: "Fixed length 4". The device responds with a 4-byte frame. The script parses it into tag key-value pairs keyed by tag code.

 1 // msg is a Uint8Array raw response frame, 4 bytes
 2 // Response frame layout:
 3 //   [0-1]  temperature (big-endian int16)
 4 //   [2-3]  humidity (big-endian int16)
 5  
 6 var arr = new Uint8Array(msg);
 7  
 8 // Guard: drop short frames
 9 if (arr.length < 4) {
10     return { error: "invalid frame" };
11 }
12  
13 return {
14     "tm": (arr[0] << 8) | arr[1],   // temperature
15     "hm": (arr[2] << 8) | arr[3]    // humidity
16 };

Downlink Write Script (Module 4.7)

When the system issues a write tag command, the script constructs the corresponding 4-byte write command frame based on the tag code. The return value must be Uint8Array.

The input msg is an array containing exactly one command object with the following fields:

 1 // msg = [{ Address, Value, DatatypeCode, TransactionId }]
 2 // Address: tag code (tm=temperature, hm=humidity)
 3 // Value:   value to write (string)
 4  
 5 var cmd      = msg[0];
 6 var writeVal = parseInt(cmd.Value, 10);
 7 var hi       = (writeVal >> 8) & 0xFF;   // value high byte
 8 var lo       = writeVal & 0xFF;           // value low byte
 9  
10 // Frame layout: [ type_hi, type_lo, value_hi, value_lo ]
11 if (cmd.Address === "hm") {
12     // Write humidity: type = 0x0002
13     return new Uint8Array([0x00, 0x02, hi, lo]);
14 } else if (cmd.Address === "tm") {
15     // Write temperature: type = 0x0003
16     return new Uint8Array([0x00, 0x03, hi, lo]);
17 } else {
18     // Unknown tag code, send no-op
19     Edge.Log("unknown address: " + cmd.Address);
20     return new Uint8Array([0x00, 0x00, 0x00, 0x00]);
21 }

7. Debugging and Troubleshooting

7.1 Common Errors

7.2 Debugging Workflow

1. Confirm input: Add Edge.Log("input: " + JSON.stringify(msg)); at the script entry to verify the actual input structure.
2. Step-by-step investigation: Add logs after key steps to locate where data goes wrong.
3. Verify return value: Add Edge.Log("output: " + JSON.stringify(result)); before return to confirm the output structure.
4. Exception capture: Wrap key logic with try/catch and log complete error details:

1 try {
2     // your logic
3 } catch (e) {
4     Edge.Log("error: " + e.message + " stack: " + e.stack);
5 }

5. Click the Debug Log menu: View all Edge.Log outputs on the frontend Debug Logs page to confirm execution order and results.

7.3 FAQ

Q: Can I use let / const in scripts?

A: Yes. The engine partially supports ES6, including let, const, arrow functions, template literals, destructuring, etc. async/await is not supported.

Q: Why do global variables disappear on the next execution?

A: Script execution instances may be reused, but global state is not guaranteed to persist across executions. Use Edge.SetKey(key, value) to store and Edge.GetKey(key) to retrieve persistent state.

Q: What is the difference between return msg; and no return?

A: return msg; means skip script processing and pass through the original data. Without a return (or return undefined), the data will not be sent to the cloud.

Q: Can scripts call external HTTP APIs?

A: Yes. Use Edge.PostJson(), Edge.GetJson(), or Edge.HttpClient() to send HTTP requests. The timeout is 2 seconds.

Q: Can scripts control gateway hardware (DI/DO)?

A: Yes. Use Edge.GetDiStatus(), Edge.GetDoStatus(), Edge.SetDoStatus() to read and control digital inputs/outputs.

Q: Do I need to restart the gateway after modifying a script?

A: No. Changes take effect immediately upon save.

Q: Can multiple scripts share variables?

A: Not directly. Different business modules use independent execution environments. To pass data across modules, use system parameters (Edge.SetParam / Edge.GetParam) as an indirect mechanism.

8. Best Practices

8.1 Error Handling

Always wrap key logic with try/catch to prevent uncaught exceptions from causing execution failures:

1 try {
2     var data = JSON.parse(msg);
3     // process data
4     return data;
5 } catch (e) {
6     Edge.Log("parse error: " + e.message);
7     return null;
8 }

8.2 Performance Tips

• Avoid large objects: Do not create large closures or objects in scripts to prevent memory growth.
• Use cache wisely: Use Edge.SetKey / Edge.GetKey to store cross-execution state, but avoid storing excessively large data.
• Avoid infinite loops: There is no built-in timeout for individual script execution. Ensure script logic can exit normally.
• Minimize HTTP requests: HTTP requests have a 2-second timeout; frequent requests will impact script response time.

8.3 Security Tips

• Do not hardcode credentials: API tokens, passwords, and other sensitive information should be stored in system parameters and read via Edge.GetParam().
• Validate external input: For MQTT subscription messages, HTTP request responses, and other external data, validate format and type before processing.
• Limit write scope: When using Edge.WriteTags(), ensure the target device and tag names are correct to avoid unintended writes.

Appendix A: Glossary