Data Transformations
Functional translations in Device Services allow the automatic transformation of data as it is collected. These transformations are controlled by Lua scripts that can be injected into a device service at run-time. The Lua scripts can intercept data, apply transformations, and deliver the transformed data northbound to the Edge Xpert message bus as standard.
All device services are supported.
Enable the Lua Transform Component
The Lua Transform Component inside a device service is disabled by default.
To enable it, use Docker Compose Override to set the environment variable USETRANSFORMSCRIPT
to true for the device service.
In the example below, we enable the Lua Transform Component in the BACnet/IP Device Service:
services:
device-bacnet-ip:
environment:
USETRANSFORMSCRIPT: "true"
Lua Script Example
In order to transform data, you need to create a Lua script. This can be created in a regular text file.
The following example converts the received readings from Celsius to Fahrenheit:
for k,v in pairs(data.readings) do
-- Convert Celsius to Fahrenheit
if v.units == 'C' then
data.readings[k].units = 'F'
data.readings[k].value = data.readings[k].value * 9 / 5 + 32
end
end
Once created, save as a .lua file. We saved this example as celsius-to-fahrenheit.lua.
The predefined variable data
is a Lua table representing an Edge Xpert Event. This contains the following information:
- deviceName
- profileName
- sourceName
- readings
- origin
- deviceName
- profileName
- resourceName
- valueType
- units
- value
Without Lua translations, value
is converted to a string. However, with a Lua script enabled, value
keeps its original data type. This allows you to directly perform calculations or transformations on the value.
In this Lua script example, Celsius readings are detected by checking the units
property of the device resource, which is defined in the device profile. For example:
name: bacnet-sim-profile
deviceResources:
- name: analog_input_0-present-value
isHidden: false
properties:
valueType: Float32
readWrite: RW
units: C
attributes:
instance: 0
property: 85
type: 0
deviceCommands: []
Upload Lua Script for Device Service via Edge Xpert Manager
-
Start Edge Xpert Manager, along with the BACnet Device Service and simulator:
edgexpert up device-bacnet-ip bacnet-sim xpert-manager
-
Open a browser and go to
http://localhost:9090
. The default username/password is admin/admin. -
Select Devices from the main menu:
-
Select the Device Services tab:
-
Click the horizontal three-dot menu on the service where you want to upload the Lua script. Select Edit:
-
Choose the Lua script file you wish to apply and click Save:
You can now proceed as standard to add the device and device profile.
All data gathered from the device service will now be transformed as defined in the Lua script and will be available in Edge Xpert for processing, analysis, and delivery as normal.
Upload Lua Script for Device Service via REST APIs
The Device Service REST APIs have been instrumented with an additional parameter that allows for the transform script to be injected into the running service.
See the Swagger definition for further information
As above, this example uses the BACnet Device Service and simulator. To upload a Lua script over REST API, follow the steps below:
-
Start the BACnet Device Service and simulator:
edgexpert up device-bacnet-ip bacnet-sim
-
Send a PATCH request with the following body:
curl -X 'PATCH' \ 'http://<core-metadata-address>/api/v2/deviceservice' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '[ { "apiVersion": "v2", "service": { "name": "device-bacnet-ip", "transformScript": "<path/<to>/<file>/celsius-to-fahrenheit.lua" } } ]'
Note
Ensure you replace the placeholders with the appropriate Lua file path and
core-metadata
adress. You can find the address forcore-metadata
with the following command:edgexpert ip | grep core-metadata
If successful, this should return:
[{"apiVersion":"v2","statusCode":200}]
When following this example, you can also confirm the Lua script has taken effect by checking the Docker logs for the simulator:
$ docker logs -f bacnet-sim Running in IP mode IOTech BACnet Simulator BACnet Stack Version 1.0.5 BACnet Device ID: 123 Max APDU: 1476 Loading lua script... Create 2 AnalogValue instances Create 2 AnalogOutput instances Create 2 AnalogInput instances Loaded lua script sucessfully.