Graphical User Interface with MATLAB App Designer

This note details how to implement a basic Graphical User Interface (GUI) in order to remotely control the B-Box RCP prototyping controller, or B-Board PRO inverter controller. The application is built on MATLAB App Designer (formerly MATLAB GUI) and the communication is achieved by using UDP/Ethernet packets.

The implementation of such an interface is typically useful in order to manage the run-time execution of a power converter, including for instance:

• Status information (running, stopped, discharge, fault, etc.)
• Real-time measurements (power flows, voltage, current, etc.)
• Fault diagnosis information (log messages, probable causes, etc.)
• Operation set points (current, power, etc.)
• Commands (start, stop, control mode change, etc.)

The use of such a GUI is often complementary to the imperix remote control software, which is often preferred for debug purposes. Also, the purpose of the GUI is limited to real-time interactions with the power converter controller(s) and is not related to how to program the controller(s), which can be done using dedicated SDKs.

Software resources

To be completed…

MATLAB App Designer

Being part of MATLAB basic package, App Designer enables to conveniently design graphical user interfaces by dragging and dropping visual components. Actions and processes are meant to be implemented in the well-known MATLAB programming language. At a later stage, standalone applications can be built and launched on any computer using the free MATLAB Runtime.

Ethernet communication

B-Box RCP and B-Board PRO support data communication protocols by providing high-level functions or blocks that allow the user to conveniently send and receive data. Examples are given in the related Simulink blockset. The present example has been implemented using UDP over Ethernet communication, because of its broad availability.

Data exchange planning

A few basic principles apply to the UDP communication with B-Box RCP and B-Board PRO:

• Packets must be 4 bytes long
• Consequently, they are usually carrying one variable of 32 bits each
• In order to allow communication of multiple variables, the system implements communication mailboxes, each mailbox being listening or sending to a given UDP port

The timing of the packets is defined such that:

• When the user code reads a packet, it gets the latest one (on the mailbox port), even though no packet was received between two reads.
• When the user code writes a packet, it is sent immediately. The send rate is limited, though.

Based on the above-mentioned considerations, a list of data exchanges is built as follows.

C/C++ code implementation overview

This section is applicable for users of the imperix CPP SDK.

The initialization of input and output mailboxes should be implemented inside function tUserSafe UserInit(void) {}. Typical initialization looks like:

constexpr unsigned int MB_ACTION_RESULT = 0;
constexpr unsigned int MB_ACTION = 1;

char ip_address[] = "10.10.10.53";
float update_frequency = 100.0;

tUserSafe UserInit(){
    // ...
    Eth_ConfigureOutputMailbox(MB_ACTION_RESULT, ...
       2222, ip_address, update_frequency);
    Eth_ConfigureInputMailbox(MB_ACTION, 2223);
    // ...
}
Code language: C++ (cpp)

At run-time, the following calls can be made so that to access the received data or send new packets:

start_cnt = Eth_ReadUint(MB_ACTION);
Eth_Write(MB_ACTION_RESULT, payload);

ACG code implementation overview

This section is applicable for users of the imperix ACG SDK.

‘Ethernet input mailbox’ and ‘Ethernet output mailbox’ blocks (available in the imperix library) should be inserted in the Simulink files to ensure communication with the GUI.

The Ethernet input mailbox receives the information from the GUI. The Ethernet port number and the signal format must be specified in the block settings.

The Ethernet output mailbox sends the information to the GUI. The Ethernet port number, the Ethernet IP address (of the PC on which the GUI is running), the signal format and the sending frequency must be specified in the block settings.

Implementation principles in App Designer

Initialization

Besides the instantiation of the controls, the application implements a few properties:

• app.timer object which will be used to trigger the data refresh
• isconnected variable that stores the connection state
• time variable that allows time counting

A startup function is implemented in order to configure the timer callback properly.

function startupFcn(app)
  app.timer.TimerFcn = @(~, ~) readEthernetandUpdate(app);
  % inits the timer (not stared yet,though. Done by ConnectButtonPushed())
end
Code language: Matlab (matlab)

Background processes

As long as isconnected > 0 a refresh task (readEthernetandUpdate()) is triggered by a timer with a period of 0.5 seconds. An excerpt of the function is:

function readEthernetandUpdate(app)
  app.time = app.time + 0.5;

  if (typecast(flip(typecast(judp('RECEIVE',2225, 4), 'uint8')'),'uint32'))>1
    app.StateLamp.Enable = 1;
  else
    app.StateLamp.Enable = 0;
  end

  % ... (truncated)

  app.IdGauge.Value = ...
    double(typecast(flip(typecast(judp('RECEIVE',2227, 4), 'uint8')'),'single'));
  app.IqGauge.Value = ...
    double(typecast(flip(typecast(judp('RECEIVE',2228, 4), 'uint8')'),'single'));

  % ... (truncated)
end
Code language: Matlab (matlab)

Actions

Actions (i.e. sending data from the computer) are implemented via callbacks on GUI elements. Two examples are presented below, one sending a uint32 and the second a float32. Typecasting as well as byte flipping must be implemented as follows.

function DisableButtonPushed(app, event)
  if app.isconnected % performs the action only when connected
    judp('SEND', 2224, app.BBoxIPEditField.Value, int8([0 0 0 1]'));
  end
end
Code language: Matlab (matlab)

function DCbusreferenceEditFieldValueChanged(app, event)
  value = app.DCbusreferenceEditField.Value;
  if app.isconnected
    judp('SEND', 2226, app.BBoxIPEditField.Value, flip(typecast(single(value), 'int8'))');
  end
end
Code language: Matlab (matlab)

Closing comments

Implementing a GUI with App Designer is a rather quick and easy task since it requires little knowledge in programming. Besides, this relies on the well-known MATLAB environment that ACG SDK users are often already familiar with. Also, given the well-integrated UDP communication functions on the B-Box RCP and B-Board PRO platforms, the data exchange is straightforward to set up.

Even though many variables can be sent and read from a remote computer, the main drawback of this approach is the performance because:

• It relies on executing an interpreted MATLAB code, which is a CPU-intensive task on the PC
• The UDP handling code processes each RECEIVE request sequentially (i.e. open port, wait for the first incoming packet, transfer data to the user code), which makes this approach inefficient (drops most of the packets) and slow.

Consequently, for use cases where performance is more important than flexibility (e.g. data logging), other solutions should be considered such as for example BB Control software.