disclaimer

just remember that it is not legal to use ETS .NET SDK without license.

steps described here is text and screenshots are computer graphics.

tldr

download link

ETS application

what is ETS app?

ETS app is precompiled binaries for .NET runtime to run inside ETS application. ETS-procedures is expoded in ETS .NET SDK libraries.

what is ETS .NET SDK?

ETS sdk is that can be used inside your project to access KNX or ETS procedures. For this procedures specific objects should be used.

dotnet relies heavely on object-oriented programming, so, knowledge of object orienting programming will be helpful.

More than that, help files in included in SDK and together with autocomplete it will be main instruments in writing app.

IDE

I installed Microsoft Visual Studio. It is downloadable from official microsoft site and individual license is free.

project

demo-app

As and example and the base I took demo application that was distributed in the SDK package. After installing it can be found at “Program Files (x86)/ETS5/SDK/DemoProjects/Knx.Sdk.Demos.Ets5App”.

starting

idea - js api

App idea was inspiring - create script interpreter inside ETS to be able to automatize routing and batch actions. As a scripting languages was considered lua and python as well. Somehow, jint was choosen, maybe because I was programming in nodejs a lot.

Structure is pretty straight:

editor.text => js engine => sdk calls

third-party libraries

editor

AvalonEdit component. It supports syntax highlighting and autocomplete. Easy to setup and place in GUI.

  completionWindow = new CompletionWindow(editor.TextArea);
  completionWindow.FontFamily = editor.FontFamily;
  IList<ICompletionData> data = completionWindow.CompletionList.CompletionData;

  string text, descr;


  text = "clear()";
  descr = "Clear log console. \n";
  descr += "Usage: \n";
  descr += "  clear();";
  data.Add(new MyCompletionData(text, descr));

  text = "alert(msg, title)";
  descr = "Show message box. \n";
  descr += "Usage: \n";
  descr += "  alert(\"There something happening here..\");";
  data.Add(new MyCompletionData(text, descr));

  text = "writeln(msg, pretty)";
  descr = "Log message to console.\n";
  descr += "pretty argument is optional. \n";
  descr += "Usage: \n";
  descr += "  writeln(\"What it is ain't exactly clear.\");\n";
  descr += "  // pretty output: \n";
  descr += "  writeln(getAllDevices(), 1);";
  data.Add(new MyCompletionData(text, descr));

autocomplete

js interpreter

Jint is the main tool and core of this project.

exposing sdk

First, we need to initialize EtsJsSdk class:

 public void Initialize(IInitializationContext initializationContext)
 {
     _project = initializationContext.Project;
     _resources = initializationContext.Resources;
     _configuration = AppConfiguration.LoadFromDocument(initializationContext.Configuration);
     _userConfiguration = Demos.Ets5App.UserConfiguration.LoadFromDocument(initializationContext.UserConfiguration);
     _hostNotification = initializationContext.HostNotification;
     EtsResourceAdapter.Initialize(_resources);
 }

Access to knx project, resources can be recieved through initializationContext which is an instance of Knx.Ets.Sdk.AddIns.AddInViews.IInitializationContext class.

As an example

 public void SetDeviceParameter(string device, string id, Object value)
 {
     DeviceCollection dc = _project.DefaultInstallation.AllDevices; // get all devices from project
     Device d = ProjectUtils.FindDevice(dc, device); // find device with addr "x.y.z"

     if (d == null && strictMode)
     {
         ThrowJsException(AppExceptions.device_doesnt_exist);
         return;
     }
     else if (d == null && !strictMode)
         return;

     ParameterInstanceRef pref = null;
     for(ushort i = 0; i < d.ParameterInstanceRefs.Count; i += 1)
     {
         if (d.ParameterInstanceRefs[i].Id == id)
         {
             // if it is parameter we want to set - assign and break the loop
             pref = d.ParameterInstanceRefs[i];
             break;
         }
     }
     if (pref == null && strictMode)
     {
         ThrowJsException(AppExceptions.parameter_doesnt_exist);
     }
     else if (pref == null && !strictMode)
         return;

     try
     {   // just set the value
         pref.Value = value;
     } catch(Exception)
     {
         if (strictMode)
             ThrowJsException(AppExceptions.cannot_assign_parameter_value);
     }
 }

Js interpreter should know all C# methods that is defined:

functions

compiling

compiling is done via Build menu. After that all is needed is just compress all files from build/release or build/debug directories to one zip archive and replace zip extension with etsapp.

app gui

examples

// for every comm object of selected device create GA and make a link
clear();
setStrictMode(false);
let device = "1.1.1";
let range = "1/1";
let i = 0;

let info = getDeviceInfo(device);
writeln(JSON.stringify(info, null, 2));


info.communication_objects.forEach(function(co) {
  let addr = range + i;
  createGroupAddress(addr, co.text);
  link(device, co.number, addr);
});
// now a quick way to swap communication objects -
// for example you need to swap two push buttons on device

clear();

function swapCo(device, num1, num2) {
  let info = getDeviceInfo(device);
  writeln(info, 1);
  let co1 = null;
  let co2 = null;

  info.communication_objects.forEach(function(co) {
    if (co.number === num1)
      co1 = co;
    else if (co.number === num2)
      co2 = co;
  });

  if (co1 === null || co2 === null)
    return writeln("some of comm objects not found");

  co1.links.forEach(function(l) {
    unlink(device, co1.number, l);
    link(device, co2.number, l);
  });
  co2.links.forEach(function(l) {
    unlink(device, co2.number, l);
    link(device, co1.number, l);
  });
};

swapCo("1.1.42", 17, 122);
swapCo("1.1.42", 27, 132);

afterword

it’s not completed manual of how to create ets app, but some hightlight.

anyway, a must to do is a looking in chm help file and using IDE features.